@unicitylabs/bridge-plugin 0.2.0-dev.1

package/lib/tron/signer.js

@@ -0,0 +1,238 @@
+const DEFAULT_FEE_LIMIT_SUN = 150_000_000; // 150 TRX — generous cap; Nile calls cost far less.
+const SIGN_TIMEOUT_MS = 120_000;
+const BROADCAST_TIMEOUT_MS = 45_000;
+/**
+ * Tron's chainId (as used by the bridge config, e.g. Nile `3448148188`) is the
+ * low 4 bytes of the genesis block's `blockID`. Deriving it from the wallet's
+ * connected node is a real network identity — not the manifest echoing itself.
+ */
+export function chainIdFromGenesisBlockId(blockId) {
+    const h = blockId.replace(/^0x/i, '');
+    if (h.length < 8)
+        throw new Error(`Malformed genesis blockID: ${blockId}`);
+    return parseInt(h.slice(-8), 16);
+}
+/**
+ * TronLink-backed signer (priority 1). Uses the injected `window.tronWeb` for
+ * building + broadcasting; `tron_requestAccounts` prompts the connection once.
+ */
+export class TronLinkSigner {
+    win;
+    expectedChainId;
+    /** True once `connect()` has prompted; `getAddress()` then reads live silently. */
+    connected = false;
+    constructor(
+    /** The injected window (defaults to the global one in a browser). */
+    win = globalThis, 
+    /** Expected Tron chainId (from the manifest) — for the caller's wrong-network message. */
+    expectedChainId) {
+        this.win = win;
+        this.expectedChainId = expectedChainId;
+    }
+    tronWeb() {
+        const tw = this.win.tronWeb;
+        if (!tw) {
+            throw new Error('TronLink not found. Install the TronLink extension and reload.');
+        }
+        return tw;
+    }
+    async connect() {
+        // Prompt the connection once if TronLink is present but not yet authorized.
+        if (this.win.tronLink) {
+            await this.win.tronLink.request({ method: 'tron_requestAccounts' });
+        }
+        const addr = this.tronWeb().defaultAddress.base58;
+        if (!addr) {
+            throw new Error('TronLink is locked or no account is selected.');
+        }
+        this.connected = true;
+        return addr;
+    }
+    async getAddress() {
+        // Read the wallet's *current* account live (silent) — no cache, so a mid-flow
+        // account switch is visible to the pre-signature guard (08 §1.4). Only
+        // `connect()` ever prompts.
+        const addr = this.tronWeb().defaultAddress.base58;
+        if (addr) {
+            this.connected = true;
+            return addr;
+        }
+        if (!this.connected)
+            return this.connect();
+        throw new Error('TronLink is locked or no account is selected.');
+    }
+    async getNetwork() {
+        // Derive the wallet node's *current* chainId live (no cache) — a network
+        // switch changes the injected node, and the guard must see it (08 §1.4).
+        const trx = this.tronWeb().trx;
+        if (!trx.getBlockByNumber) {
+            throw new Error('This Tron wallet cannot report its network (no genesis access); cannot verify the chain.');
+        }
+        const genesis = await trx.getBlockByNumber(0);
+        const blockId = genesis?.blockID;
+        if (!blockId) {
+            throw new Error('Could not read the wallet node’s genesis block to determine the network.');
+        }
+        return chainIdFromGenesisBlockId(blockId);
+    }
+    onChange(cb) {
+        const win = this.win;
+        if (!win.addEventListener || !win.removeEventListener)
+            return () => { };
+        const listener = (e) => {
+            // TronLink relays wallet state via window 'message' events.
+            const action = e?.data?.message?.action;
+            if (action === 'accountsChanged' || action === 'setAccount') {
+                cb({ kind: 'accountsChanged' });
+            }
+            else if (action === 'setNode' || action === 'connectWeb' || action === 'chainChanged') {
+                cb({ kind: 'chainChanged' });
+            }
+            else if (action === 'disconnect' || action === 'disconnectWeb') {
+                this.connected = false;
+                cb({ kind: 'disconnect' });
+            }
+        };
+        win.addEventListener('message', listener);
+        return () => win.removeEventListener?.('message', listener);
+    }
+    /** The manifest's expected chainId, for building a clear wrong-network message. */
+    get expected() {
+        return this.expectedChainId;
+    }
+    async sendCall(call, opts = {}) {
+        return sendCallVia(this.tronWeb(), await this.getAddress(), call, opts);
+    }
+}
+function tronHex(hex) {
+    return '41' + hex.replace(/^0x/i, '').toLowerCase();
+}
+/**
+ * Build → **sign (via `sign`)** → broadcast a call over any {InjectedTronWeb} (the
+ * dApp-broadcast model). The build + broadcast use `tw`; only the signature is the
+ * wallet's concern — so this serves both the injected path (`tw.trx.sign`) and
+ * adapter/WalletConnect (the adapter's `signTransaction`).
+ */
+export async function sendCallSigned(tw, issuerBase58, call, sign, opts = {}) {
+    const built = await tw.transactionBuilder.triggerSmartContract(tronHex(call.contractHex), call.functionSignature, { feeLimit: opts.feeLimitSun ?? DEFAULT_FEE_LIMIT_SUN, callValue: opts.callValueSun ?? 0 }, call.parameters.map((p) => (p.type === 'address' ? { type: p.type, value: tronHex(p.value) } : { type: p.type, value: p.value })), tw.address.toHex(issuerBase58));
+    if (built.result && built.result.result === false) {
+        throw new Error(`Tron call ${call.functionSignature} could not be built (constant-call reverted).`);
+    }
+    const signed = normalizeSignedTransaction(await withTimeout(sign(built.transaction), SIGN_TIMEOUT_MS, `Timed out waiting for wallet signature for ${call.functionSignature}.`), call.functionSignature);
+    const receipt = await withTimeout(tw.trx.sendRawTransaction(signed), BROADCAST_TIMEOUT_MS, `Timed out broadcasting ${call.functionSignature} to Tron.`);
+    // Reject an explicit broadcast failure (SIGERROR, DUP_TRANSACTION, …) instead
+    // of returning a phantom txid the caller would then wait on forever (08 §1.4).
+    if (receipt.result === false) {
+        throw new Error(`Tron broadcast of ${call.functionSignature} was rejected: ${JSON.stringify(receipt)}`);
+    }
+    const txid = receipt.txid ?? receipt.transaction?.txID;
+    if (!txid) {
+        throw new Error(`Tron broadcast of ${call.functionSignature} returned no txid: ${JSON.stringify(receipt)}`);
+    }
+    return txid;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function hasSignatureArray(value) {
+    return isRecord(value) && Array.isArray(value.signature);
+}
+function normalizeSignedTransaction(value, functionSignature) {
+    if (hasSignatureArray(value))
+        return value;
+    if (isRecord(value)) {
+        for (const key of ['transaction', 'signedTransaction', 'signed_transaction', 'tx']) {
+            const nested = value[key];
+            if (hasSignatureArray(nested))
+                return nested;
+        }
+    }
+    throw new Error(`Wallet returned an unsigned or unsupported transaction for ${functionSignature}; ` +
+        'expected a signed Tron transaction object with a signature array.');
+}
+function withTimeout(promise, timeoutMs, message) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(message)), timeoutMs);
+    });
+    return Promise.race([promise, timeout]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+    });
+}
+/**
+ * Shared build → sign → broadcast over any {InjectedTronWeb} (the dApp-broadcast
+ * model). TronLink prompts on `trx.sign`; a key-bearing TronWeb signs silently.
+ */
+export function sendCallVia(tw, issuerBase58, call, opts = {}) {
+    return sendCallSigned(tw, issuerBase58, call, (t) => tw.trx.sign(t), opts);
+}
+/**
+ * A {SourceSigner} backed by an {AdapterWallet} (WalletConnect / adapter) for signing,
+ * plus a lazily-provided node TronWeb for build + broadcast. The node builds the tx
+ * against the bridge's chain, so the tx is bound to that chain regardless of what the
+ * remote wallet reports — hence `getNetwork()` returns the configured chainId (as
+ * {ManagedTronSigner} does), and the wrong-network guard is satisfied by construction.
+ */
+export class AdapterTronSigner {
+    wallet;
+    tronWebProvider;
+    chainId;
+    address = null;
+    tw = null;
+    constructor(wallet, 
+    /** Lazily builds the node TronWeb (keeps the heavy `tronweb` import off the hot path). */
+    tronWebProvider, chainId) {
+        this.wallet = wallet;
+        this.tronWebProvider = tronWebProvider;
+        this.chainId = chainId;
+    }
+    async connect() {
+        this.address = await this.wallet.connect();
+        return this.address;
+    }
+    async getAddress() {
+        return this.address ?? this.connect();
+    }
+    async getNetwork() {
+        return this.chainId;
+    }
+    async sendCall(call, opts) {
+        const tw = (this.tw ??= await this.tronWebProvider());
+        const issuer = await this.getAddress();
+        return sendCallSigned(tw, issuer, call, (t) => this.wallet.signTransaction(t), opts);
+    }
+    onChange(cb) {
+        return this.wallet.onChange?.(cb) ?? (() => { });
+    }
+}
+/**
+ * Managed-key / WalletConnect signer (06 §W4): wraps a pre-built `TronWeb`-shaped
+ * object that already holds a key (managed: `new TronWeb({ privateKey })`; the
+ * proven `demo/tron.ts` path) or a WalletConnect-provided signer. No extension,
+ * no flow change — same `SourceSigner` surface, signs silently. Its network is
+ * known from construction (the node it was built against), so it's trusted.
+ */
+export class ManagedTronSigner {
+    tw;
+    chainId;
+    constructor(tw, chainId) {
+        this.tw = tw;
+        this.chainId = chainId;
+    }
+    async connect() {
+        return this.getAddress();
+    }
+    async getAddress() {
+        const addr = this.tw.defaultAddress.base58;
+        if (!addr)
+            throw new Error('ManagedTronSigner: TronWeb has no default address (no key configured).');
+        return addr;
+    }
+    async getNetwork() {
+        return this.chainId;
+    }
+    sendCall(call, opts) {
+        return this.getAddress().then((a) => sendCallVia(this.tw, a, call, opts));
+    }
+}

package/lib/value.d.ts

@@ -0,0 +1,23 @@
+export declare const WALLET_VALUE_TAG = 39050n;
+export declare const WALLET_VALUE_VERSION = 1n;
+/**
+ * Reads the bridged-coin amount declared in a token's `data`, or null if the
+ * token declares no value for `coinId`. Injected into the verifier so the
+ * mint-reason check can confirm the token's declared value equals the locked
+ * amount.
+ */
+export type BridgedAmountExtractor = (data: Uint8Array | null, coinId: Uint8Array) => bigint | null;
+/** Encode a single-asset value payload in the wallet format, no memo. */
+export declare function encodeBridgePaymentData(coinId: Uint8Array, amount: bigint): Uint8Array;
+/**
+ * Decode the wallet-format payload and return the amount it declares for
+ * `coinId`; null when the bytes are not that format, the version is unknown, or
+ * the coin is absent.
+ */
+export declare function decodeBridgePaymentData(data: Uint8Array | null, coinId: Uint8Array): bigint | null;
+/**
+ * Minimal self-contained value envelope used by the CLI/tests only:
+ * `CBOR [ coinId: bstr, amount: uint ]`. Never appears on a real bridged token.
+ */
+export declare function encodeBridgedValue(coinId: Uint8Array, amount: bigint): Uint8Array;
+export declare function decodeBridgedValue(data: Uint8Array | null, coinId: Uint8Array): bigint | null;

package/lib/value.js

@@ -0,0 +1,58 @@
+import { CborDeserializer } from '@unicitylabs/state-transition-sdk/lib/serialization/cbor/CborDeserializer.js';
+import { CborSerializer } from '@unicitylabs/state-transition-sdk/lib/serialization/cbor/CborSerializer.js';
+import { Asset } from '@unicitylabs/state-transition-sdk/lib/payment/asset/Asset.js';
+import { AssetId } from '@unicitylabs/state-transition-sdk/lib/payment/asset/AssetId.js';
+import { PaymentAssetCollection } from '@unicitylabs/state-transition-sdk/lib/payment/asset/PaymentAssetCollection.js';
+import { bytesEqual } from './hex.js';
+export const WALLET_VALUE_TAG = 39050n;
+export const WALLET_VALUE_VERSION = 1n;
+/** Encode a single-asset value payload in the wallet format, no memo. */
+export function encodeBridgePaymentData(coinId, amount) {
+    const assets = PaymentAssetCollection.create(new Asset(new AssetId(coinId), amount));
+    return CborSerializer.encodeTag(WALLET_VALUE_TAG, CborSerializer.encodeArray(CborSerializer.encodeUnsignedInteger(WALLET_VALUE_VERSION), assets.toCBOR(), CborSerializer.encodeNullable(null, CborSerializer.encodeByteString)));
+}
+/**
+ * Decode the wallet-format payload and return the amount it declares for
+ * `coinId`; null when the bytes are not that format, the version is unknown, or
+ * the coin is absent.
+ */
+export function decodeBridgePaymentData(data, coinId) {
+    if (!data)
+        return null;
+    try {
+        const tag = CborDeserializer.decodeTag(data);
+        if (tag.tag !== WALLET_VALUE_TAG)
+            return null;
+        const fields = CborDeserializer.decodeArray(tag.data, 3);
+        if (CborDeserializer.decodeUnsignedInteger(fields[0]) !== WALLET_VALUE_VERSION)
+            return null;
+        return PaymentAssetCollection.fromCBOR(fields[1]).get(new AssetId(coinId))?.value ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Minimal self-contained value envelope used by the CLI/tests only:
+ * `CBOR [ coinId: bstr, amount: uint ]`. Never appears on a real bridged token.
+ */
+export function encodeBridgedValue(coinId, amount) {
+    return CborSerializer.encodeArray(CborSerializer.encodeByteString(coinId), CborSerializer.encodeUnsignedInteger(amount));
+}
+export function decodeBridgedValue(data, coinId) {
+    if (!data) {
+        return null;
+    }
+    let items;
+    try {
+        items = CborDeserializer.decodeArray(data, 2);
+    }
+    catch {
+        return null;
+    }
+    const encodedCoinId = CborDeserializer.decodeByteString(items[0]);
+    if (!bytesEqual(encodedCoinId, coinId)) {
+        return null;
+    }
+    return CborDeserializer.decodeUnsignedInteger(items[1]);
+}

package/lib/wallet/allowance.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Allowance query (08 §1.1) — the read that lets bridge-in skip a redundant
+ * `approve`. Pure ABI encoding over a {ConstantCaller}; no chain library, no
+ * wallet involvement (it's a node read, not a signed tx). Kept in the plugin so
+ * Sphere never encodes a contract call.
+ */
+import type { ConstantCaller } from '../source-chain.js';
+export interface AllowanceQuery {
+    /** Token contract, in any address form of its chain. */
+    readonly assetAddress: string;
+    /** Token holder (the wallet). */
+    readonly owner: string;
+    /** Spender (the vault). */
+    readonly spender: string;
+}
+/**
+ * Read `allowance(owner, spender)` off the token contract. Returns the current
+ * approved amount in the asset's smallest unit; `0n` when nothing is approved.
+ */
+export declare function queryAllowance(rpc: ConstantCaller, q: AllowanceQuery): Promise<bigint>;

package/lib/wallet/allowance.js

@@ -0,0 +1,27 @@
+import { toEvmAddressHex } from '../address.js';
+/** Left-pad a 20-byte EVM-form hex address to a 32-byte ABI word. */
+function addressWord(evmHex) {
+    const h = evmHex.replace(/^0x/i, '').toLowerCase();
+    return h.padStart(64, '0');
+}
+/** Parse a 32-byte ABI uint256 word (hex, no `0x`) to a bigint. */
+function wordToBigInt(word) {
+    const h = word.replace(/^0x/i, '');
+    return h ? BigInt('0x' + h) : 0n;
+}
+/**
+ * Read `allowance(owner, spender)` off the token contract. Returns the current
+ * approved amount in the asset's smallest unit; `0n` when nothing is approved.
+ */
+export async function queryAllowance(rpc, q) {
+    const ownerHex = toEvmAddressHex(q.owner);
+    const spenderHex = toEvmAddressHex(q.spender);
+    const assetHex = toEvmAddressHex(q.assetAddress);
+    const word = await rpc.constantCall({
+        ownerHex,
+        contractHex: assetHex,
+        functionSignature: 'allowance(address,address)',
+        parameterHex: addressWord(ownerHex) + addressWord(spenderHex),
+    });
+    return wordToBigInt(word);
+}

package/lib/wallet/backing.d.ts

@@ -0,0 +1,2 @@
+import type { LoadedBridge } from './manifest.js';
+export declare function mintedAgainst(bridge: LoadedBridge, justification: Uint8Array | null): boolean;

package/lib/wallet/backing.js

@@ -0,0 +1,15 @@
+import { toHex } from '../hex.js';
+import { BridgeLockJustification } from '../BridgeLockJustification.js';
+export function mintedAgainst(bridge, justification) {
+    if (!justification)
+        return false;
+    let lock;
+    try {
+        lock = BridgeLockJustification.fromCBOR(justification);
+    }
+    catch {
+        return false;
+    }
+    const cfg = bridge.plugin.resolvedConfig;
+    return lock.data.chainId === cfg.chainId && toHex(lock.data.lockContract).toLowerCase() === cfg.lockContractHex;
+}

package/lib/wallet/facade.d.ts

@@ -0,0 +1,97 @@
+import type { Token } from '@unicitylabs/state-transition-sdk/lib/transaction/Token.js';
+import { type BridgeBackReason, type BridgeConfig } from '../bridge-back/derivations.js';
+import { type BridgeBackBurnReason, createBridgeBackBurnTransfer, type ReturnPreview, type WitnessRequest } from '../bridge-back/burn.js';
+import { fromHex, toHex } from '../hex.js';
+import type { ContractCall } from '../contract-call.js';
+import type { BridgePlugin } from '../index.js';
+export * from './manifest.js';
+export { buildBridgeBackBurnReason } from '../bridge-back/burn.js';
+export type { BridgeBackBurnReason } from '../bridge-back/burn.js';
+export { previewReturn } from '../bridge-back/burn.js';
+export { decodeBridgeBackReason } from '../bridge-back/derivations.js';
+export type { BridgeBackReason, BridgeConfig, DecodedBridgeBackReason, ReturnLeaf, } from '../bridge-back/derivations.js';
+export type { CallParam, ContractCall } from '../contract-call.js';
+/** Everything bridge-in needs after the user picks asset + amount (06 §A1.1). */
+export interface BridgeInPlan {
+    /** The Unicity TokenId this deposit funds (hex). The lock commits to it. */
+    readonly tokenIdHex: string;
+    /** Salt the wallet keeps to mint exactly this token (hex, 32 bytes). */
+    readonly saltHex: string;
+    /** `SHA256(ownerPredicateCbor)` committed on Tron (hex, 32 bytes). */
+    readonly recipientCommitmentHex: string;
+    /** Locked amount in the asset's smallest unit. */
+    readonly amount: bigint;
+    /** One-time max `approve` of the asset to the vault (skip if allowance already covers `amount`). */
+    readonly approve: ContractCall;
+    /** `lock(amount, tokenId, recipientCommitment)` on the vault. */
+    readonly lock: ContractCall;
+}
+/** Inputs to {buildBridgeInPlan}. Provide exactly one of `recipientPubkey` / `ownerPredicateCbor`. */
+export interface BridgeInPlanInput {
+    readonly plugin: BridgePlugin;
+    readonly amount: bigint;
+    /** Network id of the Unicity network the token is minted on (e.g. testnet2 = 4). */
+    readonly networkId: number;
+    /**
+     * The wallet's 33-byte compressed chain pubkey. The façade builds the same
+     * `SignaturePredicate(pubkey)` the engine mints to, so the lock's
+     * `recipientCommitment` binds the bridged token to this wallet. Preferred — the
+     * app never needs the SDK.
+     */
+    readonly recipientPubkey?: Uint8Array;
+    /** Alternative: a pre-encoded owner `EncodedPredicate` CBOR (commitment = SHA256 of it). */
+    readonly ownerPredicateCbor?: Uint8Array;
+    /**
+     * `approve` amount. A one-time `MAX_UINT256` reduces repeat bridges to a single
+     * prompt (06 §A1.3); default exact `amount`.
+     */
+    readonly approveAmount?: bigint;
+}
+declare const MAX_UINT256: bigint;
+/**
+ * Derive the bridge-in target token + the unsigned `approve`/`lock` calls, in
+ * the family-neutral {ContractCall} shape the wallet's signer encodes for its
+ * chain. Pure + offline (no RPC): the order is load-bearing — the lock commits
+ * to this exact `tokenId` + `recipientCommitment`, and the wallet then mints
+ * *that* token.
+ */
+export declare function buildBridgeInPlan(input: BridgeInPlanInput): Promise<BridgeInPlan>;
+/** Convenience: the max-allowance approve amount (one-time approve UX). */
+export { MAX_UINT256 };
+/**
+ * Build the terminal burn for a bridge-back (06 §A1.2 step 3). The caller
+ * certifies the returned transfer through its normal SDK path, then calls
+ * {finalizeBridgeBack} with the certified burn's stateId/txHash. For a partial
+ * return, split first and pass the child whose value == `reason.amount`.
+ */
+export declare function buildBridgeBackBurn(args: {
+    readonly token: Token;
+    readonly bridgeConfig: BridgeConfig;
+    readonly reason: BridgeBackReason;
+    readonly stateMask: Uint8Array;
+}): Promise<{
+    transfer: Awaited<ReturnType<typeof createBridgeBackBurnTransfer>>['transfer'];
+    reason: BridgeBackBurnReason;
+}>;
+/** The read-only return preview + the prover hand-off envelope, post-certification. */
+export interface BridgeBackArtifacts {
+    readonly preview: ReturnPreview;
+    readonly witnessRequest: WitnessRequest;
+}
+/**
+ * After the burn certifies, derive the pending nullifier + settlement leaf
+ * ({previewReturn}) and assemble the prover hand-off envelope
+ * ({buildWitnessRequest}). The wallet shows `preview` and POSTs `witnessRequest`
+ * (plus the burned-token blob, recovery-critical) to the return service.
+ * `reasonBytes` are the canonical bytes from {buildBridgeBackBurn}'s reason.
+ */
+export declare function finalizeBridgeBack(args: {
+    readonly configHash: Uint8Array;
+    readonly reason: BridgeBackReason;
+    readonly reasonBytes: Uint8Array;
+    readonly burnStateId: Uint8Array;
+    readonly burnTxHash: Uint8Array;
+    readonly burnedTokenCbor: Uint8Array;
+}): BridgeBackArtifacts;
+/** Hex helpers re-exported for read-only UI formatting. */
+export { fromHex, toHex };

package/lib/wallet/facade.js

@@ -0,0 +1,100 @@
+/**
+ * Wallet-facing façade (06 §W0) — the only surface Sphere calls.
+ *
+ * Boundary (decision #2): Sphere never recomputes a bridge hash or touches a
+ * chain-specific detail. It loads a {BridgeManifest}, asks this façade to derive
+ * the bridge-in plan / build the bridge-back artifacts, and renders UI. Every
+ * value here is either a pure derivation (conformance-tested against
+ * `protocol/vectors`) or a thin wrapper over an already-built bridge-back function.
+ */
+import { NetworkId } from '@unicitylabs/state-transition-sdk/lib/api/NetworkId.js';
+import { EncodedPredicate } from '@unicitylabs/state-transition-sdk/lib/predicate/EncodedPredicate.js';
+import { SignaturePredicate } from '@unicitylabs/state-transition-sdk/lib/predicate/builtin/SignaturePredicate.js';
+import { TokenId } from '@unicitylabs/state-transition-sdk/lib/transaction/TokenId.js';
+import { TokenSalt } from '@unicitylabs/state-transition-sdk/lib/transaction/TokenSalt.js';
+import { buildWitnessRequest, createBridgeBackBurnTransfer, previewReturn, } from '../bridge-back/burn.js';
+import { recipientCommitment } from '../identifiers.js';
+import { fromHex, toHex } from '../hex.js';
+export * from './manifest.js';
+// Pure bridge-back reason builder (reasonBytes + reasonHash) — the app feeds these
+// to the engine's bridgeBurn, no SDK token needed (06 §A1.2).
+export { buildBridgeBackBurnReason } from '../bridge-back/burn.js';
+// Read-only bridge-back surface the UI renders directly.
+export { previewReturn } from '../bridge-back/burn.js';
+export { decodeBridgeBackReason } from '../bridge-back/derivations.js';
+const MAX_UINT256 = (1n << 256n) - 1n;
+/**
+ * Derive the bridge-in target token + the unsigned `approve`/`lock` calls, in
+ * the family-neutral {ContractCall} shape the wallet's signer encodes for its
+ * chain. Pure + offline (no RPC): the order is load-bearing — the lock commits
+ * to this exact `tokenId` + `recipientCommitment`, and the wallet then mints
+ * *that* token.
+ */
+export async function buildBridgeInPlan(input) {
+    const saltBytes = crypto.getRandomValues(new Uint8Array(32));
+    const salt = TokenSalt.fromBytes(saltBytes);
+    const tokenId = await TokenId.fromSalt(NetworkId.fromId(input.networkId), salt);
+    const ownerCbor = input.ownerPredicateCbor ??
+        (input.recipientPubkey
+            ? EncodedPredicate.fromPredicate(SignaturePredicate.create(input.recipientPubkey)).toCBOR()
+            : undefined);
+    if (!ownerCbor) {
+        throw new Error('buildBridgeInPlan: provide recipientPubkey or ownerPredicateCbor');
+    }
+    const commitment = recipientCommitment(ownerCbor);
+    const vaultHex = input.plugin.resolvedConfig.lockContractHex;
+    const assetHex = input.plugin.resolvedConfig.assetContractHex;
+    const approveAmount = input.approveAmount ?? input.amount;
+    return {
+        tokenIdHex: toHex(tokenId.bytes),
+        saltHex: toHex(saltBytes),
+        recipientCommitmentHex: toHex(commitment),
+        amount: input.amount,
+        approve: {
+            contractHex: assetHex,
+            functionSignature: 'approve(address,uint256)',
+            parameters: [
+                { type: 'address', value: vaultHex },
+                { type: 'uint256', value: approveAmount.toString() },
+            ],
+        },
+        lock: {
+            contractHex: vaultHex,
+            functionSignature: 'lock(uint256,bytes32,bytes32)',
+            parameters: [
+                { type: 'uint256', value: input.amount.toString() },
+                { type: 'bytes32', value: '0x' + toHex(tokenId.bytes) },
+                { type: 'bytes32', value: '0x' + toHex(commitment) },
+            ],
+        },
+    };
+}
+/** Convenience: the max-allowance approve amount (one-time approve UX). */
+export { MAX_UINT256 };
+/**
+ * Build the terminal burn for a bridge-back (06 §A1.2 step 3). The caller
+ * certifies the returned transfer through its normal SDK path, then calls
+ * {finalizeBridgeBack} with the certified burn's stateId/txHash. For a partial
+ * return, split first and pass the child whose value == `reason.amount`.
+ */
+export async function buildBridgeBackBurn(args) {
+    return createBridgeBackBurnTransfer(args.token, args.bridgeConfig, args.reason, args.stateMask);
+}
+/**
+ * After the burn certifies, derive the pending nullifier + settlement leaf
+ * ({previewReturn}) and assemble the prover hand-off envelope
+ * ({buildWitnessRequest}). The wallet shows `preview` and POSTs `witnessRequest`
+ * (plus the burned-token blob, recovery-critical) to the return service.
+ * `reasonBytes` are the canonical bytes from {buildBridgeBackBurn}'s reason.
+ */
+export function finalizeBridgeBack(args) {
+    const preview = previewReturn(args.configHash, args.reason, args.burnStateId, args.burnTxHash);
+    const witnessRequest = buildWitnessRequest({
+        tokenCbor: args.burnedTokenCbor,
+        configHash: args.configHash,
+        reasonBytes: args.reasonBytes,
+    });
+    return { preview, witnessRequest };
+}
+/** Hex helpers re-exported for read-only UI formatting. */
+export { fromHex, toHex };

package/lib/wallet/finality.d.ts

@@ -0,0 +1,8 @@
+import type { LoadedBridge } from './manifest.js';
+export interface LockFinality {
+    readonly confirmations: bigint;
+    readonly required: number;
+    readonly final: boolean;
+    readonly secondsLeft: number;
+}
+export declare function lockFinality(bridge: LoadedBridge, justification: Uint8Array | null): Promise<LockFinality | null>;

package/lib/wallet/finality.js

@@ -0,0 +1,28 @@
+import { BridgeLockJustification } from '../BridgeLockJustification.js';
+import { chainFamily } from '../families.js';
+import { toHex } from '../hex.js';
+export async function lockFinality(bridge, justification) {
+    if (!justification)
+        return null;
+    let lock;
+    try {
+        lock = BridgeLockJustification.fromCBOR(justification);
+    }
+    catch {
+        return null;
+    }
+    const cfg = bridge.plugin.resolvedConfig;
+    if (lock.data.chainId !== cfg.chainId || toHex(lock.data.lockContract).toLowerCase() !== cfg.lockContractHex)
+        return null;
+    const required = cfg.confirmations;
+    const blockSeconds = chainFamily(cfg.family).blockSeconds;
+    const info = await bridge.plugin.rpc.getTransactionInfo(toHex(lock.data.txid));
+    const confirmations = info ? (await bridge.plugin.rpc.getNowBlockNumber()) - info.blockNumber : 0n;
+    const missing = BigInt(required) - confirmations;
+    return {
+        confirmations,
+        required,
+        final: missing <= 0n,
+        secondsLeft: missing <= 0n ? 0 : Number(missing) * blockSeconds,
+    };
+}

package/lib/wallet/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Wallet integration surface (06 §A2.2). The single entry point a wallet (Sphere)
+ * imports — façade (plan builders), manifest (loader/type), the family-neutral
+ * signer contract and each family's wallets. Kept as a subpath, *not* merged
+ * into the package root, so the read-only re-exports here don't collide with
+ * the root's bridge-back exports.
+ */
+export * from './facade.js';
+export * from './manifests.js';
+export * from './registry.js';
+export * from './signer.js';
+export * from '../tron/signer.js';
+export * from '../tron/providers.js';
+export * from '../tron/presentation.js';
+export * from '../evm/signer.js';
+export * from '../evm/providers.js';
+export * from '../evm/presentation.js';
+export * from './allowance.js';
+export * from './source-adapter.js';
+export * from './return-client.js';
+export * from './self-mint-verifier.js';
+export * from './token-plugin.js';
+export * from './backing.js';
+export * from './finality.js';
+export * from './payout.js';