@unicitylabs/bridge-plugin 0.2.0-dev.1

package/lib/bridge-back/derivations.js

@@ -0,0 +1,201 @@
+/**
+ * The bridge-back derivations from protocol/interop.md.
+ * Each function is the TS half of one cross-stack value and reproduces the Rust
+ * reference (`protocol/vectors/gen/src/derive.rs`) byte-for-byte. The wallet uses
+ * these read-only to show the user the pending nullifier / release leaf, and a
+ * TS relayer reuses them; the prover (Rust) and the vault (Solidity) recompute
+ * the same bytes (00 §2–7).
+ */
+import { sha256 } from '@noble/hashes/sha2.js';
+import * as abi from './abi.js';
+import * as cbor from './cbor.js';
+// Domain separators (00 §2, §3, §5, §7) — must match derive.rs exactly.
+export const DOMAIN_CONFIG = 'unicity-bridge-return-config:v1';
+export const DOMAIN_LOCK = 'unicity-bridge-lock:v1';
+export const DOMAIN_RETURN = 'unicity-bridge-return:v1';
+export const DOMAIN_BURN_TRANSITION = 'unicity-burn-transition:v1';
+export const DOMAIN_NULLIFIER = 'unicity-bridge-return-nullifier:v1';
+/** 32-byte big-endian representation of an unsigned integer. */
+export function u256be(n) {
+    if (n < 0n)
+        throw new Error('u256be: negative');
+    const out = new Uint8Array(32);
+    for (let i = 0; i < 32 && n > 0n; i++) {
+        out[31 - i] = Number(n & 0xffn);
+        n >>= 8n;
+    }
+    if (n > 0n)
+        throw new Error('u256be: overflow');
+    return out;
+}
+/** `configHash = K(abi.encode("...config:v1", fields...))` (00 §2). */
+export function configHash(c) {
+    return abi.keccak256(abi.encode([
+        abi.Str(DOMAIN_CONFIG),
+        abi.U64(c.sourceChainId),
+        abi.Addr(c.vault),
+        abi.Addr(c.asset),
+        abi.B32(c.tokenType),
+        abi.B32(c.coinId),
+        abi.U64(c.reasonTag),
+        abi.B32(c.lockDomain),
+        abi.B32(c.nullifierDomain),
+    ]));
+}
+/** `domainTag = K("unicity-bridge-return:v1")` over raw bytes (00 §7). */
+export function domainTag() {
+    return abi.keccak256(new TextEncoder().encode(DOMAIN_RETURN));
+}
+/** `lockDigest = K(abi.encode("...lock:v1", fields...))` (00 §3). */
+export function lockDigest(params) {
+    return abi.keccak256(abi.encode([
+        abi.Str(DOMAIN_LOCK),
+        abi.U64(params.sourceChainId),
+        abi.Addr(params.vault),
+        abi.U256(params.nonce),
+        abi.Addr(params.asset),
+        abi.B32(params.tokenType),
+        abi.B32(params.coinId),
+        abi.U256(params.amount),
+        abi.B32(params.unicityTokenId),
+        abi.B32(params.recipientCommitment),
+    ]));
+}
+/**
+ * Canonical CBOR of the 11-field `BridgeBackReason` array under `reasonTag`
+ * (00 §4). This is the `reasonBytes` that ride in the terminal burn's auxiliary
+ * data; the burn predicate binds `H(reasonBytes)` (see {reasonHash}).
+ */
+export function encodeBridgeBackReason(c, r) {
+    return cbor.concatBytes([
+        cbor.tag(c.reasonTag),
+        cbor.arrayHeader(11),
+        cbor.uint(r.version),
+        cbor.uint(c.sourceChainId),
+        cbor.bytes(c.vault),
+        cbor.bytes(c.asset),
+        cbor.bytes(c.tokenType),
+        cbor.bytes(c.coinId),
+        cbor.bytes(r.recipient),
+        cbor.bytes(cbor.minimalBe(u256be(r.amount))),
+        cbor.bytes(r.feeRecipient),
+        cbor.bytes(cbor.minimalBe(u256be(r.feeAmount))),
+        cbor.uint(r.deadline),
+    ]);
+}
+/** `reasonHash = H(reasonBytes)` — the value `BurnPredicate(H(reasonBytes))`
+ *  binds (00 §4, PROVISIONAL preimage pending M0 SDK confirmation). */
+export function reasonHash(reasonBytes) {
+    return sha256(reasonBytes);
+}
+/**
+ * Inverse of {encodeBridgeBackReason}: decode the canonical `reasonBytes` a
+ * burned token blob carries (the circuit performs the same decode). Strict —
+ * rejects non-canonical CBOR and any trailing bytes (00 §4). `amount`/`feeAmount`
+ * come back as the minimal-big-endian byte strings re-read as integers.
+ */
+export function decodeBridgeBackReason(reasonBytes) {
+    const r = new cbor.CborReader(reasonBytes);
+    const reasonTag = r.readTag();
+    const n = r.readArrayHeader();
+    if (n !== 11)
+        throw new Error(`BridgeBackReason: expected 11 fields, got ${n}`);
+    const version = r.readUint();
+    const sourceChainId = r.readUint();
+    const vault = r.readBytes();
+    const asset = r.readBytes();
+    const tokenType = r.readBytes();
+    const coinId = r.readBytes();
+    const recipient = r.readBytes();
+    const amount = beToBigInt(r.readBytes());
+    const feeRecipient = r.readBytes();
+    const feeAmount = beToBigInt(r.readBytes());
+    const deadline = r.readUint();
+    if (!r.done)
+        throw new Error('BridgeBackReason: trailing bytes after reason');
+    return {
+        reasonTag,
+        version,
+        sourceChainId,
+        vault,
+        asset,
+        tokenType,
+        coinId,
+        recipient,
+        amount,
+        feeRecipient,
+        feeAmount,
+        deadline,
+    };
+}
+function beToBigInt(b) {
+    let n = 0n;
+    for (const x of b)
+        n = (n << 8n) | BigInt(x);
+    return n;
+}
+/** `burnTransitionId = H("unicity-burn-transition:v1", stateId, txHash)` (00 §5). */
+export function burnTransitionId(stateId, txHash) {
+    return cbor.hArray([cbor.text(DOMAIN_BURN_TRANSITION), cbor.bytes(stateId), cbor.bytes(txHash)]);
+}
+/** `nullifier = H("...nullifier:v1", configHash, burnTransitionId)` (00 §5). */
+export function nullifier(configHashBytes, burnTransitionIdBytes) {
+    return cbor.hArray([
+        cbor.text(DOMAIN_NULLIFIER),
+        cbor.bytes(configHashBytes),
+        cbor.bytes(burnTransitionIdBytes),
+    ]);
+}
+function leafWords(l) {
+    return [
+        abi.B32(l.nullifier),
+        abi.Addr(l.recipient),
+        abi.U256(l.amount),
+        abi.Addr(l.feeRecipient),
+        abi.U256(l.feeAmount),
+        abi.U64(l.deadline),
+    ];
+}
+/** `returnRoot = K( concat of fixed-width abi.encode(leaf) )` (00 §7). */
+export function returnRoot(leaves) {
+    const parts = leaves.map((l) => abi.packWords(leafWords(l)));
+    return abi.keccak256(concatU8(parts));
+}
+/** `lockRefRoot = K( concat of fixed-width abi.encode(ref) )`, sorted by nonce
+ *  with duplicates rejected (00 §7). */
+export function lockRefRoot(refs) {
+    const sorted = [...refs].sort((a, b) => (a.nonce < b.nonce ? -1 : a.nonce > b.nonce ? 1 : 0));
+    for (let i = 1; i < sorted.length; i++) {
+        if (sorted[i].nonce === sorted[i - 1].nonce) {
+            throw new Error(`lockRefRoot: duplicate nonce ${sorted[i].nonce}`);
+        }
+    }
+    const parts = sorted.map((r) => abi.packWords([abi.U256(r.nonce), abi.B32(r.digest)]));
+    return abi.keccak256(concatU8(parts));
+}
+/** `abi.encode(PublicValues)` — the all-static layout the vault abi.decodes (00 §7). */
+export function publicValuesAbi(p) {
+    return abi.encode([
+        abi.B32(p.domainTag),
+        abi.B32(p.configHash),
+        abi.B32(p.trustBaseHash),
+        abi.B32(p.spentRootOld),
+        abi.B32(p.spentRootNew),
+        abi.B32(p.returnRoot),
+        abi.B32(p.lockRefRoot),
+        abi.U32(p.batchSize),
+        abi.U256(p.totalAmount),
+    ]);
+}
+function concatU8(parts) {
+    let len = 0;
+    for (const p of parts)
+        len += p.length;
+    const out = new Uint8Array(len);
+    let off = 0;
+    for (const p of parts) {
+        out.set(p, off);
+        off += p.length;
+    }
+    return out;
+}

package/lib/bridge-back/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Bridge-back construction (02-ts-sdk-and-wallet.md Part 2): chain-agnostic,
+ * authority-free derivations the wallet/relayer produces for the return path.
+ * Every byte here is consumed by the prover (Rust) and the vault (Solidity), so
+ * it is conformance-tested against `protocol/vectors` (interop §10).
+ */
+export * as bridgeCbor from './cbor.js';
+export * as bridgeAbi from './abi.js';
+export * from './derivations.js';
+export * from './burn.js';
+export * from './burned-blob.js';

package/lib/bridge-back/index.js

@@ -0,0 +1,11 @@
+/**
+ * Bridge-back construction (02-ts-sdk-and-wallet.md Part 2): chain-agnostic,
+ * authority-free derivations the wallet/relayer produces for the return path.
+ * Every byte here is consumed by the prover (Rust) and the vault (Solidity), so
+ * it is conformance-tested against `protocol/vectors` (interop §10).
+ */
+export * as bridgeCbor from './cbor.js';
+export * as bridgeAbi from './abi.js';
+export * from './derivations.js';
+export * from './burn.js';
+export * from './burned-blob.js';

package/lib/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/lib/cli/main.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+import { CertifiedMintTransaction } from '@unicitylabs/state-transition-sdk/lib/transaction/CertifiedMintTransaction.js';
+import { VerificationStatus } from '@unicitylabs/state-transition-sdk/lib/verification/VerificationStatus.js';
+import { createBridgePlugin, TRON_MAINNET_CHAIN_ID, TRON_NILE_CHAIN_ID, TRON_MAINNET_USDT, } from '../index.js';
+import { buildDemo, hexToBytes } from './scenario.js';
+const AMOUNT = 1000000n; // 1 USDT (6 decimals)
+const CONFIRMATIONS = 20;
+// Nile demo config (addresses are illustrative for the offline demo).
+const DEMO_CONFIG = {
+    family: 'tron',
+    chainId: TRON_NILE_CHAIN_ID,
+    lockContract: '41' + 'ab'.repeat(20),
+    assetContract: '41' + 'de'.repeat(20),
+    confirmations: CONFIRMATIONS,
+    decimals: 6,
+};
+const noNestedTokens = () => { };
+async function run(build) {
+    const r = await build.plugin.verifier.verify(build.certifiedTx, noNestedTokens);
+    return { status: r.status, message: r.message };
+}
+async function demo() {
+    console.log('Unicity ⇽ Tron USDT bridge — offline security demo');
+    console.log('(mock Tron RPC; mint reason = self-contained lock proof)\n');
+    const checks = [
+        {
+            name: 'Valid bridged mint (lock finalized, bound to this token+recipient)',
+            expect: VerificationStatus.OK,
+            build: () => buildDemo(DEMO_CONFIG, AMOUNT, CONFIRMATIONS).then(run),
+        },
+        {
+            name: 'Attack: inflate token value above locked amount',
+            expect: VerificationStatus.FAIL,
+            build: () => buildDemo(DEMO_CONFIG, AMOUNT, CONFIRMATIONS, { tokenValueAmount: AMOUNT * 1000n }).then(run),
+        },
+        {
+            name: 'Attack: tamper justification amount',
+            expect: VerificationStatus.FAIL,
+            build: () => buildDemo(DEMO_CONFIG, AMOUNT, CONFIRMATIONS, {
+                justification: (d) => ({ ...d, amount: AMOUNT + 1n }),
+            }).then(run),
+        },
+        {
+            name: 'Attack: replay lock for a different token id',
+            expect: VerificationStatus.FAIL,
+            build: () => buildDemo(DEMO_CONFIG, AMOUNT, CONFIRMATIONS, {
+                logs: (def) => [{ ...def, data: def.data.slice(0, 64) + '99'.repeat(32) + def.data.slice(128) }],
+            }).then(run),
+        },
+        {
+            name: 'Attack: steal lock by swapping recipient',
+            expect: VerificationStatus.FAIL,
+            build: () => buildDemo(DEMO_CONFIG, AMOUNT, CONFIRMATIONS, {
+                logs: (def) => [{ ...def, data: def.data.slice(0, 128) + '88'.repeat(32) }],
+            }).then(run),
+        },
+        {
+            name: 'Attack: forged lock contract emits the event',
+            expect: VerificationStatus.FAIL,
+            build: () => buildDemo(DEMO_CONFIG, AMOUNT, CONFIRMATIONS, {
+                logs: (def) => [{ ...def, address: 'ff'.repeat(20) }],
+            }).then(run),
+        },
+        {
+            name: 'Attack: spend lock before finality (insufficient confirmations)',
+            expect: VerificationStatus.FAIL,
+            build: () => buildDemo(DEMO_CONFIG, AMOUNT, CONFIRMATIONS, {
+                blockNumber: 1000n,
+                tip: 1000n + BigInt(CONFIRMATIONS) - 1n,
+            }).then(run),
+        },
+    ];
+    let failures = 0;
+    for (const check of checks) {
+        const { status, message } = await check.build();
+        const ok = status === check.expect;
+        if (!ok) {
+            failures++;
+        }
+        const tag = ok ? '✔' : '✘ UNEXPECTED';
+        const verdict = status === VerificationStatus.OK ? 'OK  ' : 'FAIL';
+        console.log(`${tag}  [${verdict}] ${check.name}`);
+        if (status === VerificationStatus.FAIL && message) {
+            console.log(`         ↳ ${message}`);
+        }
+    }
+    console.log('');
+    if (failures === 0) {
+        console.log('All checks behaved as expected: valid token accepted, every attack rejected.');
+        return 0;
+    }
+    console.error(`${failures} check(s) did not behave as expected.`);
+    return 1;
+}
+async function verifyOnChain(args) {
+    const tokenHex = args.get('token');
+    const lockContract = args.get('lock');
+    const rpcUrl = args.get('rpc');
+    if (!tokenHex || !lockContract || !rpcUrl) {
+        console.error('Usage: tron-usdt-bridge verify --token <hex> --lock <addr> --rpc <url> [--asset <addr>] [--chain mainnet|nile] [--api-key <key>] [--confirmations N]');
+        return 2;
+    }
+    const chain = (args.get('chain') ?? 'mainnet') === 'nile' ? TRON_NILE_CHAIN_ID : TRON_MAINNET_CHAIN_ID;
+    const config = {
+        family: 'tron',
+        chainId: chain,
+        lockContract,
+        assetContract: args.get('asset') ?? TRON_MAINNET_USDT,
+        confirmations: Number(args.get('confirmations') ?? CONFIRMATIONS),
+        decimals: 6,
+        rpcUrl,
+        apiKey: args.get('api-key'),
+    };
+    // Bridge tokens carry value in the wallet's format (SpherePaymentData, tag 39050); see src/value.ts.
+    const plugin = createBridgePlugin(config);
+    const tx = await CertifiedMintTransaction.fromCBOR(hexToBytes(tokenHex));
+    const result = await plugin.verifier.verify(tx, noNestedTokens);
+    console.log(`Token type expected for this asset: ${plugin.tokenTypeHex}`);
+    console.log(`Verification: ${result.status}${result.message ? ` — ${result.message}` : ''}`);
+    return result.status === VerificationStatus.OK ? 0 : 1;
+}
+function parseArgs(argv) {
+    const map = new Map();
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i].startsWith('--')) {
+            const key = argv[i].slice(2);
+            const val = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[(i += 1)] : 'true';
+            map.set(key, val);
+        }
+    }
+    return map;
+}
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    let code;
+    switch (cmd ?? 'demo') {
+        case 'demo':
+            code = await demo();
+            break;
+        case 'verify':
+            code = await verifyOnChain(parseArgs(rest));
+            break;
+        default:
+            console.error(`Unknown command: ${cmd}. Use "demo" or "verify".`);
+            code = 2;
+    }
+    process.exit(code);
+}
+void main();

package/lib/cli/scenario.d.ts

@@ -0,0 +1,36 @@
+import { NetworkId } from '@unicitylabs/state-transition-sdk/lib/api/NetworkId.js';
+import type { CertifiedMintTransaction } from '@unicitylabs/state-transition-sdk/lib/transaction/CertifiedMintTransaction.js';
+import { BridgeLockJustification, type SourceLog, type SourceChainRpc, type SourceTxInfo, type BridgeAssetConfig, type BridgePlugin } from '../index.js';
+export declare class MockTronRpc implements SourceChainRpc {
+    txInfo: SourceTxInfo | null;
+    tip: bigint;
+    constructor(txInfo: SourceTxInfo | null, tip: bigint);
+    getTransactionInfo(): Promise<SourceTxInfo | null>;
+    getNowBlockNumber(): Promise<bigint>;
+}
+export interface LockEventFields {
+    nonce: bigint;
+    fromEvmHex: string;
+    amount: bigint;
+    unicityTokenId: Uint8Array;
+    recipientCommitment: Uint8Array;
+}
+export declare function makeLockLog(addressEvmHex: string, e: LockEventFields): SourceLog;
+export declare const DEMO_NETWORK: NetworkId;
+export declare const DEMO_TXID: string;
+export declare const DEMO_NONCE = 7n;
+export interface DemoBuild {
+    plugin: BridgePlugin;
+    certifiedTx: CertifiedMintTransaction;
+    rpc: MockTronRpc;
+    tokenIdHex: string;
+}
+/** Builds a valid lock + matching bridged mint, then applies optional tampering. */
+export declare function buildDemo(config: BridgeAssetConfig, amount: bigint, confirmations: number, overrides?: {
+    logs?: (def: SourceLog) => SourceLog[];
+    justification?: (d: BridgeLockJustification['data']) => BridgeLockJustification['data'];
+    tokenValueAmount?: bigint;
+    tip?: bigint;
+    blockNumber?: bigint;
+}): Promise<DemoBuild>;
+export declare function hexToBytes(hex: string): Uint8Array;

package/lib/cli/scenario.js

@@ -0,0 +1,94 @@
+import { NetworkId } from '@unicitylabs/state-transition-sdk/lib/api/NetworkId.js';
+import { SigningService } from '@unicitylabs/state-transition-sdk/lib/crypto/secp256k1/SigningService.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 { MintTransaction } from '@unicitylabs/state-transition-sdk/lib/transaction/MintTransaction.js';
+import { TokenId } from '@unicitylabs/state-transition-sdk/lib/transaction/TokenId.js';
+import { TokenSalt } from '@unicitylabs/state-transition-sdk/lib/transaction/TokenSalt.js';
+import { TokenType } from '@unicitylabs/state-transition-sdk/lib/transaction/TokenType.js';
+import { createBridgePlugin, encodeBridgePaymentData, LOCK_EVENT_TOPIC0, recipientCommitment, toHex, BridgeLockJustification, } from '../index.js';
+export class MockTronRpc {
+    txInfo;
+    tip;
+    constructor(txInfo, tip) {
+        this.txInfo = txInfo;
+        this.tip = tip;
+    }
+    async getTransactionInfo() {
+        return this.txInfo;
+    }
+    async getNowBlockNumber() {
+        return this.tip;
+    }
+}
+function word(v) {
+    if (v instanceof Uint8Array) {
+        return toHex(v).padStart(64, '0');
+    }
+    return v.toString(16).padStart(64, '0');
+}
+export function makeLockLog(addressEvmHex, e) {
+    return {
+        address: addressEvmHex.toLowerCase(),
+        topics: [LOCK_EVENT_TOPIC0, word(e.nonce), e.fromEvmHex.toLowerCase().padStart(64, '0')],
+        data: word(e.amount) + word(e.unicityTokenId) + word(e.recipientCommitment),
+    };
+}
+export const DEMO_NETWORK = NetworkId.fromId(4);
+export const DEMO_TXID = 'a1'.repeat(32);
+export const DEMO_NONCE = 7n;
+/** Builds a valid lock + matching bridged mint, then applies optional tampering. */
+export async function buildDemo(config, amount, confirmations, overrides = {}) {
+    const recipient = SignaturePredicate.create(SigningService.generate().publicKey);
+    const recipientCommitmentBytes = recipientCommitment(EncodedPredicate.fromPredicate(recipient).toCBOR());
+    const salt = TokenSalt.generate();
+    const tokenId = await TokenId.fromSalt(DEMO_NETWORK, salt);
+    const blockNumber = overrides.blockNumber ?? 1000n;
+    const tip = overrides.tip ?? blockNumber + BigInt(confirmations);
+    // Build a probe plugin only to learn the normalized lock-contract hex.
+    const probe = createBridgePlugin(config, { rpc: new MockTronRpc(null, 0n) });
+    const defaultLog = makeLockLog(probe.resolvedConfig.lockContractHex, {
+        nonce: DEMO_NONCE,
+        fromEvmHex: 'cc'.repeat(20),
+        amount,
+        unicityTokenId: tokenId.bytes,
+        recipientCommitment: recipientCommitmentBytes,
+    });
+    const logs = overrides.logs ? overrides.logs(defaultLog) : [defaultLog];
+    const rpc = new MockTronRpc({ blockNumber, success: true, logs }, tip);
+    const plugin = createBridgePlugin(config, { rpc });
+    let jData = {
+        chainId: config.chainId,
+        lockContract: hexToBytes(plugin.resolvedConfig.lockContractHex),
+        assetContract: hexToBytes(plugin.resolvedConfig.assetContractHex),
+        txid: hexToBytes(DEMO_TXID),
+        logIndex: 0,
+        amount,
+        nonce: DEMO_NONCE,
+    };
+    if (overrides.justification) {
+        jData = overrides.justification(jData);
+    }
+    const valueData = encodeBridgePaymentData(plugin.resolvedConfig.coinId, overrides.tokenValueAmount ?? amount);
+    const tokenType = new TokenType(plugin.resolvedConfig.tokenType);
+    const mint = await MintTransaction.create(DEMO_NETWORK, recipient, {
+        data: valueData,
+        tokenType,
+        salt,
+        justification: new BridgeLockJustification(jData).toCBOR(),
+    });
+    return {
+        plugin,
+        certifiedTx: mint,
+        rpc,
+        tokenIdHex: toHex(tokenId.bytes),
+    };
+}
+export function hexToBytes(hex) {
+    const h = hex.startsWith('0x') ? hex.slice(2) : hex;
+    const out = new Uint8Array(h.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = parseInt(h.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}

package/lib/config.d.ts

@@ -0,0 +1,25 @@
+import type { ChainFamily } from '@unicitylabs/bridge-core';
+/**
+ * Configuration for one bridged asset. The family, chain, contract and asset
+ * fields are trust anchors: the verifier rejects any lock proof that does not
+ * match them.
+ */
+export interface BridgeAssetConfig {
+    /** Source chain family (CAIP-2 namespace). */
+    readonly family: ChainFamily;
+    /** Source chain id in the family's numbering. */
+    readonly chainId: number;
+    /** Canonical vault (lock) contract, in any of the family's address forms. */
+    readonly lockContract: string;
+    /** Bridged token contract, same forms. */
+    readonly assetContract: string;
+    /** Required confirmations for source finality; the family's default when omitted. */
+    readonly confirmations?: number;
+    /** Token decimals (USDT and USDC: 6). */
+    readonly decimals?: number;
+    /** Node URL for the family's RPC client (used when no client is injected). */
+    readonly rpcUrl?: string;
+    /** Node API key, where the family's node wants one (TronGrid). */
+    readonly apiKey?: string;
+}
+export declare const DEFAULT_DECIMALS = 6;

package/lib/config.js

@@ -0,0 +1 @@
+export const DEFAULT_DECIMALS = 6;

package/lib/contract-call.d.ts

@@ -0,0 +1,13 @@
+export interface CallParam {
+    readonly type: 'address' | 'uint256' | 'bytes32';
+    readonly value: string;
+}
+export interface ContractCall {
+    readonly contractHex: string;
+    /** Solidity function signature, e.g. `lock(uint256,bytes32,bytes32)`. */
+    readonly functionSignature: string;
+    /** Typed parameters in declaration order. */
+    readonly parameters: readonly CallParam[];
+}
+export declare function selectorHex(functionSignature: string): string;
+export declare function encodeCallData(call: ContractCall): string;

package/lib/contract-call.js

@@ -0,0 +1,19 @@
+import { keccak_256 } from '@noble/hashes/sha3.js';
+import { Addr, B32, U256, encode } from './bridge-back/abi.js';
+import { fromHex, toHex } from './hex.js';
+export function selectorHex(functionSignature) {
+    return toHex(keccak_256(new TextEncoder().encode(functionSignature)).subarray(0, 4));
+}
+function paramValue(p) {
+    switch (p.type) {
+        case 'address':
+            return Addr(fromHex(p.value));
+        case 'bytes32':
+            return B32(fromHex(p.value));
+        case 'uint256':
+            return U256(BigInt(p.value));
+    }
+}
+export function encodeCallData(call) {
+    return selectorHex(call.functionSignature) + toHex(encode(call.parameters.map(paramValue)));
+}

package/lib/evm/EvmRpcClient.d.ts

@@ -0,0 +1,25 @@
+import type { ConstantCallInput, ConstantCaller, SourceChainRpc, SourceTxInfo } from '../source-chain.js';
+type FetchLike = (input: string, init?: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+}>;
+export interface EvmJsonRpcClientOptions {
+    readonly rpcUrl: string;
+    /** Injectable fetch (defaults to globalThis.fetch). */
+    readonly fetchFn?: FetchLike;
+}
+export declare class EvmJsonRpcClient implements SourceChainRpc, ConstantCaller {
+    private readonly rpcUrl;
+    private readonly fetchFn;
+    constructor(options: EvmJsonRpcClientOptions);
+    private call;
+    getTransactionInfo(txidHex: string): Promise<SourceTxInfo | null>;
+    getNowBlockNumber(): Promise<bigint>;
+    constantCall(input: ConstantCallInput): Promise<string>;
+}
+export {};

package/lib/evm/EvmRpcClient.js

@@ -0,0 +1,54 @@
+import { selectorHex } from '../contract-call.js';
+function strip0x(h) {
+    return h.startsWith('0x') || h.startsWith('0X') ? h.slice(2) : h;
+}
+export class EvmJsonRpcClient {
+    rpcUrl;
+    fetchFn;
+    constructor(options) {
+        this.rpcUrl = options.rpcUrl;
+        const f = options.fetchFn ?? globalThis.fetch?.bind(globalThis);
+        if (!f) {
+            throw new Error('No fetch available; pass fetchFn in EvmJsonRpcClientOptions.');
+        }
+        this.fetchFn = f;
+    }
+    async call(method, params) {
+        const res = await this.fetchFn(this.rpcUrl, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
+        });
+        if (!res.ok) {
+            throw new Error(`Ethereum RPC ${method} failed: HTTP ${res.status}`);
+        }
+        const body = (await res.json());
+        if (body.error) {
+            throw new Error(`Ethereum RPC ${method} failed: ${body.error.message}`);
+        }
+        return body.result;
+    }
+    async getTransactionInfo(txidHex) {
+        const receipt = await this.call('eth_getTransactionReceipt', [`0x${strip0x(txidHex)}`]);
+        if (!receipt) {
+            return null;
+        }
+        const logs = receipt.logs.map((l) => ({
+            address: strip0x(l.address).toLowerCase(),
+            topics: l.topics.map((t) => strip0x(t).toLowerCase()),
+            data: strip0x(l.data).toLowerCase(),
+        }));
+        return { blockNumber: BigInt(receipt.blockNumber), success: receipt.status === '0x1', logs };
+    }
+    async getNowBlockNumber() {
+        return BigInt(await this.call('eth_blockNumber', []));
+    }
+    async constantCall(input) {
+        const data = `0x${selectorHex(input.functionSignature)}${strip0x(input.parameterHex ?? '')}`;
+        const result = await this.call('eth_call', [
+            { from: `0x${strip0x(input.ownerHex)}`, to: `0x${strip0x(input.contractHex)}`, data },
+            'latest',
+        ]);
+        return strip0x(result);
+    }
+}

package/lib/evm/config.d.ts

@@ -0,0 +1,6 @@
+export declare const ETHEREUM_MAINNET_CHAIN_ID = 1;
+export declare const SEPOLIA_CHAIN_ID = 11155111;
+export declare const ETHEREUM_MAINNET_USDC = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
+export declare const ETHEREUM_MAINNET_USDT = "0xdAC17F958D2ee523a2206206994597C13D831ec7";
+export declare const SEPOLIA_USDC = "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238";
+export declare const EVM_DEFAULT_CONFIRMATIONS = 64;

package/lib/evm/config.js

@@ -0,0 +1,6 @@
+export const ETHEREUM_MAINNET_CHAIN_ID = 1;
+export const SEPOLIA_CHAIN_ID = 11155111;
+export const ETHEREUM_MAINNET_USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+export const ETHEREUM_MAINNET_USDT = '0xdAC17F958D2ee523a2206206994597C13D831ec7';
+export const SEPOLIA_USDC = '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238';
+export const EVM_DEFAULT_CONFIRMATIONS = 64;

package/lib/evm/family.d.ts

@@ -0,0 +1,3 @@
+import type { ChainFamilyAdapter } from '../family.js';
+export declare function evmChainRef(chainId: number): string;
+export declare const evmFamily: ChainFamilyAdapter;