Namespace

Per-contract namespace objects that group constants, builders, and callers under one identifier.

Each contract ships as a namespace object that groups every artifact under one import. The namespace name is the lowercase contract name.

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

// Constants
qearn.contractIndex           // 9

// Builders — encode inputs into binary
const payload = qearn.buildUnlockInput({ amount: 10_000_000n, lockedEpoch: 213 })

// Decoders — decode raw output bytes
const output = qearn.decodeUnlockOutput(rawBytes)

// Callers — live read functions, return Result<T, QubicRpcError>
const result = await qearn.getStateOfRound(live, { epoch: 213 })

The three artifact types map directly to the three contract operation patterns:

Artifact	Used for	How
Constants	Identifying contract and input types in transaction headers	`qearn.contractIndex`, `QEARN_LOCK_INPUT_TYPE`
Builders	Write operations (transactions)	Build a payload, pass it + the constant to your wallet
Callers	Read operations	Call directly with the `live` client, get back `Result<T>`

Available namespaces

Export	Contract	Index
`random`	Random	0
`qx`	Qx	1
`quottery`	Quottery	2
`qutil`	QUtil	5
`supplyWatcher`	SupplyWatcher	—
`computorControlledFund`	ComputorControlledFund	—
`qearn`	Qearn	9
`qVAULT`	QVault	10
`msVault`	MsVault	11
`qbay`	Qbay	12
`qswap`	Qswap	—
`nostromo`	Nostromo	—
`qdraw`	Qdraw	—
`randomLottery`	RandomLottery	—
`qbond`	QBond	—
`qip`	QIP	—
`qraffle`	QRaffle	—
`qrwa`	qRWA	—
`qreservePool`	QReservePool	—
`qthirtyFour`	QThirtyFour	—
`qduel`	QDuel	—
`pulse`	Pulse	—
`vottunBridge`	VottunBridge	—
`qusino`	Qusino	—
`escrow`	Escrow	—
`generalQuorumProposal`	GeneralQuorumProposal	—
`myLastMatch`	MyLastMatch	—

Namespace members

Constants

Every procedure has a corresponding INPUT_TYPE constant on the namespace:

qearn.contractIndex       // 9  — use in the transaction destination logic
// LOCK has no input fields — no builder constant needed
// UNLOCK input type is 2

Constants can also be imported directly:

import { QEARN_CONTRACT_INDEX, QEARN_UNLOCK_INPUT_TYPE } from "@qubic.org/contracts"

Builders

Builders encode a JavaScript object into a binary payload ready to attach to a transaction:

qearn.buildUnlockInput({ amount: 10_000_000n, lockedEpoch: 213 })
// → ContractCall { contractIndex: 9, inputType: 2, payload: Uint8Array }

Not every procedure has a builder. When there are no input fields (like Qearn's Lock), the payload is empty and only the transaction amount and input type are needed.

See Builders for input type mapping and error handling.

Decoders

Decoders parse raw response bytes from a transaction receipt into a typed object:

qearn.decodeLockOutput(rawBytes)
qearn.decodeUnlockOutput(rawBytes)

See Decoders for details.

Callers

Callers call contract read functions directly and return Promise<Result<T, QubicRpcError>>:

await qearn.getStateOfRound(live, { epoch: 213 })
await qearn.getUserLockedInfo(live, { user: identity, epoch: 213 }, { identityToPublicKey })

See Callers for the full error-handling pattern.

End-to-end example

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

const live = createLiveClient()

// Read current epoch state
const state = await qearn.getStateOfRound(live, { epoch: 213 })
if (!state.ok) throw new Error(state.error.message)
console.log("Round state:", state.value.state)

// Check user's existing locks
const lockStatus = await qearn.getUserLockStatus(
  live,
  { user: "YOUR_IDENTITY" },
  { identityToPublicKey },
)
if (lockStatus.ok) {
  console.log("Lock bitmask:", lockStatus.value.status.toString(2))
}

// Lock has no payload — amount is passed in the transaction amount field

// wallet.buildScTransaction({
//   destination: QEARN_CONTRACT_ADDRESS,
//   amount: 10_000_000n,           // the lock amount
//   targetTick: currentTick + 5,
//   inputType: QEARN_LOCK_INPUT_TYPE,
//   payload: new Uint8Array(0),    // no payload for lock
// })