@unicitylabs/bridge-plugin 0.2.0-dev.1

package/lib/address.js

@@ -0,0 +1,71 @@
+import { sha256 } from '@noble/hashes/sha2.js';
+import { fromHex, toHex } from './hex.js';
+const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+const BASE58_MAP = {};
+for (let i = 0; i < BASE58_ALPHABET.length; i++) {
+    BASE58_MAP[BASE58_ALPHABET[i]] = i;
+}
+/** Tron mainnet address prefix byte (0x41). */
+export const TRON_ADDRESS_PREFIX = 0x41;
+function base58Decode(input) {
+    const bytes = [0];
+    for (const ch of input) {
+        const value = BASE58_MAP[ch];
+        if (value === undefined) {
+            throw new Error(`Invalid base58 character: ${ch}`);
+        }
+        let carry = value;
+        for (let j = 0; j < bytes.length; j++) {
+            carry += bytes[j] * 58;
+            bytes[j] = carry & 0xff;
+            carry >>= 8;
+        }
+        while (carry > 0) {
+            bytes.push(carry & 0xff);
+            carry >>= 8;
+        }
+    }
+    // Leading '1's encode leading zero bytes.
+    for (let k = 0; k < input.length && input[k] === '1'; k++) {
+        bytes.push(0);
+    }
+    return Uint8Array.from(bytes.reverse());
+}
+/**
+ * Normalize any source-chain address form to the 20-byte EVM-style address as
+ * lowercase hex (no `0x`, no `41` prefix), the form event logs use for `address`
+ * on both families.
+ *
+ * Accepts:
+ *  - Tron base58check `T...` addresses,
+ *  - Tron `41`-prefixed 21-byte hex (TronWeb `toHex()` form),
+ *  - bare 20-byte hex, optionally `0x`-prefixed (Ethereum, or either family's raw form).
+ */
+export function toEvmAddressHex(address) {
+    if (address.startsWith('T')) {
+        const decoded = base58Decode(address);
+        if (decoded.length !== 25) {
+            throw new Error(`Invalid Tron base58 address length: ${address}`);
+        }
+        const payload = decoded.subarray(0, 21);
+        const checksum = decoded.subarray(21);
+        const expected = sha256(sha256(payload)).subarray(0, 4);
+        for (let i = 0; i < 4; i++) {
+            if (checksum[i] !== expected[i]) {
+                throw new Error(`Bad checksum for Tron address: ${address}`);
+            }
+        }
+        if (payload[0] !== TRON_ADDRESS_PREFIX) {
+            throw new Error(`Unexpected Tron address prefix: ${address}`);
+        }
+        return toHex(payload.subarray(1));
+    }
+    const bytes = fromHex(address);
+    if (bytes.length === 21 && bytes[0] === TRON_ADDRESS_PREFIX) {
+        return toHex(bytes.subarray(1));
+    }
+    if (bytes.length === 20) {
+        return toHex(bytes);
+    }
+    throw new Error(`Unrecognized address form: ${address}`);
+}

package/lib/bridge-back/abi.d.ts

@@ -0,0 +1,30 @@
+export type Val = {
+    t: 'str';
+    v: string;
+} | {
+    t: 'u32';
+    v: number | bigint;
+} | {
+    t: 'u64';
+    v: number | bigint;
+} | {
+    t: 'u256';
+    v: bigint;
+} | {
+    t: 'addr';
+    v: Uint8Array;
+} | {
+    t: 'b32';
+    v: Uint8Array;
+};
+export declare const Str: (v: string) => Val;
+export declare const U32: (v: number | bigint) => Val;
+export declare const U64: (v: number | bigint) => Val;
+export declare const U256: (v: bigint) => Val;
+export declare const Addr: (v: Uint8Array) => Val;
+export declare const B32: (v: Uint8Array) => Val;
+export declare function keccak256(input: Uint8Array): Uint8Array;
+/** Solidity `abi.encode(vals...)` with proper head/tail framing. */
+export declare function encode(vals: Val[]): Uint8Array;
+/** Concatenated fixed-width 32-byte words, no array framing (00 §7). */
+export declare function packWords(vals: Val[]): Uint8Array;

package/lib/bridge-back/abi.js

@@ -0,0 +1,89 @@
+/**
+ * Minimal Solidity `abi.encode` for the static types the vault recomputes, plus
+ * the single dynamic `string` domain literal used inside `configHash`/`lockDigest`.
+ *
+ * Mirrors `protocol/vectors/gen/src/abi.rs` byte-for-byte (interop §1, §7). `encode`
+ * does proper head/tail framing; `packWords` is the non-framed 32-byte-word
+ * concatenation the vault keccak-hashes for `returnRoot`/`lockRefRoot`.
+ */
+import { keccak_256 } from '@noble/hashes/sha3.js';
+export const Str = (v) => ({ t: 'str', v });
+export const U32 = (v) => ({ t: 'u32', v });
+export const U64 = (v) => ({ t: 'u64', v });
+export const U256 = (v) => ({ t: 'u256', v });
+export const Addr = (v) => ({ t: 'addr', v });
+export const B32 = (v) => ({ t: 'b32', v });
+export function keccak256(input) {
+    return keccak_256(input);
+}
+/** 32-byte big-endian word for a small unsigned integer. */
+function wordU(n) {
+    const w = new Uint8Array(32);
+    for (let i = 0; i < 32 && n > 0n; i++) {
+        w[31 - i] = Number(n & 0xffn);
+        n >>= 8n;
+    }
+    return w;
+}
+/** The 32-byte head word for a static value (numbers/addresses left-padded). */
+function staticWord(v) {
+    switch (v.t) {
+        case 'u32':
+        case 'u64':
+            return wordU(BigInt(v.v));
+        case 'u256':
+            return wordU(v.v);
+        case 'addr': {
+            if (v.v.length !== 20)
+                throw new Error('addr must be 20 bytes');
+            const w = new Uint8Array(32);
+            w.set(v.v, 12);
+            return w;
+        }
+        case 'b32': {
+            if (v.v.length !== 32)
+                throw new Error('b32 must be 32 bytes');
+            return v.v.slice();
+        }
+        case 'str':
+            throw new Error('dynamic value has no head word');
+    }
+}
+function concat(parts) {
+    let len = 0;
+    for (const p of parts)
+        len += p.length;
+    const out = new Uint8Array(len);
+    let off = 0;
+    for (const p of parts) {
+        out.set(p, off);
+        off += p.length;
+    }
+    return out;
+}
+/** Solidity `abi.encode(vals...)` with proper head/tail framing. */
+export function encode(vals) {
+    const headSize = 32 * vals.length;
+    const heads = [];
+    const tails = [];
+    let tailLen = 0;
+    for (const v of vals) {
+        if (v.t === 'str') {
+            heads.push(wordU(BigInt(headSize + tailLen)));
+            const data = new TextEncoder().encode(v.v);
+            const padded = new Uint8Array(Math.ceil(data.length / 32) * 32);
+            padded.set(data);
+            const piece = concat([wordU(BigInt(data.length)), padded]);
+            tails.push(piece);
+            tailLen += piece.length;
+        }
+        else {
+            heads.push(staticWord(v));
+        }
+    }
+    return concat([...heads, ...tails]);
+}
+/** Concatenated fixed-width 32-byte words, no array framing (00 §7). */
+export function packWords(vals) {
+    return concat(vals.map(staticWord));
+}

package/lib/bridge-back/burn.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Bridge-back burn construction (02-ts-sdk-and-wallet.md §2a–2c).
+ *
+ * The wallet burns the source token so the terminal transfer carries the
+ * canonical `reasonBytes` in its **auxiliary data** and its recipient predicate
+ * is `BurnPredicate(H(reasonBytes))` — *not* `BurnPredicate(reasonBytes)` (00 §4).
+ * The reason is then fully self-contained in the burned blob: the circuit reads
+ * `reasonBytes` from the certified aux data, recomputes `reasonHash`, requires
+ * the terminal predicate to equal `BurnPredicate(reasonHash)`, and decodes the
+ * fields. This module produces exactly those bytes plus the read-only return
+ * preview and the prover hand-off envelope. It holds no authority and never
+ * proves or settles.
+ */
+import { BurnPredicate } from '@unicitylabs/state-transition-sdk/lib/predicate/builtin/BurnPredicate.js';
+import type { Token } from '@unicitylabs/state-transition-sdk/lib/transaction/Token.js';
+import { TransferTransaction } from '@unicitylabs/state-transition-sdk/lib/transaction/TransferTransaction.js';
+import { type BridgeBackReason, type BridgeConfig, type ReturnLeaf } from './derivations.js';
+/** The reason bytes + the predicate that binds them, ready to attach to a burn. */
+export interface BridgeBackBurnReason {
+    /** Canonical `BridgeBackReason` CBOR; rides in the burn transfer's aux data. */
+    readonly reasonBytes: Uint8Array;
+    /** `H(reasonBytes)` — the payload of the binding {BurnPredicate}. */
+    readonly reasonHash: Uint8Array;
+    /** `BurnPredicate(H(reasonBytes))` — the terminal recipient predicate. */
+    readonly burnPredicate: BurnPredicate;
+}
+/**
+ * Build the canonical reason + its binding {BurnPredicate}. Pure (no SDK token
+ * needed) so a wallet can preview the exact bytes before committing the burn.
+ */
+export declare function buildBridgeBackBurnReason(c: BridgeConfig, r: BridgeBackReason): BridgeBackBurnReason;
+/**
+ * Construct the terminal burn transfer for `token`: recipient is
+ * `BurnPredicate(H(reasonBytes))` and the aux data is the canonical
+ * `reasonBytes`. For a partial return, split first (existing split flow) and
+ * pass the child whose value equals `amount`. The caller certifies/submits this
+ * transfer through its normal SDK path; the resulting burned blob is the
+ * release-authorizing recovery material (ZK_BACK3 §13).
+ *
+ * @param token     The (whole) token to burn.
+ * @param c         Deployment config (binds the reason's config fields).
+ * @param r         The return parameters (recipient/amount/fee/deadline).
+ * @param stateMask State mask mixed into the new state (per the SDK transfer API).
+ */
+export declare function createBridgeBackBurnTransfer(token: Token, c: BridgeConfig, r: BridgeBackReason, stateMask: Uint8Array): Promise<{
+    transfer: TransferTransaction;
+    reason: BridgeBackBurnReason;
+}>;
+/** The read-only return preview the wallet shows the user (02 §2b). */
+export interface ReturnPreview {
+    readonly burnTransitionId: Uint8Array;
+    readonly nullifier: Uint8Array;
+    readonly returnLeaf: ReturnLeaf;
+}
+/**
+ * Derive the pending nullifier + settlement leaf for a burn, given the certified
+ * burn state id / tx hash (available once the burn is certified). Read-only:
+ * the prover computes the identical values, and a TS relayer reuses this (02 §2b).
+ */
+export declare function previewReturn(configHash: Uint8Array, r: BridgeBackReason, burnStateId: Uint8Array, burnTxHash: Uint8Array): ReturnPreview;
+/**
+ * The witness-request envelope the wallet/relayer posts to a prover (02 §2c).
+ * The wallet supplies only what it owns; the prover fetches anchor + inclusion
+ * proofs itself. `reasonBytes` are included for convenience, but they are also
+ * recoverable from `tokenCbor` (the burn's aux data) — the blob is self-contained.
+ */
+export interface WitnessRequest {
+    readonly tokenCbor: Uint8Array;
+    readonly configHash: Uint8Array;
+    readonly reasonBytes: Uint8Array;
+    readonly anchorHint?: bigint;
+}
+/** Assemble the prover hand-off envelope. */
+export declare function buildWitnessRequest(args: {
+    tokenCbor: Uint8Array;
+    configHash: Uint8Array;
+    reasonBytes: Uint8Array;
+    anchorHint?: bigint;
+}): WitnessRequest;

package/lib/bridge-back/burn.js

@@ -0,0 +1,78 @@
+/**
+ * Bridge-back burn construction (02-ts-sdk-and-wallet.md §2a–2c).
+ *
+ * The wallet burns the source token so the terminal transfer carries the
+ * canonical `reasonBytes` in its **auxiliary data** and its recipient predicate
+ * is `BurnPredicate(H(reasonBytes))` — *not* `BurnPredicate(reasonBytes)` (00 §4).
+ * The reason is then fully self-contained in the burned blob: the circuit reads
+ * `reasonBytes` from the certified aux data, recomputes `reasonHash`, requires
+ * the terminal predicate to equal `BurnPredicate(reasonHash)`, and decodes the
+ * fields. This module produces exactly those bytes plus the read-only return
+ * preview and the prover hand-off envelope. It holds no authority and never
+ * proves or settles.
+ */
+import { BurnPredicate } from '@unicitylabs/state-transition-sdk/lib/predicate/builtin/BurnPredicate.js';
+import { StateMask } from '@unicitylabs/state-transition-sdk/lib/transaction/StateMask.js';
+import { TransferTransaction } from '@unicitylabs/state-transition-sdk/lib/transaction/TransferTransaction.js';
+import { burnTransitionId, encodeBridgeBackReason, nullifier as deriveNullifier, reasonHash as deriveReasonHash, } from './derivations.js';
+/**
+ * Build the canonical reason + its binding {BurnPredicate}. Pure (no SDK token
+ * needed) so a wallet can preview the exact bytes before committing the burn.
+ */
+export function buildBridgeBackBurnReason(c, r) {
+    const reasonBytes = encodeBridgeBackReason(c, r);
+    const reasonHash = deriveReasonHash(reasonBytes);
+    return {
+        reasonBytes,
+        reasonHash,
+        burnPredicate: BurnPredicate.create(reasonHash),
+    };
+}
+/**
+ * Construct the terminal burn transfer for `token`: recipient is
+ * `BurnPredicate(H(reasonBytes))` and the aux data is the canonical
+ * `reasonBytes`. For a partial return, split first (existing split flow) and
+ * pass the child whose value equals `amount`. The caller certifies/submits this
+ * transfer through its normal SDK path; the resulting burned blob is the
+ * release-authorizing recovery material (ZK_BACK3 §13).
+ *
+ * @param token     The (whole) token to burn.
+ * @param c         Deployment config (binds the reason's config fields).
+ * @param r         The return parameters (recipient/amount/fee/deadline).
+ * @param stateMask State mask mixed into the new state (per the SDK transfer API).
+ */
+export async function createBridgeBackBurnTransfer(token, c, r, stateMask) {
+    const reason = buildBridgeBackBurnReason(c, r);
+    const transfer = await TransferTransaction.create(token, reason.burnPredicate, StateMask.fromBytes(stateMask), { data: reason.reasonBytes });
+    return { transfer, reason };
+}
+/**
+ * Derive the pending nullifier + settlement leaf for a burn, given the certified
+ * burn state id / tx hash (available once the burn is certified). Read-only:
+ * the prover computes the identical values, and a TS relayer reuses this (02 §2b).
+ */
+export function previewReturn(configHash, r, burnStateId, burnTxHash) {
+    const btId = burnTransitionId(burnStateId, burnTxHash);
+    const nullifier = deriveNullifier(configHash, btId);
+    return {
+        burnTransitionId: btId,
+        nullifier,
+        returnLeaf: {
+            nullifier,
+            recipient: r.recipient,
+            amount: r.amount,
+            feeRecipient: r.feeRecipient,
+            feeAmount: r.feeAmount,
+            deadline: r.deadline,
+        },
+    };
+}
+/** Assemble the prover hand-off envelope. */
+export function buildWitnessRequest(args) {
+    const req = {
+        tokenCbor: args.tokenCbor,
+        configHash: args.configHash,
+        reasonBytes: args.reasonBytes,
+    };
+    return args.anchorHint === undefined ? req : { ...req, anchorHint: args.anchorHint };
+}

package/lib/bridge-back/burned-blob.d.ts

@@ -0,0 +1,6 @@
+export interface BurnIdentifiers {
+    readonly burnStateId: Uint8Array;
+    readonly burnTxHash: Uint8Array;
+    readonly reasonBytes: Uint8Array;
+}
+export declare function burnIdentifiers(burnedToken: Uint8Array): Promise<BurnIdentifiers>;

package/lib/bridge-back/burned-blob.js

@@ -0,0 +1,16 @@
+import { StateId } from '@unicitylabs/state-transition-sdk/lib/api/StateId.js';
+import { Token } from '@unicitylabs/state-transition-sdk/lib/transaction/Token.js';
+export async function burnIdentifiers(burnedToken) {
+    const token = await Token.fromCBOR(burnedToken);
+    const burn = token.transactions.at(-1);
+    if (!burn)
+        throw new Error('burnIdentifiers: the blob has no transfer; it is not a burned token');
+    const reasonBytes = burn.data;
+    if (!reasonBytes)
+        throw new Error('burnIdentifiers: the terminal transfer carries no reason bytes');
+    return {
+        burnStateId: (await StateId.fromTransaction(burn)).data,
+        burnTxHash: (await burn.calculateTransactionHash()).data,
+        reasonBytes: new Uint8Array(reasonBytes),
+    };
+}

package/lib/bridge-back/cbor.d.ts

@@ -0,0 +1,32 @@
+declare function concat(parts: Uint8Array[]): Uint8Array;
+/** major type 0: unsigned integer. */
+export declare function uint(n: number | bigint): Uint8Array;
+/** major type 2: byte string. */
+export declare function bytes(b: Uint8Array): Uint8Array;
+/** major type 3: text string. */
+export declare function text(s: string): Uint8Array;
+/** major type 4: array header (followed by `len` items). */
+export declare function arrayHeader(len: number): Uint8Array;
+/** major type 6: semantic tag. */
+export declare function tag(t: number | bigint): Uint8Array;
+/** Concatenate pre-encoded CBOR items. */
+export { concat as concatBytes };
+/** `H(fields...) = SHA-256( CBOR-array(fields) )` (00 §8 / appendix convention). */
+export declare function hArray(items: Uint8Array[]): Uint8Array;
+/** Strip leading zero bytes (minimal big-endian); zero becomes the empty string. */
+export declare function minimalBe(b: Uint8Array): Uint8Array;
+/** A cursor over CBOR bytes. */
+export declare class CborReader {
+    readonly buf: Uint8Array;
+    pos: number;
+    constructor(buf: Uint8Array);
+    get done(): boolean;
+    /** Read one item head; returns its major type and argument. Rejects
+     *  non-minimal (non-canonical) argument encodings. */
+    private head;
+    private expect;
+    readTag(): bigint;
+    readArrayHeader(): number;
+    readUint(): bigint;
+    readBytes(): Uint8Array;
+}

package/lib/bridge-back/cbor.js

@@ -0,0 +1,146 @@
+/**
+ * Minimal deterministic (canonical) CBOR encoder — only the item types the
+ * bridge structures use: definite-length, minimal-length integer arguments.
+ *
+ * This mirrors `protocol/vectors/gen/src/cbor.rs` byte-for-byte; it is the TS half
+ * of the cross-stack contract (00 §4, §5, §8). `H(...)` is SHA-256 over a CBOR
+ * array of fields. Conformance is asserted against `protocol/vectors/{reason,
+ * nullifier}` — do not "improve" the encoding without bumping BRIDGE_PROTO_VERSION.
+ */
+import { sha256 } from '@noble/hashes/sha2.js';
+/** major<<5 | argument, minimal-length per canonical CBOR. */
+function head(major, arg) {
+    const m = major << 5;
+    const n = BigInt(arg);
+    if (n < 24n)
+        return Uint8Array.of(m | Number(n));
+    if (n <= 0xffn)
+        return Uint8Array.of(m | 24, Number(n));
+    if (n <= 0xffffn) {
+        return Uint8Array.of(m | 25, Number((n >> 8n) & 0xffn), Number(n & 0xffn));
+    }
+    if (n <= 0xffffffffn) {
+        return Uint8Array.of(m | 26, Number((n >> 24n) & 0xffn), Number((n >> 16n) & 0xffn), Number((n >> 8n) & 0xffn), Number(n & 0xffn));
+    }
+    const out = new Uint8Array(9);
+    out[0] = m | 27;
+    for (let i = 0; i < 8; i++)
+        out[8 - i] = Number((n >> BigInt(8 * i)) & 0xffn);
+    return out;
+}
+function concat(parts) {
+    let len = 0;
+    for (const p of parts)
+        len += p.length;
+    const out = new Uint8Array(len);
+    let off = 0;
+    for (const p of parts) {
+        out.set(p, off);
+        off += p.length;
+    }
+    return out;
+}
+/** major type 0: unsigned integer. */
+export function uint(n) {
+    return head(0, n);
+}
+/** major type 2: byte string. */
+export function bytes(b) {
+    return concat([head(2, b.length), b]);
+}
+/** major type 3: text string. */
+export function text(s) {
+    const enc = new TextEncoder().encode(s);
+    return concat([head(3, enc.length), enc]);
+}
+/** major type 4: array header (followed by `len` items). */
+export function arrayHeader(len) {
+    return head(4, len);
+}
+/** major type 6: semantic tag. */
+export function tag(t) {
+    return head(6, t);
+}
+/** Concatenate pre-encoded CBOR items. */
+export { concat as concatBytes };
+/** `H(fields...) = SHA-256( CBOR-array(fields) )` (00 §8 / appendix convention). */
+export function hArray(items) {
+    return sha256(concat([arrayHeader(items.length), ...items]));
+}
+/** Strip leading zero bytes (minimal big-endian); zero becomes the empty string. */
+export function minimalBe(b) {
+    let first = 0;
+    while (first < b.length && b[first] === 0)
+        first++;
+    return b.slice(first);
+}
+// --- canonical reader (decode side) ----------------------------------------
+// Only the item types the bridge structures use, with strict canonical checks:
+// minimal-length argument, no trailing bytes (the caller asserts full
+// consumption). Mirrors the encoder above so a blob round-trips exactly.
+/** A cursor over CBOR bytes. */
+export class CborReader {
+    buf;
+    pos = 0;
+    constructor(buf) {
+        this.buf = buf;
+    }
+    get done() {
+        return this.pos >= this.buf.length;
+    }
+    /** Read one item head; returns its major type and argument. Rejects
+     *  non-minimal (non-canonical) argument encodings. */
+    head() {
+        if (this.done)
+            throw new Error('CBOR: unexpected end');
+        const ib = this.buf[this.pos++];
+        const major = ib >> 5;
+        const ai = ib & 0x1f;
+        if (ai < 24)
+            return { major, arg: BigInt(ai) };
+        let len;
+        if (ai === 24)
+            len = 1;
+        else if (ai === 25)
+            len = 2;
+        else if (ai === 26)
+            len = 4;
+        else if (ai === 27)
+            len = 8;
+        else
+            throw new Error(`CBOR: bad additional info ${ai}`);
+        if (this.pos + len > this.buf.length)
+            throw new Error('CBOR: truncated argument');
+        let arg = 0n;
+        for (let i = 0; i < len; i++)
+            arg = (arg << 8n) | BigInt(this.buf[this.pos++]);
+        // canonical: the value must not fit in a shorter encoding
+        const min = ai === 24 ? 24n : ai === 25 ? 0x100n : ai === 26 ? 0x10000n : 0x100000000n;
+        if (arg < min)
+            throw new Error('CBOR: non-canonical (non-minimal) integer');
+        return { major, arg };
+    }
+    expect(major, what) {
+        const h = this.head();
+        if (h.major !== major)
+            throw new Error(`CBOR: expected ${what} (major ${major}), got major ${h.major}`);
+        return h.arg;
+    }
+    readTag() {
+        return this.expect(6, 'tag');
+    }
+    readArrayHeader() {
+        return Number(this.expect(4, 'array'));
+    }
+    readUint() {
+        return this.expect(0, 'uint');
+    }
+    readBytes() {
+        const len = Number(this.expect(2, 'byte string'));
+        if (this.pos + len > this.buf.length)
+            throw new Error('CBOR: truncated byte string');
+        const out = this.buf.slice(this.pos, this.pos + len);
+        this.pos += len;
+        return out;
+    }
+}

package/lib/bridge-back/derivations.d.ts

@@ -0,0 +1,112 @@
+export declare const DOMAIN_CONFIG = "unicity-bridge-return-config:v1";
+export declare const DOMAIN_LOCK = "unicity-bridge-lock:v1";
+export declare const DOMAIN_RETURN = "unicity-bridge-return:v1";
+export declare const DOMAIN_BURN_TRANSITION = "unicity-burn-transition:v1";
+export declare const DOMAIN_NULLIFIER = "unicity-bridge-return-nullifier:v1";
+/** Deployment configuration (00 §2). Byte fields are raw (no `0x`). */
+export interface BridgeConfig {
+    readonly sourceChainId: bigint;
+    readonly vault: Uint8Array;
+    readonly asset: Uint8Array;
+    readonly tokenType: Uint8Array;
+    readonly coinId: Uint8Array;
+    readonly reasonTag: bigint;
+    readonly lockDomain: Uint8Array;
+    readonly nullifierDomain: Uint8Array;
+}
+/** 32-byte big-endian representation of an unsigned integer. */
+export declare function u256be(n: bigint): Uint8Array;
+/** `configHash = K(abi.encode("...config:v1", fields...))` (00 §2). */
+export declare function configHash(c: BridgeConfig): Uint8Array;
+/** `domainTag = K("unicity-bridge-return:v1")` over raw bytes (00 §7). */
+export declare function domainTag(): Uint8Array;
+/** `lockDigest = K(abi.encode("...lock:v1", fields...))` (00 §3). */
+export declare function lockDigest(params: {
+    sourceChainId: bigint;
+    vault: Uint8Array;
+    nonce: bigint;
+    asset: Uint8Array;
+    tokenType: Uint8Array;
+    coinId: Uint8Array;
+    amount: bigint;
+    unicityTokenId: Uint8Array;
+    recipientCommitment: Uint8Array;
+}): Uint8Array;
+/** Per-return parameters of a `BridgeBackReason` (00 §4); config-bound fields
+ *  (sourceChainId/vault/asset/tokenType/coinId) come from {BridgeConfig}. */
+export interface BridgeBackReason {
+    readonly version: bigint;
+    readonly recipient: Uint8Array;
+    readonly amount: bigint;
+    readonly feeRecipient: Uint8Array;
+    readonly feeAmount: bigint;
+    readonly deadline: bigint;
+}
+/**
+ * Canonical CBOR of the 11-field `BridgeBackReason` array under `reasonTag`
+ * (00 §4). This is the `reasonBytes` that ride in the terminal burn's auxiliary
+ * data; the burn predicate binds `H(reasonBytes)` (see {reasonHash}).
+ */
+export declare function encodeBridgeBackReason(c: BridgeConfig, r: BridgeBackReason): Uint8Array;
+/** `reasonHash = H(reasonBytes)` — the value `BurnPredicate(H(reasonBytes))`
+ *  binds (00 §4, PROVISIONAL preimage pending M0 SDK confirmation). */
+export declare function reasonHash(reasonBytes: Uint8Array): Uint8Array;
+/** The fully-decoded `BridgeBackReason`, including its config-bound fields. */
+export interface DecodedBridgeBackReason {
+    readonly reasonTag: bigint;
+    readonly version: bigint;
+    readonly sourceChainId: bigint;
+    readonly vault: Uint8Array;
+    readonly asset: Uint8Array;
+    readonly tokenType: Uint8Array;
+    readonly coinId: Uint8Array;
+    readonly recipient: Uint8Array;
+    readonly amount: bigint;
+    readonly feeRecipient: Uint8Array;
+    readonly feeAmount: bigint;
+    readonly deadline: bigint;
+}
+/**
+ * Inverse of {encodeBridgeBackReason}: decode the canonical `reasonBytes` a
+ * burned token blob carries (the circuit performs the same decode). Strict —
+ * rejects non-canonical CBOR and any trailing bytes (00 §4). `amount`/`feeAmount`
+ * come back as the minimal-big-endian byte strings re-read as integers.
+ */
+export declare function decodeBridgeBackReason(reasonBytes: Uint8Array): DecodedBridgeBackReason;
+/** `burnTransitionId = H("unicity-burn-transition:v1", stateId, txHash)` (00 §5). */
+export declare function burnTransitionId(stateId: Uint8Array, txHash: Uint8Array): Uint8Array;
+/** `nullifier = H("...nullifier:v1", configHash, burnTransitionId)` (00 §5). */
+export declare function nullifier(configHashBytes: Uint8Array, burnTransitionIdBytes: Uint8Array): Uint8Array;
+/** One settlement leaf committed by `returnRoot`, in submission order (00 §7). */
+export interface ReturnLeaf {
+    readonly nullifier: Uint8Array;
+    readonly recipient: Uint8Array;
+    readonly amount: bigint;
+    readonly feeRecipient: Uint8Array;
+    readonly feeAmount: bigint;
+    readonly deadline: bigint;
+}
+/** `returnRoot = K( concat of fixed-width abi.encode(leaf) )` (00 §7). */
+export declare function returnRoot(leaves: ReturnLeaf[]): Uint8Array;
+/** One source-lock reference committed by `lockRefRoot` (00 §7). */
+export interface SourceLockRef {
+    readonly nonce: bigint;
+    readonly digest: Uint8Array;
+}
+/** `lockRefRoot = K( concat of fixed-width abi.encode(ref) )`, sorted by nonce
+ *  with duplicates rejected (00 §7). */
+export declare function lockRefRoot(refs: SourceLockRef[]): Uint8Array;
+/** The public statement the circuit commits and the vault decodes (00 §7). */
+export interface PublicValues {
+    readonly domainTag: Uint8Array;
+    readonly configHash: Uint8Array;
+    readonly trustBaseHash: Uint8Array;
+    readonly spentRootOld: Uint8Array;
+    readonly spentRootNew: Uint8Array;
+    readonly returnRoot: Uint8Array;
+    readonly lockRefRoot: Uint8Array;
+    readonly batchSize: number;
+    readonly totalAmount: bigint;
+}
+/** `abi.encode(PublicValues)` — the all-static layout the vault abi.decodes (00 §7). */
+export declare function publicValuesAbi(p: PublicValues): Uint8Array;