# 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 (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)
(opens new window) (api docs (opens new window)) - Gets information about an address, such as its balanceaddressTransactions(address, limit, offset)
(opens new window) (api docs (opens new window)) - Gets recent transactions by an addressaddressNames(address)
(opens new window) (api docs (opens new window)) - Gets names owned by an addressaddresses(limit, offset)
(opens new window) (api docs (opens new window)) - List all addressesrich(limit, offset)
(opens new window) (api docs (opens new window)) - List the addresses with the highest balancetransactions(limit, offset)
(opens new window) (api docs (opens new window)) - List all transactionslatestTransactions(limit, offset)
(opens new window) (api docs (opens new window)) - List all recent transactionstransaction(transactionID)
(opens new window) (api docs (opens new window)) - Get information about a single transactionmakeTransaction(privatekey, to, amount, metadata)
(opens new window) (api docs (opens new window)) - 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 (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.