@unicitylabs/bridge-plugin 0.2.0-dev.1

package/lib/wallet/index.js

@@ -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';

package/lib/wallet/manifest.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Bridge manifest — the integrity-pinned descriptor a wallet (Sphere) loads to
+ * surface one bridged asset, plus the loader that turns it into a ready plugin.
+ *
+ * Decision #2 (06 §A2): Sphere holds *zero* chain-specific bridge code. It
+ * imports this façade + a manifest and renders UI; everything else (derivations,
+ * chain specifics, the verifier) lives here in the plugin. The manifest names the
+ * deployed vault/asset/config so the loader can (a) build the bridge plugin and
+ * its `IMintJustificationVerifier`, and (b) cross-check the declared `configHash`
+ * against the one recomputed from the manifest fields — a misconfigured manifest
+ * fails loudly at load, never silently accepts a wrong trust anchor.
+ */
+import type { BridgeManifestBase, BridgePresentation } from '@unicitylabs/bridge-core';
+import { toEvmAddressHex } from '../address.js';
+import { type BridgeConfig } from '../bridge-back/derivations.js';
+import { BRIDGE_LOCK_JUSTIFICATION_TAG } from '../BridgeLockJustification.js';
+import type { BridgeAssetConfig } from '../config.js';
+import { type BridgePlugin, type CreateBridgePluginDeps } from '../index.js';
+export type { BridgeManifestBase } from '@unicitylabs/bridge-core';
+export { evmChainRef } from '../evm/family.js';
+export { tronChainRef } from '../tron/family.js';
+/** A Tron-family bridged-asset manifest. `chainId` is Tron's genesis-derived id, cross-checked against `chainRef`. */
+export interface TronBridgeManifest extends BridgeManifestBase {
+    readonly family: 'tron';
+    readonly chainId: number;
+    /** Tron HTTP RPC base URL. */
+    readonly rpcUrl: string;
+    /** Optional TronGrid API key. */
+    readonly apiKey?: string;
+}
+/** An Ethereum-family (eip155) bridged-asset manifest. `chainId` is the EIP-155 id, cross-checked against `chainRef`. */
+export interface EvmBridgeManifest extends BridgeManifestBase {
+    readonly family: 'eip155';
+    readonly chainId: number;
+    /** JSON-RPC endpoint. */
+    readonly rpcUrl: string;
+}
+export type BridgeManifest = TronBridgeManifest | EvmBridgeManifest;
+/** A manifest entry resolved into everything the wallet needs to use it. */
+export interface LoadedBridge {
+    readonly manifest: BridgeManifest;
+    /** The ready plugin (TokenType/coinId derivations + the registered verifier). */
+    readonly plugin: BridgePlugin;
+    /** The `BridgeConfig` the bridge-back reason/nullifier bind to (00 §2). */
+    readonly bridgeConfig: BridgeConfig;
+    /** 32-byte `configHash` recomputed from the manifest (== `manifest.configHash`). */
+    readonly configHash: Uint8Array;
+}
+export declare function assetConfigFromManifest(m: BridgeManifest, confirmations: number): BridgeAssetConfig;
+/** Build the canonical {BridgeConfig} (00 §2) from a manifest + a resolved plugin. */
+export declare function bridgeConfigFromManifest(m: BridgeManifest, plugin: BridgePlugin): BridgeConfig;
+/**
+ * Resolve a manifest (or array) into ready {LoadedBridge}s. Throws if a declared
+ * identifier (`tokenTypeHex`/`coinIdHex`/`configHash`) does not match the value
+ * recomputed from the manifest fields — the integrity-pin (06 Risks: manifest
+ * trust-anchor misconfig).
+ */
+export declare function loadBridges(manifest: BridgeManifest | readonly BridgeManifest[], deps?: CreateBridgePluginDeps): LoadedBridge[];
+/**
+ * The {BridgePresentation} for a resolved bridge, from its chain family, so the
+ * wallet UI asks the bridge for its explorer link / address validation instead
+ * of keying on a numeric chainId (08 §8).
+ */
+export declare function bridgePresentation(bridge: LoadedBridge): BridgePresentation;
+export declare function chainName(bridge: LoadedBridge): string;
+/** The justification CBOR tag every bridged mint reason carries (dispatch key). */
+export { BRIDGE_LOCK_JUSTIFICATION_TAG };
+/** Normalize any address form to 20-byte EVM-style hex (re-exported for UI). */
+export { toEvmAddressHex };

package/lib/wallet/manifest.js

@@ -0,0 +1,81 @@
+import { toEvmAddressHex } from '../address.js';
+import { configHash as deriveConfigHash } from '../bridge-back/derivations.js';
+import { BRIDGE_LOCK_JUSTIFICATION_TAG } from '../BridgeLockJustification.js';
+import { chainFamily } from '../families.js';
+import { fromHex, toHex } from '../hex.js';
+import { createBridgePlugin } from '../index.js';
+export { evmChainRef } from '../evm/family.js';
+export { tronChainRef } from '../tron/family.js';
+export function assetConfigFromManifest(m, confirmations) {
+    return {
+        family: m.family,
+        chainId: m.chainId,
+        lockContract: m.vault,
+        assetContract: m.asset,
+        confirmations,
+        decimals: m.decimals,
+        rpcUrl: m.rpcUrl,
+        apiKey: m.family === 'tron' ? m.apiKey : undefined,
+    };
+}
+/** Build the canonical {BridgeConfig} (00 §2) from a manifest + a resolved plugin. */
+export function bridgeConfigFromManifest(m, plugin) {
+    return {
+        sourceChainId: BigInt(plugin.resolvedConfig.chainId),
+        vault: fromHex(plugin.resolvedConfig.lockContractHex),
+        asset: fromHex(plugin.resolvedConfig.assetContractHex),
+        tokenType: plugin.resolvedConfig.tokenType,
+        coinId: plugin.resolvedConfig.coinId,
+        reasonTag: BigInt(m.reasonTag),
+        lockDomain: fromHex(m.lockDomain),
+        nullifierDomain: fromHex(m.nullifierDomain),
+    };
+}
+/**
+ * Resolve a manifest (or array) into ready {LoadedBridge}s. Throws if a declared
+ * identifier (`tokenTypeHex`/`coinIdHex`/`configHash`) does not match the value
+ * recomputed from the manifest fields — the integrity-pin (06 Risks: manifest
+ * trust-anchor misconfig).
+ */
+export function loadBridges(manifest, deps = {}) {
+    const list = Array.isArray(manifest) ? manifest : [manifest];
+    return list.map((m) => loadOne(m, deps));
+}
+function loadOne(m, deps) {
+    // The generic chainRef must agree with the family's native chainId — an
+    // integrity pin like tokenType/coinId/configHash: a misdescribed chain fails
+    // loudly at load.
+    const expectedRef = chainFamily(m.family).chainRef(m.chainId);
+    if (m.chainRef.toLowerCase() !== expectedRef.toLowerCase()) {
+        throw new Error(`BridgeManifest(${m.label}): chainRef mismatch — declared ${m.chainRef}, derived ${expectedRef} from chainId ${m.chainId}`);
+    }
+    const plugin = createBridgePlugin(assetConfigFromManifest(m, m.confirmations), deps);
+    if (m.tokenTypeHex && m.tokenTypeHex.toLowerCase() !== plugin.tokenTypeHex) {
+        throw new Error(`BridgeManifest(${m.label}): tokenTypeHex mismatch — declared ${m.tokenTypeHex}, derived ${plugin.tokenTypeHex}`);
+    }
+    if (m.coinIdHex && m.coinIdHex.toLowerCase() !== plugin.coinIdHex) {
+        throw new Error(`BridgeManifest(${m.label}): coinIdHex mismatch — declared ${m.coinIdHex}, derived ${plugin.coinIdHex}`);
+    }
+    const bridgeConfig = bridgeConfigFromManifest(m, plugin);
+    const configHash = deriveConfigHash(bridgeConfig);
+    if (toHex(configHash) !== m.configHash.toLowerCase()) {
+        throw new Error(`BridgeManifest(${m.label}): configHash mismatch — declared ${m.configHash}, derived ${toHex(configHash)}. ` +
+            `The manifest does not describe the deployed vault.`);
+    }
+    return { manifest: m, plugin, bridgeConfig, configHash };
+}
+/**
+ * The {BridgePresentation} for a resolved bridge, from its chain family, so the
+ * wallet UI asks the bridge for its explorer link / address validation instead
+ * of keying on a numeric chainId (08 §8).
+ */
+export function bridgePresentation(bridge) {
+    return chainFamily(bridge.manifest.family).presentation(bridge.manifest.chainId);
+}
+export function chainName(bridge) {
+    return chainFamily(bridge.manifest.family).chainName;
+}
+/** The justification CBOR tag every bridged mint reason carries (dispatch key). */
+export { BRIDGE_LOCK_JUSTIFICATION_TAG };
+/** Normalize any address form to 20-byte EVM-style hex (re-exported for UI). */
+export { toEvmAddressHex };

package/lib/wallet/manifests.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Built-in {BridgeManifest}s for known deployments. Frozen from
+ * `deployments/nile/nile-usdt.json` (the cross-stack config freeze —
+ * `configHash` equals the deployed vault's on-chain `CONFIG_HASH`). A wallet can
+ * import one of these directly instead of shipping its own manifest file.
+ */
+import type { BridgeManifest, EvmBridgeManifest, TronBridgeManifest } from './manifest.js';
+/**
+ * Tron Nile testnet USDT — the **live v2** deployment (2026-09-21). Vault
+ * `TBKJ84417jdxo6j92TxQuYpZdRZGaeZVrv`, BridgeBackReason tag **39048** (distinct
+ * from SpherePaymentData tag 39050), real SP1 verifier `TN4nQmnVz3H3zDnN77NQZTAfBpzkEdoeBR`
+ * (vkey `0x0039a542…` — the BRIDGE_PROTO_VERSION 2 guest, which reads the wallet's
+ * value payload and rejects empty burn batches), the R6 false-tolerant safe-transfer
+ * (with an explicit energy stipend — TVM doesn't reliably forward all remaining
+ * energy to a bare nested `.call()`) for the non-standard Nile USDT
+ * `TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf`, push-payment. `configHash` equals the
+ * vault's on-chain `CONFIG_HASH` (cross-checked TS == Solidity), the integrity
+ * pin. tokenType/coinId are asset-derived (stable across vault redeploys).
+ *
+ * `returnServiceUrl` defaults to a local Part-B service; override per environment.
+ *
+ * Disabled since 2026-09-22: Tron bounds a transaction to 80 ms of CPU and the
+ * Groth16 verification needs more, so no return can settle on any Tron network
+ * (docs/OPERATIONS.md §10). The entry stays listed so the wallet keeps showing
+ * the deployment and its tokens; it refuses new locks and burns.
+ */
+export declare const NILE_USDT_BRIDGE: TronBridgeManifest;
+export declare const NILE_USDT_BRIDGE_V1: TronBridgeManifest;
+export declare const SEPOLIA_USDC_BRIDGE: EvmBridgeManifest;
+/** Override the return-service URL on a manifest (env-specific, keeps the freeze intact). */
+export declare function withReturnServiceUrl<M extends BridgeManifest>(m: M, returnServiceUrl: string): M;

package/lib/wallet/manifests.js

@@ -0,0 +1,70 @@
+/**
+ * Tron Nile testnet USDT — the **live v2** deployment (2026-09-21). Vault
+ * `TBKJ84417jdxo6j92TxQuYpZdRZGaeZVrv`, BridgeBackReason tag **39048** (distinct
+ * from SpherePaymentData tag 39050), real SP1 verifier `TN4nQmnVz3H3zDnN77NQZTAfBpzkEdoeBR`
+ * (vkey `0x0039a542…` — the BRIDGE_PROTO_VERSION 2 guest, which reads the wallet's
+ * value payload and rejects empty burn batches), the R6 false-tolerant safe-transfer
+ * (with an explicit energy stipend — TVM doesn't reliably forward all remaining
+ * energy to a bare nested `.call()`) for the non-standard Nile USDT
+ * `TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf`, push-payment. `configHash` equals the
+ * vault's on-chain `CONFIG_HASH` (cross-checked TS == Solidity), the integrity
+ * pin. tokenType/coinId are asset-derived (stable across vault redeploys).
+ *
+ * `returnServiceUrl` defaults to a local Part-B service; override per environment.
+ *
+ * Disabled since 2026-09-22: Tron bounds a transaction to 80 ms of CPU and the
+ * Groth16 verification needs more, so no return can settle on any Tron network
+ * (docs/OPERATIONS.md §10). The entry stays listed so the wallet keeps showing
+ * the deployment and its tokens; it refuses new locks and burns.
+ */
+export const NILE_USDT_BRIDGE = {
+    family: 'tron',
+    label: 'USDT (bridged · Tron)',
+    symbol: 'USDT',
+    chainRef: 'tron:0xcd8690dc',
+    chainId: 3448148188,
+    vault: 'TBKJ84417jdxo6j92TxQuYpZdRZGaeZVrv',
+    asset: 'TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf',
+    confirmations: 20,
+    decimals: 6,
+    rpcUrl: 'https://nile.trongrid.io',
+    returnServiceUrl: 'http://localhost:8787',
+    reasonTag: 39048,
+    lockDomain: '158b847f78b3910a5f5f42820de61abba1bf5ae1fbb29dabfba09118f393f932',
+    nullifierDomain: 'd4530e4ea58fc8e38f84506e62b421476c3eeec70f4cbebefc32688a510e2d5d',
+    vkey: '0x0039a5424014e57caf45d3451053e6c014547837ae09c9eb724aa569389b90d5',
+    configHash: 'fa77a13a6fb24658fa75377b0eef7cf3e92f8caede9ea127afe21be7a036cb1b',
+    tokenTypeHex: '6f2d10d27abeb4960a7ef19370c965ec090bb4da1f17752be77334e2dde19c74',
+    coinIdHex: 'f1634862e1b932acd1c791a1860c62f69c7f55aa6c6115ba631d3bf4a9d8ddbb',
+    disabledReason: 'Tron limits a transaction to 80 ms of CPU, less than the proof verification needs, so returns cannot settle. Bridging on Tron is paused.',
+};
+export const NILE_USDT_BRIDGE_V1 = {
+    ...NILE_USDT_BRIDGE,
+    vault: 'TTKKLyhnRRQ7XV5vsRarV8xWWEvF9225mY',
+    vkey: '0x00c34ae0ebb63e86218a754892813f4744b2f6c9ed613c085ea40999b16ce3ad',
+    configHash: '7f376b16b3bff3455f375e7cf30b9d29d2a14332912f0ffb69d78e1b31d5193f',
+};
+export const SEPOLIA_USDC_BRIDGE = {
+    family: 'eip155',
+    label: 'USDC (bridged · Ethereum)',
+    symbol: 'USDC',
+    chainRef: 'eip155:11155111',
+    chainId: 11155111,
+    vault: '0x9C2BF4Ed5b85130fFD14BE8FA65c60F299Fc9a2E',
+    asset: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
+    confirmations: 12,
+    decimals: 6,
+    rpcUrl: 'https://ethereum-sepolia-rpc.publicnode.com',
+    returnServiceUrl: 'http://localhost:8787',
+    reasonTag: 39048,
+    lockDomain: '158b847f78b3910a5f5f42820de61abba1bf5ae1fbb29dabfba09118f393f932',
+    nullifierDomain: 'd4530e4ea58fc8e38f84506e62b421476c3eeec70f4cbebefc32688a510e2d5d',
+    vkey: '0x0039a5424014e57caf45d3451053e6c014547837ae09c9eb724aa569389b90d5',
+    configHash: '4058e87dff330d9c6925af755e0732dbc80be85643fdce46c8315eae51c9f7e8',
+    tokenTypeHex: '2ccbf3157add2b9a2dcc10e772abf5cf328e2723f9f290a9d2b6c4a42a132d6c',
+    coinIdHex: 'eae954053183b9d1836d6b5c892867014bcc1571fcc6813f5b56b16a78d0497f',
+};
+/** Override the return-service URL on a manifest (env-specific, keeps the freeze intact). */
+export function withReturnServiceUrl(m, returnServiceUrl) {
+    return { ...m, returnServiceUrl };
+}

package/lib/wallet/payout.d.ts

@@ -0,0 +1,5 @@
+import type { ContractCall } from '../contract-call.js';
+import type { ConstantCaller } from '../source-chain.js';
+import type { LoadedBridge } from './manifest.js';
+export declare function owedTo(bridge: LoadedBridge, rpc: ConstantCaller, destination: string): Promise<bigint>;
+export declare function withdrawCall(bridge: LoadedBridge): ContractCall;

package/lib/wallet/payout.js

@@ -0,0 +1,14 @@
+import { toEvmAddressHex } from '../address.js';
+export async function owedTo(bridge, rpc, destination) {
+    const destinationHex = toEvmAddressHex(destination);
+    const word = await rpc.constantCall({
+        ownerHex: destinationHex,
+        contractHex: bridge.plugin.resolvedConfig.lockContractHex,
+        functionSignature: 'owed(address)',
+        parameterHex: destinationHex.padStart(64, '0'),
+    });
+    return word ? BigInt('0x' + word) : 0n;
+}
+export function withdrawCall(bridge) {
+    return { contractHex: bridge.plugin.resolvedConfig.lockContractHex, functionSignature: 'withdraw()', parameters: [] };
+}

package/lib/wallet/registry.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Bridge registry (08 Phase 4 — "manifest registry keyed by family+chain+asset").
+ *
+ * A wallet may load several bridged assets across chains; this indexes the
+ * resolved {LoadedBridge}s so a flow can address one deterministically. The
+ * canonical key is **family + chain + asset** — expressed as `chainRef` (which
+ * already encodes `family:chain`, e.g. `tron:0xcd8690dc`) plus the resolved asset
+ * hex. That key is **stable across vault redeploys**: a redeploy changes the vault
+ * address (and `configHash`), but the same asset on the same chain keeps the same
+ * key — so pending balances/records keep resolving to their bridge (00 "redeploy /
+ * migration discipline"). Registering two manifests for the same key is a config
+ * error and throws.
+ *
+ * Chain-neutral: it reads only `manifest.chainRef` + the plugin's resolved asset
+ * hex / coinId / tokenType — no Tron-specific logic — so a second family drops in
+ * without touching this file.
+ */
+import type { LoadedBridge } from './manifest.js';
+/**
+ * The family+chain+asset key for a resolved bridge — stable across vault
+ * redeploys. `chainRef` carries `family:chain`; the resolved asset hex completes it.
+ */
+export declare function bridgeAssetKey(bridge: LoadedBridge): string;
+/** An index over the app's resolved bridges, keyed for deterministic lookup. */
+export interface BridgeRegistry {
+    /** Every registered bridge (insertion order). */
+    readonly all: readonly LoadedBridge[];
+    /** By the family+chain+asset key ({bridgeAssetKey}); undefined if not registered. */
+    byKey(key: string): LoadedBridge | undefined;
+    /** By the bridged coinId (what the wallet UI holds); case-insensitive. */
+    byCoinId(coinIdHex: string): LoadedBridge | undefined;
+    /** By the Unicity TokenType; case-insensitive. */
+    byTokenType(tokenTypeHex: string): LoadedBridge | undefined;
+}
+/**
+ * Build a {BridgeRegistry} from resolved bridges. Throws on a duplicate
+ * family+chain+asset key — two manifests describing the same bridged asset is a
+ * misconfiguration, never a silent last-one-wins.
+ */
+export declare function buildBridgeRegistry(loaded: readonly LoadedBridge[]): BridgeRegistry;

package/lib/wallet/registry.js

@@ -0,0 +1,34 @@
+/**
+ * The family+chain+asset key for a resolved bridge — stable across vault
+ * redeploys. `chainRef` carries `family:chain`; the resolved asset hex completes it.
+ */
+export function bridgeAssetKey(bridge) {
+    return `${bridge.manifest.chainRef}:${bridge.plugin.resolvedConfig.assetContractHex}`;
+}
+/**
+ * Build a {BridgeRegistry} from resolved bridges. Throws on a duplicate
+ * family+chain+asset key — two manifests describing the same bridged asset is a
+ * misconfiguration, never a silent last-one-wins.
+ */
+export function buildBridgeRegistry(loaded) {
+    const byKey = new Map();
+    const byCoin = new Map();
+    const byType = new Map();
+    for (const bridge of loaded) {
+        const key = bridgeAssetKey(bridge);
+        const existing = byKey.get(key);
+        if (existing) {
+            throw new Error(`Duplicate bridge for ${key}: "${bridge.manifest.label}" and "${existing.manifest.label}" ` +
+                `describe the same family+chain+asset.`);
+        }
+        byKey.set(key, bridge);
+        byCoin.set(bridge.plugin.coinIdHex, bridge);
+        byType.set(bridge.plugin.tokenTypeHex, bridge);
+    }
+    return {
+        all: loaded,
+        byKey: (key) => byKey.get(key),
+        byCoinId: (coinIdHex) => byCoin.get(coinIdHex.toLowerCase()),
+        byTokenType: (tokenTypeHex) => byType.get(tokenTypeHex.toLowerCase()),
+    };
+}

package/lib/wallet/return-client.d.ts

@@ -0,0 +1,91 @@
+import type { WitnessRequest } from '../bridge-back/burn.js';
+/** Lifecycle of a submitted return (07 §B4 — matches the service's status enum). */
+export type ReturnStatus = 'queued' | 'proving' | 'proven' | 'submitted' | 'settled' | 'failed';
+/** Typed failure detail (service `failure` object). */
+export interface ReturnFailure {
+    readonly kind: string;
+    readonly message: string;
+    readonly recoverable: boolean;
+}
+/** A return record as the service reports it (camelCase, `/returns/:id`). */
+export interface ReturnRecord {
+    readonly returnId: string;
+    /** 32-byte nullifier (hex) — the wallet's idempotency key. */
+    readonly nullifier: string;
+    readonly status: ReturnStatus;
+    /** Terminal (`settled`/`failed`) — stop polling. */
+    readonly terminal?: boolean;
+    readonly success?: boolean | null;
+    /** 0–100 coarse progress for the UI. */
+    readonly progress?: number;
+    /** Human status message. */
+    readonly message?: string;
+    /** Suggested next poll delay (ms); 0 when terminal. */
+    readonly nextPollMs?: number;
+    /** Batch the return landed in, once sequenced. */
+    readonly batchId?: string;
+    /** `fulfillBatch` txid, on settle (denormalized from the batch). */
+    readonly settleTxid?: string;
+    /** Typed failure detail for `failed`. */
+    readonly failure?: ReturnFailure;
+    readonly attempts?: number;
+    readonly notBeforeMs?: number | null;
+    readonly queuePosition?: number | null;
+    readonly createdAtMs?: number;
+    readonly updatedAtMs?: number;
+    /** True only on the `POST /returns` response when the nullifier was already known. */
+    readonly duplicate?: boolean;
+}
+/** `/health` snapshot (07 §B4) — used for batch-ETA + ops display. */
+export interface ReturnServiceHealth {
+    readonly status: string;
+    readonly queueDepth: number;
+    /** The batch currently proving, if any. */
+    readonly activeBatch?: string | null;
+    readonly activeBatchSize: number;
+    readonly provingSinceMs?: number | null;
+    readonly lastProofMs?: number | null;
+    readonly averageProofMs?: number | null;
+    readonly maxBatchSize: number;
+    readonly idleWaitMs: number;
+    /** `PrecheckOnly` | `Sp1Groth16`. */
+    readonly proveMode: string;
+}
+/** The published on-chain bundle (07 §B4) — anyone can self-submit it. */
+export interface BatchBundle {
+    readonly batchId: string;
+    readonly mode: string;
+    readonly vkey?: string | null;
+    readonly publicValues: string;
+    readonly proofBytes: string;
+    readonly settleTxid?: string | null;
+}
+export interface ReturnServiceClientOptions {
+    /** `fetch` impl (default: the global one). Injectable for tests. */
+    readonly fetch?: typeof fetch;
+}
+/** Thin REST client over the return service base URL. */
+export declare class ReturnServiceClient {
+    private readonly base;
+    private readonly doFetch;
+    constructor(baseUrl: string, opts?: ReturnServiceClientOptions);
+    /** Submit a witness request; idempotent on `nullifier`. S1 precheck rejects bad burns synchronously. */
+    postReturn(req: WitnessRequest): Promise<ReturnRecord>;
+    /** Status of a return by id. */
+    getReturn(returnId: string): Promise<ReturnRecord>;
+    /** Lookup by nullifier (32-byte hex) — wallet idempotency / recovery. */
+    getByNullifier(nullifierHex: string): Promise<ReturnRecord | null>;
+    /** The published bundle for a batch (self-settle source). */
+    getBatch(batchId: string): Promise<BatchBundle>;
+    /** Service health (queue depth, prover busy, gas) for batch-ETA + ops UI. */
+    getHealth(): Promise<ReturnServiceHealth>;
+    private json;
+}
+/** A typed return-service rejection (07 §B4). `recoverable: false` means retrying the
+ * exact same request will never succeed (e.g. a stale configHash after a vault
+ * redeploy) — callers should stop retrying and surface it as terminal. */
+export declare class ReturnServiceError extends Error {
+    readonly code: string;
+    readonly recoverable: boolean;
+    constructor(message: string, code: string, recoverable: boolean);
+}

package/lib/wallet/return-client.js

@@ -0,0 +1,100 @@
+/**
+ * `ReturnServiceClient` (06 §W3) — typed client for the Part-B return service
+ * (07 §B4). The wallet POSTs the {WitnessRequest} envelope and tracks the claim
+ * by polling `/returns/:id`; it *also* watches the vault's `Released{nullifier}`
+ * over Tron RPC independently (never trusts the service alone — 06 §A2.4). The
+ * service is trustless: it can't steal or forge, only sequence + prove (07 §B2).
+ */
+import { toHex } from '../hex.js';
+/** Thin REST client over the return service base URL. */
+export class ReturnServiceClient {
+    base;
+    doFetch;
+    constructor(baseUrl, opts = {}) {
+        this.base = baseUrl.replace(/\/+$/, '');
+        // Bind to globalThis: native `fetch` requires `this` to be the real global;
+        // calling it later as `this.doFetch(...)` would rebind `this` to the client
+        // instance and throw "Illegal invocation".
+        this.doFetch = opts.fetch ?? fetch.bind(globalThis);
+    }
+    /** Submit a witness request; idempotent on `nullifier`. S1 precheck rejects bad burns synchronously. */
+    async postReturn(req) {
+        const body = {
+            tokenCbor: toHex(req.tokenCbor),
+            configHash: toHex(req.configHash),
+            reasonBytes: toHex(req.reasonBytes),
+            ...(req.anchorHint !== undefined ? { anchorHint: req.anchorHint.toString() } : {}),
+        };
+        return this.json('POST', '/returns', body);
+    }
+    /** Status of a return by id. */
+    getReturn(returnId) {
+        return this.json('GET', `/returns/${encodeURIComponent(returnId)}`);
+    }
+    /** Lookup by nullifier (32-byte hex) — wallet idempotency / recovery. */
+    getByNullifier(nullifierHex) {
+        return this.json('GET', `/returns?nullifier=${encodeURIComponent(nullifierHex.toLowerCase())}`);
+    }
+    /** The published bundle for a batch (self-settle source). */
+    getBatch(batchId) {
+        return this.json('GET', `/batches/${encodeURIComponent(batchId)}`);
+    }
+    /** Service health (queue depth, prover busy, gas) for batch-ETA + ops UI. */
+    getHealth() {
+        return this.json('GET', '/health');
+    }
+    async json(method, path, body) {
+        const res = await this.doFetch(`${this.base}${path}`, {
+            method,
+            headers: body === undefined ? undefined : { 'content-type': 'application/json' },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        if (res.status === 404 && method === 'GET' && path.startsWith('/returns?')) {
+            return null; // not-found lookup is a clean "no record", not an error.
+        }
+        if (!res.ok) {
+            const text = await safeText(res);
+            const typed = parseTypedError(text);
+            if (typed) {
+                throw new ReturnServiceError(typed.message, typed.code, typed.recoverable);
+            }
+            throw new Error(`Return service ${method} ${path} failed: HTTP ${res.status} ${text}`);
+        }
+        return (await res.json());
+    }
+}
+/** `{error:{code,message,recoverable}}` (07 §B4 typed error shape). */
+function parseTypedError(text) {
+    try {
+        const parsed = JSON.parse(text);
+        const e = parsed.error;
+        if (e && typeof e.code === 'string' && typeof e.message === 'string' && typeof e.recoverable === 'boolean') {
+            return { code: e.code, message: e.message, recoverable: e.recoverable };
+        }
+    }
+    catch {
+        /* not JSON — fall through to the generic error */
+    }
+    return null;
+}
+/** A typed return-service rejection (07 §B4). `recoverable: false` means retrying the
+ * exact same request will never succeed (e.g. a stale configHash after a vault
+ * redeploy) — callers should stop retrying and surface it as terminal. */
+export class ReturnServiceError extends Error {
+    code;
+    recoverable;
+    constructor(message, code, recoverable) {
+        super(message);
+        this.code = code;
+        this.recoverable = recoverable;
+        this.name = 'ReturnServiceError';
+    }
+}
+async function safeText(res) {
+    try {
+        return await res.text();
+    }
+    catch {
+        return '';
+    }
+}

package/lib/wallet/self-mint-verifier.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The depositor's own mint-reason verifier: identical to the strict one the
+ * wallet registers, but at `confirmations: 0`. The depositor witnessed its own
+ * lock, so it accepts the mint as soon as the lock is in a block; every other
+ * wallet that receives the token re-verifies under the manifest's `K`.
+ */
+import type { IMintJustificationVerifier } from '@unicitylabs/state-transition-sdk/lib/transaction/verification/IMintJustificationVerifier.js';
+import { type CreateBridgePluginDeps } from '../index.js';
+import { type LoadedBridge } from './manifest.js';
+export declare function selfMintVerifier(bridge: LoadedBridge, deps?: CreateBridgePluginDeps): IMintJustificationVerifier;

package/lib/wallet/self-mint-verifier.js

@@ -0,0 +1,5 @@
+import { createBridgePlugin } from '../index.js';
+import { assetConfigFromManifest } from './manifest.js';
+export function selfMintVerifier(bridge, deps = {}) {
+    return createBridgePlugin(assetConfigFromManifest(bridge.manifest, 0), deps).verifier;
+}

package/lib/wallet/signer.d.ts

@@ -0,0 +1,18 @@
+import type { ContractCall } from '../contract-call.js';
+export interface SourceSigner {
+    connect(): Promise<string>;
+    getAddress(): Promise<string>;
+    getNetwork(): Promise<number>;
+    sendCall(call: ContractCall): Promise<string>;
+    onChange?(cb: (e: WalletChange) => void): () => void;
+}
+export interface WalletChange {
+    readonly kind: 'accountsChanged' | 'chainChanged' | 'disconnect';
+}
+export interface SourceWalletProvider {
+    readonly id: string;
+    readonly name: string;
+    /** True when this wallet can be used in the current environment (extension present, etc.). */
+    isAvailable(): boolean;
+    create(chainId: number): SourceSigner;
+}

package/lib/wallet/signer.js

@@ -0,0 +1 @@
+export {};

package/lib/wallet/source-adapter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Bridge-in **source adapter** (08 Phase 4 — the three-boundary abstraction).
+ *
+ * The orchestrator (Sphere) is chain-neutral: it runs an ordered list of opaque
+ * {DepositStep}s, waits for receipts, guards account/network, persists recovery,
+ * and mints. Everything chain-specific — how many signatures a deposit takes,
+ * whether an ERC-20 `approve` is needed, how the commit (lock) event decodes, and
+ * how the mint justification is built — lives behind {BridgeSourceAdapter}.
+ *
+ * One adapter serves every family: the deposit is the same two calls on the
+ * same vault ABI, the lock event decodes the same way, and the signer the
+ * wallet hands in encodes the calls for its chain.
+ */
+import type { BridgeSourceAdapter } from '@unicitylabs/bridge-core';
+import type { ContractCall } from '../contract-call.js';
+import type { CreateBridgePluginDeps } from '../index.js';
+import type { ConstantCaller } from '../source-chain.js';
+import { type LoadedBridge } from './manifest.js';
+export type { BridgeSourceAdapter, CommitInfo, DepositParams, DepositRecovery, DepositStep, MintRequest, MintRequestArgs, PreparedDeposit, } from '@unicitylabs/bridge-core';
+/** The wallet capability a deposit step needs. */
+export interface DepositWallet {
+    getAddress(): Promise<string>;
+    sendCall(call: ContractCall): Promise<string>;
+}
+/** The node read the adapter needs (allowance). */
+export type AllowanceReader = ConstantCaller;
+/**
+ * Build the {BridgeSourceAdapter} for a loaded bridge. Closes over the wallet
+ * (for the deposit steps) and a node client (for the allowance read); the mint
+ * verifier override is built with `deps`; by default it reads the wallet's value
+ * payload, which is the production bridge token value format.
+ */
+export declare function createSourceAdapter(bridge: LoadedBridge, wallet: DepositWallet, rpc: AllowanceReader, deps?: CreateBridgePluginDeps): BridgeSourceAdapter;