Programmatic transactions (`demos.run`)

Every DEMOS transaction has historically been a three-step dance:

const tx           = await demos.pay(to, amount)   // build + sign
const validityData = await demos.confirm(tx)       // gas / validity check
const res          = await demos.broadcast(validityData)

The programmatic transaction system collapses that into a single call per transaction type. One method fills its parameters from arguments and routes through a single shared runner that handles confirm → broadcast for you, auto-broadcasting within a configurable fee ceiling (default 5 DEM).

// same payment, one call, auto-broadcast within the 5 DEM fee cap
const res = await demos.run.pay(to, amount)

All programmatic methods live under demos.run.*. The classic demos.pay / demos.confirm / demos.broadcast methods are unchanged — demos.run is an additive facade, so nothing breaks.

Prefer this API for scripts and automation where you want one call per action. The step-by-step flow documented in Creating, Signing and Broadcasting remains fully supported and is the right choice when you need to inspect or gate each stage yourself.

Setup

import { Demos } from "@kynesyslabs/demosdk/websdk"

// one-call bootstrap (node + wallet), ready for demos.run.*
const demos = await Demos.start("https://node2.demos.sh", mnemonic)

// …equivalent to the classic two-step setup, which still works:
// const demos = Demos.instance
// await demos.connect("https://node2.demos.sh")
// await demos.connectWallet(mnemonic)

Demos.start(rpc, wallet?, walletOptions?) returns the connected instance; omit wallet to connect read-only.

The uniform result

Every demos.run.* method (except attest.dahr, see below) resolves to a ProgrammaticTxResult:

interface ProgrammaticTxResult {
    broadcasted: boolean          // did it hit the network?
    skippedReason?: "manual" | "rejected"
    transaction: Transaction      // the signed, confirmed tx
    hash: string                  // tx hash
    validityData: RPCResponseWithValidityData
    broadcast?: RPCResponse       // present when broadcasted === true
    feeOs: bigint                 // total fee in OS (smallest unit)
    feeDem: string                // total fee, human-readable DEM
}

The fee ceiling (`maxFee`)

In the default "auto" mode the runner broadcasts only if the confirmed fee is within maxFee (DEM, default 5). If it is exceeded, the tx is signed and confirmed but NOT broadcast, and the runner throws FeeCapExceededError carrying the fee details — a loud safety net against surprise fees.

import { FeeCapExceededError } from "@kynesyslabs/demosdk/websdk"

try {
    await demos.run.pay(to, amount)                 // cap = 5 DEM
} catch (e) {
    if (e instanceof FeeCapExceededError) {
        console.log(`fee was ${e.info.feeDem} DEM, over the cap`)
    }
}

// raise the ceiling for this call:
await demos.run.pay(to, amount, { maxFee: 25 })

// disable the ceiling entirely:
await demos.run.pay(to, amount, { maxFee: null })

Confirmation strategies (`confirm`)

// 1. auto (default): broadcast within maxFee
await demos.run.pay(to, amount)

// 2. manual: build + sign + confirm only, broadcast yourself later
const r = await demos.run.pay(to, amount, { confirm: "manual" })
console.log("would cost", r.feeDem, "DEM")
await demos.broadcast(r.validityData)

// 3. callback: decide per-transaction from the fee/validity snapshot
await demos.run.pay(to, amount, {
    confirm: (info) => {
        console.log(`about to pay ${info.feeDem} DEM in fees`)
        return info.withinFeeCap            // return true to broadcast
    },
})

In callback mode the callback is the sole authority — maxFee is not auto-enforced. Use info.withinFeeCap inside the callback if you still want to respect the ceiling.

Waiting for inclusion (`wait`)

// return only once the tx lands on-chain (or fails / times out)
const r = await demos.run.pay(to, amount, {
    wait: true,
    waitOptions: { timeoutMs: 30_000, pollIntervalMs: 500 },
})

Nonce management

When sending a single transaction using a Demos client, the nonce for that transaction is read from the network and incremented by 1 to match what’s expected on-chain. When broadcasting batch transactions, calling Demos transaction methods at the same time to create multiple transactions will result in multiple transactions having the same nonce. This means that only one of them will be executed while all the rest will fail.

import { denomination } from "@kynesyslabs/demosdk"

// only one of these is executed
// the rest are rejected
await Promise.all([
    demos.run.pay(alice, denomination.demToOs(1)),
    demos.run.pay(bob, denomination.demToOs(2)),
    demos.run.pay(carol, denomination.demToOs(3)),
])

To fix this, we need to assign increasing nonces for each transaction, in the order we want them to be executed.

Auto-nonce

The Demos client has an opt-in built-in auto-nonce tracking feature. You can enable it as shown below:

const demos = await Demos.start("https://node2.demos.sh", mnemonic)
demos.enableAutoNonce()

await Promise.all([
    demos.run.pay(alice, denomination.demToOs(1)), // nonce == N+1
    demos.run.pay(bob, denomination.demToOs(2)), // nonce == N+2
    demos.run.pay(carol, denomination.demToOs(3)), // nonce == N+3
])

All the transactions get incrementing nonces and they will all be executed, even if they are not broadcasted in order.

The nonce for the connected wallet will only be tracked locally on that Demos instance. If you create a new instance, you’ll need to enable it again.

Auto-nonce applies to every transaction builder on the instance — demos.run.*, the classic demos.pay / demos.transfer, storage, escrow, tokens, and so on. You can inspect or switch it off at any time:

demos.autoNonceEnabled    // boolean
demos.disableAutoNonce()  // switch off and clear counters

If the same key signs from another device or process, or a reserved transaction never lands on-chain, the counter drifts from the chain. You can recover as shown below:

try {
    await demos.run.pay(to, amount)
} catch (e) {
    // after a nonce rejection, reseed and retry
    demos.resetNonce(demos.getAddress())
    await demos.run.pay(to, amount)
}

Reconnecting to a different node resets all counters automatically.

Explicit nonces

Every demos.run.* method (and the classic builders) accepts a nonce option. You can track the nonce manually and override any internally calculated nonce as shown:

// current nonce
const base = await demos.getAddressNonce(demos.getAddress())

await demos.run.pay(alice, amount, { nonce: base + 1 })
await demos.run.pay(bob, amount, { nonce: base + 2 })
await demos.run.pay(carol, amount, { nonce: base + 3 })

Namespaces

`demos.run.pay` / `demos.run.transfer`

Native value transfers. Amount is a DEM number (legacy) or OS bigint (preferred). See Amounts & Denominations for how the two formats are handled.

import { denomination } from "@kynesyslabs/demosdk"
await demos.run.pay("0x...", denomination.demToOs(100))   // 100 DEM
await demos.run.transfer("0x...", 1_500_000_000n)          // 1.5 DEM in OS

`demos.run.attest.*`

Identity attestations. Each returns a ProgrammaticTxResult.

await demos.run.attest.github(gistProofUrl)
await demos.run.attest.twitter(tweetProofUrl)
await demos.run.attest.discord(messageProofUrl)
await demos.run.attest.telegram(signedAttestation)
await demos.run.attest.domain("example.com")
await demos.run.attest.removeWeb2({ context: "github", username: "alice" })

`demos.run.attest.dahr` — the exception

DAHR (Demos Attestation Hash Response) is a web2 proxy attestation: the node performs the HTTP request and its confirm/broadcast lifecycle happens server-side. So dahr does not go through the fee-cap runner and returns the web2 result directly (not a ProgrammaticTxResult); maxFee / confirm options do not apply.

const result = await demos.run.attest.dahr({
    url: "https://api.example.com/data",
    method: "GET",
})

`demos.run.tokens.*`

Token creation and execution.

await demos.run.tokens.create({ /* TokenCreationParams */ })
await demos.run.tokens.transfer(tokenAddress, to, "1000000000")
await demos.run.tokens.approve(tokenAddress, spender, "1000000000")
await demos.run.tokens.mint(tokenAddress, to, "1000000000")
await demos.run.tokens.burn(tokenAddress, from, "1000000000")

Coverage & caveats

demos.run.* namespaces: pay / transfer, attest.* (web2 + web3/xm + pqc + ud + nomis + humanpassport + ethos + tlsn + dahr), tokens.*, storage.* (store, program), escrow.*, validator.*, governance.*, xm.submit, bridge.submit, demoswork.submit, ipfs.*, d402.pay.

Live-verified against a node: pay / transfer, storage.store, storage.program, plus the fee-cap / confirm-mode behaviour.
ipfs.*, d402.pay and contracts.* are wired and type-checked but the underlying operations are not enabled on production nodes yet — they cannot be exercised end-to-end until the network turns them on.
contracts.* (deploy / call / deployTemplate / …) is RPC-native and NOT fee-capped: it bypasses the confirm → broadcast runner and returns the contract’s own result types (ContractInstance, ContractCallResult, gas bigint), not a ProgrammaticTxResult. It lives under demos.run.contracts for a uniform surface, but maxFee / confirm / wait do not apply there.
xm.submit takes an already-assembled XMScript; building that script (per-chain signed payloads) stays with the caller.

Design note

Under the hood a single runner (runProgrammaticTx) is the only place that calls confirm / broadcast. Each typed method just builds and signs its transaction and hands it to the runner, which normalises the three historical builder shapes (returns-signed-tx, returns-validityData, server-internal lifecycle) into one confirmation policy and one result type. This is the “common element” that makes demos.run.pay(addr) and demos.run.attest.dahr(params) feel the same despite very different underlying operations.

Getting Started

WebSDK

Cross Chain

Utilities

Storage Programs

Code Examples

Web2 Integration

Bridges

Advanced

Wallet Integration

Programmatic Transactions

Programmatic transactions (`demos.run`)

Setup

The uniform result

The fee ceiling (`maxFee`)

Confirmation strategies (`confirm`)

Waiting for inclusion (`wait`)

Nonce management

Auto-nonce

Explicit nonces

Namespaces

`demos.run.pay` / `demos.run.transfer`

`demos.run.attest.*`

`demos.run.attest.dahr` — the exception

`demos.run.tokens.*`

Coverage & caveats

Design note

​Programmatic transactions (demos.run)

​Setup

​The uniform result

​The fee ceiling (maxFee)

​Confirmation strategies (confirm)

​Waiting for inclusion (wait)

​Nonce management

​Auto-nonce

​Explicit nonces

​Namespaces

​demos.run.pay / demos.run.transfer

​demos.run.attest.*

​demos.run.attest.dahr — the exception

​demos.run.tokens.*

​Coverage & caveats

​Design note

Programmatic transactions (`demos.run`)

Setup

The uniform result

The fee ceiling (`maxFee`)

Confirmation strategies (`confirm`)

Waiting for inclusion (`wait`)

Nonce management

Auto-nonce

Explicit nonces

Namespaces

`demos.run.pay` / `demos.run.transfer`

`demos.run.attest.*`

`demos.run.attest.dahr` — the exception

`demos.run.tokens.*`

Coverage & caveats

Design note