@kynesyslabs/demosdk 4.0.12 → 4.0.14

package/build/websdk/programmatic/ipfs.d.ts

@@ -0,0 +1,74 @@
+import { type AddOptionsWithCharges, type PinOptionsWithCharges } from "../../ipfs";
+import type { ProgrammaticContext } from "./context";
+import type { ProgrammaticTxOptions, ProgrammaticTxResult } from "./types";
+/**
+ * IPFS operations as one-call programmatic transactions.
+ *
+ * Unlike `pay`/`store`/`storagePrograms`, there is no single Demos builder
+ * that returns a signed `ipfs` transaction: the payloads come from
+ * {@link IPFSOperations}' static creators (`createAddPayload`,
+ * `createPinPayload`, `createUnpinPayload`) and the caller must assemble the
+ * transaction around them. This namespace does that assembly.
+ *
+ * Each method builds the payload, wraps it in an UNSIGNED `ipfs` transaction
+ * (nonce set exactly like `demos.storagePrograms.sign`), and hands a thunk
+ * producing it to `ctx.run(...)`. The shared runner signs it and confirms it
+ * against the fee ceiling before auto-broadcasting — keeping fee-cap policy,
+ * confirmation strategy and result shape uniform with the rest of
+ * `demos.run.*`.
+ *
+ * Cost control ("custom charges") is opt-in and stays simple: forward a
+ * `customCharges` block through `addOptions`/`pinOptions` (obtained from
+ * `IPFSOperations.quoteToCustomCharges(await demos.ipfs.quote(...))`). The
+ * payload creators embed it in the payload; this namespace additionally
+ * mirrors it onto `tx.content.custom_charges` so the node sees the ceiling
+ * the sender signed. No quote round-trip is performed here.
+ */
+export declare function createIpfsNamespace(ctx: ProgrammaticContext): {
+    /**
+     * Upload content to IPFS (and auto-pin it), end to end.
+     *
+     * @example
+     * ```ts
+     * // auto-broadcast within the 5 DEM fee cap:
+     * await demos.run.ipfs.add("hello world", { filename: "hello.txt" })
+     *
+     * // with a signed cost ceiling from a quote:
+     * const quote = await demos.ipfs.quote(bytes.length, "IPFS_ADD")
+     * await demos.run.ipfs.add(bytes, {
+     *     customCharges: IPFSOperations.quoteToCustomCharges(quote),
+     * })
+     * ```
+     *
+     * @param content - Content to upload (Buffer, Uint8Array or string).
+     * @param addOptions - Filename, metadata and optional custom charges.
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    add: (content: Buffer | Uint8Array | string, addOptions?: AddOptionsWithCharges, opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+    /**
+     * Pin an existing CID to the sender's account, end to end.
+     *
+     * @example
+     * ```ts
+     * await demos.run.ipfs.pin("QmExampleCID...")
+     * ```
+     *
+     * @param cid - The Content Identifier to pin (CIDv0 or CIDv1).
+     * @param pinOptions - Duration, metadata, `fileSize` and optional
+     *                     custom charges.
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    pin: (cid: string, pinOptions?: PinOptionsWithCharges, opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+    /**
+     * Remove a pin from the sender's account, end to end.
+     *
+     * @example
+     * ```ts
+     * await demos.run.ipfs.unpin("QmExampleCID...")
+     * ```
+     *
+     * @param cid - The Content Identifier to unpin (CIDv0 or CIDv1).
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    unpin: (cid: string, opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+};

package/build/websdk/programmatic/ipfs.js

@@ -0,0 +1,106 @@
+import { uint8ArrayToHex } from "../../encryption/unifiedCrypto.js";
+import { IPFSOperations, } from "../../ipfs/index.js";
+import { DemosTransactions } from "../DemosTransactions.js";
+import { resolveNonce } from "../../utils/index.js";
+/**
+ * IPFS operations as one-call programmatic transactions.
+ *
+ * Unlike `pay`/`store`/`storagePrograms`, there is no single Demos builder
+ * that returns a signed `ipfs` transaction: the payloads come from
+ * {@link IPFSOperations}' static creators (`createAddPayload`,
+ * `createPinPayload`, `createUnpinPayload`) and the caller must assemble the
+ * transaction around them. This namespace does that assembly.
+ *
+ * Each method builds the payload, wraps it in an UNSIGNED `ipfs` transaction
+ * (nonce set exactly like `demos.storagePrograms.sign`), and hands a thunk
+ * producing it to `ctx.run(...)`. The shared runner signs it and confirms it
+ * against the fee ceiling before auto-broadcasting — keeping fee-cap policy,
+ * confirmation strategy and result shape uniform with the rest of
+ * `demos.run.*`.
+ *
+ * Cost control ("custom charges") is opt-in and stays simple: forward a
+ * `customCharges` block through `addOptions`/`pinOptions` (obtained from
+ * `IPFSOperations.quoteToCustomCharges(await demos.ipfs.quote(...))`). The
+ * payload creators embed it in the payload; this namespace additionally
+ * mirrors it onto `tx.content.custom_charges` so the node sees the ceiling
+ * the sender signed. No quote round-trip is performed here.
+ */
+export function createIpfsNamespace(ctx) {
+    /**
+     * Assemble an UNSIGNED `ipfs` transaction around a ready IPFS payload.
+     *
+     * Replicates the nonce pattern from `demos.storagePrograms.sign`: read the
+     * sender's ed25519 public key, fetch its on-chain nonce and set
+     * `content.nonce = nonce + 1`. The transaction is returned unsigned; the
+     * shared runner signs it.
+     *
+     * @param payload - An IPFS payload from an `IPFSOperations.create*` method.
+     * @returns The unsigned `ipfs` transaction, ready for `ctx.run`.
+     */
+    const buildIpfsTx = async (payload, customNonce) => {
+        const nonce = await resolveNonce(customNonce, async () => {
+            const { publicKey } = await ctx.demos.crypto.getIdentity("ed25519");
+            return ctx.demos.getAddressNonce(uint8ArrayToHex(publicKey));
+        });
+        const tx = DemosTransactions.empty();
+        tx.content.type = "ipfs";
+        tx.content.nonce = nonce;
+        tx.content.data = ["ipfs", payload];
+        // Mirror the signed cost ceiling onto the transaction content when the
+        // payload carries one, so the node enforces the same `max_cost_os` the
+        // sender agreed to. `IPFSUnpinPayload` never has this field.
+        if ("custom_charges" in payload && payload.custom_charges) {
+            tx.content.custom_charges = payload.custom_charges;
+        }
+        return tx;
+    };
+    return {
+        /**
+         * Upload content to IPFS (and auto-pin it), end to end.
+         *
+         * @example
+         * ```ts
+         * // auto-broadcast within the 5 DEM fee cap:
+         * await demos.run.ipfs.add("hello world", { filename: "hello.txt" })
+         *
+         * // with a signed cost ceiling from a quote:
+         * const quote = await demos.ipfs.quote(bytes.length, "IPFS_ADD")
+         * await demos.run.ipfs.add(bytes, {
+         *     customCharges: IPFSOperations.quoteToCustomCharges(quote),
+         * })
+         * ```
+         *
+         * @param content - Content to upload (Buffer, Uint8Array or string).
+         * @param addOptions - Filename, metadata and optional custom charges.
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        add: (content, addOptions, opts) => ctx.run(() => buildIpfsTx(IPFSOperations.createAddPayload(content, addOptions), opts?.nonce), opts),
+        /**
+         * Pin an existing CID to the sender's account, end to end.
+         *
+         * @example
+         * ```ts
+         * await demos.run.ipfs.pin("QmExampleCID...")
+         * ```
+         *
+         * @param cid - The Content Identifier to pin (CIDv0 or CIDv1).
+         * @param pinOptions - Duration, metadata, `fileSize` and optional
+         *                     custom charges.
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        pin: (cid, pinOptions, opts) => ctx.run(() => buildIpfsTx(IPFSOperations.createPinPayload(cid, pinOptions), opts?.nonce), opts),
+        /**
+         * Remove a pin from the sender's account, end to end.
+         *
+         * @example
+         * ```ts
+         * await demos.run.ipfs.unpin("QmExampleCID...")
+         * ```
+         *
+         * @param cid - The Content Identifier to unpin (CIDv0 or CIDv1).
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        unpin: (cid, opts) => ctx.run(() => buildIpfsTx(IPFSOperations.createUnpinPayload(cid), opts?.nonce), opts),
+    };
+}
+//# sourceMappingURL=ipfs.js.map

package/build/websdk/programmatic/ipfs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipfs.js","sourceRoot":"","sources":["../../../../src/websdk/programmatic/ipfs.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAC5D,OAAO,EACH,cAAc,GAIjB,MAAM,QAAQ,CAAA;AACf,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAGxD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAEtC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAwB;IACxD;;;;;;;;;;OAUG;IACH,MAAM,WAAW,GAAG,KAAK,EACrB,OAAoB,EACpB,WAAoB,EACA,EAAE;QACtB,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,WAAW,EAAE,KAAK,IAAI,EAAE;YACrD,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,CAAA;YACnE,OAAO,GAAG,CAAC,KAAK,CAAC,eAAe,CAC5B,eAAe,CAAC,SAAuB,CAAC,CAC3C,CAAA;QACL,CAAC,CAAC,CAAA;QAEF,MAAM,EAAE,GAAG,iBAAiB,CAAC,KAAK,EAAE,CAAA;QACpC,EAAE,CAAC,OAAO,CAAC,IAAI,GAAG,MAAM,CAAA;QACxB,EAAE,CAAC,OAAO,CAAC,KAAK,GAAG,KAAK,CAAA;QACxB,EAAE,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAEnC,uEAAuE;QACvE,uEAAuE;QACvE,6DAA6D;QAC7D,IAAI,gBAAgB,IAAI,OAAO,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;YACxD,EAAE,CAAC,OAAO,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAA;QACtD,CAAC;QAED,OAAO,EAAE,CAAA;IACb,CAAC,CAAA;IAED,OAAO;QACH;;;;;;;;;;;;;;;;;;WAkBG;QACH,GAAG,EAAE,CACD,OAAqC,EACrC,UAAkC,EAClC,IAA4B,EACC,EAAE,CAC/B,GAAG,CAAC,GAAG,CACH,GAAG,EAAE,CACD,WAAW,CACP,cAAc,CAAC,gBAAgB,CAAC,OAAO,EAAE,UAAU,CAAC,EACpD,IAAI,EAAE,KAAK,CACd,EACL,IAAI,CACP;QAEL;;;;;;;;;;;;WAYG;QACH,GAAG,EAAE,CACD,GAAW,EACX,UAAkC,EAClC,IAA4B,EACC,EAAE,CAC/B,GAAG,CAAC,GAAG,CACH,GAAG,EAAE,CACD,WAAW,CACP,cAAc,CAAC,gBAAgB,CAAC,GAAG,EAAE,UAAU,CAAC,EAChD,IAAI,EAAE,KAAK,CACd,EACL,IAAI,CACP;QAEL;;;;;;;;;;WAUG;QACH,KAAK,EAAE,CACH,GAAW,EACX,IAA4B,EACC,EAAE,CAC/B,GAAG,CAAC,GAAG,CACH,GAAG,EAAE,CAAC,WAAW,CAAC,cAAc,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,EACtE,IAAI,CACP;KACR,CAAA;AACL,CAAC"}

package/build/websdk/programmatic/pay.d.ts

@@ -0,0 +1,36 @@
+import type { ProgrammaticContext } from "./context";
+import type { ProgrammaticTxOptions, ProgrammaticTxResult } from "./types";
+/**
+ * Native-value transfers as one-call programmatic transactions.
+ *
+ * Collapses the classic `pay → confirm → broadcast` flow into a single call
+ * that auto-broadcasts within the configured fee ceiling.
+ */
+export declare function createPayNamespace(ctx: ProgrammaticContext): {
+    /**
+     * Send native DEMOS tokens to an address, end to end.
+     *
+     * @example
+     * ```ts
+     * import { denomination } from "@kynesyslabs/demosdk"
+     * // auto-broadcast within the 5 DEM fee cap:
+     * await demos.run.pay("0x...", denomination.demToOs(100))
+     * // build + confirm only, broadcast later yourself:
+     * const r = await demos.run.pay("0x...", 100n, { confirm: "manual" })
+     * await demos.broadcast(r.validityData)
+     * ```
+     *
+     * @param to - Receiver address (0x-prefixed hex).
+     * @param amount - DEM `number` (legacy) or OS `bigint` (preferred).
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    pay: (to: string, amount: number | bigint, opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+    /**
+     * Alias of {@link pay}. Same dual-input amount semantics.
+     *
+     * @param to - Receiver address (0x-prefixed hex).
+     * @param amount - DEM `number` (legacy) or OS `bigint` (preferred).
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    transfer: (to: string, amount: number | bigint, opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+};

package/build/websdk/programmatic/pay.js

@@ -0,0 +1,37 @@
+/**
+ * Native-value transfers as one-call programmatic transactions.
+ *
+ * Collapses the classic `pay → confirm → broadcast` flow into a single call
+ * that auto-broadcasts within the configured fee ceiling.
+ */
+export function createPayNamespace(ctx) {
+    return {
+        /**
+         * Send native DEMOS tokens to an address, end to end.
+         *
+         * @example
+         * ```ts
+         * import { denomination } from "@kynesyslabs/demosdk"
+         * // auto-broadcast within the 5 DEM fee cap:
+         * await demos.run.pay("0x...", denomination.demToOs(100))
+         * // build + confirm only, broadcast later yourself:
+         * const r = await demos.run.pay("0x...", 100n, { confirm: "manual" })
+         * await demos.broadcast(r.validityData)
+         * ```
+         *
+         * @param to - Receiver address (0x-prefixed hex).
+         * @param amount - DEM `number` (legacy) or OS `bigint` (preferred).
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        pay: (to, amount, opts) => ctx.run(() => ctx.demos.pay(to, amount, { nonce: opts?.nonce }), opts),
+        /**
+         * Alias of {@link pay}. Same dual-input amount semantics.
+         *
+         * @param to - Receiver address (0x-prefixed hex).
+         * @param amount - DEM `number` (legacy) or OS `bigint` (preferred).
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        transfer: (to, amount, opts) => ctx.run(() => ctx.demos.transfer(to, amount, { nonce: opts?.nonce }), opts),
+    };
+}
+//# sourceMappingURL=pay.js.map

package/build/websdk/programmatic/pay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pay.js","sourceRoot":"","sources":["../../../../src/websdk/programmatic/pay.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAwB;IACvD,OAAO;QACH;;;;;;;;;;;;;;;;WAgBG;QACH,GAAG,EAAE,CACD,EAAU,EACV,MAAuB,EACvB,IAA4B,EACC,EAAE,CAC/B,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC;QAE1E;;;;;;WAMG;QACH,QAAQ,EAAE,CACN,EAAU,EACV,MAAuB,EACvB,IAA4B,EACC,EAAE,CAC/B,GAAG,CAAC,GAAG,CACH,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAC5D,IAAI,CACP;KACR,CAAA;AACL,CAAC"}

package/build/websdk/programmatic/runner.d.ts

@@ -0,0 +1,30 @@
+import type { RPCResponseWithValidityData } from "../../types/communication/rpc";
+import type { Demos } from "../demosclass";
+import { type ProgrammaticTxOptions, type ProgrammaticTxResult, type TxSource } from "./types";
+/**
+ * Sum `network_fee + rpc_fee + additional_fee` into a single OS `bigint`.
+ *
+ * The fee is read from the node's confirm response. Two shapes are handled:
+ *  - `gas_operation.fees` — the node's authoritative gas operation, when the
+ *    node populates it (post-fork gas-separation model), preferred; else
+ *  - `transaction.content.transaction_fee` — the fee carried on the confirmed
+ *    transaction itself, which live nodes return with `gas_operation: null`.
+ *
+ * Returns `0n` when neither is present (fee not exposed at confirm time).
+ */
+export declare function totalFeeOs(validityData: RPCResponseWithValidityData): bigint;
+/**
+ * The shared programmatic-transaction runner — the single place where
+ * `confirm → (fee cap / callback) → broadcast` lives.
+ *
+ * Every typed one-call method (`demos.run.pay`, `demos.run.attest.*`,
+ * `demos.run.tokens.*`, …) builds/signs its transaction and hands it here,
+ * so confirmation policy and result shape are uniform across the SDK.
+ *
+ * @param demos - The connected Demos instance.
+ * @param source - A signed/unsigned tx, an already-confirmed validityData,
+ *                 or a thunk producing either.
+ * @param opts - Fee ceiling, confirmation strategy and wait behaviour.
+ * @returns A uniform {@link ProgrammaticTxResult}.
+ */
+export declare function runProgrammaticTx(demos: Demos, source: TxSource, opts?: ProgrammaticTxOptions): Promise<ProgrammaticTxResult>;

package/build/websdk/programmatic/runner.js

@@ -0,0 +1,188 @@
+import { demToOs, osToDem } from "../../denomination/index.js";
+import { FeeCapExceededError } from "./errors.js";
+import { DEFAULT_MAX_FEE_DEM, } from "./types.js";
+/**
+ * Normalise a single {@link TxFee} field to OS (`bigint`).
+ *
+ * Wire-format compatibility (see `TxFee` docs):
+ *  - pre-fork node: `number` in DEM,
+ *  - post-fork node: decimal `string` in OS.
+ *
+ * A defensive `"."`-in-string branch treats decimal strings as DEM so a
+ * mixed/legacy shape can never be misread as a huge OS integer.
+ */
+function feeFieldToOs(value) {
+    if (value == null)
+        return 0n;
+    try {
+        if (typeof value === "number")
+            return demToOs(value);
+        const s = value.trim();
+        if (s === "")
+            return 0n;
+        // Decimal string ⇒ DEM (human) shape; integer string ⇒ OS (wire) shape.
+        return s.includes(".") ? demToOs(s) : BigInt(s);
+    }
+    catch {
+        // The value comes from the node's confirm response — surface which
+        // field/shape failed instead of a bare BigInt/demToOs SyntaxError.
+        throw new Error(`[programmatic-tx] unparseable fee field ${JSON.stringify(value)} in the node's confirm response`);
+    }
+}
+/**
+ * Sum `network_fee + rpc_fee + additional_fee` into a single OS `bigint`.
+ *
+ * The fee is read from the node's confirm response. Two shapes are handled:
+ *  - `gas_operation.fees` — the node's authoritative gas operation, when the
+ *    node populates it (post-fork gas-separation model), preferred; else
+ *  - `transaction.content.transaction_fee` — the fee carried on the confirmed
+ *    transaction itself, which live nodes return with `gas_operation: null`.
+ *
+ * Returns `0n` when neither is present (fee not exposed at confirm time).
+ */
+export function totalFeeOs(validityData) {
+    const data = validityData?.response?.data;
+    const fees = (data?.gas_operation?.fees ??
+        data?.transaction?.content?.transaction_fee);
+    if (!fees)
+        return 0n;
+    return (feeFieldToOs(fees.network_fee) +
+        feeFieldToOs(fees.rpc_fee) +
+        feeFieldToOs(fees.additional_fee));
+}
+/**
+ * Resolve the configured fee ceiling to OS. Returns `null` when the cap is
+ * disabled — only `null` or `Infinity` disable it. `undefined` falls back to
+ * the default ceiling. Any other value (including `NaN` or a non-numeric
+ * string) is routed through `demToOs`, which throws loudly: silently
+ * disabling the cap on a `NaN` from `Number(userInput)` would remove the very
+ * safety this feature promises.
+ */
+function resolveCapOs(maxFee) {
+    if (maxFee === null)
+        return null;
+    if (maxFee === undefined)
+        return demToOs(DEFAULT_MAX_FEE_DEM);
+    if (maxFee === Infinity)
+        return null;
+    return demToOs(maxFee);
+}
+/** Distinguish an already-confirmed validity-data object from a Transaction. */
+function isValidityData(v) {
+    return (v != null &&
+        typeof v === "object" &&
+        "response" in v &&
+        v.response?.data != null);
+}
+/**
+ * Turn any {@link TxSource} into an `RPCResponseWithValidityData`:
+ *  - a thunk is invoked,
+ *  - an already-confirmed value is returned as-is (pattern B, e.g. the
+ *    `Identities.*` builders),
+ *  - a `Transaction` is signed if needed, then confirmed (pattern A).
+ */
+async function resolveToConfirmed(demos, source, customNonce) {
+    const resolved = typeof source === "function" ? await source() : source;
+    if (isValidityData(resolved)) {
+        return resolved;
+    }
+    const tx = resolved;
+    // A tx counts as signed only when its signature actually carries data.
+    // Some builders (e.g. DemosTokens) return an UNSIGNED tx with a truthy
+    // placeholder `signature: { type: "ed25519", data: "" }`, so a bare
+    // `tx.signature` truthiness check would wrongly skip signing and confirm
+    // an empty-signature tx. Gate on the signature payload instead.
+    const sig = tx.signature;
+    const isSigned = !!(sig && sig.data);
+    const signed = isSigned
+        ? tx
+        : await demos.sign(tx, customNonce !== undefined ? { nonce: customNonce } : undefined);
+    return await demos.confirm(signed);
+}
+/**
+ * The shared programmatic-transaction runner — the single place where
+ * `confirm → (fee cap / callback) → broadcast` lives.
+ *
+ * Every typed one-call method (`demos.run.pay`, `demos.run.attest.*`,
+ * `demos.run.tokens.*`, …) builds/signs its transaction and hands it here,
+ * so confirmation policy and result shape are uniform across the SDK.
+ *
+ * @param demos - The connected Demos instance.
+ * @param source - A signed/unsigned tx, an already-confirmed validityData,
+ *                 or a thunk producing either.
+ * @param opts - Fee ceiling, confirmation strategy and wait behaviour.
+ * @returns A uniform {@link ProgrammaticTxResult}.
+ */
+export async function runProgrammaticTx(demos, source, opts = {}) {
+    const validityData = await resolveToConfirmed(demos, source, opts.nonce);
+    const transaction = validityData.response.data.transaction;
+    // A successful confirm always echoes the transaction; guard so the
+    // non-optional `transaction`/`hash` on the result types stay truthful
+    // (rather than silently handing callers `undefined.hash`).
+    if (!transaction) {
+        throw new Error("[programmatic-tx] confirm response did not include a transaction");
+    }
+    const hash = transaction.hash;
+    const referenceBlock = validityData.response.data.reference_block;
+    const feeOs = totalFeeOs(validityData);
+    const feeDem = osToDem(feeOs);
+    const capOs = resolveCapOs(opts.maxFee);
+    const withinFeeCap = capOs === null || feeOs <= capOs;
+    const info = {
+        transaction,
+        validityData,
+        feeOs,
+        feeDem,
+        withinFeeCap,
+        referenceBlock,
+    };
+    const mode = opts.confirm ?? "auto";
+    // "manual": stop after confirm, hand back the validity data unbroadcast.
+    if (mode === "manual") {
+        return {
+            broadcasted: false,
+            skippedReason: "manual",
+            transaction,
+            hash,
+            validityData,
+            feeOs,
+            feeDem,
+        };
+    }
+    // Decide whether to broadcast.
+    let allowed;
+    if (typeof mode === "function") {
+        allowed = await mode(info);
+    }
+    else {
+        // "auto": enforce the fee ceiling loudly.
+        if (!withinFeeCap) {
+            throw new FeeCapExceededError(feeOs, capOs, info);
+        }
+        allowed = true;
+    }
+    if (!allowed) {
+        return {
+            broadcasted: false,
+            skippedReason: "rejected",
+            transaction,
+            hash,
+            validityData,
+            feeOs,
+            feeDem,
+        };
+    }
+    const broadcast = opts.wait
+        ? await demos.broadcastAndWait(validityData, opts.waitOptions)
+        : await demos.broadcast(validityData);
+    return {
+        broadcasted: true,
+        transaction,
+        hash,
+        validityData,
+        broadcast,
+        feeOs,
+        feeDem,
+    };
+}
+//# sourceMappingURL=runner.js.map

package/build/websdk/programmatic/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../../../src/websdk/programmatic/runner.ts"],"names":[],"mappings":"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"}

package/build/websdk/programmatic/storage.d.ts

@@ -0,0 +1,49 @@
+import type { StorageProgramPayload } from "../../storage";
+import type { ProgrammaticContext } from "./context";
+import type { ProgrammaticTxOptions, ProgrammaticTxResult } from "./types";
+/**
+ * On-chain storage as one-call programmatic transactions.
+ *
+ * Wraps {@link Demos.store} and {@link Demos.storagePrograms} so persisting
+ * binary data or signing a storage program collapses the classic
+ * `build/sign → confirm → broadcast` flow into a single call. Each builder
+ * here returns a SIGNED transaction; the method hands a thunk producing it
+ * to `ctx.run(...)`, which confirms against the fee ceiling and
+ * auto-broadcasts — keeping fee-cap policy, confirmation strategy and result
+ * shape uniform with the rest of `demos.run.*`.
+ */
+export declare function createStorageNamespace(ctx: ProgrammaticContext): {
+    /**
+     * Store binary data on the blockchain, end to end.
+     *
+     * @example
+     * ```ts
+     * const bytes = new TextEncoder().encode("hello world")
+     * // auto-broadcast within the 5 DEM fee cap:
+     * await demos.run.storage.store(bytes)
+     * // build + confirm only, broadcast later yourself:
+     * const r = await demos.run.storage.store(bytes, { confirm: "manual" })
+     * await demos.broadcast(r.validityData)
+     * ```
+     *
+     * @param bytes - The binary data to store in the sender's account.
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    store: (bytes: Uint8Array, opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+    /**
+     * Sign and submit a storage program, end to end.
+     *
+     * @example
+     * ```ts
+     * const r = await demos.run.storage.program({
+     *     storageAddress: "0x...",
+     *     // …program payload fields
+     * })
+     * ```
+     *
+     * @param payload - The storage program payload to sign (must carry a
+     *                   `storageAddress`).
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    program: (payload: StorageProgramPayload, opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+};

package/build/websdk/programmatic/storage.js

@@ -0,0 +1,51 @@
+/**
+ * On-chain storage as one-call programmatic transactions.
+ *
+ * Wraps {@link Demos.store} and {@link Demos.storagePrograms} so persisting
+ * binary data or signing a storage program collapses the classic
+ * `build/sign → confirm → broadcast` flow into a single call. Each builder
+ * here returns a SIGNED transaction; the method hands a thunk producing it
+ * to `ctx.run(...)`, which confirms against the fee ceiling and
+ * auto-broadcasts — keeping fee-cap policy, confirmation strategy and result
+ * shape uniform with the rest of `demos.run.*`.
+ */
+export function createStorageNamespace(ctx) {
+    return {
+        /**
+         * Store binary data on the blockchain, end to end.
+         *
+         * @example
+         * ```ts
+         * const bytes = new TextEncoder().encode("hello world")
+         * // auto-broadcast within the 5 DEM fee cap:
+         * await demos.run.storage.store(bytes)
+         * // build + confirm only, broadcast later yourself:
+         * const r = await demos.run.storage.store(bytes, { confirm: "manual" })
+         * await demos.broadcast(r.validityData)
+         * ```
+         *
+         * @param bytes - The binary data to store in the sender's account.
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        store: (bytes, opts) => ctx.run(() => ctx.demos.store(bytes, { nonce: opts?.nonce }), opts),
+        /**
+         * Sign and submit a storage program, end to end.
+         *
+         * @example
+         * ```ts
+         * const r = await demos.run.storage.program({
+         *     storageAddress: "0x...",
+         *     // …program payload fields
+         * })
+         * ```
+         *
+         * @param payload - The storage program payload to sign (must carry a
+         *                   `storageAddress`).
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        program: (payload, opts) => ctx.run(() => ctx.demos.storagePrograms.sign(payload, {
+            nonce: opts?.nonce,
+        }), opts),
+    };
+}
+//# sourceMappingURL=storage.js.map

package/build/websdk/programmatic/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../../../src/websdk/programmatic/storage.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAwB;IAC3D,OAAO;QACH;;;;;;;;;;;;;;;WAeG;QACH,KAAK,EAAE,CACH,KAAiB,EACjB,IAA4B,EACC,EAAE,CAC/B,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC;QAEvE;;;;;;;;;;;;;;WAcG;QACH,OAAO,EAAE,CACL,OAA8B,EAC9B,IAA4B,EACC,EAAE,CAC/B,GAAG,CAAC,GAAG,CACH,GAAG,EAAE,CACD,GAAG,CAAC,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,OAAO,EAAE;YACpC,KAAK,EAAE,IAAI,EAAE,KAAK;SACrB,CAAC,EACN,IAAI,CACP;KACR,CAAA;AACL,CAAC"}