@unicitylabs/bridge-core 0.2.0-dev.1

package/lib/index.d.ts

@@ -0,0 +1,207 @@
+/**
+ * `@unicitylabs/bridge-core` — the chain-neutral bridge contracts (08 Phase 4,
+ * the three-boundary abstraction). A wallet's bridge-in orchestration runs on
+ * these interfaces alone; each source chain (Tron today, EVM next) ships a plugin
+ * that *implements* them. The orchestrator therefore never imports a chain
+ * package — only this one — so adding a chain is additive, never a fork.
+ *
+ * The three boundaries:
+ *   - {ChainWallet}          connect · live account/network (no reads, no sends)
+ *   - {ReceiptReader}        node reads: tx receipts (no signing)
+ *   - {BridgeSourceAdapter}  "deposit X for recipient" -> opaque {DepositStep}[],
+ *                            decode the commit, build the Unicity mint request
+ * plus {BridgePresentation} (explorer link + address validation) for the UI.
+ */
+import type { IMintJustificationVerifier } from '@unicitylabs/state-transition-sdk/lib/transaction/verification/IMintJustificationVerifier.js';
+/**
+ * The wallet capabilities the orchestrator needs: connect once, then read the
+ * **live** account/network before every signature. No signing here — the deposit
+ * steps sign via the wallet the adapter closed over.
+ */
+export interface ChainWallet {
+    connect(): Promise<string>;
+    getAddress(): Promise<string>;
+    getNetwork(): Promise<number>;
+}
+/**
+ * A committing/approval tx receipt the orchestrator inspects only for revert; the
+ * rest is opaque and handed back to the adapter's `decodeCommit`. `null` until the
+ * tx is mined.
+ */
+export interface TxReceipt {
+    readonly success: boolean;
+}
+/** Node-read surface the orchestrator needs: a tx receipt by id. */
+export interface ReceiptReader {
+    getReceipt(txid: string): Promise<TxReceipt | null>;
+}
+/** One opaque step the orchestrator runs blindly (sign+broadcast → txid). */
+export interface DepositStep {
+    /** Progress label shown while the step runs. */
+    readonly label: string;
+    /** Whether the orchestrator must wait for this tx to succeed before the next step. */
+    readonly awaitReceipt: boolean;
+    /** Sign + broadcast; resolves to the txid. The wallet + call are the adapter's concern. */
+    send(): Promise<string>;
+}
+/** Recovery material the orchestrator persists before the committing step. */
+export interface DepositRecovery {
+    readonly tokenIdHex: string;
+    readonly saltHex: string;
+    readonly recipientCommitmentHex: string;
+    readonly coinIdHex: string;
+    readonly tokenTypeHex: string;
+    readonly chainId: number;
+}
+export interface PreparedDeposit {
+    readonly recovery: DepositRecovery;
+    /** Ordered steps; the one at {commitIndex} carries the commit (lock) event. */
+    readonly steps: readonly DepositStep[];
+    readonly commitIndex: number;
+}
+/** Decoded commit (lock) facts the mint justification binds to. */
+export interface CommitInfo {
+    readonly nonce: bigint;
+    readonly blockNumber: bigint;
+    readonly logIndex: number;
+}
+/** A chain-neutral Unicity mint request (the orchestrator hands this to the wallet via {mintBridgedToken}). */
+export interface MintRequest {
+    readonly coinIdHex: string;
+    readonly amount: bigint;
+    /** The genesis value payload, in the wallet's value format. */
+    readonly mintData: Uint8Array;
+    readonly tokenType: Uint8Array;
+    readonly salt: Uint8Array;
+    readonly genesisReason: Uint8Array;
+    readonly mintJustificationVerifiers: readonly IMintJustificationVerifier[];
+}
+export interface DepositParams {
+    readonly amount: bigint;
+    readonly networkId: number;
+    readonly recipientPubkey?: Uint8Array;
+    readonly ownerPredicateCbor?: Uint8Array;
+    readonly approveAmount?: bigint;
+}
+export interface MintRequestArgs {
+    readonly saltHex: string;
+    readonly amount: bigint;
+    readonly commit: CommitInfo;
+    readonly commitTxid: string;
+}
+/** The chain-neutral bridge-in source the orchestrator drives. */
+export interface BridgeSourceAdapter {
+    /** Derive the recovery material + the ordered opaque deposit steps. */
+    prepareDeposit(params: DepositParams): Promise<PreparedDeposit>;
+    /** Decode a committing tx's raw receipt into {CommitInfo}; null if the event isn't present yet. */
+    decodeCommit(rawReceipt: unknown): CommitInfo | null;
+    /** Build the Unicity mint request for a (recovered) committed deposit. */
+    buildMintRequest(args: MintRequestArgs): MintRequest;
+}
+/**
+ * The chain-specific UI presentation a bridge needs: a source-chain explorer link
+ * and destination-address validation. The wallet UI holds one per bridge and never
+ * keys on a numeric chainId or hardcodes a chain's URL / address shape — the bridge
+ * supplies it.
+ */
+export interface BridgePresentation {
+    /** Block-explorer URL for a source-chain transaction. */
+    explorerTxUrl(txid: string): string;
+    /** Structural validity of a destination address on this bridge's source chain. */
+    validateAddress(addr: string): boolean;
+}
+/**
+ * Chain-neutral fields every bridged-asset manifest carries, whatever the source
+ * chain family. Integrity-pinned; all byte fields are lowercase hex, no `0x`. The
+ * chain is identified by {chainRef} — a CAIP-2-style string/hex reference
+ * (`tron:0x…`, `eip155:1`) — not a JavaScript number; a family's native numeric id
+ * (if any) lives inside that family's plugin manifest variant.
+ */
+export type ChainFamily = 'tron' | 'eip155';
+export interface BridgeManifestBase {
+    /** Human label for the bridged asset, e.g. "USDT (bridged · Tron)". */
+    readonly label: string;
+    readonly symbol: string;
+    /** CAIP-2-style chain reference (e.g. `tron:0xcd8690dc`) — the generic chain identity. */
+    readonly chainRef: string;
+    /** Deployed vault (lock) address, in any of the chain's address forms. */
+    readonly vault: string;
+    /** Bridged asset (token) address, same forms. */
+    readonly asset: string;
+    /** Source-finality threshold an independent receiver enforces (K). */
+    readonly confirmations: number;
+    /** Token decimals. */
+    readonly decimals: number;
+    /** Part-B return-service base URL (bridge-back handoff). */
+    readonly returnServiceUrl: string;
+    /** `BridgeBackReason` CBOR tag the vault/prover bind (frozen config). */
+    readonly reasonTag: number;
+    /** 32-byte lock domain separator the deployed vault was constructed with (hex). */
+    readonly lockDomain: string;
+    /** 32-byte nullifier domain separator (hex). */
+    readonly nullifierDomain: string;
+    /** Groth16 verification key fingerprint the vault enforces (`0x…`); display/ops. */
+    readonly vkey: string;
+    /** 32-byte `configHash` the deployed vault self-derives (hex). Cross-checked at load. */
+    readonly configHash: string;
+    /** Optional explicit `tokenTypeHex`; derived + cross-checked when present. */
+    readonly tokenTypeHex?: string;
+    /** Optional explicit `coinIdHex`; derived + cross-checked when present. */
+    readonly coinIdHex?: string;
+    readonly disabledReason?: string;
+}
+export interface WalletTokenPlugin {
+    readonly id: string;
+    readonly mintJustificationVerifiers: readonly IMintJustificationVerifier[];
+}
+export interface WalletMintResult {
+    readonly success: boolean;
+    readonly tokenId?: string;
+    readonly error?: string;
+}
+export interface WalletBurnResult {
+    readonly success: boolean;
+    readonly burnId: string;
+    readonly tokenId: string;
+    readonly burnedToken?: Uint8Array;
+    readonly error?: string;
+}
+export interface WalletPendingBurn {
+    readonly burnId: string;
+    readonly tokenId: string;
+    readonly reasonBytes: Uint8Array;
+    readonly burnedToken: Uint8Array | null;
+    readonly settled: boolean;
+}
+export interface BridgePayments {
+    mintCustom(request: {
+        readonly tokenType: Uint8Array;
+        readonly salt: Uint8Array;
+        readonly data: Uint8Array;
+        readonly justification?: Uint8Array;
+        readonly assets: readonly {
+            coinId: string;
+            amount: bigint;
+        }[];
+        readonly mintJustificationVerifiers?: readonly IMintJustificationVerifier[];
+    }): Promise<WalletMintResult>;
+    burn(request: {
+        readonly tokenId: string;
+        readonly reasonBytes: Uint8Array;
+    }): Promise<WalletBurnResult>;
+    tokenJustification(tokenId: string): Promise<Uint8Array | null>;
+    pendingBurns(): Promise<readonly WalletPendingBurn[]>;
+    acknowledgeBurn(burnId: string): Promise<void>;
+}
+export declare function mintBridgedToken(payments: BridgePayments, request: MintRequest): Promise<WalletMintResult>;
+export interface BurnForReturnArgs {
+    readonly tokenId: string;
+    readonly reasonBytes: Uint8Array;
+    readonly persist: (burnedToken: Uint8Array, burnId: string) => Promise<void>;
+}
+export interface BurnForReturnResult {
+    readonly burnId: string;
+    readonly burnedToken: Uint8Array;
+}
+export declare function burnForReturn(payments: BridgePayments, args: BurnForReturnArgs): Promise<BurnForReturnResult>;
+export declare function recoverPendingBurns(payments: BridgePayments, persist: BurnForReturnArgs['persist']): Promise<readonly BurnForReturnResult[]>;

package/lib/index.js

@@ -0,0 +1,30 @@
+export function mintBridgedToken(payments, request) {
+    return payments.mintCustom({
+        tokenType: request.tokenType,
+        salt: request.salt,
+        data: request.mintData,
+        justification: request.genesisReason,
+        assets: [{ coinId: request.coinIdHex, amount: request.amount }],
+        mintJustificationVerifiers: request.mintJustificationVerifiers,
+    });
+}
+export async function burnForReturn(payments, args) {
+    const result = await payments.burn({ tokenId: args.tokenId, reasonBytes: args.reasonBytes });
+    if (!result.success || !result.burnedToken) {
+        throw new Error(`burn failed for token ${args.tokenId}: ${result.error ?? 'no burned blob returned'}`);
+    }
+    await args.persist(result.burnedToken, result.burnId);
+    await payments.acknowledgeBurn(result.burnId);
+    return { burnId: result.burnId, burnedToken: result.burnedToken };
+}
+export async function recoverPendingBurns(payments, persist) {
+    const recovered = [];
+    for (const pending of await payments.pendingBurns()) {
+        if (!pending.settled || pending.burnedToken === null)
+            continue;
+        await persist(pending.burnedToken, pending.burnId);
+        await payments.acknowledgeBurn(pending.burnId);
+        recovered.push({ burnId: pending.burnId, burnedToken: pending.burnedToken });
+    }
+    return recovered;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@unicitylabs/bridge-core",
+  "version": "0.2.0-dev.1",
+  "description": "Chain-neutral bridge contracts: the source-adapter, wallet/client boundaries, and presentation interfaces a wallet's bridge orchestration runs on. Chain plugins (Tron, EVM, …) implement these; the orchestrator never imports a chain package.",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "files": [
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./lib/*.js": {
+      "types": "./lib/*.d.ts",
+      "default": "./lib/*.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unicitynetwork/unicity-bridge.git",
+    "directory": "packages/bridge-core"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@unicitylabs/state-transition-sdk": "3.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}