Builders

build{Contract}{Procedure}Input — encode procedure inputs into binary transaction payloads.

Builders serialize a JavaScript object into the binary format expected by a smart contract procedure. The result is either a raw Uint8Array (for function payloads) or a ContractCall object that bundles the contract index, input type, and payload together.

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

const call = buildQearnUnlockInput({ amount: 10_000_000n, lockedEpoch: 213 })
// → { contractIndex: 9, inputType: 2, payload: Uint8Array }

Or via the namespace object:

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

const call = qearn.buildUnlockInput({ amount: 10_000_000n, lockedEpoch: 213 })

Naming convention

build{ContractName}{ProcedureName}Input(input, identityToPublicKey?)

The identityToPublicKey argument is required only when the input contains id-type fields (Qubic identities). It's injected rather than imported directly to keep the package tree-shakeable in environments without crypto.

import { buildQxTransferShareOwnershipAndPossessionInput } from "@qubic.org/contracts"
import { identityToPublicKey } from "@qubic.org/crypto"

const call = buildQxTransferShareOwnershipAndPossessionInput(
  { issuer, newOwnerAndPossessor, assetName, numberOfShares },
  identityToPublicKey,
)

Using the payload

Pass the builder result to wallet.buildScTransaction:

const call = qearn.buildUnlockInput({ amount: 10_000_000n, lockedEpoch: 213 })

const { encoded } = await wallet.buildScTransaction({
  destination: QEARN_CONTRACT_ADDRESS,
  amount: 0n,
  targetTick: tick + 5,
  currentTick: tick,
  inputType: call.inputType,
  payload: call.payload,
})

Field type mapping

ABI type	JavaScript type
`uint8` / `uint16` / `uint32` / `sint8` / `sint32`	`number`
`uint64` / `sint64` / `uint128`	`bigint`
`id`	`string` (Qubic identity, 60 chars)
`bytes`	`Uint8Array`
`array`	`T[]` where T matches the element type
`struct`	Object with nested fields

Error handling

Builders throw PayloadBuildError synchronously when the input is invalid. This is a programming error — not a network failure.

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

try {
  buildQearnUnlockInput({ amount: -1n, lockedEpoch: 213 })
} catch (e) {
  if (e instanceof PayloadBuildError) {
    console.error("Build error:", e.message)
    // e.field — which field failed
    // e.value — the bad value
  }
}

Three categories of build errors:

Category	Example	Cause
Wrong JS type	Passing `number` for a `uint64` field	Field expects `bigint`
Value out of range	`-1n` for `uint64`	Unsigned types must be non-negative
Missing required field	Omitting `lockedEpoch` from an unlock input	Required field absent from the input object

Constants

Each procedure has a corresponding INPUT_TYPE constant. Use it to set the transaction's input type field:

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

// or via namespace:
import { qearn } from "@qubic.org/contracts"
qearn.contractIndex  // 9

These match the values in ContractCall.inputType returned by builder functions.