@kynesyslabs/demosdk 4.0.11 → 4.0.13

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

@@ -0,0 +1,155 @@
+import type { TokenCreationParams, TokenHookType, TokenScriptMethod } from "../../types/token";
+import type { ProgrammaticContext } from "./context";
+import type { ProgrammaticTxOptions, ProgrammaticTxResult } from "./types";
+/**
+ * Token creation and execution as one-call programmatic transactions.
+ *
+ * Wraps {@link DemosTokens} so deploying a token or running a token
+ * operation (transfer, approve, mint, burn, …) collapses the classic
+ * `build → sign → confirm → broadcast` flow into a single call. Each
+ * builder here returns an UNSIGNED transaction; the method hands a thunk
+ * producing it to `ctx.run(...)`, which signs, confirms against the fee
+ * ceiling and auto-broadcasts — keeping fee-cap policy, confirmation
+ * strategy and result shape uniform with the rest of `demos.run.*`.
+ *
+ * All amounts are bigint-valued decimal strings, mirroring
+ * {@link DemosTokens}.
+ */
+export declare function createTokensNamespace(ctx: ProgrammaticContext): {
+    /**
+     * Deploy a new token, end to end.
+     *
+     * @example
+     * ```ts
+     * const r = await demos.run.tokens.create({
+     *     name: "My Token",
+     *     ticker: "MYT",
+     *     decimals: 18,
+     *     initialSupply: "1000000",
+     * })
+     * console.log(r.transaction.content.to) // derived token address
+     * ```
+     *
+     * @param params - Token creation parameters (name, ticker, decimals,
+     *                  initial supply, optional script/ACL).
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    create: (params: TokenCreationParams, opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+    /**
+     * Transfer tokens to another address, end to end.
+     *
+     * @example
+     * ```ts
+     * // auto-broadcast within the 5 DEM fee cap:
+     * await demos.run.tokens.transfer("0xToken...", "0xTo...", "1000")
+     * // build + confirm only, broadcast later yourself:
+     * const r = await demos.run.tokens.transfer(
+     *     "0xToken...", "0xTo...", "1000", { confirm: "manual" },
+     * )
+     * await demos.broadcast(r.validityData)
+     * ```
+     *
+     * @param tokenAddress - Token contract address.
+     * @param to - Recipient address.
+     * @param amount - Amount to transfer (bigint-valued decimal string).
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    transfer: (tokenAddress: string, to: string, amount: string, opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+    /**
+     * Approve a spender to move tokens on your behalf, end to end.
+     *
+     * @param tokenAddress - Token contract address.
+     * @param spender - Spender address being granted the allowance.
+     * @param amount - Amount to approve (bigint-valued decimal string).
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    approve: (tokenAddress: string, spender: string, amount: string, opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+    /**
+     * Mint new tokens to an address, end to end.
+     *
+     * @param tokenAddress - Token contract address.
+     * @param to - Recipient of the minted tokens.
+     * @param amount - Amount to mint (bigint-valued decimal string).
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    mint: (tokenAddress: string, to: string, amount: string, opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+    /**
+     * Burn tokens from an address, end to end.
+     *
+     * @param tokenAddress - Token contract address.
+     * @param from - Address to burn tokens from.
+     * @param amount - Amount to burn (bigint-valued decimal string).
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    burn: (tokenAddress: string, from: string, amount: string, opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+    /**
+     * Transfer tokens from one address to another using an existing
+     * allowance, end to end.
+     *
+     * @param tokenAddress - Token contract address.
+     * @param from - Owner address the tokens are moved from.
+     * @param to - Recipient address.
+     * @param amount - Amount to transfer (bigint-valued decimal string).
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    transferFrom: (tokenAddress: string, from: string, to: string, amount: string, opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+    /**
+     * Pause all token operations, end to end.
+     *
+     * @param tokenAddress - Token contract address.
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    pause: (tokenAddress: string, opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+    /**
+     * Resume a paused token, end to end.
+     *
+     * @param tokenAddress - Token contract address.
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    unpause: (tokenAddress: string, opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+    /**
+     * Transfer ownership of the token to a new owner, end to end.
+     *
+     * @param tokenAddress - Token contract address.
+     * @param newOwner - Address of the new owner.
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    transferOwnership: (tokenAddress: string, newOwner: string, opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+    /**
+     * Grant ACL permissions to an address, end to end.
+     *
+     * @param tokenAddress - Token contract address.
+     * @param address - Address being granted the permissions.
+     * @param permissions - Permissions to grant.
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    grantPermissions: (tokenAddress: string, address: string, permissions: string[], opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+    /**
+     * Revoke ACL permissions from an address, end to end.
+     *
+     * @param tokenAddress - Token contract address.
+     * @param address - Address the permissions are revoked from.
+     * @param permissions - Permissions to revoke.
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    revokePermissions: (tokenAddress: string, address: string, permissions: string[], opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+    /**
+     * Upgrade the token's on-chain script, end to end.
+     *
+     * @param tokenAddress - Token contract address.
+     * @param newCode - New script code.
+     * @param newMethods - New method definitions to install.
+     * @param newHooks - New hooks to activate.
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    upgradeScript: (tokenAddress: string, newCode: string, newMethods: TokenScriptMethod[], newHooks: TokenHookType[], opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+    /**
+     * Call a custom script method on the token, end to end.
+     *
+     * @param tokenAddress - Token contract address.
+     * @param method - Method name to invoke.
+     * @param params - Method parameters.
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    callMethod: (tokenAddress: string, method: string, params: unknown[], opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+};

package/build/websdk/programmatic/tokens.js

@@ -0,0 +1,157 @@
+import { DemosTokens } from "../DemosTokens.js";
+/**
+ * Token creation and execution as one-call programmatic transactions.
+ *
+ * Wraps {@link DemosTokens} so deploying a token or running a token
+ * operation (transfer, approve, mint, burn, …) collapses the classic
+ * `build → sign → confirm → broadcast` flow into a single call. Each
+ * builder here returns an UNSIGNED transaction; the method hands a thunk
+ * producing it to `ctx.run(...)`, which signs, confirms against the fee
+ * ceiling and auto-broadcasts — keeping fee-cap policy, confirmation
+ * strategy and result shape uniform with the rest of `demos.run.*`.
+ *
+ * All amounts are bigint-valued decimal strings, mirroring
+ * {@link DemosTokens}.
+ */
+export function createTokensNamespace(ctx) {
+    const tokens = new DemosTokens(ctx.demos);
+    return {
+        /**
+         * Deploy a new token, end to end.
+         *
+         * @example
+         * ```ts
+         * const r = await demos.run.tokens.create({
+         *     name: "My Token",
+         *     ticker: "MYT",
+         *     decimals: 18,
+         *     initialSupply: "1000000",
+         * })
+         * console.log(r.transaction.content.to) // derived token address
+         * ```
+         *
+         * @param params - Token creation parameters (name, ticker, decimals,
+         *                  initial supply, optional script/ACL).
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        create: (params, opts) => ctx.run(() => tokens.createToken(params), opts),
+        /**
+         * Transfer tokens to another address, end to end.
+         *
+         * @example
+         * ```ts
+         * // auto-broadcast within the 5 DEM fee cap:
+         * await demos.run.tokens.transfer("0xToken...", "0xTo...", "1000")
+         * // build + confirm only, broadcast later yourself:
+         * const r = await demos.run.tokens.transfer(
+         *     "0xToken...", "0xTo...", "1000", { confirm: "manual" },
+         * )
+         * await demos.broadcast(r.validityData)
+         * ```
+         *
+         * @param tokenAddress - Token contract address.
+         * @param to - Recipient address.
+         * @param amount - Amount to transfer (bigint-valued decimal string).
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        transfer: (tokenAddress, to, amount, opts) => ctx.run(() => tokens.transfer(tokenAddress, to, amount), opts),
+        /**
+         * Approve a spender to move tokens on your behalf, end to end.
+         *
+         * @param tokenAddress - Token contract address.
+         * @param spender - Spender address being granted the allowance.
+         * @param amount - Amount to approve (bigint-valued decimal string).
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        approve: (tokenAddress, spender, amount, opts) => ctx.run(() => tokens.approve(tokenAddress, spender, amount), opts),
+        /**
+         * Mint new tokens to an address, end to end.
+         *
+         * @param tokenAddress - Token contract address.
+         * @param to - Recipient of the minted tokens.
+         * @param amount - Amount to mint (bigint-valued decimal string).
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        mint: (tokenAddress, to, amount, opts) => ctx.run(() => tokens.mint(tokenAddress, to, amount), opts),
+        /**
+         * Burn tokens from an address, end to end.
+         *
+         * @param tokenAddress - Token contract address.
+         * @param from - Address to burn tokens from.
+         * @param amount - Amount to burn (bigint-valued decimal string).
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        burn: (tokenAddress, from, amount, opts) => ctx.run(() => tokens.burn(tokenAddress, from, amount), opts),
+        /**
+         * Transfer tokens from one address to another using an existing
+         * allowance, end to end.
+         *
+         * @param tokenAddress - Token contract address.
+         * @param from - Owner address the tokens are moved from.
+         * @param to - Recipient address.
+         * @param amount - Amount to transfer (bigint-valued decimal string).
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        transferFrom: (tokenAddress, from, to, amount, opts) => ctx.run(() => tokens.transferFrom(tokenAddress, from, to, amount), opts),
+        /**
+         * Pause all token operations, end to end.
+         *
+         * @param tokenAddress - Token contract address.
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        pause: (tokenAddress, opts) => ctx.run(() => tokens.pause(tokenAddress), opts),
+        /**
+         * Resume a paused token, end to end.
+         *
+         * @param tokenAddress - Token contract address.
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        unpause: (tokenAddress, opts) => ctx.run(() => tokens.unpause(tokenAddress), opts),
+        /**
+         * Transfer ownership of the token to a new owner, end to end.
+         *
+         * @param tokenAddress - Token contract address.
+         * @param newOwner - Address of the new owner.
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        transferOwnership: (tokenAddress, newOwner, opts) => ctx.run(() => tokens.transferOwnership(tokenAddress, newOwner), opts),
+        /**
+         * Grant ACL permissions to an address, end to end.
+         *
+         * @param tokenAddress - Token contract address.
+         * @param address - Address being granted the permissions.
+         * @param permissions - Permissions to grant.
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        grantPermissions: (tokenAddress, address, permissions, opts) => ctx.run(() => tokens.grantPermissions(tokenAddress, address, permissions), opts),
+        /**
+         * Revoke ACL permissions from an address, end to end.
+         *
+         * @param tokenAddress - Token contract address.
+         * @param address - Address the permissions are revoked from.
+         * @param permissions - Permissions to revoke.
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        revokePermissions: (tokenAddress, address, permissions, opts) => ctx.run(() => tokens.revokePermissions(tokenAddress, address, permissions), opts),
+        /**
+         * Upgrade the token's on-chain script, end to end.
+         *
+         * @param tokenAddress - Token contract address.
+         * @param newCode - New script code.
+         * @param newMethods - New method definitions to install.
+         * @param newHooks - New hooks to activate.
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        upgradeScript: (tokenAddress, newCode, newMethods, newHooks, opts) => ctx.run(() => tokens.upgradeScript(tokenAddress, newCode, newMethods, newHooks), opts),
+        /**
+         * Call a custom script method on the token, end to end.
+         *
+         * @param tokenAddress - Token contract address.
+         * @param method - Method name to invoke.
+         * @param params - Method parameters.
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        callMethod: (tokenAddress, method, params, opts) => ctx.run(() => tokens.callMethod(tokenAddress, method, params), opts),
+    };
+}
+//# sourceMappingURL=tokens.js.map

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

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

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

@@ -0,0 +1,95 @@
+import type { Transaction } from "../../types";
+import type { RPCResponse, RPCResponseWithValidityData } from "../../types/communication/rpc";
+/**
+ * Default fee ceiling, in DEM, applied by the programmatic-tx runner when
+ * `maxFee` is not specified. If a confirmed transaction's total fee exceeds
+ * this and no `confirm` callback is provided, the runner throws
+ * {@link FeeCapExceededError} instead of broadcasting.
+ */
+export declare const DEFAULT_MAX_FEE_DEM = 5;
+/**
+ * Anything the runner can turn into a confirmed transaction:
+ *  - a `Transaction` (signed or unsigned — unsigned is signed first),
+ *  - an already-confirmed `RPCResponseWithValidityData` (e.g. the value the
+ *    `Identities.*` builders return), or
+ *  - a thunk producing either of the above.
+ */
+export type TxSource = Transaction | RPCResponseWithValidityData | (() => Promise<Transaction | RPCResponseWithValidityData>);
+/**
+ * Snapshot handed to a {@link ConfirmHook} (and carried on
+ * {@link FeeCapExceededError}) after `confirm` but before `broadcast`.
+ */
+export interface TxConfirmInfo {
+    /** The signed, confirmed transaction. */
+    transaction: Transaction;
+    /** Raw validity data from the node (gas operation, reference block, …). */
+    validityData: RPCResponseWithValidityData;
+    /** Total fee for this transaction, in OS (smallest unit). */
+    feeOs: bigint;
+    /** Total fee for this transaction, human-readable DEM string. */
+    feeDem: string;
+    /** Whether `feeOs` is within the configured `maxFee` ceiling. */
+    withinFeeCap: boolean;
+    /** Node reference block the tx was confirmed against. */
+    referenceBlock: number;
+}
+/**
+ * Decides whether a confirmed transaction should be broadcast. Return `true`
+ * to broadcast, `false` to skip (the result reports `skippedReason: "rejected"`).
+ */
+export type ConfirmHook = (info: TxConfirmInfo) => boolean | Promise<boolean>;
+export interface ProgrammaticTxOptions {
+    /**
+     * Fee ceiling, in DEM. When the confirmed fee exceeds this in `"auto"`
+     * mode the runner throws {@link FeeCapExceededError} rather than
+     * broadcasting. Defaults to {@link DEFAULT_MAX_FEE_DEM} (5 DEM). Pass
+     * `null` or `Infinity` to disable the cap entirely.
+     */
+    maxFee?: number | string | null;
+    /**
+     * Confirmation strategy:
+     *  - `"auto"` (default): broadcast automatically, subject to `maxFee`.
+     *  - `"manual"`: build + sign + confirm only; return the validity data
+     *    without broadcasting (the classic three-step flow, collapsed to one
+     *    call for the confirm stage).
+     *  - a {@link ConfirmHook}: called with the fee/validity snapshot; the tx
+     *    is broadcast only if it returns `true`. `maxFee` is not auto-enforced
+     *    in this mode — the callback is the sole authority.
+     */
+    confirm?: "auto" | "manual" | ConfirmHook;
+    /**
+     * When broadcasting, wait for on-chain inclusion via `broadcastAndWait`
+     * instead of returning after the broadcast RPC. Defaults to `false`.
+     */
+    wait?: boolean;
+    /** Options forwarded to `broadcastAndWait` when `wait` is `true`. */
+    waitOptions?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    };
+}
+/** Why a confirmed transaction was not broadcast. */
+export type SkippedReason = "manual" | "rejected";
+/**
+ * Uniform result of a programmatic transaction. `broadcasted` tells you
+ * whether the tx actually hit the network; everything needed to broadcast
+ * later (in `"manual"` mode) is on `validityData`.
+ */
+export interface ProgrammaticTxResult {
+    /** `true` if the transaction was broadcast to the network. */
+    broadcasted: boolean;
+    /** Set when `broadcasted` is `false`, explaining why. */
+    skippedReason?: SkippedReason;
+    /** The signed, confirmed transaction. */
+    transaction: Transaction;
+    /** Transaction hash (as confirmed by the node). */
+    hash: string;
+    /** Raw validity data from `confirm`. */
+    validityData: RPCResponseWithValidityData;
+    /** Broadcast response, present only when `broadcasted` is `true`. */
+    broadcast?: RPCResponse;
+    /** Total fee, in OS (smallest unit). */
+    feeOs: bigint;
+    /** Total fee, human-readable DEM string. */
+    feeDem: string;
+}

package/build/websdk/programmatic/types.js

@@ -0,0 +1,8 @@
+/**
+ * Default fee ceiling, in DEM, applied by the programmatic-tx runner when
+ * `maxFee` is not specified. If a confirmed transaction's total fee exceeds
+ * this and no `confirm` callback is provided, the runner throws
+ * {@link FeeCapExceededError} instead of broadcasting.
+ */
+export const DEFAULT_MAX_FEE_DEM = 5;
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/websdk/programmatic/types.ts"],"names":[],"mappings":"AAMA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAA"}

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

@@ -0,0 +1,63 @@
+import type { ProgrammaticContext } from "./context";
+import type { ProgrammaticTxOptions, ProgrammaticTxResult } from "./types";
+/**
+ * Validator staking lifecycle as one-call programmatic transactions.
+ *
+ * Collapses the classic `build → confirm → broadcast` flow for the validator
+ * `stake`, `unstake` and `exit` operations into a single call that
+ * auto-broadcasts within the configured fee ceiling.
+ */
+export declare function createValidatorNamespace(ctx: ProgrammaticContext): {
+    /**
+     * Stake toward validator registration, or top up an existing stake,
+     * end to end.
+     *
+     * @example
+     * ```ts
+     * import { denomination } from "@kynesyslabs/demosdk"
+     * // register + auto-broadcast within the 5 DEM fee cap:
+     * await demos.run.validator.stake(
+     *     denomination.demToOs(1000).toString(),
+     *     "https://my-validator.example",
+     * )
+     * // build + confirm only, broadcast later yourself:
+     * const r = await demos.run.validator.stake(
+     *     "1000000000",
+     *     "https://my-validator.example",
+     *     { confirm: "manual" },
+     * )
+     * await demos.broadcast(r.validityData)
+     * ```
+     *
+     * @param amount - Stake amount as a non-negative bigint-encoded string (OS).
+     * @param connectionUrl - Validator's public endpoint (required on first
+     *                         stake; used to reach the node).
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    stake: (amount: string, connectionUrl: string, opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+    /**
+     * Arm the unstake lock, end to end. Starts the timelock after which
+     * {@link exit} becomes accepted by the network.
+     *
+     * @example
+     * ```ts
+     * await demos.run.validator.unstake()
+     * ```
+     *
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    unstake: (opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+    /**
+     * Complete validator exit, end to end. Only accepted by the network
+     * once the unstake timelock has elapsed
+     * (`unstake_available_at <= currentBlock`).
+     *
+     * @example
+     * ```ts
+     * await demos.run.validator.exit()
+     * ```
+     *
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    exit: (opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+};

package/build/websdk/programmatic/validator.js

@@ -0,0 +1,64 @@
+/**
+ * Validator staking lifecycle as one-call programmatic transactions.
+ *
+ * Collapses the classic `build → confirm → broadcast` flow for the validator
+ * `stake`, `unstake` and `exit` operations into a single call that
+ * auto-broadcasts within the configured fee ceiling.
+ */
+export function createValidatorNamespace(ctx) {
+    return {
+        /**
+         * Stake toward validator registration, or top up an existing stake,
+         * end to end.
+         *
+         * @example
+         * ```ts
+         * import { denomination } from "@kynesyslabs/demosdk"
+         * // register + auto-broadcast within the 5 DEM fee cap:
+         * await demos.run.validator.stake(
+         *     denomination.demToOs(1000).toString(),
+         *     "https://my-validator.example",
+         * )
+         * // build + confirm only, broadcast later yourself:
+         * const r = await demos.run.validator.stake(
+         *     "1000000000",
+         *     "https://my-validator.example",
+         *     { confirm: "manual" },
+         * )
+         * await demos.broadcast(r.validityData)
+         * ```
+         *
+         * @param amount - Stake amount as a non-negative bigint-encoded string (OS).
+         * @param connectionUrl - Validator's public endpoint (required on first
+         *                         stake; used to reach the node).
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        stake: (amount, connectionUrl, opts) => ctx.run(() => ctx.demos.tx.stake(amount, connectionUrl, ctx.demos), opts),
+        /**
+         * Arm the unstake lock, end to end. Starts the timelock after which
+         * {@link exit} becomes accepted by the network.
+         *
+         * @example
+         * ```ts
+         * await demos.run.validator.unstake()
+         * ```
+         *
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        unstake: (opts) => ctx.run(() => ctx.demos.tx.unstake(ctx.demos), opts),
+        /**
+         * Complete validator exit, end to end. Only accepted by the network
+         * once the unstake timelock has elapsed
+         * (`unstake_available_at <= currentBlock`).
+         *
+         * @example
+         * ```ts
+         * await demos.run.validator.exit()
+         * ```
+         *
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        exit: (opts) => ctx.run(() => ctx.demos.tx.validatorExit(ctx.demos), opts),
+    };
+}
+//# sourceMappingURL=validator.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../../../src/websdk/programmatic/validator.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAwB;IAC7D,OAAO;QACH;;;;;;;;;;;;;;;;;;;;;;;;;WAyBG;QACH,KAAK,EAAE,CACH,MAAc,EACd,aAAqB,EACrB,IAA4B,EACC,EAAE,CAC/B,GAAG,CAAC,GAAG,CACH,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,CAAC,KAAK,CAAC,EAC1D,IAAI,CACP;QAEL;;;;;;;;;;WAUG;QACH,OAAO,EAAE,CACL,IAA4B,EACC,EAAE,CAC/B,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC;QAExD;;;;;;;;;;;WAWG;QACH,IAAI,EAAE,CACF,IAA4B,EACC,EAAE,CAC/B,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC;KACjE,CAAA;AACL,CAAC"}

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

@@ -0,0 +1,36 @@
+import type { XMScript } from "../../types";
+import type { ProgrammaticContext } from "./context";
+import type { ProgrammaticTxOptions, ProgrammaticTxResult } from "./types";
+/**
+ * Cross-chain (XM) operations as one-call programmatic transactions.
+ *
+ * Building the `XMScript` is inherently chain-specific (per-chain signed
+ * payloads, RPC selection, EVM vs non-EVM task shape, …) and therefore stays
+ * with the caller. Once a script is assembled, this namespace collapses the
+ * classic `prepareXMPayload → confirm → broadcast` flow into a single call
+ * that auto-broadcasts within the configured fee ceiling.
+ */
+export declare function createXmNamespace(ctx: ProgrammaticContext): {
+    /**
+     * Submit a fully-built {@link XMScript} as a `crosschainOperation`
+     * transaction, end to end.
+     *
+     * `prepareXMPayload` signs the transaction; the shared runner then
+     * confirms it and (in `"auto"` mode) broadcasts it within the fee cap.
+     *
+     * @example
+     * ```ts
+     * import { prepareXMScript } from "@kynesyslabs/demosdk"
+     * const xmScript = prepareXMScript({ chain: "eth", ... })
+     * // auto-broadcast within the fee cap:
+     * await demos.run.xm.submit(xmScript)
+     * // build + confirm only, broadcast later yourself:
+     * const r = await demos.run.xm.submit(xmScript, { confirm: "manual" })
+     * await demos.broadcast(r.validityData)
+     * ```
+     *
+     * @param xmScript - The assembled cross-chain script to execute.
+     * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+     */
+    submit: (xmScript: XMScript, opts?: ProgrammaticTxOptions) => Promise<ProgrammaticTxResult>;
+};

package/build/websdk/programmatic/xm.js

@@ -0,0 +1,37 @@
+import { prepareXMPayload } from "../XMTransactions.js";
+/**
+ * Cross-chain (XM) operations as one-call programmatic transactions.
+ *
+ * Building the `XMScript` is inherently chain-specific (per-chain signed
+ * payloads, RPC selection, EVM vs non-EVM task shape, …) and therefore stays
+ * with the caller. Once a script is assembled, this namespace collapses the
+ * classic `prepareXMPayload → confirm → broadcast` flow into a single call
+ * that auto-broadcasts within the configured fee ceiling.
+ */
+export function createXmNamespace(ctx) {
+    return {
+        /**
+         * Submit a fully-built {@link XMScript} as a `crosschainOperation`
+         * transaction, end to end.
+         *
+         * `prepareXMPayload` signs the transaction; the shared runner then
+         * confirms it and (in `"auto"` mode) broadcasts it within the fee cap.
+         *
+         * @example
+         * ```ts
+         * import { prepareXMScript } from "@kynesyslabs/demosdk"
+         * const xmScript = prepareXMScript({ chain: "eth", ... })
+         * // auto-broadcast within the fee cap:
+         * await demos.run.xm.submit(xmScript)
+         * // build + confirm only, broadcast later yourself:
+         * const r = await demos.run.xm.submit(xmScript, { confirm: "manual" })
+         * await demos.broadcast(r.validityData)
+         * ```
+         *
+         * @param xmScript - The assembled cross-chain script to execute.
+         * @param opts - Fee ceiling / confirmation strategy / wait behaviour.
+         */
+        submit: (xmScript, opts) => ctx.run(() => prepareXMPayload(xmScript, ctx.demos), opts),
+    };
+}
+//# sourceMappingURL=xm.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"xm.js","sourceRoot":"","sources":["../../../../src/websdk/programmatic/xm.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAIpD;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAwB;IACtD,OAAO;QACH;;;;;;;;;;;;;;;;;;;;WAoBG;QACH,MAAM,EAAE,CACJ,QAAkB,EAClB,IAA4B,EACC,EAAE,CAC/B,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,gBAAgB,CAAC,QAAQ,EAAE,GAAG,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC;KACjE,CAAA;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@kynesyslabs/demosdk",
-    "version": "4.0.11",
+    "version": "4.0.13",
     "type": "module",
     "description": "Demosdk is a JavaScript/TypeScript SDK that provides a unified interface for interacting with Demos network",
     "main": "build/index.js",