boing-sdk 0.3.0

package/dist/nativeTokenSecurity.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Optional **native token deploy security** metadata (wizard parity with EVM “security features”).
+ *
+ * The default Boing **reference fungible** bytecode is minimal (`transfer` / single `mint_first`). DApps that
+ * ship **custom bytecode** can still commit the user’s security choices on-chain via **`description_hash`**
+ * (Blake3 over canonical JSON). Indexers, explorers, and QA reviewers can decode the same JSON shape.
+ *
+ * For the **secured** fungible, **`buildReferenceFungibleSecuredDeployMetaTx`** maps these fields into
+ * **`0xFD` init** storage (on-chain enforcement) when `nativeTokenSecurity` is passed — see
+ * **`referenceFungibleSecuredConfigFromNativeTokenSecurity`**. **`renounceOwnership`** is still metadata-only
+ * (admin must call renounce selector after deploy). **`timelock`** uses **`chainContext.chainHeight`** +
+ * **`timelockDelay`** as a **transfer-unlock block height**.
+ *
+ * Boing VM **`BlockHeight` (`0x40`)** and **`Timestamp` (`0x41`)** opcodes support time/block-gated rules.
+ */
+/** Mirrors boing.finance `DeployToken.jsx` `SECURITY_FEATURES` / wizard toggles (all optional on input). */
+export type NativeTokenSecurityFeaturesInput = {
+    renounceMint?: boolean;
+    enableFreezing?: boolean;
+    enableBlacklist?: boolean;
+    maxTxAmount?: string;
+    renounceOwnership?: boolean;
+    antiBot?: boolean;
+    /** Cooldown between transfers (e.g. seconds); empty string means disabled. */
+    cooldownPeriod?: string;
+    antiWhale?: boolean;
+    pauseFunction?: boolean;
+    timelock?: boolean;
+    /** Admin timelock delay (dApp-defined units, often seconds). */
+    timelockDelay?: string;
+    maxWallet?: boolean;
+    maxWalletPercentage?: string;
+};
+/** Canonical JSON-ready object (every known key present). */
+export type NativeTokenSecurityFeaturesNormalized = {
+    schema: 'boing.native_token_security.v1';
+    renounceMint: boolean;
+    enableFreezing: boolean;
+    enableBlacklist: boolean;
+    maxTxAmount: string;
+    renounceOwnership: boolean;
+    antiBot: boolean;
+    cooldownPeriod: string;
+    antiWhale: boolean;
+    pauseFunction: boolean;
+    timelock: boolean;
+    timelockDelay: string;
+    maxWallet: boolean;
+    maxWalletPercentage: string;
+};
+/**
+ * Stable object for hashing / logging (fixed key order via explicit construction).
+ */
+export declare function normalizeNativeTokenSecurity(input: NativeTokenSecurityFeaturesInput | undefined): NativeTokenSecurityFeaturesNormalized;
+/**
+ * Blake3-256 digest of UTF-8 JSON, as **`0x` + 64 hex** (fits `description_hash` on `contract_deploy_meta`).
+ */
+export declare function descriptionHashHexFromNativeTokenSecurity(input: NativeTokenSecurityFeaturesInput | undefined): `0x${string}`;
+//# sourceMappingURL=nativeTokenSecurity.d.ts.map

package/dist/nativeTokenSecurity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nativeTokenSecurity.d.ts","sourceRoot":"","sources":["../src/nativeTokenSecurity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,4GAA4G;AAC5G,MAAM,MAAM,gCAAgC,GAAG;IAC7C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF,6DAA6D;AAC7D,MAAM,MAAM,qCAAqC,GAAG;IAClD,MAAM,EAAE,gCAAgC,CAAC;IACzC,YAAY,EAAE,OAAO,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;IACxB,eAAe,EAAE,OAAO,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,mBAAmB,EAAE,MAAM,CAAC;CAC7B,CAAC;AAWF;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,gCAAgC,GAAG,SAAS,GAClD,qCAAqC,CAiBvC;AAED;;GAEG;AACH,wBAAgB,yCAAyC,CACvD,KAAK,EAAE,gCAAgC,GAAG,SAAS,GAClD,KAAK,MAAM,EAAE,CASf"}

package/dist/nativeTokenSecurity.js

@@ -0,0 +1,59 @@
+/**
+ * Optional **native token deploy security** metadata (wizard parity with EVM “security features”).
+ *
+ * The default Boing **reference fungible** bytecode is minimal (`transfer` / single `mint_first`). DApps that
+ * ship **custom bytecode** can still commit the user’s security choices on-chain via **`description_hash`**
+ * (Blake3 over canonical JSON). Indexers, explorers, and QA reviewers can decode the same JSON shape.
+ *
+ * For the **secured** fungible, **`buildReferenceFungibleSecuredDeployMetaTx`** maps these fields into
+ * **`0xFD` init** storage (on-chain enforcement) when `nativeTokenSecurity` is passed — see
+ * **`referenceFungibleSecuredConfigFromNativeTokenSecurity`**. **`renounceOwnership`** is still metadata-only
+ * (admin must call renounce selector after deploy). **`timelock`** uses **`chainContext.chainHeight`** +
+ * **`timelockDelay`** as a **transfer-unlock block height**.
+ *
+ * Boing VM **`BlockHeight` (`0x40`)** and **`Timestamp` (`0x41`)** opcodes support time/block-gated rules.
+ */
+import { blake3 } from '@noble/hashes/blake3';
+import { bytesToHex } from '@noble/hashes/utils';
+function bool(v, defaultFalse = false) {
+    if (v === undefined || v === null)
+        return defaultFalse;
+    return Boolean(v);
+}
+function str(v) {
+    return typeof v === 'string' ? v.trim() : '';
+}
+/**
+ * Stable object for hashing / logging (fixed key order via explicit construction).
+ */
+export function normalizeNativeTokenSecurity(input) {
+    return {
+        schema: 'boing.native_token_security.v1',
+        renounceMint: bool(input?.renounceMint),
+        enableFreezing: bool(input?.enableFreezing),
+        enableBlacklist: bool(input?.enableBlacklist),
+        maxTxAmount: str(input?.maxTxAmount),
+        renounceOwnership: bool(input?.renounceOwnership),
+        antiBot: bool(input?.antiBot),
+        cooldownPeriod: str(input?.cooldownPeriod),
+        antiWhale: bool(input?.antiWhale),
+        pauseFunction: bool(input?.pauseFunction),
+        timelock: bool(input?.timelock),
+        timelockDelay: str(input?.timelockDelay),
+        maxWallet: bool(input?.maxWallet),
+        maxWalletPercentage: str(input?.maxWalletPercentage),
+    };
+}
+/**
+ * Blake3-256 digest of UTF-8 JSON, as **`0x` + 64 hex** (fits `description_hash` on `contract_deploy_meta`).
+ */
+export function descriptionHashHexFromNativeTokenSecurity(input) {
+    const norm = normalizeNativeTokenSecurity(input);
+    const json = JSON.stringify(norm);
+    const digest = blake3(new TextEncoder().encode(json));
+    const h = bytesToHex(digest);
+    if (h.length !== 64) {
+        throw new Error('descriptionHashHexFromNativeTokenSecurity: unexpected digest length');
+    }
+    return `0x${h}`;
+}

package/dist/networkProfile.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Capture a JSON-serializable snapshot of RPC endpoint identity + capabilities (CI / local dev pins).
+ */
+import type { BoingClient } from './client.js';
+import type { BoingNetworkProfile } from './types.js';
+/** Fetch health, optional network info, supported methods, and {@link BoingClient.preflightRpc}. */
+export declare function captureBoingNetworkProfile(client: BoingClient): Promise<BoingNetworkProfile>;
+//# sourceMappingURL=networkProfile.d.ts.map

package/dist/networkProfile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"networkProfile.d.ts","sourceRoot":"","sources":["../src/networkProfile.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,oGAAoG;AACpG,wBAAsB,0BAA0B,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAsBlG"}

package/dist/networkProfile.js

@@ -0,0 +1,29 @@
+/**
+ * Capture a JSON-serializable snapshot of RPC endpoint identity + capabilities (CI / local dev pins).
+ */
+/** Fetch health, optional network info, supported methods, and {@link BoingClient.preflightRpc}. */
+export async function captureBoingNetworkProfile(client) {
+    const preflight = await client.preflightRpc();
+    let network_info = null;
+    try {
+        network_info = await client.getNetworkInfo();
+    }
+    catch {
+        network_info = null;
+    }
+    let supported_methods = null;
+    try {
+        supported_methods = await client.rpcSupportedMethods();
+    }
+    catch {
+        supported_methods = null;
+    }
+    return {
+        captured_at_ms: Date.now(),
+        base_url: client.getBaseUrl(),
+        health: preflight.health,
+        network_info,
+        supported_methods,
+        preflight,
+    };
+}

package/dist/newHeadsWs.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Browser-oriented **`GET /ws`** **newHeads** subscriber (handshake + JSON text frames).
+ * Uses global **`WebSocket`**; safe to omit in SSR bundles if you never instantiate.
+ */
+export type BoingNewHeadsWsState = 'idle' | 'connecting' | 'subscribed' | 'reconnecting' | 'closed' | 'error';
+export interface BoingNewHeadsWsOptions {
+    /** WebSocket path on the RPC host (default **`/ws`**). */
+    path?: string;
+    /** First reconnect delay in ms (default **1000**); doubles up to **`maxReconnectDelayMs`**. */
+    initialReconnectDelayMs?: number;
+    maxReconnectDelayMs?: number;
+    /** Cap manual reconnect attempts after close (**default 8**). */
+    maxReconnectAttempts?: number;
+    onState?: (s: BoingNewHeadsWsState) => void;
+    /** Fired for server **`newHead`** payloads (parsed JSON). */
+    onHead?: (payload: unknown) => void;
+    /** Subscribe handshake succeeded. */
+    onSubscribed?: () => void;
+    onError?: (err: unknown) => void;
+}
+/** Build **`ws:` / `wss:`** URL for the node’s WebSocket endpoint. */
+export declare function boingRpcWebSocketUrl(rpcBaseUrl: string, path?: string): string;
+/**
+ * Thin wrapper around **`WebSocket`** with reconnect and typed callbacks.
+ */
+export declare class BoingNewHeadsWs {
+    private readonly rpcBaseUrl;
+    private readonly options;
+    private ws;
+    private state;
+    private reconnectAttempt;
+    private reconnectTimer;
+    private closedByUser;
+    constructor(rpcBaseUrl: string, options?: BoingNewHeadsWsOptions);
+    private setState;
+    getState(): BoingNewHeadsWsState;
+    /** Open socket and send subscribe handshake. */
+    connect(): void;
+    private scheduleReconnect;
+    /** Stop reconnecting and close the socket. */
+    close(): void;
+}
+//# sourceMappingURL=newHeadsWs.d.ts.map

package/dist/newHeadsWs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"newHeadsWs.d.ts","sourceRoot":"","sources":["../src/newHeadsWs.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,oBAAoB,GAC5B,MAAM,GACN,YAAY,GACZ,YAAY,GACZ,cAAc,GACd,QAAQ,GACR,OAAO,CAAC;AAEZ,MAAM,WAAW,sBAAsB;IACrC,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+FAA+F;IAC/F,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,iEAAiE;IACjE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,oBAAoB,KAAK,IAAI,CAAC;IAC5C,6DAA6D;IAC7D,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACpC,qCAAqC;IACrC,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CAClC;AAED,sEAAsE;AACtE,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,SAAQ,GAAG,MAAM,CAU7E;AAID;;GAEG;AACH,qBAAa,eAAe;IAQxB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAR1B,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,YAAY,CAAS;gBAGV,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,sBAA2B;IAGvD,OAAO,CAAC,QAAQ;IAKhB,QAAQ,IAAI,oBAAoB;IAIhC,gDAAgD;IAChD,OAAO,IAAI,IAAI;IAqEf,OAAO,CAAC,iBAAiB;IAmBzB,8CAA8C;IAC9C,KAAK,IAAI,IAAI;CAgBd"}

package/dist/newHeadsWs.js

@@ -0,0 +1,139 @@
+/**
+ * Browser-oriented **`GET /ws`** **newHeads** subscriber (handshake + JSON text frames).
+ * Uses global **`WebSocket`**; safe to omit in SSR bundles if you never instantiate.
+ */
+/** Build **`ws:` / `wss:`** URL for the node’s WebSocket endpoint. */
+export function boingRpcWebSocketUrl(rpcBaseUrl, path = '/ws') {
+    const trimmed = rpcBaseUrl.replace(/\/$/, '');
+    const withProto = trimmed.includes('://') ? trimmed : `http://${trimmed}`;
+    const u = new URL(withProto);
+    u.protocol = u.protocol === 'https:' ? 'wss:' : 'ws:';
+    const p = path.startsWith('/') ? path : `/${path}`;
+    u.pathname = p;
+    u.search = '';
+    u.hash = '';
+    return u.toString();
+}
+const SUBSCRIBE = JSON.stringify({ type: 'subscribe', channel: 'newHeads' });
+/**
+ * Thin wrapper around **`WebSocket`** with reconnect and typed callbacks.
+ */
+export class BoingNewHeadsWs {
+    constructor(rpcBaseUrl, options = {}) {
+        this.rpcBaseUrl = rpcBaseUrl;
+        this.options = options;
+        this.ws = null;
+        this.state = 'idle';
+        this.reconnectAttempt = 0;
+        this.reconnectTimer = null;
+        this.closedByUser = false;
+    }
+    setState(s) {
+        this.state = s;
+        this.options.onState?.(s);
+    }
+    getState() {
+        return this.state;
+    }
+    /** Open socket and send subscribe handshake. */
+    connect() {
+        const WS = globalThis.WebSocket;
+        if (WS == null) {
+            const err = new Error('WebSocket is not available in this environment');
+            this.setState('error');
+            this.options.onError?.(err);
+            throw err;
+        }
+        this.closedByUser = false;
+        if (this.reconnectTimer != null) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        const path = this.options.path ?? '/ws';
+        const url = boingRpcWebSocketUrl(this.rpcBaseUrl, path);
+        this.setState(this.reconnectAttempt > 0 ? 'reconnecting' : 'connecting');
+        const ws = new WS(url);
+        this.ws = ws;
+        ws.onopen = () => {
+            try {
+                ws.send(SUBSCRIBE);
+            }
+            catch (e) {
+                this.options.onError?.(e);
+            }
+        };
+        ws.onmessage = (ev) => {
+            if (typeof ev.data !== 'string')
+                return;
+            let j;
+            try {
+                j = JSON.parse(ev.data);
+            }
+            catch {
+                return;
+            }
+            if (!j || typeof j !== 'object')
+                return;
+            const o = j;
+            if (o.type === 'subscribed' && o.channel === 'newHeads') {
+                this.reconnectAttempt = 0;
+                this.setState('subscribed');
+                this.options.onSubscribed?.();
+                return;
+            }
+            if (o.type === 'newHead') {
+                this.options.onHead?.(j);
+                return;
+            }
+            if (o.type === 'error') {
+                this.options.onError?.(j);
+            }
+        };
+        ws.onerror = () => {
+            this.options.onError?.(new Error('WebSocket error'));
+        };
+        ws.onclose = () => {
+            this.ws = null;
+            if (this.closedByUser) {
+                this.setState('closed');
+                return;
+            }
+            this.scheduleReconnect();
+        };
+    }
+    scheduleReconnect() {
+        const maxAttempts = this.options.maxReconnectAttempts ?? 8;
+        if (this.reconnectAttempt >= maxAttempts) {
+            this.setState('error');
+            this.options.onError?.(new Error('WebSocket: max reconnect attempts reached'));
+            return;
+        }
+        const base = this.options.initialReconnectDelayMs ?? 1000;
+        const maxDelay = this.options.maxReconnectDelayMs ?? 30000;
+        const delay = Math.min(maxDelay, base * Math.pow(2, this.reconnectAttempt));
+        this.reconnectAttempt += 1;
+        this.setState('reconnecting');
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect();
+        }, delay);
+    }
+    /** Stop reconnecting and close the socket. */
+    close() {
+        this.closedByUser = true;
+        if (this.reconnectTimer != null) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws != null) {
+            try {
+                this.ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+            this.ws = null;
+        }
+        this.setState('closed');
+    }
+}

package/dist/preflightGate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Fail fast before heavy flows (swap UI, indexer tick) when the RPC environment is unhealthy.
+ */
+import type { BoingClient } from './client.js';
+import { type BoingRpcDoctorOptions, type BoingRpcDoctorResult } from './rpcDoctor.js';
+export declare class BoingRpcPreflightError extends Error {
+    readonly doctor: BoingRpcDoctorResult;
+    constructor(doctor: BoingRpcDoctorResult);
+}
+export declare function isBoingRpcPreflightError(e: unknown): e is BoingRpcPreflightError;
+/**
+ * Runs {@link doctorBoingRpcEnvironment}; throws {@link BoingRpcPreflightError} when **`ok`** is false.
+ * Use in dApp “connect” or before starting polling loops.
+ */
+export declare function assertBoingRpcEnvironment(client: BoingClient, options?: BoingRpcDoctorOptions): Promise<BoingRpcDoctorResult>;
+//# sourceMappingURL=preflightGate.d.ts.map

package/dist/preflightGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflightGate.d.ts","sourceRoot":"","sources":["../src/preflightGate.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAA6B,KAAK,qBAAqB,EAAE,KAAK,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAElH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;gBAE1B,MAAM,EAAE,oBAAoB;CAUzC;AAED,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,sBAAsB,CAEhF;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,oBAAoB,CAAC,CAM/B"}

package/dist/preflightGate.js

@@ -0,0 +1,29 @@
+/**
+ * Fail fast before heavy flows (swap UI, indexer tick) when the RPC environment is unhealthy.
+ */
+import { doctorBoingRpcEnvironment } from './rpcDoctor.js';
+export class BoingRpcPreflightError extends Error {
+    constructor(doctor) {
+        const msg = doctor.messages.length > 0
+            ? doctor.messages.join('\n')
+            : 'RPC environment check failed (see BoingRpcPreflightError.doctor).';
+        super(msg);
+        this.name = 'BoingRpcPreflightError';
+        this.doctor = doctor;
+        Object.setPrototypeOf(this, BoingRpcPreflightError.prototype);
+    }
+}
+export function isBoingRpcPreflightError(e) {
+    return e instanceof BoingRpcPreflightError;
+}
+/**
+ * Runs {@link doctorBoingRpcEnvironment}; throws {@link BoingRpcPreflightError} when **`ok`** is false.
+ * Use in dApp “connect” or before starting polling loops.
+ */
+export async function assertBoingRpcEnvironment(client, options) {
+    const doctor = await doctorBoingRpcEnvironment(client, options);
+    if (!doctor.ok) {
+        throw new BoingRpcPreflightError(doctor);
+    }
+    return doctor;
+}

package/dist/receiptLogs.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Helpers for execution logs on receipts and blocks (no `address` field — use `boing_getLogs` / {@link BoingClient.getLogs} when you need attributed contract ids).
+ */
+import type { Block, ExecutionLog, ExecutionReceipt } from './types.js';
+/** Normalize one 32-byte topic to lowercase `0x` + 64 hex (throws if invalid). */
+export declare function normalizeTopicWord(topic: string): string;
+/** Normalize `ExecutionLog` topics and data to lowercase hex with `0x`. */
+export declare function normalizeExecutionLog(log: ExecutionLog): ExecutionLog;
+/** `topics[0]` after normalize, or `undefined`. */
+export declare function logTopic0(log: ExecutionLog): string | undefined;
+export interface ReceiptLogRef {
+    receipt: ExecutionReceipt;
+    log: ExecutionLog;
+    logIndex: number;
+}
+/** Yield each log in a receipt (empty if none). */
+export declare function iterReceiptLogs(receipt: ExecutionReceipt): Generator<ReceiptLogRef>;
+/**
+ * Topic filter semantics (common log-RPC shape): `filter[i]` null/undefined = wildcard; otherwise exact match on `topics[i]` (normalized).
+ */
+export declare function logMatchesTopicFilter(log: ExecutionLog, filter: (string | null | undefined)[]): boolean;
+/** Optional `topic0` filter on receipt logs. */
+export declare function filterReceiptLogsByTopic0(receipt: ExecutionReceipt, topic0: string): ExecutionLog[];
+/**
+ * Walk `block.receipts` (same order as `transactions`) and emit every log with receipt context.
+ * Skips `null` receipt slots.
+ */
+export declare function iterBlockReceiptLogs(block: Block): Generator<ReceiptLogRef>;
+//# sourceMappingURL=receiptLogs.d.ts.map

package/dist/receiptLogs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receiptLogs.d.ts","sourceRoot":"","sources":["../src/receiptLogs.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAIxE,kFAAkF;AAClF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMxD;AAED,2EAA2E;AAC3E,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY,CAKrE;AAED,mDAAmD;AACnD,wBAAgB,SAAS,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,GAAG,SAAS,CAG/D;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,GAAG,EAAE,YAAY,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,mDAAmD;AACnD,wBAAiB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAAC,aAAa,CAAC,CAIpF;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,GAAG,OAAO,CASvG;AAED,gDAAgD;AAChD,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,MAAM,GACb,YAAY,EAAE,CAGhB;AAED;;;GAGG;AACH,wBAAiB,oBAAoB,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC,aAAa,CAAC,CAO5E"}

package/dist/receiptLogs.js

@@ -0,0 +1,66 @@
+/**
+ * Helpers for execution logs on receipts and blocks (no `address` field — use `boing_getLogs` / {@link BoingClient.getLogs} when you need attributed contract ids).
+ */
+import { ensureHex } from './hex.js';
+const TOPIC_HEX_RE = /^[0-9a-fA-F]{64}$/;
+/** Normalize one 32-byte topic to lowercase `0x` + 64 hex (throws if invalid). */
+export function normalizeTopicWord(topic) {
+    const raw = topic.trim().replace(/^0x/i, '');
+    if (raw.length !== 64 || !TOPIC_HEX_RE.test(raw)) {
+        throw new Error(`Topic must be 32 bytes (64 hex chars), got ${raw.length}`);
+    }
+    return '0x' + raw.toLowerCase();
+}
+/** Normalize `ExecutionLog` topics and data to lowercase hex with `0x`. */
+export function normalizeExecutionLog(log) {
+    return {
+        topics: log.topics.map((t) => normalizeTopicWord(t)),
+        data: ensureHex(log.data.trim().replace(/^0X/i, '0x')).toLowerCase(),
+    };
+}
+/** `topics[0]` after normalize, or `undefined`. */
+export function logTopic0(log) {
+    const t0 = log.topics[0];
+    return t0 != null ? normalizeTopicWord(t0) : undefined;
+}
+/** Yield each log in a receipt (empty if none). */
+export function* iterReceiptLogs(receipt) {
+    for (let logIndex = 0; logIndex < receipt.logs.length; logIndex++) {
+        yield { receipt, log: receipt.logs[logIndex], logIndex };
+    }
+}
+/**
+ * Topic filter semantics (common log-RPC shape): `filter[i]` null/undefined = wildcard; otherwise exact match on `topics[i]` (normalized).
+ */
+export function logMatchesTopicFilter(log, filter) {
+    for (let i = 0; i < filter.length; i++) {
+        const want = filter[i];
+        if (want == null)
+            continue;
+        const a = log.topics[i];
+        if (a == null)
+            return false;
+        if (normalizeTopicWord(a) !== normalizeTopicWord(want))
+            return false;
+    }
+    return true;
+}
+/** Optional `topic0` filter on receipt logs. */
+export function filterReceiptLogsByTopic0(receipt, topic0) {
+    const want = normalizeTopicWord(topic0);
+    return receipt.logs.filter((log) => logTopic0(log) === want);
+}
+/**
+ * Walk `block.receipts` (same order as `transactions`) and emit every log with receipt context.
+ * Skips `null` receipt slots.
+ */
+export function* iterBlockReceiptLogs(block) {
+    const receipts = block.receipts;
+    if (receipts == null)
+        return;
+    for (const receipt of receipts) {
+        if (receipt == null)
+            continue;
+        yield* iterReceiptLogs(receipt);
+    }
+}

package/dist/referenceFungibleSecuredDeployBytecode.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Build **`0xFD` + init** deploy payloads for the secured reference fungible, matching
+ * `boing_execution::reference_fungible_secured_deploy_bytecode` / init layout.
+ *
+ * Runtime bytes are pinned from `defaultReferenceFungibleSecuredRuntimeBytecodeHex.ts`
+ * (regenerated with `embed-reference-fungible-secured-template-hex.mjs`).
+ */
+import { type NativeTokenSecurityFeaturesInput } from './nativeTokenSecurity.js';
+/** Mirrors `reference_fungible_secured` flag words (u32). */
+export declare const FLAG_DENYLIST = 1;
+export declare const FLAG_MAX_TX = 2;
+export declare const FLAG_MAX_WALLET = 4;
+export declare const FLAG_ANTI_BOT = 8;
+export declare const FLAG_COOLDOWN = 16;
+export declare const FLAG_NO_MINT = 32;
+export declare const FLAG_TRANSFER_UNLOCK = 64;
+export type ReferenceFungibleSecuredConfigBytes = {
+    flags: number;
+    maxTx: bigint;
+    maxWallet: bigint;
+    antiBotExtraBlocks: bigint;
+    antiBotMaxAmount: bigint;
+    cooldownSecs: bigint;
+    transferUnlockHeight: bigint;
+    initialPaused: boolean;
+};
+/**
+ * Init bytecode only (no `0xFD` prefix), matching `reference_fungible_secured_init_bytecode`.
+ */
+export declare function referenceFungibleSecuredInitBytecode(config: ReferenceFungibleSecuredConfigBytes, runtime: Uint8Array): Uint8Array;
+/** Full deploy: `0xFD || init` (init `RETURN`s runtime). */
+export declare function referenceFungibleSecuredDeployBytecode(config: ReferenceFungibleSecuredConfigBytes, runtime?: Uint8Array): Uint8Array;
+export declare function referenceFungibleSecuredDeployBytecodeHex(config: ReferenceFungibleSecuredConfigBytes, runtime?: Uint8Array): `0x${string}`;
+export type SecuredWizardBuildContext = {
+    /**
+     * Current height from `boing_chainHeight` — **required** when `timelock` is enabled in
+     * `nativeTokenSecurity` so `transfer_unlock_height` can be set (`FLAG_TRANSFER_UNLOCK`).
+     */
+    chainHeight?: bigint;
+    /**
+     * Total supply (base units) planned for the initial `mint_first`, used with `maxWalletPercentage`
+     * / anti-whale percentage to derive `max_wallet`.
+     */
+    mintFirstTotalSupplyWei?: bigint;
+};
+/**
+ * Map wizard / `boing.native_token_security.v1` fields to secured init storage (on-chain enforcement).
+ *
+ * - **renounceOwnership**: not applied at deploy (admin is deployer); use admin `0x05` after deploy.
+ * - **timelock**: maps to transfer-unlock **block height** = `chainHeight + timelockDelay` (both decimals).
+ */
+export declare function referenceFungibleSecuredConfigFromNativeTokenSecurity(input: NativeTokenSecurityFeaturesInput | undefined, ctx?: SecuredWizardBuildContext): ReferenceFungibleSecuredConfigBytes;
+export declare function buildReferenceFungibleSecuredDeployBytecodeHexFromNativeTokenSecurity(input: NativeTokenSecurityFeaturesInput | undefined, ctx?: SecuredWizardBuildContext): `0x${string}`;
+//# sourceMappingURL=referenceFungibleSecuredDeployBytecode.d.ts.map

package/dist/referenceFungibleSecuredDeployBytecode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"referenceFungibleSecuredDeployBytecode.d.ts","sourceRoot":"","sources":["../src/referenceFungibleSecuredDeployBytecode.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAEL,KAAK,gCAAgC,EACtC,MAAM,0BAA0B,CAAC;AAqBlC,6DAA6D;AAC7D,eAAO,MAAM,aAAa,IAAO,CAAC;AAClC,eAAO,MAAM,WAAW,IAAO,CAAC;AAChC,eAAO,MAAM,eAAe,IAAO,CAAC;AACpC,eAAO,MAAM,aAAa,IAAO,CAAC;AAClC,eAAO,MAAM,aAAa,KAAO,CAAC;AAClC,eAAO,MAAM,YAAY,KAAO,CAAC;AACjC,eAAO,MAAM,oBAAoB,KAAO,CAAC;AAEzC,MAAM,MAAM,mCAAmC,GAAG;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,aAAa,EAAE,OAAO,CAAC;CACxB,CAAC;AAgFF;;GAEG;AACH,wBAAgB,oCAAoC,CAClD,MAAM,EAAE,mCAAmC,EAC3C,OAAO,EAAE,UAAU,GAClB,UAAU,CAgDZ;AAED,4DAA4D;AAC5D,wBAAgB,sCAAsC,CACpD,MAAM,EAAE,mCAAmC,EAC3C,OAAO,CAAC,EAAE,UAAU,GACnB,UAAU,CAMZ;AAED,wBAAgB,yCAAyC,CACvD,MAAM,EAAE,mCAAmC,EAC3C,OAAO,CAAC,EAAE,UAAU,GACnB,KAAK,MAAM,EAAE,CAEf;AAED,MAAM,MAAM,yBAAyB,GAAG;IACtC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC,CAAC;AA4BF;;;;;GAKG;AACH,wBAAgB,qDAAqD,CACnE,KAAK,EAAE,gCAAgC,GAAG,SAAS,EACnD,GAAG,GAAE,yBAA8B,GAClC,mCAAmC,CAoFrC;AAED,wBAAgB,qEAAqE,CACnF,KAAK,EAAE,gCAAgC,GAAG,SAAS,EACnD,GAAG,GAAE,yBAA8B,GAClC,KAAK,MAAM,EAAE,CAGf"}