@kynesyslabs/demosdk 4.0.11 → 4.0.13

package/build/l2ps/channel/negotiate.js.map

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

package/build/l2ps/channel/transport.d.ts

@@ -0,0 +1,117 @@
+/**
+ * SR-4 WI-A — Channel-over-L2PS transport adapter.
+ *
+ * The DACS channel layer (`ChannelSession`) is transport-agnostic: it
+ * produces signed `ChannelMessage` envelopes and verifies incoming ones,
+ * but does not move bytes. The L2PS instant-messaging layer
+ * (`L2PSMessagingPeer`) moves encrypted bytes between subnet members but
+ * knows nothing about channel envelopes. This adapter bridges the two:
+ * it serialises + encrypts an outgoing envelope onto the messaging
+ * transport, and on the receive side decrypts, deserialises, and feeds
+ * envelopes into the session **in strict sequence order**.
+ *
+ * Why a reorder buffer is mandatory:
+ * `ChannelSession.receiveIncoming` accepts any sequence strictly greater
+ * than the highest it has seen and then advances its counter to that
+ * value — so a *gap* (seq N+2 arriving before N+1) is not rejected, it
+ * permanently skips the missing messages. The L2PS transport delivers by
+ * timestamp and replays an offline queue, so out-of-order arrival is
+ * normal. This adapter therefore only hands the session the next
+ * contiguous sequence and buffers anything ahead of the gap until it
+ * fills.
+ *
+ * Scope / assumptions:
+ * - The shared per-channel sequence counter assumes turn-based messaging
+ *   (DACS negotiation is offer → counter → accept; a party waits for the
+ *   counter before replying). Two parties emitting the same sequence
+ *   concurrently is out of scope for SR-4 v1; such a colliding inbound
+ *   message (seq <= already-applied) is dropped as a duplicate.
+ * - Membership is the channel's `members`; the transport sends to every
+ *   member except self. Confidentiality is the subnet AES key (only
+ *   members hold it) — CH-2.
+ */
+import type { ChannelMessage, ChannelMessageType } from "./types";
+/**
+ * Minimal surface of `ChannelSession` the adapter depends on. Declared
+ * structurally so tests can inject a fake without real signing keys.
+ */
+export interface ChannelSessionLike {
+    readonly channelId: string;
+    sendOutgoing(opts: {
+        type: ChannelMessageType;
+        body: unknown;
+        sentAt?: number;
+        repliesTo?: number;
+    }): Promise<ChannelMessage>;
+    receiveIncoming(msg: ChannelMessage): Promise<void>;
+}
+/** Wire shape the L2PS messaging transport carries (ciphertext + nonce, base64). */
+export interface SerializedEncryptedMessage {
+    ciphertext: string;
+    nonce: string;
+    ephemeralKey?: string;
+}
+/** Incoming payload the messaging peer hands to an onMessage handler. */
+export interface IncomingMessagePayload {
+    from: string;
+    encrypted: SerializedEncryptedMessage;
+    messageHash: string;
+    offline?: boolean;
+}
+/**
+ * Minimal surface of `L2PSMessagingPeer` the adapter depends on.
+ * Declared structurally for the same reason as `ChannelSessionLike`.
+ */
+export interface L2PSMessagingPeerLike {
+    send(to: string, encrypted: SerializedEncryptedMessage, messageHash: string): Promise<unknown>;
+    onMessage(handler: (payload: IncomingMessagePayload) => void): void;
+}
+export interface L2PSChannelTransportOpts {
+    session: ChannelSessionLike;
+    peer: L2PSMessagingPeerLike;
+    /** Subnet AES-256 key (raw 32 bytes) — only members hold it (CH-2). */
+    sharedKey: Uint8Array;
+    /**
+     * Recipient public keys to deliver to (every channel member except
+     * self), in the format the messaging peer routes on.
+     */
+    recipients: string[];
+    /** Called with each envelope once it has been applied in order. */
+    onMessage?: (msg: ChannelMessage) => void;
+    /** Called on a decrypt / parse / verification failure. */
+    onError?: (err: Error) => void;
+}
+export declare class L2PSChannelTransport {
+    private readonly session;
+    private readonly peer;
+    private readonly sharedKey;
+    private readonly recipients;
+    private readonly onMessage?;
+    private readonly onError?;
+    /** Sequences seen ahead of the gap, awaiting contiguous application. */
+    private readonly buffer;
+    /** Highest contiguous sequence applied locally (sent or received). */
+    private appliedSeq;
+    /** Serialises drain() so concurrent inbound frames can't interleave. */
+    private draining;
+    private started;
+    constructor(opts: L2PSChannelTransportOpts);
+    /** Wire the peer's inbound handler. Call once. */
+    start(): void;
+    /**
+     * Build + sign the next outgoing envelope via the session, encrypt
+     * it under the subnet key, and deliver to every recipient.
+     */
+    send(opts: {
+        type: ChannelMessageType;
+        body: unknown;
+        repliesTo?: number;
+    }): Promise<ChannelMessage>;
+    private ingest;
+    /** Apply every buffered message that is now contiguous with appliedSeq. */
+    private drain;
+    /** Count of out-of-order messages currently held awaiting the gap. */
+    get bufferedCount(): number;
+    private encrypt;
+    private decrypt;
+}

package/build/l2ps/channel/transport.js

@@ -0,0 +1,178 @@
+/**
+ * SR-4 WI-A — Channel-over-L2PS transport adapter.
+ *
+ * The DACS channel layer (`ChannelSession`) is transport-agnostic: it
+ * produces signed `ChannelMessage` envelopes and verifies incoming ones,
+ * but does not move bytes. The L2PS instant-messaging layer
+ * (`L2PSMessagingPeer`) moves encrypted bytes between subnet members but
+ * knows nothing about channel envelopes. This adapter bridges the two:
+ * it serialises + encrypts an outgoing envelope onto the messaging
+ * transport, and on the receive side decrypts, deserialises, and feeds
+ * envelopes into the session **in strict sequence order**.
+ *
+ * Why a reorder buffer is mandatory:
+ * `ChannelSession.receiveIncoming` accepts any sequence strictly greater
+ * than the highest it has seen and then advances its counter to that
+ * value — so a *gap* (seq N+2 arriving before N+1) is not rejected, it
+ * permanently skips the missing messages. The L2PS transport delivers by
+ * timestamp and replays an offline queue, so out-of-order arrival is
+ * normal. This adapter therefore only hands the session the next
+ * contiguous sequence and buffers anything ahead of the gap until it
+ * fills.
+ *
+ * Scope / assumptions:
+ * - The shared per-channel sequence counter assumes turn-based messaging
+ *   (DACS negotiation is offer → counter → accept; a party waits for the
+ *   counter before replying). Two parties emitting the same sequence
+ *   concurrently is out of scope for SR-4 v1; such a colliding inbound
+ *   message (seq <= already-applied) is dropped as a duplicate.
+ * - Membership is the channel's `members`; the transport sends to every
+ *   member except self. Confidentiality is the subnet AES key (only
+ *   members hold it) — CH-2.
+ */
+/**
+ * Max number of sequences a buffered inbound frame may sit ahead of the
+ * current contiguous point before it is dropped, bounding reorder-buffer
+ * memory. Turn-based negotiation never legitimately exceeds this.
+ */
+const MAX_REORDER_AHEAD = 256;
+export class L2PSChannelTransport {
+    constructor(opts) {
+        /** Sequences seen ahead of the gap, awaiting contiguous application. */
+        this.buffer = new Map();
+        /** Highest contiguous sequence applied locally (sent or received). */
+        this.appliedSeq = 0;
+        /** Serialises drain() so concurrent inbound frames can't interleave. */
+        this.draining = Promise.resolve();
+        this.started = false;
+        this.session = opts.session;
+        this.peer = opts.peer;
+        this.sharedKey = opts.sharedKey;
+        this.recipients = opts.recipients;
+        this.onMessage = opts.onMessage;
+        this.onError = opts.onError;
+    }
+    /** Wire the peer's inbound handler. Call once. */
+    start() {
+        if (this.started)
+            throw new Error("L2PSChannelTransport: already started");
+        this.started = true;
+        this.peer.onMessage(payload => {
+            // Chain onto `draining` so frames are processed one at a time
+            // in arrival order; each appends to the buffer then drains.
+            this.draining = this.draining
+                .then(() => this.ingest(payload))
+                .catch(err => this.onError?.(err));
+        });
+    }
+    /**
+     * Build + sign the next outgoing envelope via the session, encrypt
+     * it under the subnet key, and deliver to every recipient.
+     */
+    async send(opts) {
+        const signed = await this.session.sendOutgoing(opts);
+        const encrypted = await this.encrypt(JSON.stringify(signed));
+        const messageHash = signed.signature.signature; // unique per signed envelope
+        // Deliver to every recipient BEFORE committing the sequence locally.
+        // If any send rejects, the throw propagates here and appliedSeq is
+        // left untouched, so a retry re-emits the same sequence rather than
+        // skipping ahead and stranding peers behind a reorder gap. (Recipients
+        // that did receive it will drop the duplicate on resend — seq <=
+        // appliedSeq — so at-least-once delivery is safe.)
+        for (const to of this.recipients) {
+            await this.peer.send(to, encrypted, messageHash);
+        }
+        // Our own send advances the shared per-channel counter; record it
+        // so we expect the peer's reply at appliedSeq + 1.
+        if (signed.sequence > this.appliedSeq)
+            this.appliedSeq = signed.sequence;
+        return signed;
+    }
+    async ingest(payload) {
+        let msg;
+        try {
+            const json = await this.decrypt(payload.encrypted);
+            msg = JSON.parse(json);
+        }
+        catch (e) {
+            throw new Error(`L2PSChannelTransport: failed to decrypt/parse inbound frame from ${payload.from}: ${e.message}`);
+        }
+        // Ignore traffic for other channels sharing the same subnet.
+        if (msg.channelId !== this.session.channelId)
+            return;
+        // Duplicate / already-applied (or a colliding concurrent send): drop.
+        if (msg.sequence <= this.appliedSeq)
+            return;
+        // Bound the reorder window: a member could otherwise stream many
+        // validly-encrypted frames at far-future sequences without ever
+        // filling the gap, growing `buffer` without limit. Drop anything
+        // beyond MAX_REORDER_AHEAD of the current contiguous point — a
+        // legitimate turn-based negotiation never runs that far ahead, and
+        // a dropped frame is re-deliverable (the offline queue replays it
+        // once the gap closes and appliedSeq advances).
+        if (msg.sequence > this.appliedSeq + MAX_REORDER_AHEAD) {
+            this.onError?.(new Error(`L2PSChannelTransport: dropping seq ${msg.sequence} — ` +
+                `more than ${MAX_REORDER_AHEAD} ahead of applied ${this.appliedSeq}`));
+            return;
+        }
+        // Buffer; a later sequence with the same value would be a protocol
+        // error — keep the first seen.
+        if (!this.buffer.has(msg.sequence))
+            this.buffer.set(msg.sequence, msg);
+        await this.drain();
+    }
+    /** Apply every buffered message that is now contiguous with appliedSeq. */
+    async drain() {
+        // Sequence counter is shared across both directions, so the next
+        // expected inbound is appliedSeq + 1.
+        let next = this.buffer.get(this.appliedSeq + 1);
+        while (next) {
+            this.buffer.delete(next.sequence);
+            // Throws on tamper (bad signature, wrong sender, channelId
+            // mismatch) — propagate as channel-fatal per §8.12.
+            await this.session.receiveIncoming(next);
+            this.appliedSeq = next.sequence;
+            this.onMessage?.(next);
+            next = this.buffer.get(this.appliedSeq + 1);
+        }
+    }
+    /** Count of out-of-order messages currently held awaiting the gap. */
+    get bufferedCount() {
+        return this.buffer.size;
+    }
+    // ── AES-256-GCM (Web Crypto) — matches the messaging wire format:
+    //    ciphertext (with auth tag) + 12-byte nonce, both base64. ──
+    async encrypt(plaintext) {
+        const nonce = crypto.getRandomValues(new Uint8Array(12));
+        const key = await crypto.subtle.importKey("raw", keyBytes(this.sharedKey), "AES-GCM", false, ["encrypt"]);
+        const cipher = await crypto.subtle.encrypt({ name: "AES-GCM", iv: nonce }, key, new TextEncoder().encode(plaintext));
+        return {
+            ciphertext: bytesToBase64(new Uint8Array(cipher)),
+            nonce: bytesToBase64(nonce),
+        };
+    }
+    async decrypt(enc) {
+        const key = await crypto.subtle.importKey("raw", keyBytes(this.sharedKey), "AES-GCM", false, ["decrypt"]);
+        const plain = await crypto.subtle.decrypt({ name: "AES-GCM", iv: base64ToBytes(enc.nonce) }, key, base64ToBytes(enc.ciphertext));
+        return new TextDecoder().decode(plain);
+    }
+}
+/**
+ * Return a standalone `ArrayBuffer` holding exactly the bytes of `view`.
+ * `view.buffer` exposes the whole backing buffer, which for a `subarray`
+ * (e.g. a 32-byte key sliced out of a larger buffer) is longer than the
+ * view — Web Crypto would then see the wrong length / wrong bytes and
+ * reject or mis-key the AES import. Copying the exact `[byteOffset,
+ * byteOffset+byteLength)` window guarantees the key import sees only the
+ * intended bytes.
+ */
+function keyBytes(view) {
+    return view.buffer.slice(view.byteOffset, view.byteOffset + view.byteLength);
+}
+function bytesToBase64(bytes) {
+    return Buffer.from(bytes).toString("base64");
+}
+function base64ToBytes(b64) {
+    return new Uint8Array(Buffer.from(b64, "base64"));
+}
+//# sourceMappingURL=transport.js.map

package/build/l2ps/channel/transport.js.map

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

package/build/websdk/BroadcastFailedError.js.map

@@ -1 +1 @@
-{"version":3,"file":"BroadcastFailedError.js","sourceRoot":"","sources":["../../../src/websdk/BroadcastFailedError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAI3C,YAAY,IAA0D;QAClE,MAAM,YAAY,GACb,IAAI,CAAC,KAAa,EAAE,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI,SAAS,CAAC,CAAA;QACnE,KAAK,CACD,IAAI,CAAC,OAAO;YACR,iEAAiE,IAAI,CAAC,MAAM,MAAM,YAAY,EAAE,CACvG,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;QAClC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;QACzB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;IAC3B,CAAC;CACJ"}
+{"version":3,"file":"BroadcastFailedError.js","sourceRoot":"","sources":["../../../src/websdk/BroadcastFailedError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAM3C,YAAY,IAA0D;QAClE,MAAM,YAAY,GACb,IAAI,CAAC,KAAa,EAAE,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI,SAAS,CAAC,CAAA;QACnE,KAAK,CACD,IAAI,CAAC,OAAO;YACR,iEAAiE,IAAI,CAAC,MAAM,MAAM,YAAY,EAAE,CACvG,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;QAClC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;QACzB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;IAC3B,CAAC;CACJ"}

package/build/websdk/DemosTransactions.d.ts

@@ -98,7 +98,7 @@ export declare const DemosTransactions: {
      * Broadcast a confirmed transaction and wait for inclusion.
      *
      * Polls the node's `getTransactionStatus` RPC until the tx is observed
-     * `included` or `failed`, or until `opts.timeoutMs` elapses (default 30s).
+     * `included` or `failed`, or until `opts.timeoutMs` elapses (default 60s).
      *
      * Use this when you want a single call with a deterministic outcome.
      * Use plain `broadcast()` when you want to handle async confirmation
@@ -117,7 +117,7 @@ export declare const DemosTransactions: {
      *
      * @param validationData - The validity data of the transaction (from `confirm`)
      * @param demos - The demos instance
-     * @param opts.timeoutMs - Total time to wait for inclusion. Defaults to 30_000.
+     * @param opts.timeoutMs - Total time to wait for inclusion. Defaults to 60_000.
      * @param opts.pollIntervalMs - Delay between status polls. Defaults to 500.
      * @param opts.failFastOnBroadcastError - If true, throw `BroadcastFailedError`
      *   immediately when the broadcast can't contact the node. Defaults to false.

package/build/websdk/DemosTransactions.js

@@ -271,7 +271,7 @@ export const DemosTransactions = {
      * Broadcast a confirmed transaction and wait for inclusion.
      *
      * Polls the node's `getTransactionStatus` RPC until the tx is observed
-     * `included` or `failed`, or until `opts.timeoutMs` elapses (default 30s).
+     * `included` or `failed`, or until `opts.timeoutMs` elapses (default 60s).
      *
      * Use this when you want a single call with a deterministic outcome.
      * Use plain `broadcast()` when you want to handle async confirmation
@@ -290,7 +290,7 @@ export const DemosTransactions = {
      *
      * @param validationData - The validity data of the transaction (from `confirm`)
      * @param demos - The demos instance
-     * @param opts.timeoutMs - Total time to wait for inclusion. Defaults to 30_000.
+     * @param opts.timeoutMs - Total time to wait for inclusion. Defaults to 60_000.
      * @param opts.pollIntervalMs - Delay between status polls. Defaults to 500.
      * @param opts.failFastOnBroadcastError - If true, throw `BroadcastFailedError`
      *   immediately when the broadcast can't contact the node. Defaults to false.
@@ -298,7 +298,7 @@ export const DemosTransactions = {
      * @returns The original broadcast response and the terminal status.
      */
     broadcastAndWait: async function (validationData, demos, opts) {
-        const timeout = opts?.timeoutMs ?? 30000;
+        const timeout = opts?.timeoutMs ?? 60000;
         const pollInterval = opts?.pollIntervalMs ?? 500;
         const failFast = opts?.failFastOnBroadcastError ?? false;
         // Extract the tx hash from the validity data before broadcasting so

package/build/websdk/TransportError.js.map

@@ -1 +1 @@
-{"version":3,"file":"TransportError.js","sourceRoot":"","sources":["../../../src/websdk/TransportError.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAIrC,YAAY,OAAe,EAAE,IAA0C;QACnE,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;QAC5B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAA;QAC7B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;IAC3B,CAAC;CACJ"}
+{"version":3,"file":"TransportError.js","sourceRoot":"","sources":["../../../src/websdk/TransportError.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAMrC,YAAY,OAAe,EAAE,IAA0C;QACnE,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;QAC5B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAA;QAC7B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;IAC3B,CAAC;CACJ"}

package/build/websdk/demosclass.d.ts

@@ -7,6 +7,7 @@ import type { ValidatorInfo } from "../types/validator/ValidatorTypes";
 import type { NetworkParameters, NetworkUpgradeProposal, ProposalVoteInfo } from "../types/blockchain/NetworkParameters";
 import { RPCRequest, RPCResponse, RPCResponseWithValidityData } from "../types/communication/rpc";
 import { IKeyPair } from "./types/KeyPair";
+import { type ProgrammaticTx } from "./programmatic";
 import { UnifiedCrypto } from "../encryption/unifiedCrypto";
 import { type NetworkInfo } from "../denomination/networkInfo";
 import { TweetSimplified } from "../types";
@@ -67,6 +68,50 @@ export declare class Demos {
      * @returns Whether the connection was successful
      */
     connect(rpc_url: string): Promise<boolean>;
+    /**
+     * One-call bootstrap: connect to a node and (optionally) a wallet, then
+     * return the ready instance for immediate use with `demos.run.*`.
+     *
+     * Convenience wrapper over {@link connect} + {@link connectWallet} — no
+     * new behaviour, just the two-step setup collapsed into one. Omit
+     * `wallet` to connect read-only.
+     *
+     * @example
+     * ```ts
+     * import { Demos } from "@kynesyslabs/demosdk/websdk"
+     * const demos = await Demos.start("https://node2.demos.sh", mnemonic)
+     * await demos.run.pay("0x...", 100n)
+     * ```
+     *
+     * @param rpc_url - The URL of the demos node.
+     * @param wallet - Master seed / mnemonic (string) or raw seed bytes.
+     *                 Omit to connect without a wallet.
+     * @param walletOptions - Forwarded to {@link connectWallet}.
+     * @returns This connected Demos instance.
+     */
+    start(rpc_url: string, wallet?: string | Uint8Array, walletOptions?: {
+        algorithm?: SigningAlgorithm;
+        dual_sign?: boolean;
+    }): Promise<this>;
+    /**
+     * Static one-call bootstrap over the shared singleton — starts
+     * {@link Demos.instance} and returns it ready for `demos.run.*`.
+     *
+     * @example
+     * ```ts
+     * const demos = await Demos.start("https://node2.demos.sh", mnemonic)
+     * await demos.run.pay("0x...", 100n)
+     * ```
+     *
+     * @param rpc_url - The URL of the demos node.
+     * @param wallet - Master seed / mnemonic (string) or raw seed bytes.
+     * @param walletOptions - Forwarded to {@link connectWallet}.
+     * @returns The started shared Demos instance.
+     */
+    static start(rpc_url: string, wallet?: string | Uint8Array, walletOptions?: {
+        algorithm?: SigningAlgorithm;
+        dual_sign?: boolean;
+    }): Promise<Demos>;
     /**
      * Connects to a Demos wallet using the provided master seed.
      *
@@ -202,7 +247,7 @@ export declare class Demos {
      * handle async confirmation yourself.
      *
      * @param validationData - The validity data of the transaction
-     * @param opts.timeoutMs - Total time to wait. Defaults to 30_000.
+     * @param opts.timeoutMs - Total time to wait. Defaults to 60_000.
      * @param opts.pollIntervalMs - Delay between polls. Defaults to 500.
      */
     broadcastAndWait(validationData: RPCResponseWithValidityData, opts?: {
@@ -654,6 +699,41 @@ export declare class Demos {
         }, demos: Demos): Promise<Transaction>;
         voteOnUpgrade(proposalId: string, approve: boolean, demos: Demos): Promise<Transaction>;
     };
+    private _run?;
+    /**
+     * Programmatic transaction facade — one call per transaction type.
+     *
+     * Collapses the classic `build → sign → confirm → broadcast` flow into a
+     * single method per operation (`run.pay`, `run.attest.*`, `run.tokens.*`,
+     * …) that auto-broadcasts within a configurable fee ceiling (default
+     * 5 DEM). Additive: the classic `pay`/`confirm`/`broadcast` methods are
+     * unchanged.
+     *
+     * Built lazily on first access (and memoised) rather than in the
+     * constructor. Two reasons: (1) the singleton `demos = Demos.instance` is
+     * created at import time, so eagerly *constructing* the namespaces during
+     * `new Demos()` — which reach into `@/abstraction`, tokens, contracts — is
+     * the part that risked tripping the websdk↔abstraction import cycle;
+     * deferring construction removes that crash vector. (2) it avoids building
+     * ~6 objects on every `new Demos()` that many callers never touch.
+     *
+     * Note: the programmatic module graph is still *loaded* when this file is
+     * imported (a static `import` cannot be deferred in ESM). That residual
+     * cycle is benign — no module reads a cross-cycle binding at evaluation
+     * time, only inside functions — and has been narrowed by importing
+     * `Identities` directly from `@/abstraction/Identities` rather than via the
+     * `@/abstraction` barrel.
+     *
+     * @example
+     * ```ts
+     * // one-call payment, auto-broadcast within the 5 DEM fee cap
+     * await demos.run.pay("0x...", 100n)
+     * // build + confirm only, broadcast yourself later
+     * const r = await demos.run.pay("0x...", 100n, { confirm: "manual" })
+     * await demos.broadcast(r.validityData)
+     * ```
+     */
+    get run(): ProgrammaticTx;
     DemosTransactions: {
         empty: () => Transaction;
         prepare: (data?: any) => Promise<Transaction>;

package/build/websdk/demosclass.js

@@ -12,6 +12,7 @@ import { DemosWebAuth } from "./DemosWebAuth.js";
 import { prepareXMPayload } from "./XMTransactions.js";
 import { _required as required } from "./utils/required.js";
 import { web2Calls } from "./Web2Calls.js";
+import { createProgrammaticTx, } from "./programmatic/index.js";
 import { hexToUint8Array, uint8ArrayToHex, UnifiedCrypto, } from "../encryption/unifiedCrypto.js";
 import { GCRGeneration } from "./GCRGeneration.js";
 import { Hashing } from "../encryption/Hashing.js";
@@ -276,6 +277,52 @@ export class Demos {
         this.connected = true;
         return this.connected;
     }
+    /**
+     * One-call bootstrap: connect to a node and (optionally) a wallet, then
+     * return the ready instance for immediate use with `demos.run.*`.
+     *
+     * Convenience wrapper over {@link connect} + {@link connectWallet} — no
+     * new behaviour, just the two-step setup collapsed into one. Omit
+     * `wallet` to connect read-only.
+     *
+     * @example
+     * ```ts
+     * import { Demos } from "@kynesyslabs/demosdk/websdk"
+     * const demos = await Demos.start("https://node2.demos.sh", mnemonic)
+     * await demos.run.pay("0x...", 100n)
+     * ```
+     *
+     * @param rpc_url - The URL of the demos node.
+     * @param wallet - Master seed / mnemonic (string) or raw seed bytes.
+     *                 Omit to connect without a wallet.
+     * @param walletOptions - Forwarded to {@link connectWallet}.
+     * @returns This connected Demos instance.
+     */
+    async start(rpc_url, wallet, walletOptions) {
+        await this.connect(rpc_url);
+        if (wallet !== undefined) {
+            await this.connectWallet(wallet, walletOptions);
+        }
+        return this;
+    }
+    /**
+     * Static one-call bootstrap over the shared singleton — starts
+     * {@link Demos.instance} and returns it ready for `demos.run.*`.
+     *
+     * @example
+     * ```ts
+     * const demos = await Demos.start("https://node2.demos.sh", mnemonic)
+     * await demos.run.pay("0x...", 100n)
+     * ```
+     *
+     * @param rpc_url - The URL of the demos node.
+     * @param wallet - Master seed / mnemonic (string) or raw seed bytes.
+     * @param walletOptions - Forwarded to {@link connectWallet}.
+     * @returns The started shared Demos instance.
+     */
+    static async start(rpc_url, wallet, walletOptions) {
+        return Demos.instance.start(rpc_url, wallet, walletOptions);
+    }
     /**
      * Connects to a Demos wallet using the provided master seed.
      *
@@ -454,7 +501,7 @@ export class Demos {
      * handle async confirmation yourself.
      *
      * @param validationData - The validity data of the transaction
-     * @param opts.timeoutMs - Total time to wait. Defaults to 30_000.
+     * @param opts.timeoutMs - Total time to wait. Defaults to 60_000.
      * @param opts.pollIntervalMs - Delay between polls. Defaults to 500.
      */
     broadcastAndWait(validationData, opts) {
@@ -1417,6 +1464,42 @@ export class Demos {
         }
         return tlsn;
     }
+    /**
+     * Programmatic transaction facade — one call per transaction type.
+     *
+     * Collapses the classic `build → sign → confirm → broadcast` flow into a
+     * single method per operation (`run.pay`, `run.attest.*`, `run.tokens.*`,
+     * …) that auto-broadcasts within a configurable fee ceiling (default
+     * 5 DEM). Additive: the classic `pay`/`confirm`/`broadcast` methods are
+     * unchanged.
+     *
+     * Built lazily on first access (and memoised) rather than in the
+     * constructor. Two reasons: (1) the singleton `demos = Demos.instance` is
+     * created at import time, so eagerly *constructing* the namespaces during
+     * `new Demos()` — which reach into `@/abstraction`, tokens, contracts — is
+     * the part that risked tripping the websdk↔abstraction import cycle;
+     * deferring construction removes that crash vector. (2) it avoids building
+     * ~6 objects on every `new Demos()` that many callers never touch.
+     *
+     * Note: the programmatic module graph is still *loaded* when this file is
+     * imported (a static `import` cannot be deferred in ESM). That residual
+     * cycle is benign — no module reads a cross-cycle binding at evaluation
+     * time, only inside functions — and has been narrowed by importing
+     * `Identities` directly from `@/abstraction/Identities` rather than via the
+     * `@/abstraction` barrel.
+     *
+     * @example
+     * ```ts
+     * // one-call payment, auto-broadcast within the 5 DEM fee cap
+     * await demos.run.pay("0x...", 100n)
+     * // build + confirm only, broadcast yourself later
+     * const r = await demos.run.pay("0x...", 100n, { confirm: "manual" })
+     * await demos.broadcast(r.validityData)
+     * ```
+     */
+    get run() {
+        return (this._run ?? (this._run = createProgrammaticTx(this)));
+    }
 }
 Demos._instance = null;
 /**