@unicitylabs/bridge-plugin 0.2.0-dev.1

package/DEMO.md

@@ -0,0 +1,255 @@
+# Real end-to-end bridge demo — Tron Nile → Unicity
+
+This is a **live** demo. It deploys a real lock contract to the **Tron Nile
+testnet**, locks USDT there, mints a **real Unicity token** (testnet2) whose
+mint reason is the on-chain Tron lock, transfers that token to a second owner
+over the Unicity aggregator, and has the receiver re-verify it — which
+re-queries the live Tron node to confirm the lock still backs the token.
+
+**Finality model.** The party who locked the asset trusts its own lock, so it
+mints as soon as the lock tx is **in a block** — it does not wait for `K`
+confirmations. The confirmation threshold is a *verifier-side* parameter: an
+independent receiver enforces `K` (default 20) and, if the lock isn't final yet,
+reports "awaiting source finality" and **retries until it is** (see step 5).
+
+Nothing here is mocked: every step produces an on-chain transaction or a real
+aggregator commitment you can open in a block explorer.
+
+```
+Tron Nile (TVM)                         Unicity testnet2 (aggregator)
+───────────────                         ─────────────────────────────
+MockTRC20 (USDT)  ──approve──┐
+                             ▼
+UnicityLock.lock(amount, tokenId, recipientCommitment)
+        │  emits Lock(nonce, from, amount, tokenId, recipientCommitment)
+        │
+        └────────────── mint reason (self-contained proof) ──────────────┐
+                                                                          ▼
+                                          MintTransaction(justification) ─┴─► Token
+                                                   │  (Token.mint re-checks the
+                                                   │   lock against live Nile RPC)
+                                                   ▼
+                                          transfer ─► new owner
+                                                   ▼
+                                          receiver: token.verify()  ── re-queries Nile ──► OK
+```
+
+## What you need
+
+| Requirement | How to get it |
+|---|---|
+| Node ≥ 22 | `node -v` |
+| A funded **Tron Nile** account | private key (hex) holding test TRX — faucet: https://nileex.io/join/getJoinPage |
+| (optional) TronGrid API key | https://www.trongrid.io — raises rate limits |
+| Network access to Unicity testnet2 | `https://gateway.testnet2.unicity.network` (default, no key) |
+
+The Unicity recipient/owner keys are **generated by the demo** (throwaway). The
+USDT is a `MockTRC20` the demo deploys, so you don't need real Nile USDT.
+
+## Setup
+
+```bash
+cd packages/bridge-plugin
+npm install          # or run npm install from the repository root
+
+# Required: a Nile-testnet account funded with test TRX.
+export TRON_PRIVATE_KEY=<your-nile-private-key-hex>
+
+# Optional overrides (defaults shown):
+export TRON_RPC=https://nile.trongrid.io
+# export TRON_API_KEY=<trongrid-api-key>
+export AMOUNT=1000000                                   # 1.000000 USDT (6 decimals)
+export CONFIRMATIONS=20                                 # receiver-side finality threshold (K)
+export MINT_CONFIRMATIONS=0                             # minter self-trust: 0 = just needs to be in a block
+# export VERIFY_TIMEOUT_MS=300000                       # receiver keeps retrying to finality this long
+# export VERIFY_RETRY_MS=6000                           # delay between receiver retries
+export UNICITY_AGGREGATOR=https://gateway.testnet2.unicity.network
+# export UNICITY_API_KEY=<aggregator-api-key>   # only if your gateway requires one
+export UNICITY_NETWORK_ID=4
+```
+
+State is written to `demo/.demo-state.json` between steps, so you can run each
+command independently and inspect what happened. Delete that file to start over.
+
+---
+
+## Step 1 — Deploy the lock + test USDT to Tron Nile
+
+```bash
+npm run e2e deploy
+```
+
+Deploys `MockTRC20` (the bridged "USDT") and `UnicityLock(asset, admin)`, then
+mints test-USDT to your account. Prints the two contract addresses, the deploy
+tx hashes (open them on https://nile.tronscan.org), and the **deterministic
+bridged-asset identifiers** (`TokenType`, `coinId`) derived from
+`chainId + assetContract`.
+
+```
+Deployer: T...  (chainId 3448148188)
+Deploying MockTRC20 (USDT stand-in)...
+  asset (USDT) = T...   https://nile.tronscan.org/#/transaction/...
+Deploying UnicityLock(asset, admin)...
+  lock         = T...   https://nile.tronscan.org/#/transaction/...
+Minting 10000000 test-USDT to deployer...
+✔ deploy complete.
+```
+
+### Step 1 alternative — attach to the deployed vault and real Nile USDT
+
+```bash
+TRON_VAULT=TTKKLyhnRRQ7XV5vsRarV8xWWEvF9225mY \
+TRON_USDT=TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf \
+npm run e2e attach
+```
+
+Skips deployment and records the live Nile vault (`deployments/nile/nile-usdt.json`)
+and the faucet USDT as the target. Your `TRON_PRIVATE_KEY` account must already
+hold Nile USDT (faucet: https://nileex.io/join/getJoinPage) and TRX for fees.
+Everything after (`lock`, `mint`, `transfer`, `verify`) is unchanged, and the
+resulting token is minted against the same vault the wallet manifest points at.
+
+## Step 2 — Lock USDT, bound to a specific Unicity token + recipient
+
+```bash
+npm run e2e lock
+```
+
+Generates the Unicity recipient key, derives the `tokenId` from a fresh salt,
+and computes `recipientCommitment = SHA256(recipient predicate)`. Then on Tron
+it `approve`s and calls `lock(amount, tokenId, recipientCommitment)`. The
+`Lock` event commits the deposit to **exactly this token id and recipient** — so
+it can fund one token, ownable only by that recipient.
+
+```
+Bridge intent:
+  Unicity tokenId        = ...
+  recipientCommitment    = ...
+  amount                 = 1000000 (6 decimals)
+  approve tx = https://nile.tronscan.org/#/transaction/...
+  lock tx    = https://nile.tronscan.org/#/transaction/...
+  block = ..., logIndex = 0, nonce = 0
+✔ lock complete.
+```
+
+## Step 3 — Mint the bridged Unicity token (immediately, no finality wait)
+
+```bash
+npm run e2e mint
+```
+
+Builds the mint reason — a self-contained CBOR proof (`tag 1330002`) referencing
+the real Nile lock tx — and mints the token on Unicity testnet2. `Token.mint`
+runs the bridge plugin's verifier at `MINT_CONFIRMATIONS` (default **0**), so it
+confirms the lock **exists, succeeded, and binds this exact token id +
+recipient** — without waiting for finality, because the minter is the locker and
+trusts its own deposit. (Run this right after `lock`; you don't wait a minute.)
+
+```
+Submitting mint commitment to https://gateway.testnet2.unicity.network ...
+Waiting for inclusion proof + checking the lock is in a block on Nile...
+✔ mint complete. A real Unicity token now encapsulates the bridged USDT.
+  tokenId  = ...
+  value    = 1000000 (coinId ...)
+```
+
+> Optional: `npm run e2e wait` is a read-only helper that just watches
+> confirmations accrue on Nile. It's not on the critical path.
+
+## Step 4 — Transfer the token to a second owner
+
+```bash
+npm run e2e transfer
+```
+
+Generates a new owner, builds a `TransferTransaction`, certifies it on the
+aggregator, and applies it. This is an ordinary Unicity off-chain transfer of
+the bridged token.
+
+## Step 5 — Receiver verifies the received token (enforces finality)
+
+```bash
+npm run e2e verify
+```
+
+The receiver deserializes the token and calls `token.verify(...)`, which checks
+ownership + history **and re-runs the bridge mint-reason check against the live
+Tron node** at the strict `CONFIRMATIONS` threshold. If you ran `mint`
+immediately, the lock may not be final yet — the receiver then reports
+"awaiting source finality (X < K)" and **retries every few seconds until it is**,
+rather than failing:
+
+```
+Receiver verifies from scratch (requires 20 confirmations on Tron)...
+  [attempt 1] Insufficient confirmations: 4 < 20 (awaiting source finality).
+            not final yet — retrying in 6s ...
+  [attempt 2] Insufficient confirmations: 11 < 20 (awaiting source finality).
+            not final yet — retrying in 6s ...
+
+  ownership + history (Unicity)   : OK
+  mint reason (re-checked vs Nile): OK
+✔ RECEIVED TOKEN VERIFIED.
+  The token is genuinely backed by 1000000 locked USDT on Tron Nile,
+  bound to this token id, and now owned by the receiver — no trusted bridge operator.
+```
+
+Exit codes: `0` verified, `1` genuine rejection (the token does **not** back its
+claimed lock — full trace printed), `2` timed out still awaiting finality (re-run
+later, or lower `CONFIRMATIONS` as a receiver-side trust choice). A real
+rejection (e.g. wrong amount, wrong recipient) is reported as fatal immediately —
+only insufficient-confirmations is treated as transient and retried.
+
+---
+
+## One-shot
+
+To run the whole flow end to end (with the finality wait built in):
+
+```bash
+TRON_PRIVATE_KEY=<hex> ./demo/run-demo.sh
+```
+
+## Inspect / reset
+
+```bash
+npm run e2e status                 # what's been done so far
+cat demo/.demo-state.json          # addresses, tx hashes, tokenId, serialized token
+rm demo/.demo-state.json           # start over
+```
+
+## How this maps to the design
+
+- **Mint reason format & verification rule:** [`../../docs/spec/MINT_REASON.md`](../../docs/spec/MINT_REASON.md)
+- **Lock contract:** [`../../contracts/tron/contracts/UnicityLock.sol`](../../contracts/tron/contracts/UnicityLock.sol)
+- **Verifier (the security):** [`src/TronUsdtMintJustificationVerifier.ts`](src/TronUsdtMintJustificationVerifier.ts)
+- **Offline security demo (mock RPC, attack matrix):** `npm run cli demo`
+
+## Bridge-BACK demo (return path, live testnet2)
+
+`npm run e2e:back` runs the return path against the **live** Unicity aggregator
+(only the Tron lock is mocked in-process): it mints a **bridge-lock-genesis**
+token (real `TronUsdtLockJustification`, structurally verified at mint), burns it
+to a canonical `BridgeBackReason` — terminal recipient predicate
+`BurnPredicate(H(reasonBytes))` with `reasonBytes` in the burn's auxiliary data
+(00 §4) — certifies the burn on the aggregator, then derives the `nullifier` +
+return leaf from the **real** certified burn (state id + tx hash) exactly as the
+prover will (00 §5/§7). It writes the burned-token blob + prover config +
+witness-request envelope to `demo/.bridge-back-state.json`. Reads the repo-root
+`.env` (`UNICITY_GATEWAY`, `UNICITY_API_KEY`, `UNICITY_TRUSTBASE`).
+Source: [`demo/bridge-back-e2e.ts`](demo/bridge-back-e2e.ts).
+
+**Cross-stack closure.** The Rust prover then decodes that exact live blob and
+confirms it derives identical values (E3 `bridge_lock_obligation` lockDigest +
+nonce, `configHash`, burn state id/tx hash, `burnTransitionId`, `nullifier`):
+
+```
+cd ../prover && cargo run -p bridge-return-host --example cross_check_live -- \
+  ../packages/bridge-plugin/demo/.bridge-back-state.json
+```
+
+> Interop note: the token's value payload is the **wallet's format**
+> (`SpherePaymentData`, CBOR tag 39050; `protocol/interop.md` §2.1), written and
+> read by `encodeBridgePaymentData` / `decodeBridgePaymentData` in `src/value.ts`.
+> The bespoke `encodeBridgedValue` there is CLI-only. The Rust prover's decoder
+> follows in the SDK-v3 port (`docs/dev-plan/09-testnet-e2e.md`, Phase 2); until
+> then `cross_check_live` does not accept tokens minted by this demo.

package/README.md

@@ -0,0 +1,89 @@
+# @unicitylabs/bridge-plugin
+
+Unicity bridge plugin that validates **bridged USDT-on-Tron** tokens. It is an
+`IMintJustificationVerifier` for the Unicity state-transition SDK: every
+recipient of a bridged token re-checks the token's **mint reason** (a
+self-contained Tron lock proof) against a Tron RPC node. There is no trusted
+bridge operator.
+
+See the design docs:
+- [`../../docs/spec/MINT_REASON.md`](../../docs/spec/MINT_REASON.md) — proof format + verification rule
+- [`../../docs/spec/PLUGIN_ARCHITECTURE.md`](../../docs/spec/PLUGIN_ARCHITECTURE.md) — how plugins plug in
+- [`../../docs/spec/ZK_BACK3.md`](../../docs/spec/ZK_BACK3.md) — returning to Tron
+
+## How security works
+
+Minting on Unicity is permissionless (the minter key is derived from the
+`tokenId`), so all bridge security comes from this verifier. The Tron
+`UnicityLock` contract commits each deposit to the exact Unicity `tokenId` and to
+`recipientCommitment = SHA256(recipient predicate)`. A deposit can therefore fund
+exactly one token, owned only by the designated recipient:
+
+| Attack | Rejected because |
+|---|---|
+| Mint without a real lock | RPC finds no matching Lock event |
+| Replay a lock for a second token | event.unicityTokenId ≠ this token's id |
+| Inflate value vs. locked amount | token value ≠ event amount |
+| Steal/front-run a lock | event.recipientCommitment ≠ H(recipient) |
+| Point at a rogue lock contract | trust-anchor (chain/contract/asset) mismatch |
+| Use an unconfirmed lock | confirmations < threshold |
+
+## Usage
+
+```ts
+import { createTronUsdtBridgePlugin, tronMainnetUsdtConfig } from '@unicitylabs/bridge-plugin';
+import { MintJustificationVerifierService } from '@unicitylabs/state-transition-sdk/lib/transaction/verification/MintJustificationVerifierService.js';
+
+const plugin = createTronUsdtBridgePlugin(
+  tronMainnetUsdtConfig('TYourDeployedUnicityLockAddress'),
+  // { rpc, extractAmount }  // optional: inject a TronRpc and a value extractor
+);
+
+const service = new MintJustificationVerifierService();
+service.register(plugin.verifier); // dispatched by CBOR tag 1330002
+
+// plugin.tokenTypeHex / plugin.coinIdHex identify the bridged asset.
+```
+
+In a Sphere wallet the plugin is registered through the SDK's generic token-plugin
+seam, `Sphere.init({ plugins: [bridgeTokenPlugin(loaded)] })` (see
+`src/wallet/token-plugin.ts`); the wallet SDK has no bridge-specific code. The
+bridge-in mint and the bridge-out burn are composed over the wallet's generic
+`mintCustom` / `burn` by `@unicitylabs/bridge-core` (`mintBridgedToken`,
+`burnForReturn`, `recoverPendingBurns`). The token's declared value is checked
+by `decodeBridgePaymentData` (the wallet's value format, `src/value.ts`).
+
+## CLI
+
+```bash
+npm run cli demo          # offline security demo (mock Tron RPC)
+# or after build:
+node lib/cli/main.js demo
+
+# verify a real serialized CertifiedMintTransaction against a live node:
+node lib/cli/main.js verify --token <hex> --lock <addr> --asset <addr> \
+  --chain mainnet --rpc https://api.trongrid.io [--api-key <key>]
+```
+
+The `demo` exits non-zero if the valid token is rejected or any attack is
+accepted. Sample output:
+
+```
+✔  [OK  ] Valid bridged mint (lock finalized, bound to this token+recipient)
+✔  [FAIL] Attack: inflate token value above locked amount
+✔  [FAIL] Attack: tamper justification amount
+✔  [FAIL] Attack: replay lock for a different token id
+✔  [FAIL] Attack: steal lock by swapping recipient
+✔  [FAIL] Attack: forged lock contract emits the event
+✔  [FAIL] Attack: spend lock before finality (insufficient confirmations)
+All checks behaved as expected: valid token accepted, every attack rejected.
+```
+
+## Develop
+
+```bash
+npm install      # from the repository root; links local workspaces
+npm run typecheck
+npm test         # node:test via tsx
+npm run build
+```

package/lib/BridgeLockJustification.d.ts

@@ -0,0 +1,31 @@
+/**
+ * CBOR tag of the bridge lock justification, the same on every source chain:
+ * the chain id inside the justification tells the families apart, and the
+ * wallet's verifier for this tag dispatches on it.
+ */
+export declare const BRIDGE_LOCK_JUSTIFICATION_TAG = 1330002n;
+/** Decoded contents of a lock justification (the token's mint reason). */
+export interface BridgeLockJustificationData {
+    /** Source chain id (Tron mainnet 728126428, Nile 3448148188, Sepolia 11155111). */
+    readonly chainId: number;
+    /** 20-byte address of the canonical vault (lock) contract. */
+    readonly lockContract: Uint8Array;
+    /** 20-byte address of the bridged asset's token contract. */
+    readonly assetContract: Uint8Array;
+    /** 32-byte transaction hash of the lock() call. */
+    readonly txid: Uint8Array;
+    /** Index of the Lock event within that transaction's logs. */
+    readonly logIndex: number;
+    /** Locked amount in the asset's smallest unit. */
+    readonly amount: bigint;
+    /** Lock nonce assigned by the contract (echoed in the Lock event). */
+    readonly nonce: bigint;
+}
+/** Encodes/decodes the self-contained lock proof carried in a token's mint reason. */
+export declare class BridgeLockJustification {
+    readonly data: BridgeLockJustificationData;
+    static readonly CBOR_TAG = 1330002n;
+    constructor(data: BridgeLockJustificationData);
+    toCBOR(): Uint8Array;
+    static fromCBOR(bytes: Uint8Array): BridgeLockJustification;
+}

package/lib/BridgeLockJustification.js

@@ -0,0 +1,41 @@
+import { CborDeserializer } from '@unicitylabs/state-transition-sdk/lib/serialization/cbor/CborDeserializer.js';
+import { CborSerializer } from '@unicitylabs/state-transition-sdk/lib/serialization/cbor/CborSerializer.js';
+/**
+ * CBOR tag of the bridge lock justification, the same on every source chain:
+ * the chain id inside the justification tells the families apart, and the
+ * wallet's verifier for this tag dispatches on it.
+ */
+export const BRIDGE_LOCK_JUSTIFICATION_TAG = 1330002n;
+const VERSION = 1n;
+/** Encodes/decodes the self-contained lock proof carried in a token's mint reason. */
+export class BridgeLockJustification {
+    data;
+    static CBOR_TAG = BRIDGE_LOCK_JUSTIFICATION_TAG;
+    constructor(data) {
+        this.data = data;
+    }
+    toCBOR() {
+        const d = this.data;
+        return CborSerializer.encodeTag(BridgeLockJustification.CBOR_TAG, CborSerializer.encodeArray(CborSerializer.encodeUnsignedInteger(VERSION), CborSerializer.encodeUnsignedInteger(d.chainId), CborSerializer.encodeByteString(d.lockContract), CborSerializer.encodeByteString(d.assetContract), CborSerializer.encodeByteString(d.txid), CborSerializer.encodeUnsignedInteger(d.logIndex), CborSerializer.encodeUnsignedInteger(d.amount), CborSerializer.encodeUnsignedInteger(d.nonce)));
+    }
+    static fromCBOR(bytes) {
+        const tag = CborDeserializer.decodeTag(bytes);
+        if (tag.tag !== BridgeLockJustification.CBOR_TAG) {
+            throw new Error(`Invalid CBOR tag for BridgeLockJustification: ${tag.tag}`);
+        }
+        const items = CborDeserializer.decodeArray(tag.data, 8);
+        const version = CborDeserializer.decodeUnsignedInteger(items[0]);
+        if (version !== VERSION) {
+            throw new Error(`Unsupported BridgeLockJustification version: ${version}`);
+        }
+        return new BridgeLockJustification({
+            chainId: Number(CborDeserializer.decodeUnsignedInteger(items[1])),
+            lockContract: CborDeserializer.decodeByteString(items[2]),
+            assetContract: CborDeserializer.decodeByteString(items[3]),
+            txid: CborDeserializer.decodeByteString(items[4]),
+            logIndex: Number(CborDeserializer.decodeUnsignedInteger(items[5])),
+            amount: CborDeserializer.decodeUnsignedInteger(items[6]),
+            nonce: CborDeserializer.decodeUnsignedInteger(items[7]),
+        });
+    }
+}

package/lib/BridgeMintJustificationVerifier.d.ts

@@ -0,0 +1,12 @@
+import type { CertifiedMintTransaction } from '@unicitylabs/state-transition-sdk/lib/transaction/CertifiedMintTransaction.js';
+import type { Token } from '@unicitylabs/state-transition-sdk/lib/transaction/Token.js';
+import type { IMintJustificationVerifier } from '@unicitylabs/state-transition-sdk/lib/transaction/verification/IMintJustificationVerifier.js';
+import { VerificationResult } from '@unicitylabs/state-transition-sdk/lib/verification/VerificationResult.js';
+import { VerificationStatus } from '@unicitylabs/state-transition-sdk/lib/verification/VerificationStatus.js';
+import type { LockMintJustificationVerifier } from './LockMintJustificationVerifier.js';
+export declare class BridgeMintJustificationVerifier implements IMintJustificationVerifier {
+    private readonly verifiers;
+    constructor(verifiers: readonly LockMintJustificationVerifier[]);
+    get tag(): bigint;
+    verify(transaction: CertifiedMintTransaction, nestedTokenCollector: (token: Token) => void): Promise<VerificationResult<VerificationStatus>>;
+}

package/lib/BridgeMintJustificationVerifier.js

@@ -0,0 +1,35 @@
+import { VerificationResult } from '@unicitylabs/state-transition-sdk/lib/verification/VerificationResult.js';
+import { VerificationStatus } from '@unicitylabs/state-transition-sdk/lib/verification/VerificationStatus.js';
+import { BridgeLockJustification, BRIDGE_LOCK_JUSTIFICATION_TAG } from './BridgeLockJustification.js';
+import { toHex } from './hex.js';
+const RULE = 'BridgeMintJustificationVerifier';
+export class BridgeMintJustificationVerifier {
+    verifiers;
+    constructor(verifiers) {
+        this.verifiers = verifiers;
+    }
+    get tag() {
+        return BRIDGE_LOCK_JUSTIFICATION_TAG;
+    }
+    verify(transaction, nestedTokenCollector) {
+        const bytes = transaction.justification;
+        if (!bytes) {
+            return fail('Transaction has no justification.');
+        }
+        let j;
+        try {
+            j = BridgeLockJustification.fromCBOR(bytes);
+        }
+        catch (e) {
+            return fail(`Malformed justification: ${e.message}`);
+        }
+        const owner = this.verifiers.find((v) => v.accepts(j.data));
+        if (!owner) {
+            return fail(`No bridge verifies chain ${j.data.chainId} vault 0x${toHex(j.data.lockContract)}.`);
+        }
+        return owner.verify(transaction, nestedTokenCollector);
+    }
+}
+function fail(message) {
+    return Promise.resolve(new VerificationResult(RULE, VerificationStatus.FAIL, message));
+}

package/lib/LockMintJustificationVerifier.d.ts

@@ -0,0 +1,42 @@
+import type { CertifiedMintTransaction } from '@unicitylabs/state-transition-sdk/lib/transaction/CertifiedMintTransaction.js';
+import type { Token } from '@unicitylabs/state-transition-sdk/lib/transaction/Token.js';
+import type { IMintJustificationVerifier } from '@unicitylabs/state-transition-sdk/lib/transaction/verification/IMintJustificationVerifier.js';
+import { VerificationResult } from '@unicitylabs/state-transition-sdk/lib/verification/VerificationResult.js';
+import { VerificationStatus } from '@unicitylabs/state-transition-sdk/lib/verification/VerificationStatus.js';
+import type { ChainFamily } from '@unicitylabs/bridge-core';
+import { type BridgeLockJustificationData } from './BridgeLockJustification.js';
+import type { SourceChainRpc } from './source-chain.js';
+import { type BridgedAmountExtractor } from './value.js';
+/** Trust anchors + identifiers a verifier instance is bound to. */
+export interface ResolvedBridgeConfig {
+    readonly family: ChainFamily;
+    readonly chainId: number;
+    /** 20-byte EVM-form address, lowercase hex. */
+    readonly lockContractHex: string;
+    /** 20-byte EVM-form address, lowercase hex. */
+    readonly assetContractHex: string;
+    readonly confirmations: number;
+    /** 32-byte Unicity TokenType for this asset. */
+    readonly tokenType: Uint8Array;
+    /** 32-byte Sphere coinId for this asset. */
+    readonly coinId: Uint8Array;
+}
+export interface LockVerifierDeps {
+    readonly rpc: SourceChainRpc;
+    /** Defaults to the simple CLI value envelope decoder. */
+    readonly extractAmount?: BridgedAmountExtractor;
+}
+/**
+ * Validates a bridged token by re-checking its mint reason against a node of
+ * the source chain: the lock exists, is final, has the right amount, and
+ * commits to exactly this token's id + recipient. See docs/spec/MINT_REASON.md.
+ */
+export declare class LockMintJustificationVerifier implements IMintJustificationVerifier {
+    private readonly config;
+    private readonly rpc;
+    private readonly extractAmount;
+    constructor(config: ResolvedBridgeConfig, deps: LockVerifierDeps);
+    get tag(): bigint;
+    accepts(j: BridgeLockJustificationData): boolean;
+    verify(transaction: CertifiedMintTransaction, _nestedTokenCollector: (token: Token) => void): Promise<VerificationResult<VerificationStatus>>;
+}

package/lib/LockMintJustificationVerifier.js

@@ -0,0 +1,108 @@
+import { VerificationResult } from '@unicitylabs/state-transition-sdk/lib/verification/VerificationResult.js';
+import { VerificationStatus } from '@unicitylabs/state-transition-sdk/lib/verification/VerificationStatus.js';
+import { bytesEqual, toHex } from './hex.js';
+import { recipientCommitment } from './identifiers.js';
+import { decodeLockEvent } from './lock-event.js';
+import { BridgeLockJustification, BRIDGE_LOCK_JUSTIFICATION_TAG } from './BridgeLockJustification.js';
+import { decodeBridgePaymentData } from './value.js';
+const RULE = 'LockMintJustificationVerifier';
+function fail(message) {
+    return new VerificationResult(RULE, VerificationStatus.FAIL, message);
+}
+/**
+ * Validates a bridged token by re-checking its mint reason against a node of
+ * the source chain: the lock exists, is final, has the right amount, and
+ * commits to exactly this token's id + recipient. See docs/spec/MINT_REASON.md.
+ */
+export class LockMintJustificationVerifier {
+    config;
+    rpc;
+    extractAmount;
+    constructor(config, deps) {
+        this.config = config;
+        this.rpc = deps.rpc;
+        this.extractAmount = deps.extractAmount ?? decodeBridgePaymentData;
+    }
+    get tag() {
+        return BRIDGE_LOCK_JUSTIFICATION_TAG;
+    }
+    accepts(j) {
+        return j.chainId === this.config.chainId && toHex(j.lockContract).toLowerCase() === this.config.lockContractHex;
+    }
+    async verify(transaction, _nestedTokenCollector) {
+        const bytes = transaction.justification;
+        if (!bytes) {
+            return fail('Transaction has no justification.');
+        }
+        let justification;
+        try {
+            justification = BridgeLockJustification.fromCBOR(bytes);
+        }
+        catch (e) {
+            return fail(`Malformed justification: ${e.message}`);
+        }
+        const j = justification.data;
+        // 1. Trust anchors: which chain/contract/asset is authoritative.
+        if (j.chainId !== this.config.chainId) {
+            return fail(`Chain id mismatch: proof ${j.chainId}, expected ${this.config.chainId}.`);
+        }
+        if (toHex(j.lockContract).toLowerCase() !== this.config.lockContractHex) {
+            return fail('Lock contract is not the canonical bridge contract.');
+        }
+        if (toHex(j.assetContract).toLowerCase() !== this.config.assetContractHex) {
+            return fail('Asset contract is not the canonical bridged asset.');
+        }
+        // 2. Token type must be this asset's type.
+        if (!bytesEqual(transaction.tokenType.bytes, this.config.tokenType)) {
+            return fail('Token type does not match this bridged asset.');
+        }
+        // 3-4. Fetch the lock tx and require success + finality.
+        const txInfo = await this.rpc.getTransactionInfo(toHex(j.txid));
+        if (!txInfo) {
+            return fail(`Lock transaction not found: ${toHex(j.txid)}.`);
+        }
+        if (!txInfo.success) {
+            return fail('Lock transaction did not succeed.');
+        }
+        const tip = await this.rpc.getNowBlockNumber();
+        const confirmations = tip - txInfo.blockNumber;
+        if (confirmations < BigInt(this.config.confirmations)) {
+            return fail(`Insufficient confirmations: ${confirmations} < ${this.config.confirmations} (awaiting source finality).`);
+        }
+        // 5. Locate the Lock event and confirm it came from the canonical contract.
+        const log = txInfo.logs[j.logIndex];
+        if (!log) {
+            return fail(`No log at index ${j.logIndex}.`);
+        }
+        if (log.address.toLowerCase() !== this.config.lockContractHex) {
+            return fail('Log was not emitted by the canonical lock contract.');
+        }
+        const event = decodeLockEvent(log);
+        if (!event) {
+            return fail(`Log at index ${j.logIndex} is not a Lock event.`);
+        }
+        // 6. Amount: event == justification == token's declared value.
+        if (event.amount !== j.amount) {
+            return fail(`Amount mismatch: event ${event.amount}, justification ${j.amount}.`);
+        }
+        const declared = this.extractAmount(transaction.data, this.config.coinId);
+        if (declared == null) {
+            return fail('Token declares no bridged-asset value.');
+        }
+        if (declared !== event.amount) {
+            return fail(`Token value ${declared} does not match locked amount ${event.amount}.`);
+        }
+        // 7. Binding: the lock commits to exactly this token id, recipient and nonce.
+        if (event.nonce !== j.nonce) {
+            return fail(`Nonce mismatch: event ${event.nonce}, justification ${j.nonce}.`);
+        }
+        if (!bytesEqual(event.unicityTokenId, transaction.tokenId.bytes)) {
+            return fail('Lock is bound to a different token id (replay/forgery).');
+        }
+        const expectedRecipient = recipientCommitment(transaction.recipient.toCBOR());
+        if (!bytesEqual(event.recipientCommitment, expectedRecipient)) {
+            return fail('Lock is bound to a different recipient (theft/front-run).');
+        }
+        return new VerificationResult(RULE, VerificationStatus.OK);
+    }
+}

package/lib/address.d.ts

@@ -0,0 +1,13 @@
+/** Tron mainnet address prefix byte (0x41). */
+export declare const TRON_ADDRESS_PREFIX = 65;
+/**
+ * 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 declare function toEvmAddressHex(address: string): string;