Callers

Typed async functions that query contract read endpoints and return Result<T, QubicRpcError> — they never throw.

Callers are generated async functions for calling contract read (query) functions. They handle payload encoding, RPC dispatch, and response decoding internally. Failures come back as { ok: false, error } — callers never throw.

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

const live = createLiveClient()

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

if (result.ok) {
  console.log("State:", result.value.state)
} else {
  console.error("RPC error:", result.error.status, result.error.message)
}

Naming convention

{contractName}{FunctionName}(live, input?, options?)

Via namespace (recommended):

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

Or via named export:

import { qearnGetStateOfRound } from "@qubic.org/contracts"
await qearnGetStateOfRound(live, { epoch: 213 })

Parameters

Name	Type	Description
`live`	`SmartContractCaller`	Any object with `querySmartContract`. Typically `createLiveClient()` from `@qubic.org/rpc`.
`input`	object	Input fields for the function. Omit or pass `undefined` for zero-input functions.
`options`	`ContractCallOptions`	Converters for identity-encoding. Required when input or output has `id`-type fields.
`options.identityToPublicKey`	`(id: string) => Uint8Array`	Converts a 60-char identity string to 32 raw bytes.
`options.publicKeyToIdentity`	`(pk: Uint8Array) => string`	Converts 32 raw bytes to a 60-char identity string.

Import converters from @qubic.org/crypto:

import { identityToPublicKey, publicKeyToIdentity } from "@qubic.org/crypto"
const converters = { identityToPublicKey, publicKeyToIdentity }

Return type

All callers return Promise<Result<Output, QubicRpcError>>.

type Result<T, E> =
  | { ok: true; value: T }
  | { ok: false; error: E }

Error handling

Check result.ok before accessing result.value. Never assume success:

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

if (!result.ok) {
  if (result.error.status === 404) {
    console.log("No lock found for this user and epoch")
  } else {
    // Re-throw or surface to the user
    throw result.error
  }
  return
}

console.log("Locked amount:", result.value.lockedAmount.toString())

QubicRpcError has two useful fields:

status: number — HTTP-like status code (404, 500, etc.)
message: string — Human-readable description

Converters and tree-shaking

Converters are injected as options rather than imported internally. This keeps @qubic.org/contracts from bundling @qubic.org/crypto in environments that don't need it. Share one converters object across all calls:

import { identityToPublicKey, publicKeyToIdentity } from "@qubic.org/crypto"

const converters = { identityToPublicKey, publicKeyToIdentity }

const [roundState, lockedInfo] = await Promise.all([
  qearn.getStateOfRound(live, { epoch: 213 }, converters),
  qearn.getUserLockedInfo(live, { user: identity, epoch: 213 }, converters),
])

Qearn callers reference

// Round state for an epoch (no id fields — no converters needed)
await qearn.getStateOfRound(live, { epoch: 213 })

// Lock info totals for an epoch
await qearn.getLockInfoPerEpoch(live, { Epoch: 213 })

// A specific user's locked amount
await qearn.getUserLockedInfo(live, { user: identity, epoch: 213 }, converters)

// All epoch bitmask for a user
await qearn.getUserLockStatus(live, { user: identity }, converters)

// Post-epoch unlock summary
await qearn.getEndedStatus(live, { user: identity }, converters)

// Epoch-level statistics
await qearn.getStatsPerEpoch(live, { epoch: 213 })

// Lifetime burn/boost stats
await qearn.getBurnedAndBoostedStats(live)

// Per-epoch burn/boost stats
await qearn.getBurnedAndBoostedStatsPerEpoch(live, { epoch: 213 })