@unicitylabs/bridge-plugin 0.2.0-dev.1

package/lib/wallet/source-adapter.js

@@ -0,0 +1,99 @@
+import { BridgeLockJustification } from '../BridgeLockJustification.js';
+import { fromHex } from '../hex.js';
+import { decodeLockEvent } from '../lock-event.js';
+import { encodeBridgePaymentData } from '../value.js';
+import { queryAllowance } from './allowance.js';
+import { buildBridgeInPlan } from './facade.js';
+import { chainName } from './manifest.js';
+import { selfMintVerifier } from './self-mint-verifier.js';
+/**
+ * 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 function createSourceAdapter(bridge, wallet, rpc, deps = {}) {
+    const cfg = bridge.plugin.resolvedConfig;
+    const vaultHex = cfg.lockContractHex;
+    const where = `${bridge.manifest.symbol} on ${chainName(bridge)}`;
+    return {
+        async prepareDeposit(params) {
+            const plan = await buildBridgeInPlan({
+                plugin: bridge.plugin,
+                amount: params.amount,
+                networkId: params.networkId,
+                recipientPubkey: params.recipientPubkey,
+                ownerPredicateCbor: params.ownerPredicateCbor,
+                approveAmount: params.approveAmount,
+            });
+            const recovery = {
+                tokenIdHex: plan.tokenIdHex,
+                saltHex: plan.saltHex,
+                recipientCommitmentHex: plan.recipientCommitmentHex,
+                coinIdHex: bridge.plugin.coinIdHex,
+                tokenTypeHex: bridge.plugin.tokenTypeHex,
+                chainId: bridge.manifest.chainId,
+            };
+            const lockStep = {
+                label: `Lock ${where}…`,
+                awaitReceipt: false, // the orchestrator waits for the commit receipt to decode it
+                send: () => wallet.sendCall(plan.lock),
+            };
+            // Skip the approval when the vault's allowance already covers the amount
+            // (08 §1.1). A read failure is treated as "approve" — a redundant approval
+            // is safe, a skipped-but-needed one is not.
+            let needApprove = true;
+            try {
+                const owner = await wallet.getAddress();
+                const allowance = await queryAllowance(rpc, {
+                    assetAddress: cfg.assetContractHex,
+                    owner,
+                    spender: cfg.lockContractHex,
+                });
+                needApprove = allowance < params.amount;
+            }
+            catch {
+                needApprove = true;
+            }
+            if (!needApprove) {
+                return { recovery, steps: [lockStep], commitIndex: 0 };
+            }
+            const approveStep = {
+                label: `Approve ${where}…`,
+                awaitReceipt: true,
+                send: () => wallet.sendCall(plan.approve),
+            };
+            return { recovery, steps: [approveStep, lockStep], commitIndex: 1 };
+        },
+        decodeCommit(rawReceipt) {
+            const info = rawReceipt;
+            if (!info)
+                return null;
+            const logIndex = info.logs.findIndex((l) => l.address.toLowerCase() === vaultHex);
+            const decoded = logIndex >= 0 ? decodeLockEvent(info.logs[logIndex]) : null;
+            if (!decoded)
+                return null;
+            return { nonce: decoded.nonce, blockNumber: info.blockNumber, logIndex };
+        },
+        buildMintRequest({ saltHex, amount, commit, commitTxid }) {
+            const genesisReason = new BridgeLockJustification({
+                chainId: bridge.manifest.chainId,
+                lockContract: fromHex(cfg.lockContractHex),
+                assetContract: fromHex(cfg.assetContractHex),
+                txid: fromHex(commitTxid),
+                logIndex: commit.logIndex,
+                amount,
+                nonce: commit.nonce,
+            }).toCBOR();
+            return {
+                coinIdHex: bridge.plugin.coinIdHex,
+                amount,
+                mintData: encodeBridgePaymentData(cfg.coinId, amount),
+                tokenType: cfg.tokenType,
+                salt: fromHex(saltHex),
+                genesisReason,
+                mintJustificationVerifiers: [selfMintVerifier(bridge, deps)],
+            };
+        },
+    };
+}

package/lib/wallet/token-plugin.d.ts

@@ -0,0 +1,4 @@
+import type { WalletTokenPlugin } from '@unicitylabs/bridge-core';
+import type { LoadedBridge } from './manifest.js';
+export declare function bridgeTokenPlugin(bridge: LoadedBridge): WalletTokenPlugin;
+export declare function mergeBridgeTokenPlugins(plugins: readonly WalletTokenPlugin[]): WalletTokenPlugin;

package/lib/wallet/token-plugin.js

@@ -0,0 +1,20 @@
+import { BridgeMintJustificationVerifier } from '../BridgeMintJustificationVerifier.js';
+import { LockMintJustificationVerifier } from '../LockMintJustificationVerifier.js';
+export function bridgeTokenPlugin(bridge) {
+    return {
+        id: `bridge:${bridge.manifest.chainRef}:${bridge.manifest.symbol.toLowerCase()}`,
+        mintJustificationVerifiers: [bridge.plugin.verifier],
+    };
+}
+export function mergeBridgeTokenPlugins(plugins) {
+    const verifiers = plugins.flatMap((p) => p.mintJustificationVerifiers);
+    for (const v of verifiers) {
+        if (!(v instanceof LockMintJustificationVerifier)) {
+            throw new Error(`mergeBridgeTokenPlugins: verifier for tag ${v.tag} is not a bridge lock verifier`);
+        }
+    }
+    return {
+        id: 'bridge',
+        mintJustificationVerifiers: [new BridgeMintJustificationVerifier(verifiers)],
+    };
+}

package/manifests/bridges.nile.json

@@ -0,0 +1,23 @@
+{
+  "description": "Sphere bridge manifest — Tron Nile USDT (M3/M4). Frozen from deployments/nile/nile-usdt.json; configHash equals the deployed vault CONFIG_HASH. returnServiceUrl is environment-specific.",
+  "bridges": [
+    {
+      "label": "USDT (bridged · Tron)",
+      "symbol": "USDT",
+      "chainId": 3448148188,
+      "vault": "TTKKLyhnRRQ7XV5vsRarV8xWWEvF9225mY",
+      "asset": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
+      "confirmations": 20,
+      "decimals": 6,
+      "rpcUrl": "https://nile.trongrid.io",
+      "returnServiceUrl": "http://localhost:8787",
+      "reasonTag": 39048,
+      "lockDomain": "158b847f78b3910a5f5f42820de61abba1bf5ae1fbb29dabfba09118f393f932",
+      "nullifierDomain": "d4530e4ea58fc8e38f84506e62b421476c3eeec70f4cbebefc32688a510e2d5d",
+      "vkey": "0x00c34ae0ebb63e86218a754892813f4744b2f6c9ed613c085ea40999b16ce3ad",
+      "configHash": "7f376b16b3bff3455f375e7cf30b9d29d2a14332912f0ffb69d78e1b31d5193f",
+      "tokenTypeHex": "6f2d10d27abeb4960a7ef19370c965ec090bb4da1f17752be77334e2dde19c74",
+      "coinIdHex": "f1634862e1b932acd1c791a1860c62f69c7f55aa6c6115ba631d3bf4a9d8ddbb"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@unicitylabs/bridge-plugin",
+  "version": "0.2.0-dev.1",
+  "description": "Unicity bridge plugin: verifies bridged tokens against their source-chain lock (Tron and Ethereum-family chains) and drives bridge-in and bridge-out for a wallet.",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "files": [
+    "lib",
+    "manifests",
+    "README.md",
+    "DEMO.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./wallet": {
+      "types": "./lib/wallet/index.d.ts",
+      "default": "./lib/wallet/index.js"
+    },
+    "./bridge-back": {
+      "types": "./lib/bridge-back/index.d.ts",
+      "default": "./lib/bridge-back/index.js"
+    },
+    "./lib/*.js": {
+      "types": "./lib/*.d.ts",
+      "default": "./lib/*.js"
+    },
+    "./lib/wallet/*.js": {
+      "types": "./lib/wallet/*.d.ts",
+      "default": "./lib/wallet/*.js"
+    },
+    "./lib/bridge-back/*.js": {
+      "types": "./lib/bridge-back/*.d.ts",
+      "default": "./lib/bridge-back/*.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unicitynetwork/unicity-bridge.git",
+    "directory": "packages/bridge-plugin"
+  },
+  "bin": {
+    "tron-usdt-bridge": "./lib/cli/main.js"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "cli": "tsx src/cli/main.ts",
+    "e2e": "tsx demo/e2e.ts",
+    "e2e:back": "tsx demo/bridge-back-e2e.ts"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@noble/hashes": "2.2.0",
+    "@unicitylabs/bridge-core": "0.2.0-dev.1",
+    "@unicitylabs/state-transition-sdk": "3.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tronweb": "^6.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}