Krist Documentation

# k.lua

The recommended Krist API for Lua is k.lua (opens new window) by tmpim (opens new window). This API makes use of r.lua (opens new window), w.lua (opens new window) and Jua (opens new window) to make the Krist API a breeze to interact with. You will also need the JSON API by ElvishJerricco (opens new window) to create and parse the JSON objects required by the Krist API.

# Quick start

# Installing k.lua and dependencies

There is a simple script to download + install k.lua and all its dependencies. It can be used in one of two ways - with wget (recommended, CC: Tweaked 1.84 and higher), or Pastebin (old ComputerCraft versions):

wget run https://raw.githubusercontent.com/tmpim/k.lua/master/kstrap.lua

# Pastebin (old ComputerCraft versions)

pastebin run 4ddNhMYd

# Initialization

First, make sure you have required all the dependencies for k.lua:

local w = require("w") -- allows interaction with krist websocket api (for realtime data)
local r = require("r") -- makes http requests easier
local k = require("k") -- the krist api itself
local jua = require("jua") -- makes events easier
os.loadAPI("json.lua") -- to parse data returned by the krist api
local await = jua.await

-- initialise w.lua, r.lua and k.lua
r.init(jua)
w.init(jua)
k.init(jua, json, w, r)

# Understanding Jua

Jua is a callback system for ComputerCraft, inspired by JavaScript callbacks. It gets rid of the usual event loop, and replaces it with jua.on("event", callback). For example:

local jua = require("jua")

jua.on("key", function(event, key)
  -- this code is called every time there is a `key` event
  print("Key pressed: " .. keys.getName(key))
end)

jua.on("terminate", function()
  -- this event is required to ensure we can actually close our program
  jua.stop()
  printError("Terminated")
end)

jua.go(function()
  -- jua is ready, and you can run all your code in here
  print("Jua is ready.")
end)

# Making requests to the Krist API

# Supported API calls

K.lua currently supports the following API calls:

# Making a request

To make a request, you need to await() the API call, for example:

-- success is true if the request went ok, false if not
-- address contains information about the address
local success, address = await(k.address, "khugepoopy")
assert(success, "Failed to get address.")

print("Address: " .. address.address)
print("Balance: " .. address.balance)

This code should go inside the jua.go call.

WARNING

Make sure you don't forget to await! If you don't await when using k.lua functions, you must pass a callback, or else you will get an error.

# Using websockets

K.lua also supports websockets. These allow you to receive event data from the Krist node in realtime.

WARNING

Make sure your privatekey is in the correct format. If you don't convert the privatekey to the correct privatekey format, you may authenticate as the wrong address. You can read more about wallet privatekey formats here.

local function openWebsocket()
  local success, ws = await(k.connect, "your-private-key")
  assert(success, "Failed to get websocket URL")

  print("Connected to websocket.")

  -- here we subscribe to the 'transactions' event
  local success = await(ws.subscribe, "transactions", function(data)
    -- this function is called every time a transaction is made
    local transaction = data.transaction

    print("Transaction made:")
    print("From: " .. transaction.from)
    print("To: " .. transaction.to)
    print("Value: " .. transaction.value .. " KST")
    -- Transactions have other properties, including "metadata", "id" and "time".
    -- Metadata can be parsed using k.parseMeta
  end)
  assert(success, "Failed to subscribe to event")
end

jua.go(function()
  openWebsocket()
  -- your other code
end)

Available events can be found in the Krist API documentation (opens new window). These can be subscribed to as transactions are in the example above. Multiple events can be subscribed to at once. It may also be useful to connect some sort of indicator to the keepalive event if k.lua is being used in ComputerCraft, so that it is easy to tell whether a computer is functioning or not.

← krist.js (JavaScript/TypeScript) →