k.lua

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

• Quick start
  • Installing k.lua and dependencies
  • Initialization
• Understanding Jua
• Making requests to the Krist API
  • Supported API calls
  • Making a request
  • Using websockets

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 (recommended, CC: Tweaked 1.84 and higher)

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:

• address(address) (api docs) - Gets information about an address, such as its balance
• addressTransactions(address, limit, offset) (api docs) - Gets recent transactions by an address
• addressNames(address) (api docs) - Gets names owned by an address
• addresses(limit, offset) (api docs) - List all addresses
• rich(limit, offset) (api docs) - List the addresses with the highest balance
• transactions(limit, offset) (api docs) - List all transactions
• latestTransactions(limit, offset) (api docs) - List all recent transactions
• transaction(transactionID) (api docs) - Get information about a single transaction
• makeTransaction(privatekey, to, amount, metadata) (api docs) - Make a transaction

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. 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.