@qubic.org/contracts

Generated typed wrappers for every deployed Qubic smart contract. Zero manual payload construction required.

The wrappers in this package are output from a code generator that reads the latest @qubic.org/registry snapshot and produces typed functions for every contract, procedure, and read function. When a new epoch ships a changed ABI, the SDK maintainers run the generator and publish an updated version.

Three things per procedure/function

For each contract operation you get:

Builder — encodes a JS object to binary: buildQearnLockInput({ amount })
Decoder — decodes binary response bytes to a typed object: decodeQearnLockOutput(bytes)
Caller (read functions only) — calls the RPC gateway and returns Result<T, QubicRpcError>: qearnGetStateOfRound(live, input, converters)

Namespace pattern

Every contract is also exported as a namespace object that groups all three:

import { qearn } from "@qubic.org/contracts"

qearn.contractIndex          // 9
qearn.buildLockInput(...)    // payload builder
qearn.decodeLockOutput(...)  // output decoder
qearn.getStateOfRound(...)   // live read caller

Error model

Read callers — return Promise<Result<T, QubicRpcError>>. Never throw.
Builders — throw PayloadBuildError synchronously on bad input.
Decoders — throw PayloadDecodeError on malformed bytes.

Installation

bun add @qubic.org/contracts

npm install @qubic.org/contracts

pnpm add @qubic.org/contracts

API reference

Page	What's covered
Namespace	Per-contract namespace objects — `qearn`, `qx`, `qvault`, etc.
Builders	`build{Contract}{Procedure}Input` — encode inputs to binary
Decoders	`decode{Contract}{Procedure}Output` — decode response bytes
Callers	`{contract}{Function}` — typed live read functions
callContractFunction	Low-level primitive for unlisted contracts

Supported contracts

Index	Name	Address	Procedures	Functions
1	Qx	BAAAAAAA…RMID	7	5
2	Quottery	CAAAAAAA…CNKL	17	8
3	Random	DAAAAAAA…NMIG	1	0
4	QUtil	EAAAAAAA…VWRF	13	9
5	MyLastMatch	FAAAAAAA…YWJB	0	0
6	GeneralQuorumProposal	GAAAAAAA…QGNM	2	5
7	SupplyWatcher	HAAAAAAA…HYCM	0	0
8	ComputorControlledFund	IAAAAAAA…BXSH	2	7
9	Qearn	JAAAAAAA…VKHO	2	8
10	QVAULT	KAAAAAAA…XIUO	12	20
11	MsVault	LAAAAAAA…KPTJ	9	16
12	Qbay	MAAAAAAA…WLWD	17	9
13	Qswap	NAAAAAAA…MAML	11	8
14	Nostromo	OAAAAAAA…ZTPD	9	10
15	Qdraw	PAAAAAAA…YVRC	1	2
16	RandomLottery	QAAAAAAA…PIYE	3	10
17	QBond	RAAAAAAA…DKAH	8	8
18	QIP	SAAAAAAA…ABNI	3	1
19	QRaffle	TAAAAAAA…XRFC	8	9
20	qRWA	UAAAAAAA…HQEE	6	14
21	QReservePool	VAAAAAAA…ILLJ	4	2
22	QThirtyFour	WAAAAAAA…VDQA	8	11
23	QDuel	XAAAAAAA…XNMD	7	6
24	Pulse	YAAAAAAA…MSME	13	14
25	VottunBridge	ZAAAAAAA…ZUQI	8	7
26	Qusino	ABAAAAAA…YYHH	8	5
27	Escrow	BBAAAAAA…XPZM	5	2
27 contracts active · registry last updated May 16, 2026

Examples

Read a contract function

import { qearn } from "@qubic.org/contracts"
import { createLiveClient } from "@qubic.org/rpc"
import { identityToPublicKey, publicKeyToIdentity } from "@qubic.org/crypto"

const live = createLiveClient()
const converters = { identityToPublicKey, publicKeyToIdentity }

const result = await qearn.getStateOfRound(live, { epoch: 213 }, converters)

if (!result.ok) {
  console.error("RPC error:", result.error.status, result.error.message)
  process.exit(1)
}
console.log("Round state:", result.value)

Build a smart contract transaction

import { qearn } from "@qubic.org/contracts"
import { createWallet, generateSeed } from "@qubic.org/wallet"
import { createLiveClient } from "@qubic.org/rpc"
import { toIdentity } from "@qubic.org/types"

const live   = createLiveClient()
const wallet = createWallet(generateSeed())
const { tick } = await live.getTickInfo()

const payload     = qearn.buildLockInput({ amount: 10_000_000n })
const destination = toIdentity("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA")

const { encoded, hash } = await wallet.buildScTransaction({
  destination,
  amount: 10_000_000n,
  targetTick: tick + 5,
  currentTick: tick,
  inputType: qearn.LOCK_INPUT_TYPE,
  payload,
})

const result = await live.broadcastTransaction(encoded)
console.log(`TX ${hash} broadcast to ${result.peersBroadcastedTo} peers`)

Decode historical output from archive

import { decodeQearnLockOutput } from "@qubic.org/contracts"
import { publicKeyToIdentity } from "@qubic.org/crypto"
import { createQueryClient } from "@qubic.org/rpc"
import { toTxHash } from "@qubic.org/types"

const archive = createQueryClient()
const tx = await archive.getTransaction(toTxHash("abcdef..."))

const output = decodeQearnLockOutput(
  Buffer.from(tx.responseData ?? "", "base64"),
  publicKeyToIdentity,
)
console.log("Lock output:", output)