@acala-network/chopsticks 1.4.2 → 1.5.0

package/dist/cjs/bridge.d.ts

@@ -0,0 +1,77 @@
+import type { ApiPromise } from '@polkadot/api';
+import type { AddressOrPair } from '@polkadot/api/types';
+export interface ConnectBridgeHubsConfig {
+    /** Signs `receive_messages_proof` (on destination) and `receive_messages_delivery_proof`
+     * (on source). Must hold a balance on **both** chains. */
+    signer: AddressOrPair;
+    /** Pallet name overrides. Auto-detected by storage shape when omitted. */
+    sourceMessagesPallet?: string;
+    destParachainsPallet?: string;
+    destMessagesPallet?: string;
+    /** Auto-detected via `parachainInfo.parachainId` when omitted. */
+    sourceParaId?: number;
+    /** Credited as `relayer_id_at_bridged_chain`. Defaults to signer's address. */
+    relayerIdAtSource?: string;
+    /** Per-message weight upper bound. Default fits a typical XCM Transact. */
+    dispatchWeightPerMessage?: {
+        refTime: bigint;
+        proofSize: bigint;
+    };
+    /** Source-side `pallet_bridge_parachains` tracking the destination. Auto-detected. */
+    sourceParachainsPallet?: string;
+    /** Destination para id, used by the delivery-confirmation proofs. Auto-detected. */
+    destParaId?: number;
+}
+export interface BridgeHandle {
+    disconnect: () => Promise<void>;
+}
+/** One relayer entry's `DeliveredMessages` range. */
+type RelayerEntry = {
+    messages?: {
+        begin?: number | string;
+        end?: number | string;
+    };
+};
+/** Raw `InboundLaneData` JSON for one lane. */
+type InboundLaneJson = {
+    relayers?: RelayerEntry[];
+    lastConfirmedNonce?: number | string;
+} | null;
+/** `last_delivered_nonce` derived as the pallet does: last relayer entry's `messages.end`, or
+ * `last_confirmed_nonce` when the relayer queue is empty. */
+export declare const lastDeliveredFromInbound: (v: InboundLaneJson) => bigint;
+export interface UnrewardedRelayersState {
+    unrewardedRelayerEntries: number;
+    messagesInOldestEntry: bigint;
+    totalMessages: bigint;
+    lastDeliveredNonce: bigint;
+}
+/** `UnrewardedRelayersState` derived from an inbound lane's relayer queue exactly as the pallet's
+ * `impl From<&InboundLaneData>` does (the dispatch rejects any mismatch with
+ * `InvalidUnrewardedRelayersState`):
+ * - `unrewardedRelayerEntries` = number of relayer entries in the queue;
+ * - `totalMessages` spans the whole queue, `back.end - front.begin + 1` (NOT a per-entry sum);
+ * - `messagesInOldestEntry` is only the *front* entry's own size, `front.end - front.begin + 1`;
+ * - `lastDeliveredNonce` = `back.end`, or the passed `lastDelivered` (the lane's
+ *   `last_confirmed_nonce`) when the queue is empty.
+ */
+export declare const deriveUnrewardedRelayersState: (relayers: RelayerEntry[], lastDelivered: bigint) => UnrewardedRelayersState;
+/**
+ * Relay bridge messages between two forked bridge hubs via two reactive loops, each driven by a
+ * chain's new heads; terminate with `handle.disconnect()`. The connector never builds blocks — it
+ * reads state and pushes extrinsics to pools, then reacts to the heads produced by whatever builds
+ * blocks (auto-build under `Instant`/`Batch`, or a host driving `dev_newBlock` under `Manual`), so
+ * it works identically across build modes.
+ *
+ * - **deliver**: push `receive_messages_proof` for `[last_delivered+1 .. latest_generated]` (chunked
+ *   to MAX_MESSAGES_PER_PROOF) to the destination pool. Starting at the live `last_delivered+1` gives
+ *   `is_obsolete` its contiguity and re-delivers nothing.
+ * - **confirm**: push `receive_messages_delivery_proof` to the source pool so `latest_received_nonce`
+ *   advances and the destination prunes its relayers queue (else long runs hit the unconfirmed limit).
+ *
+ * `signer` must hold a balance on both sides.
+ */
+export declare const connectBridgeHubs: (source: ApiPromise, destination: ApiPromise, config: ConnectBridgeHubsConfig) => Promise<BridgeHandle>;
+/** Whether `api`'s runtime registers a `pallet_bridge_messages` instance. */
+export declare const hasBridgeMessagesPallet: (api: ApiPromise) => boolean;
+export {};

package/dist/cjs/bridge.js

@@ -0,0 +1,409 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get connectBridgeHubs () {
+        return connectBridgeHubs;
+    },
+    get deriveUnrewardedRelayersState () {
+        return deriveUnrewardedRelayersState;
+    },
+    get hasBridgeMessagesPallet () {
+        return hasBridgeMessagesPallet;
+    },
+    get lastDeliveredFromInbound () {
+        return lastDeliveredFromInbound;
+    }
+});
+const _chopstickscore = require("@acala-network/chopsticks-core");
+const _util = require("@polkadot/util");
+const DEFAULT_DISPATCH_WEIGHT = {
+    refTime: 5_000_000_000n,
+    proofSize: 65_536n
+};
+// Max nonces per `receive_messages_proof`; cumulus hubs reject larger proofs as `TooManyMessagesInTheProof`.
+const MAX_MESSAGES_PER_PROOF = 4096n;
+// Serialize pool submissions per chain so concurrent submits don't read the same nonce and drop one.
+const chainLocks = new WeakMap();
+const runOnChain = (api, fn)=>{
+    const run = (chainLocks.get(api) ?? Promise.resolve()).catch(()=>{}).then(fn);
+    chainLocks.set(api, run);
+    return run;
+};
+// Submit to `api`'s pool (no-callback form resolves on pool acceptance), serialized via `runOnChain`.
+const submitTx = (api, tx, signer)=>runOnChain(api, ()=>tx.signAndSend(signer, {
+            era: 0
+        }).then(()=>undefined));
+// `is_obsolete` rejects an already-applied or gapped proof as `InvalidTransaction::Stale` — benign
+// for the relayer (the lane already advanced), so it's matched rather than treated as a failure.
+const isStaleError = (message)=>/stale/i.test(message);
+// Single-slot serializer: each task runs after the previous; throws are logged under `label`.
+const serialChain = (label)=>{
+    let tail = Promise.resolve();
+    return {
+        enqueue: (fn)=>{
+            tail = tail.then(fn).catch((err)=>_chopstickscore.bridgeLogger.error({
+                    err: err.message
+                }, label));
+        },
+        drain: ()=>tail
+    };
+};
+// Lane id is the first (and only) key arg of an `entries()` key; polkadot.js doesn't type it, hence the cast.
+const laneHexFromKey = (key)=>key.args[0].toHex();
+// The three `pallet_bridge_parachains` writes that import a bridged head, so a proof taken at that
+// head verifies against it. Used both ways: deliver imports the source head on the destination,
+// confirm imports the destination head on the source. Keys are derived from `api`'s metadata
+// (hashers and key codecs included); only the values are hand-encoded.
+const importParaHead = (api, pallet, paraId, headHashHex, blockNumber, stateRoot)=>{
+    const query = api.query[pallet];
+    const headBytes = (0, _util.hexToU8a)(headHashHex);
+    return [
+        [
+            query.parasInfo.key(paraId),
+            (0, _chopstickscore.encodeParaInfo)(blockNumber, headBytes, 1)
+        ],
+        [
+            query.importedParaHeads.key(paraId, headHashHex),
+            (0, _chopstickscore.encodeParaStoredHeaderData)(blockNumber, stateRoot)
+        ],
+        [
+            query.importedParaHashes.key(paraId, 0),
+            headHashHex
+        ]
+    ];
+};
+const lastDeliveredFromInbound = (v)=>{
+    const relayers = v?.relayers ?? [];
+    return relayers.length ? BigInt(relayers[relayers.length - 1].messages?.end ?? 0) : BigInt(v?.lastConfirmedNonce ?? 0);
+};
+const deriveUnrewardedRelayersState = (relayers, lastDelivered)=>{
+    if (relayers.length === 0) {
+        return {
+            unrewardedRelayerEntries: 0,
+            messagesInOldestEntry: 0n,
+            totalMessages: 0n,
+            lastDeliveredNonce: lastDelivered
+        };
+    }
+    const frontBegin = BigInt(relayers[0].messages?.begin ?? 0);
+    const frontEnd = BigInt(relayers[0].messages?.end ?? 0);
+    return {
+        unrewardedRelayerEntries: relayers.length,
+        messagesInOldestEntry: frontEnd - frontBegin + 1n,
+        totalMessages: lastDelivered - frontBegin + 1n,
+        lastDeliveredNonce: lastDelivered
+    };
+};
+const connectBridgeHubs = async (source, destination, config)=>{
+    const sourceMessagesPallet = config.sourceMessagesPallet ?? detectSourceMessagesPallet(source);
+    const destParachainsPallet = config.destParachainsPallet ?? detectBridgeParachainsPallet(destination, 'destination');
+    const destMessagesPallet = config.destMessagesPallet ?? detectDestMessagesPallet(destination);
+    const dispatchWeight = config.dispatchWeightPerMessage ?? DEFAULT_DISPATCH_WEIGHT;
+    const signerAddress = typeof config.signer === 'string' ? config.signer : config.signer.address;
+    const relayerIdAtSource = config.relayerIdAtSource ?? signerAddress;
+    const [sourceParaId, destParaId] = await Promise.all([
+        config.sourceParaId ?? detectParaId(source, 'source'),
+        config.destParaId ?? detectParaId(destination, 'destination')
+    ]);
+    // Confirm proves the destination's inbound lane on the source, so it needs the source-side
+    // bridge-parachains pallet and the destination's para id (deliver's deps, reversed).
+    const sourceParachainsPallet = config.sourceParachainsPallet ?? detectBridgeParachainsPallet(source, 'source');
+    // camelCase pallet names for `api.query`/`api.tx` lookups.
+    const sourceMessages = (0, _util.stringCamelCase)(sourceMessagesPallet);
+    const destMessages = (0, _util.stringCamelCase)(destMessagesPallet);
+    const sourceParachains = (0, _util.stringCamelCase)(sourceParachainsPallet);
+    const destParachains = (0, _util.stringCamelCase)(destParachainsPallet);
+    // lane -> source `latest_generated_nonce` observed on source heads (deliver up to this).
+    const generated = new Map();
+    // lane -> `noncesEnd` of a delivery pushed to the destination pool but not yet observed applied.
+    const inFlight = new Map();
+    // lane -> highest destination `last_delivered_nonce` already confirmed back to source.
+    const confirmed = new Map();
+    // lane -> highest destination `last_delivered_nonce` observed by the deliver loop. It's
+    // monotonic, so it lets idle heads skip the per-lane inbound query.
+    const deliveredCache = new Map();
+    // Latest observed source head; outbound messages are proven against it (they exist there, since
+    // `latest_generated >= to`). Set on connect and refreshed on every source head.
+    let latestSourceHash;
+    let latestSourceNumber = 0;
+    // Push one chunk `[from..=to]` to the destination pool, proven against the given source head
+    // (the messages exist there since `latest_generated >= to`). Outbound lane state proven alongside.
+    const deliverRange = async (laneHex, from, to, sourceHash, sourceNumber)=>{
+        // `OutboundMessages` is keyed by `MessageKey { lane_id, nonce }`, passed as one struct arg.
+        const outboundMessages = source.query[sourceMessages].outboundMessages;
+        const keys = [
+            source.query[sourceMessages].outboundLanes.key(laneHex)
+        ];
+        for(let n = from; n <= to; n++){
+            keys.push(outboundMessages.key({
+                laneId: laneHex,
+                nonce: n
+            }));
+        }
+        // `dev_getReadProof` (not spec `state_getReadProof`) returns the recomputed `stateRoot` that the
+        // verifier checks against — it diverges from `header.state_root` once local overrides are applied.
+        const proof = await rawRpc(source, 'dev_getReadProof', [
+            keys,
+            sourceHash
+        ]);
+        const setStoragePayload = importParaHead(destination, destParachains, sourceParaId, sourceHash, sourceNumber, (0, _util.hexToU8a)(proof.stateRoot));
+        await rawRpc(destination, 'dev_setStorage', [
+            setStoragePayload
+        ]);
+        const count = Number(to - from + 1n);
+        const tx = destination.tx[destMessages].receiveMessagesProof(relayerIdAtSource, {
+            bridgedHeaderHash: sourceHash,
+            storageProof: proof.proof,
+            lane: laneHex,
+            noncesStart: from,
+            noncesEnd: to
+        }, count, {
+            refTime: dispatchWeight.refTime * BigInt(count),
+            proofSize: dispatchWeight.proofSize * BigInt(count)
+        });
+        await submitTx(destination, tx, config.signer);
+        _chopstickscore.bridgeLogger.info({
+            lane: laneHex,
+            range: `${from}..=${to}`,
+            sourceBlock: sourceNumber
+        }, 'pushed bridge delivery');
+    };
+    // Push the next chunk for a lane if ready. Reads the live `last_delivered_nonce` so the proof
+    // starts at `last_delivered+1` (is_obsolete contiguity); an in-flight chunk blocks further pushes
+    // until a destination head shows it applied.
+    const tryDeliverLane = async (laneHex)=>{
+        const sourceHash = latestSourceHash;
+        const sourceNumber = latestSourceNumber;
+        if (sourceHash === undefined) return;
+        const generatedNonce = generated.get(laneHex) ?? 0n;
+        // Idle short-circuit: `last_delivered_nonce` is monotonic, so when the cached value already
+        // covers everything generated and nothing is in flight, skip the inbound query entirely.
+        if (generatedNonce <= (deliveredCache.get(laneHex) ?? 0n) && !inFlight.has(laneHex)) return;
+        const delivered = lastDeliveredFromInbound((await destination.query[destMessages].inboundLanes(laneHex)).toJSON());
+        deliveredCache.set(laneHex, delivered);
+        const pending = inFlight.get(laneHex);
+        if (pending !== undefined) {
+            if (delivered >= pending) inFlight.delete(laneHex);
+            else return; // previous chunk not applied yet — a further push would gap
+        }
+        if (generatedNonce <= delivered) return; // nothing new to deliver
+        const from = delivered + 1n;
+        const lastInChunk = from + MAX_MESSAGES_PER_PROOF - 1n;
+        const to = lastInChunk < generatedNonce ? lastInChunk : generatedNonce;
+        await deliverRange(laneHex, from, to, sourceHash, sourceNumber);
+        inFlight.set(laneHex, to);
+    };
+    // On any head, push whatever is currently deliverable on each known lane.
+    const syncDeliveries = async ()=>{
+        for (const laneHex of generated.keys()){
+            try {
+                await tryDeliverLane(laneHex);
+            } catch (err) {
+                const message = err.message;
+                inFlight.delete(laneHex); // allow a re-push on the next head
+                // a `stale` push means our `last_delivered` view lagged the chain — benign, just retry
+                if (isStaleError(message)) {
+                    _chopstickscore.bridgeLogger.debug({
+                        lane: laneHex
+                    }, 'delivery push stale; will retry');
+                } else {
+                    _chopstickscore.bridgeLogger.warn({
+                        err: message,
+                        lane: laneHex
+                    }, 'delivery push failed; will retry');
+                }
+            }
+        }
+    };
+    // Relay one lane's confirmation to `source`: prove the destination's `InboundLanes[lane]` (at
+    // `destHashHex`, where the delivery is applied) and submit `receive_messages_delivery_proof`,
+    // advancing the source's `latest_received_nonce`. Mirror of deliver.
+    const confirm = async (destHashHex, destBlockNumber, lane)=>{
+        const { laneHex, relayers, lastDelivered } = lane;
+        // Idempotency guard: skip if the source already covers `lastDelivered` (else `is_obsolete`
+        // rejects the re-submit as stale).
+        const sourceReceived = BigInt((await source.query[sourceMessages].outboundLanes(laneHex)).toJSON()?.latestReceivedNonce ?? 0);
+        if (lastDelivered <= sourceReceived) return;
+        const relayersState = deriveUnrewardedRelayersState(relayers, lastDelivered);
+        const proof = await rawRpc(destination, 'dev_getReadProof', [
+            [
+                destination.query[destMessages].inboundLanes.key(laneHex)
+            ],
+            destHashHex
+        ]);
+        const setStoragePayload = importParaHead(source, sourceParachains, destParaId, destHashHex, destBlockNumber, (0, _util.hexToU8a)(proof.stateRoot));
+        await rawRpc(source, 'dev_setStorage', [
+            setStoragePayload
+        ]);
+        const tx = source.tx[sourceMessages].receiveMessagesDeliveryProof({
+            bridgedHeaderHash: destHashHex,
+            storageProof: proof.proof,
+            lane: laneHex
+        }, relayersState);
+        await submitTx(source, tx, config.signer);
+        _chopstickscore.bridgeLogger.info({
+            lane: laneHex,
+            lastDelivered: lastDelivered.toString(),
+            destBlock: destBlockNumber
+        }, 'confirmed bridge deliveries');
+    };
+    // Per-lane `latest_generated_nonce` from `OutboundLanes` at a pinned source block.
+    const readOutboundLanes = async (apiAt)=>{
+        const entries = await apiAt.query[sourceMessages].outboundLanes.entries();
+        return entries.map(([key, valueCodec])=>{
+            const v = valueCodec.toJSON();
+            return [
+                laneHexFromKey(key),
+                BigInt(v?.latestGeneratedNonce ?? 0)
+            ];
+        });
+    };
+    // Per-lane `InboundLaneData` from `InboundLanes` at a pinned destination block, with
+    // `last_delivered_nonce` derived as the pallet does (see `lastDeliveredFromInbound`).
+    const readInboundLanes = async (apiAt)=>{
+        const entries = await apiAt.query[destMessages].inboundLanes.entries();
+        return entries.map(([key, valueCodec])=>{
+            const v = valueCodec.toJSON();
+            return {
+                laneHex: laneHexFromKey(key),
+                relayers: v?.relayers ?? [],
+                lastDelivered: lastDeliveredFromInbound(v)
+            };
+        });
+    };
+    // On a source head: pin it as the proving head and update each lane's generated high-water mark.
+    // Read at the header's own hash so a later proof attests exactly the nonces extant at that head.
+    const refreshGenerated = async (sourceHeader)=>{
+        const sourceHashHex = sourceHeader.hash.toHex();
+        try {
+            const lanes = await readOutboundLanes(await source.at(sourceHashHex));
+            latestSourceHash = sourceHashHex;
+            latestSourceNumber = sourceHeader.number.toNumber();
+            for (const [laneHex, latestGenerated] of lanes)generated.set(laneHex, latestGenerated);
+        } catch (err) {
+            _chopstickscore.bridgeLogger.warn({
+                err: err.message,
+                sourceHash: sourceHashHex
+            }, 'outboundLanes enumeration failed');
+        }
+    };
+    const pumpConfirm = async (destHeader)=>{
+        const destHashHex = destHeader.hash.toHex();
+        const destBlockNumber = destHeader.number.toNumber();
+        let lanes;
+        try {
+            lanes = await readInboundLanes(await destination.at(destHashHex));
+        } catch (err) {
+            _chopstickscore.bridgeLogger.warn({
+                err: err.message,
+                destHash: destHashHex
+            }, 'inboundLanes enumeration failed');
+            return;
+        }
+        for (const lane of lanes){
+            if (lane.lastDelivered <= (confirmed.get(lane.laneHex) ?? 0n)) continue;
+            try {
+                await confirm(destHashHex, destBlockNumber, lane);
+                confirmed.set(lane.laneHex, lane.lastDelivered);
+            } catch (err) {
+                const message = err.message;
+                // A `stale` rejection is benign: the source lane already advanced (a competing
+                // confirmation, or our own already-applied submit racing the read), so mark it done.
+                if (isStaleError(message)) {
+                    confirmed.set(lane.laneHex, lane.lastDelivered);
+                    _chopstickscore.bridgeLogger.debug({
+                        lane: lane.laneHex
+                    }, 'confirmation already applied (stale); skipping');
+                } else {
+                    // Leave `confirmed` un-advanced so the next destination head retries.
+                    _chopstickscore.bridgeLogger.warn({
+                        err: message,
+                        lane: lane.laneHex
+                    }, 'confirmation failed; will retry');
+                }
+            }
+        }
+    };
+    // Delivery self-seeds (live `last_delivered` + `refreshGenerated` on the first source head), so
+    // only confirm needs a baseline: pin `confirmed` to the current `last_delivered` so a fork's
+    // pre-existing delivered-but-unconfirmed backlog isn't re-confirmed.
+    try {
+        const destHead = await destination.rpc.chain.getBlockHash();
+        for (const lane of (await readInboundLanes(await destination.at(destHead)))){
+            confirmed.set(lane.laneHex, lane.lastDelivered);
+        }
+    } catch (err) {
+        _chopstickscore.bridgeLogger.warn({
+            err: err.message
+        }, 'confirmation baseline seed failed; lanes baseline on first head');
+    }
+    // Delivery is serialized across both head streams (source heads update generated, destination
+    // heads observe applied chunks); confirmation is its own queue on destination heads.
+    const deliverQueue = serialChain('unexpected deliver error');
+    const confirmQueue = serialChain('unexpected confirm-pump error');
+    const unsubSource = await source.rpc.chain.subscribeNewHeads((header)=>{
+        deliverQueue.enqueue(async ()=>{
+            await refreshGenerated(header);
+            await syncDeliveries();
+        });
+    });
+    const unsubDest = await destination.rpc.chain.subscribeNewHeads((header)=>{
+        // A destination block may have applied an in-flight chunk → push the next one.
+        deliverQueue.enqueue(()=>syncDeliveries());
+        confirmQueue.enqueue(()=>pumpConfirm(header));
+    });
+    _chopstickscore.bridgeLogger.info({
+        sourceMessagesPallet,
+        destParachainsPallet,
+        destMessagesPallet,
+        sourceParaId,
+        sourceParachainsPallet,
+        destParaId
+    }, 'bridge connector started');
+    return {
+        async disconnect () {
+            unsubSource();
+            unsubDest();
+            await Promise.all([
+                deliverQueue.drain(),
+                confirmQueue.drain()
+            ]);
+            _chopstickscore.bridgeLogger.info('bridge connector stopped');
+        }
+    };
+};
+const rawRpc = async (api, method, params)=>{
+    const provider = api._rpcCore?.provider;
+    if (!provider?.send) throw new Error(`connectBridgeHubs: cannot access provider for ${method}`);
+    return provider.send(method, params);
+};
+/** Storage-shape predicate for a `pallet_bridge_messages` instance. */ const isBridgeMessagesPallet = (pallet)=>!!(pallet?.outboundLanes && pallet?.outboundMessages);
+const hasBridgeMessagesPallet = (api)=>Object.values(api.query).some(isBridgeMessagesPallet);
+/**
+ * Find the unique pallet in `namespace` matching `predicate`, returning its PascalCase
+ * name. Throws a remediation-pointing error on zero or multiple matches.
+ */ const detectPallet = (namespace, predicate, kind, label, overrideField)=>{
+    const matches = Object.keys(namespace).filter((key)=>predicate(namespace[key]));
+    if (matches.length === 0) throw new Error(`connectBridgeHubs: no pallet_bridge_${kind} instance on ${label}`);
+    if (matches.length > 1) {
+        const names = matches.map(_util.stringPascalCase).join(', ');
+        throw new Error(`connectBridgeHubs: ${label} has multiple bridge-${kind} instances (${names}); set ${overrideField}`);
+    }
+    return (0, _util.stringPascalCase)(matches[0]);
+};
+const detectSourceMessagesPallet = (api)=>detectPallet(api.query, isBridgeMessagesPallet, 'messages', 'source', 'sourceMessagesPallet');
+const detectDestMessagesPallet = (api)=>detectPallet(api.tx, (p)=>p?.receiveMessagesProof, 'messages', 'destination', 'destMessagesPallet');
+const detectBridgeParachainsPallet = (api, label)=>detectPallet(api.query, (p)=>p?.parasInfo && p?.importedParaHeads, 'parachains', label, label === 'source' ? 'sourceParachainsPallet' : 'destParachainsPallet');
+const detectParaId = async (api, label)=>{
+    const idCodec = await api.query.parachainInfo?.parachainId?.();
+    if (idCodec) return idCodec.toNumber();
+    throw new Error(`connectBridgeHubs: cannot auto-detect ${label === 'source' ? 'sourceParaId' : 'destParaId'}`);
+};

package/dist/cjs/cli.js

@@ -3,11 +3,14 @@ Object.defineProperty(exports, "__esModule", {
     value: true
 });
 const _chopstickscore = require("@acala-network/chopsticks-core");
+const _api = require("@polkadot/api");
+const _utilcrypto = require("@polkadot/util-crypto");
 const _dotenv = require("dotenv");
 const _lodash = /*#__PURE__*/ _interop_require_default(require("lodash"));
 const _yargs = /*#__PURE__*/ _interop_require_default(require("yargs"));
 const _helpers = require("yargs/helpers");
 const _zod = require("zod");
+const _bridge = require("./bridge.js");
 const _index = require("./index.js");
 const _index1 = require("./plugins/index.js");
 const _index2 = require("./schema/index.js");
@@ -17,6 +20,51 @@ function _interop_require_default(obj) {
     };
 }
 (0, _dotenv.config)();
+/** Fork relay (optional) + parachains and wire them with UMP/DMP/HRMP — the `xcm` command's core. */ const setupNetwork = async (relayConfigRef, parachainConfigRefs)=>{
+    const parachains = [];
+    for (const configRef of parachainConfigRefs){
+        const { chain, addr } = await (0, _index.setupWithServer)(await (0, _index2.fetchConfig)(configRef));
+        parachains.push({
+            chain,
+            addr,
+            configRef
+        });
+    }
+    if (parachains.length > 1) {
+        await (0, _chopstickscore.connectParachains)(parachains.map((c)=>c.chain), _chopstickscore.environment.DISABLE_AUTO_HRMP);
+    }
+    if (relayConfigRef) {
+        const { chain: relay } = await (0, _index.setupWithServer)(await (0, _index2.fetchConfig)(relayConfigRef));
+        for (const c of parachains)await (0, _chopstickscore.connectVertical)(relay, c.chain);
+    }
+    return parachains;
+};
+/** One side of a bridged setup: an xcm network plus an `ApiPromise` per parachain. */ const setupBridgeSide = async (relayConfigRef, parachainConfigRefs)=>{
+    const parachains = await setupNetwork(relayConfigRef, parachainConfigRefs);
+    return Promise.all(parachains.map(async ({ chain, addr, configRef })=>{
+        const url = `ws://${addr}`;
+        const api = await _api.ApiPromise.create({
+            provider: new _api.WsProvider(url, 3_000),
+            noInitWarn: true
+        });
+        return {
+            chain,
+            api,
+            url,
+            configRef
+        };
+    }));
+};
+/** Pick the parachain whose runtime registers `pallet_bridge_messages`. */ const findBridgeHub = (side, label)=>{
+    const candidates = side.filter((c)=>(0, _bridge.hasBridgeMessagesPallet)(c.api));
+    if (candidates.length === 0) {
+        throw new Error(`chopsticks bridge: no ${label}-side parachain hosts pallet_bridge_messages. ` + `Provided: ${side.map((c)=>c.configRef).join(', ')}. Include a bridge-hub config.`);
+    }
+    if (candidates.length > 1) {
+        throw new Error(`chopsticks bridge: multiple ${label}-side parachains host pallet_bridge_messages (${candidates.map((c)=>c.configRef).join(', ')}). Cannot disambiguate — provide only one bridge hub per side.`);
+    }
+    return candidates[0];
+};
 const processArgv = async (argv)=>{
     try {
         if (argv.unsafeRpcMethods) {
@@ -51,20 +99,61 @@ const commands = (0, _yargs.default)((0, _helpers.hideBin)(process.argv)).script
             required: true
         }
     }).alias('relaychain', 'r').alias('parachain', 'p'), async (argv)=>{
-    const parachains = [];
-    for (const config of argv.parachain){
-        const { chain } = await (0, _index.setupWithServer)(await (0, _index2.fetchConfig)(config));
-        parachains.push(chain);
-    }
-    if (parachains.length > 1) {
-        await (0, _chopstickscore.connectParachains)(parachains, _chopstickscore.environment.DISABLE_AUTO_HRMP);
-    }
-    if (argv.relaychain) {
-        const { chain: relaychain } = await (0, _index.setupWithServer)(await (0, _index2.fetchConfig)(argv.relaychain));
-        for (const parachain of parachains){
-            await (0, _chopstickscore.connectVertical)(relaychain, parachain);
+    await setupNetwork(argv.relaychain, argv.parachain);
+}).command('bridge', 'Bridged-XCM setup: two ecosystems wired with pallet_bridge_messages in both directions', (yargs)=>yargs.options({
+        'left-relaychain': {
+            desc: 'Left-side relaychain config (named or path). Example: westend',
+            string: true
+        },
+        'left-parachain': {
+            desc: 'Left-side parachain config(s). One of them must host pallet_bridge_messages.',
+            type: 'array',
+            string: true,
+            required: true
+        },
+        'right-relaychain': {
+            desc: 'Right-side relaychain config (named or path). Example: rococo',
+            string: true
+        },
+        'right-parachain': {
+            desc: 'Right-side parachain config(s). One of them must host pallet_bridge_messages.',
+            type: 'array',
+            string: true,
+            required: true
+        },
+        'bridge-signer-uri': {
+            desc: 'Relayer URI for the forward direction (left → right). Submits receive_messages_proof / _delivery_proof.',
+            string: true,
+            default: '//Alice'
+        },
+        'bridge-reverse-signer-uri': {
+            desc: 'Relayer URI for the reverse direction (right → left). Defaults to <bridge-signer-uri>//reverse. Must differ from the forward relayer so their nonces on the shared hubs do not collide.',
+            string: true
         }
-    }
+    }).alias('left-relaychain', 'r').alias('left-parachain', 'p').alias('right-relaychain', 'R').alias('right-parachain', 'P'), async (argv)=>{
+    await (0, _utilcrypto.cryptoWaitReady)();
+    const left = await setupBridgeSide(argv['left-relaychain'], argv['left-parachain']);
+    const right = await setupBridgeSide(argv['right-relaychain'], argv['right-parachain']);
+    const leftBh = findBridgeHub(left, 'left');
+    const rightBh = findBridgeHub(right, 'right');
+    // Each direction needs its OWN relayer account. Both connectors submit relayer txs to the
+    // same two hubs (the forward direction's confirmations and the reverse direction's deliveries
+    // both land on a given hub), so a shared signer collides on its nonce and one direction's tx
+    // is silently dropped. Distinct accounts give each direction its own nonce sequence.
+    const keyring = new _api.Keyring({
+        type: 'sr25519'
+    });
+    const forwardSigner = keyring.addFromUri(argv['bridge-signer-uri']);
+    const reverseSigner = keyring.addFromUri(argv['bridge-reverse-signer-uri'] ?? `${argv['bridge-signer-uri']}//reverse`);
+    await Promise.all([
+        (0, _bridge.connectBridgeHubs)(leftBh.api, rightBh.api, {
+            signer: forwardSigner
+        }),
+        (0, _bridge.connectBridgeHubs)(rightBh.api, leftBh.api, {
+            signer: reverseSigner
+        })
+    ]);
+    console.log(`Bridge connected:\n  left  bridge-hub @ ${leftBh.url}\n  right bridge-hub @ ${rightBh.url}\n` + `Relayers (fund BOTH on BOTH hubs): forward ${forwardSigner.address}, reverse ${reverseSigner.address}. ` + 'They push proofs to each hub; blocks are produced by the hubs (build mode) or by you (dev_newBlock).');
 }).strict().help().alias('help', 'h').alias('version', 'v').alias('config', 'c').alias('endpoint', 'e').alias('port', 'p').alias('block', 'b').alias('unsafe-rpc-methods', 'ur').alias('import-storage', 's').alias('wasm-override', 'w').usage('Usage: $0 <command> [options]').example('$0', '-c acala').showHelpOnFail(false);
 if (!_chopstickscore.environment.DISABLE_PLUGINS) {
     (0, _index1.pluginExtendCli)(commands.config('config', 'Path to config file with default options', ()=>({}))).then(()=>commands.parse());

package/dist/cjs/index.d.ts

@@ -1,4 +1,5 @@
 import '@polkadot/api-augment';
 export * from '@acala-network/chopsticks-core';
+export * from './bridge.js';
 export { fetchConfig } from './schema/index.js';
 export { setupWithServer } from './setup-with-server.js';

package/dist/cjs/index.js

@@ -18,6 +18,7 @@ _export(exports, {
 });
 require("@polkadot/api-augment");
 _export_star(require("@acala-network/chopsticks-core"), exports);
+_export_star(require("./bridge.js"), exports);
 const _index = require("./schema/index.js");
 const _setupwithserver = require("./setup-with-server.js");
 function _export_star(from, to) {

package/dist/esm/bridge.d.ts

@@ -0,0 +1,77 @@
+import type { ApiPromise } from '@polkadot/api';
+import type { AddressOrPair } from '@polkadot/api/types';
+export interface ConnectBridgeHubsConfig {
+    /** Signs `receive_messages_proof` (on destination) and `receive_messages_delivery_proof`
+     * (on source). Must hold a balance on **both** chains. */
+    signer: AddressOrPair;
+    /** Pallet name overrides. Auto-detected by storage shape when omitted. */
+    sourceMessagesPallet?: string;
+    destParachainsPallet?: string;
+    destMessagesPallet?: string;
+    /** Auto-detected via `parachainInfo.parachainId` when omitted. */
+    sourceParaId?: number;
+    /** Credited as `relayer_id_at_bridged_chain`. Defaults to signer's address. */
+    relayerIdAtSource?: string;
+    /** Per-message weight upper bound. Default fits a typical XCM Transact. */
+    dispatchWeightPerMessage?: {
+        refTime: bigint;
+        proofSize: bigint;
+    };
+    /** Source-side `pallet_bridge_parachains` tracking the destination. Auto-detected. */
+    sourceParachainsPallet?: string;
+    /** Destination para id, used by the delivery-confirmation proofs. Auto-detected. */
+    destParaId?: number;
+}
+export interface BridgeHandle {
+    disconnect: () => Promise<void>;
+}
+/** One relayer entry's `DeliveredMessages` range. */
+type RelayerEntry = {
+    messages?: {
+        begin?: number | string;
+        end?: number | string;
+    };
+};
+/** Raw `InboundLaneData` JSON for one lane. */
+type InboundLaneJson = {
+    relayers?: RelayerEntry[];
+    lastConfirmedNonce?: number | string;
+} | null;
+/** `last_delivered_nonce` derived as the pallet does: last relayer entry's `messages.end`, or
+ * `last_confirmed_nonce` when the relayer queue is empty. */
+export declare const lastDeliveredFromInbound: (v: InboundLaneJson) => bigint;
+export interface UnrewardedRelayersState {
+    unrewardedRelayerEntries: number;
+    messagesInOldestEntry: bigint;
+    totalMessages: bigint;
+    lastDeliveredNonce: bigint;
+}
+/** `UnrewardedRelayersState` derived from an inbound lane's relayer queue exactly as the pallet's
+ * `impl From<&InboundLaneData>` does (the dispatch rejects any mismatch with
+ * `InvalidUnrewardedRelayersState`):
+ * - `unrewardedRelayerEntries` = number of relayer entries in the queue;
+ * - `totalMessages` spans the whole queue, `back.end - front.begin + 1` (NOT a per-entry sum);
+ * - `messagesInOldestEntry` is only the *front* entry's own size, `front.end - front.begin + 1`;
+ * - `lastDeliveredNonce` = `back.end`, or the passed `lastDelivered` (the lane's
+ *   `last_confirmed_nonce`) when the queue is empty.
+ */
+export declare const deriveUnrewardedRelayersState: (relayers: RelayerEntry[], lastDelivered: bigint) => UnrewardedRelayersState;
+/**
+ * Relay bridge messages between two forked bridge hubs via two reactive loops, each driven by a
+ * chain's new heads; terminate with `handle.disconnect()`. The connector never builds blocks — it
+ * reads state and pushes extrinsics to pools, then reacts to the heads produced by whatever builds
+ * blocks (auto-build under `Instant`/`Batch`, or a host driving `dev_newBlock` under `Manual`), so
+ * it works identically across build modes.
+ *
+ * - **deliver**: push `receive_messages_proof` for `[last_delivered+1 .. latest_generated]` (chunked
+ *   to MAX_MESSAGES_PER_PROOF) to the destination pool. Starting at the live `last_delivered+1` gives
+ *   `is_obsolete` its contiguity and re-delivers nothing.
+ * - **confirm**: push `receive_messages_delivery_proof` to the source pool so `latest_received_nonce`
+ *   advances and the destination prunes its relayers queue (else long runs hit the unconfirmed limit).
+ *
+ * `signer` must hold a balance on both sides.
+ */
+export declare const connectBridgeHubs: (source: ApiPromise, destination: ApiPromise, config: ConnectBridgeHubsConfig) => Promise<BridgeHandle>;
+/** Whether `api`'s runtime registers a `pallet_bridge_messages` instance. */
+export declare const hasBridgeMessagesPallet: (api: ApiPromise) => boolean;
+export {};

package/dist/esm/bridge.js

@@ -0,0 +1,408 @@
+import { bridgeLogger, encodeParaInfo, encodeParaStoredHeaderData } from '@acala-network/chopsticks-core';
+import { hexToU8a, stringCamelCase, stringPascalCase } from '@polkadot/util';
+const DEFAULT_DISPATCH_WEIGHT = {
+    refTime: 5_000_000_000n,
+    proofSize: 65_536n
+};
+// Max nonces per `receive_messages_proof`; cumulus hubs reject larger proofs as `TooManyMessagesInTheProof`.
+const MAX_MESSAGES_PER_PROOF = 4096n;
+// Serialize pool submissions per chain so concurrent submits don't read the same nonce and drop one.
+const chainLocks = new WeakMap();
+const runOnChain = (api, fn)=>{
+    const run = (chainLocks.get(api) ?? Promise.resolve()).catch(()=>{}).then(fn);
+    chainLocks.set(api, run);
+    return run;
+};
+// Submit to `api`'s pool (no-callback form resolves on pool acceptance), serialized via `runOnChain`.
+const submitTx = (api, tx, signer)=>runOnChain(api, ()=>tx.signAndSend(signer, {
+            era: 0
+        }).then(()=>undefined));
+// `is_obsolete` rejects an already-applied or gapped proof as `InvalidTransaction::Stale` — benign
+// for the relayer (the lane already advanced), so it's matched rather than treated as a failure.
+const isStaleError = (message)=>/stale/i.test(message);
+// Single-slot serializer: each task runs after the previous; throws are logged under `label`.
+const serialChain = (label)=>{
+    let tail = Promise.resolve();
+    return {
+        enqueue: (fn)=>{
+            tail = tail.then(fn).catch((err)=>bridgeLogger.error({
+                    err: err.message
+                }, label));
+        },
+        drain: ()=>tail
+    };
+};
+// Lane id is the first (and only) key arg of an `entries()` key; polkadot.js doesn't type it, hence the cast.
+const laneHexFromKey = (key)=>key.args[0].toHex();
+// The three `pallet_bridge_parachains` writes that import a bridged head, so a proof taken at that
+// head verifies against it. Used both ways: deliver imports the source head on the destination,
+// confirm imports the destination head on the source. Keys are derived from `api`'s metadata
+// (hashers and key codecs included); only the values are hand-encoded.
+const importParaHead = (api, pallet, paraId, headHashHex, blockNumber, stateRoot)=>{
+    const query = api.query[pallet];
+    const headBytes = hexToU8a(headHashHex);
+    return [
+        [
+            query.parasInfo.key(paraId),
+            encodeParaInfo(blockNumber, headBytes, 1)
+        ],
+        [
+            query.importedParaHeads.key(paraId, headHashHex),
+            encodeParaStoredHeaderData(blockNumber, stateRoot)
+        ],
+        [
+            query.importedParaHashes.key(paraId, 0),
+            headHashHex
+        ]
+    ];
+};
+/** `last_delivered_nonce` derived as the pallet does: last relayer entry's `messages.end`, or
+ * `last_confirmed_nonce` when the relayer queue is empty. */ export const lastDeliveredFromInbound = (v)=>{
+    const relayers = v?.relayers ?? [];
+    return relayers.length ? BigInt(relayers[relayers.length - 1].messages?.end ?? 0) : BigInt(v?.lastConfirmedNonce ?? 0);
+};
+/** `UnrewardedRelayersState` derived from an inbound lane's relayer queue exactly as the pallet's
+ * `impl From<&InboundLaneData>` does (the dispatch rejects any mismatch with
+ * `InvalidUnrewardedRelayersState`):
+ * - `unrewardedRelayerEntries` = number of relayer entries in the queue;
+ * - `totalMessages` spans the whole queue, `back.end - front.begin + 1` (NOT a per-entry sum);
+ * - `messagesInOldestEntry` is only the *front* entry's own size, `front.end - front.begin + 1`;
+ * - `lastDeliveredNonce` = `back.end`, or the passed `lastDelivered` (the lane's
+ *   `last_confirmed_nonce`) when the queue is empty.
+ */ export const deriveUnrewardedRelayersState = (relayers, lastDelivered)=>{
+    if (relayers.length === 0) {
+        return {
+            unrewardedRelayerEntries: 0,
+            messagesInOldestEntry: 0n,
+            totalMessages: 0n,
+            lastDeliveredNonce: lastDelivered
+        };
+    }
+    const frontBegin = BigInt(relayers[0].messages?.begin ?? 0);
+    const frontEnd = BigInt(relayers[0].messages?.end ?? 0);
+    return {
+        unrewardedRelayerEntries: relayers.length,
+        messagesInOldestEntry: frontEnd - frontBegin + 1n,
+        totalMessages: lastDelivered - frontBegin + 1n,
+        lastDeliveredNonce: lastDelivered
+    };
+};
+/**
+ * Relay bridge messages between two forked bridge hubs via two reactive loops, each driven by a
+ * chain's new heads; terminate with `handle.disconnect()`. The connector never builds blocks — it
+ * reads state and pushes extrinsics to pools, then reacts to the heads produced by whatever builds
+ * blocks (auto-build under `Instant`/`Batch`, or a host driving `dev_newBlock` under `Manual`), so
+ * it works identically across build modes.
+ *
+ * - **deliver**: push `receive_messages_proof` for `[last_delivered+1 .. latest_generated]` (chunked
+ *   to MAX_MESSAGES_PER_PROOF) to the destination pool. Starting at the live `last_delivered+1` gives
+ *   `is_obsolete` its contiguity and re-delivers nothing.
+ * - **confirm**: push `receive_messages_delivery_proof` to the source pool so `latest_received_nonce`
+ *   advances and the destination prunes its relayers queue (else long runs hit the unconfirmed limit).
+ *
+ * `signer` must hold a balance on both sides.
+ */ export const connectBridgeHubs = async (source, destination, config)=>{
+    const sourceMessagesPallet = config.sourceMessagesPallet ?? detectSourceMessagesPallet(source);
+    const destParachainsPallet = config.destParachainsPallet ?? detectBridgeParachainsPallet(destination, 'destination');
+    const destMessagesPallet = config.destMessagesPallet ?? detectDestMessagesPallet(destination);
+    const dispatchWeight = config.dispatchWeightPerMessage ?? DEFAULT_DISPATCH_WEIGHT;
+    const signerAddress = typeof config.signer === 'string' ? config.signer : config.signer.address;
+    const relayerIdAtSource = config.relayerIdAtSource ?? signerAddress;
+    const [sourceParaId, destParaId] = await Promise.all([
+        config.sourceParaId ?? detectParaId(source, 'source'),
+        config.destParaId ?? detectParaId(destination, 'destination')
+    ]);
+    // Confirm proves the destination's inbound lane on the source, so it needs the source-side
+    // bridge-parachains pallet and the destination's para id (deliver's deps, reversed).
+    const sourceParachainsPallet = config.sourceParachainsPallet ?? detectBridgeParachainsPallet(source, 'source');
+    // camelCase pallet names for `api.query`/`api.tx` lookups.
+    const sourceMessages = stringCamelCase(sourceMessagesPallet);
+    const destMessages = stringCamelCase(destMessagesPallet);
+    const sourceParachains = stringCamelCase(sourceParachainsPallet);
+    const destParachains = stringCamelCase(destParachainsPallet);
+    // lane -> source `latest_generated_nonce` observed on source heads (deliver up to this).
+    const generated = new Map();
+    // lane -> `noncesEnd` of a delivery pushed to the destination pool but not yet observed applied.
+    const inFlight = new Map();
+    // lane -> highest destination `last_delivered_nonce` already confirmed back to source.
+    const confirmed = new Map();
+    // lane -> highest destination `last_delivered_nonce` observed by the deliver loop. It's
+    // monotonic, so it lets idle heads skip the per-lane inbound query.
+    const deliveredCache = new Map();
+    // Latest observed source head; outbound messages are proven against it (they exist there, since
+    // `latest_generated >= to`). Set on connect and refreshed on every source head.
+    let latestSourceHash;
+    let latestSourceNumber = 0;
+    // Push one chunk `[from..=to]` to the destination pool, proven against the given source head
+    // (the messages exist there since `latest_generated >= to`). Outbound lane state proven alongside.
+    const deliverRange = async (laneHex, from, to, sourceHash, sourceNumber)=>{
+        // `OutboundMessages` is keyed by `MessageKey { lane_id, nonce }`, passed as one struct arg.
+        const outboundMessages = source.query[sourceMessages].outboundMessages;
+        const keys = [
+            source.query[sourceMessages].outboundLanes.key(laneHex)
+        ];
+        for(let n = from; n <= to; n++){
+            keys.push(outboundMessages.key({
+                laneId: laneHex,
+                nonce: n
+            }));
+        }
+        // `dev_getReadProof` (not spec `state_getReadProof`) returns the recomputed `stateRoot` that the
+        // verifier checks against — it diverges from `header.state_root` once local overrides are applied.
+        const proof = await rawRpc(source, 'dev_getReadProof', [
+            keys,
+            sourceHash
+        ]);
+        const setStoragePayload = importParaHead(destination, destParachains, sourceParaId, sourceHash, sourceNumber, hexToU8a(proof.stateRoot));
+        await rawRpc(destination, 'dev_setStorage', [
+            setStoragePayload
+        ]);
+        const count = Number(to - from + 1n);
+        const tx = destination.tx[destMessages].receiveMessagesProof(relayerIdAtSource, {
+            bridgedHeaderHash: sourceHash,
+            storageProof: proof.proof,
+            lane: laneHex,
+            noncesStart: from,
+            noncesEnd: to
+        }, count, {
+            refTime: dispatchWeight.refTime * BigInt(count),
+            proofSize: dispatchWeight.proofSize * BigInt(count)
+        });
+        await submitTx(destination, tx, config.signer);
+        bridgeLogger.info({
+            lane: laneHex,
+            range: `${from}..=${to}`,
+            sourceBlock: sourceNumber
+        }, 'pushed bridge delivery');
+    };
+    // Push the next chunk for a lane if ready. Reads the live `last_delivered_nonce` so the proof
+    // starts at `last_delivered+1` (is_obsolete contiguity); an in-flight chunk blocks further pushes
+    // until a destination head shows it applied.
+    const tryDeliverLane = async (laneHex)=>{
+        const sourceHash = latestSourceHash;
+        const sourceNumber = latestSourceNumber;
+        if (sourceHash === undefined) return;
+        const generatedNonce = generated.get(laneHex) ?? 0n;
+        // Idle short-circuit: `last_delivered_nonce` is monotonic, so when the cached value already
+        // covers everything generated and nothing is in flight, skip the inbound query entirely.
+        if (generatedNonce <= (deliveredCache.get(laneHex) ?? 0n) && !inFlight.has(laneHex)) return;
+        const delivered = lastDeliveredFromInbound((await destination.query[destMessages].inboundLanes(laneHex)).toJSON());
+        deliveredCache.set(laneHex, delivered);
+        const pending = inFlight.get(laneHex);
+        if (pending !== undefined) {
+            if (delivered >= pending) inFlight.delete(laneHex);
+            else return; // previous chunk not applied yet — a further push would gap
+        }
+        if (generatedNonce <= delivered) return; // nothing new to deliver
+        const from = delivered + 1n;
+        const lastInChunk = from + MAX_MESSAGES_PER_PROOF - 1n;
+        const to = lastInChunk < generatedNonce ? lastInChunk : generatedNonce;
+        await deliverRange(laneHex, from, to, sourceHash, sourceNumber);
+        inFlight.set(laneHex, to);
+    };
+    // On any head, push whatever is currently deliverable on each known lane.
+    const syncDeliveries = async ()=>{
+        for (const laneHex of generated.keys()){
+            try {
+                await tryDeliverLane(laneHex);
+            } catch (err) {
+                const message = err.message;
+                inFlight.delete(laneHex); // allow a re-push on the next head
+                // a `stale` push means our `last_delivered` view lagged the chain — benign, just retry
+                if (isStaleError(message)) {
+                    bridgeLogger.debug({
+                        lane: laneHex
+                    }, 'delivery push stale; will retry');
+                } else {
+                    bridgeLogger.warn({
+                        err: message,
+                        lane: laneHex
+                    }, 'delivery push failed; will retry');
+                }
+            }
+        }
+    };
+    // Relay one lane's confirmation to `source`: prove the destination's `InboundLanes[lane]` (at
+    // `destHashHex`, where the delivery is applied) and submit `receive_messages_delivery_proof`,
+    // advancing the source's `latest_received_nonce`. Mirror of deliver.
+    const confirm = async (destHashHex, destBlockNumber, lane)=>{
+        const { laneHex, relayers, lastDelivered } = lane;
+        // Idempotency guard: skip if the source already covers `lastDelivered` (else `is_obsolete`
+        // rejects the re-submit as stale).
+        const sourceReceived = BigInt((await source.query[sourceMessages].outboundLanes(laneHex)).toJSON()?.latestReceivedNonce ?? 0);
+        if (lastDelivered <= sourceReceived) return;
+        const relayersState = deriveUnrewardedRelayersState(relayers, lastDelivered);
+        const proof = await rawRpc(destination, 'dev_getReadProof', [
+            [
+                destination.query[destMessages].inboundLanes.key(laneHex)
+            ],
+            destHashHex
+        ]);
+        const setStoragePayload = importParaHead(source, sourceParachains, destParaId, destHashHex, destBlockNumber, hexToU8a(proof.stateRoot));
+        await rawRpc(source, 'dev_setStorage', [
+            setStoragePayload
+        ]);
+        const tx = source.tx[sourceMessages].receiveMessagesDeliveryProof({
+            bridgedHeaderHash: destHashHex,
+            storageProof: proof.proof,
+            lane: laneHex
+        }, relayersState);
+        await submitTx(source, tx, config.signer);
+        bridgeLogger.info({
+            lane: laneHex,
+            lastDelivered: lastDelivered.toString(),
+            destBlock: destBlockNumber
+        }, 'confirmed bridge deliveries');
+    };
+    // Per-lane `latest_generated_nonce` from `OutboundLanes` at a pinned source block.
+    const readOutboundLanes = async (apiAt)=>{
+        const entries = await apiAt.query[sourceMessages].outboundLanes.entries();
+        return entries.map(([key, valueCodec])=>{
+            const v = valueCodec.toJSON();
+            return [
+                laneHexFromKey(key),
+                BigInt(v?.latestGeneratedNonce ?? 0)
+            ];
+        });
+    };
+    // Per-lane `InboundLaneData` from `InboundLanes` at a pinned destination block, with
+    // `last_delivered_nonce` derived as the pallet does (see `lastDeliveredFromInbound`).
+    const readInboundLanes = async (apiAt)=>{
+        const entries = await apiAt.query[destMessages].inboundLanes.entries();
+        return entries.map(([key, valueCodec])=>{
+            const v = valueCodec.toJSON();
+            return {
+                laneHex: laneHexFromKey(key),
+                relayers: v?.relayers ?? [],
+                lastDelivered: lastDeliveredFromInbound(v)
+            };
+        });
+    };
+    // On a source head: pin it as the proving head and update each lane's generated high-water mark.
+    // Read at the header's own hash so a later proof attests exactly the nonces extant at that head.
+    const refreshGenerated = async (sourceHeader)=>{
+        const sourceHashHex = sourceHeader.hash.toHex();
+        try {
+            const lanes = await readOutboundLanes(await source.at(sourceHashHex));
+            latestSourceHash = sourceHashHex;
+            latestSourceNumber = sourceHeader.number.toNumber();
+            for (const [laneHex, latestGenerated] of lanes)generated.set(laneHex, latestGenerated);
+        } catch (err) {
+            bridgeLogger.warn({
+                err: err.message,
+                sourceHash: sourceHashHex
+            }, 'outboundLanes enumeration failed');
+        }
+    };
+    const pumpConfirm = async (destHeader)=>{
+        const destHashHex = destHeader.hash.toHex();
+        const destBlockNumber = destHeader.number.toNumber();
+        let lanes;
+        try {
+            lanes = await readInboundLanes(await destination.at(destHashHex));
+        } catch (err) {
+            bridgeLogger.warn({
+                err: err.message,
+                destHash: destHashHex
+            }, 'inboundLanes enumeration failed');
+            return;
+        }
+        for (const lane of lanes){
+            if (lane.lastDelivered <= (confirmed.get(lane.laneHex) ?? 0n)) continue;
+            try {
+                await confirm(destHashHex, destBlockNumber, lane);
+                confirmed.set(lane.laneHex, lane.lastDelivered);
+            } catch (err) {
+                const message = err.message;
+                // A `stale` rejection is benign: the source lane already advanced (a competing
+                // confirmation, or our own already-applied submit racing the read), so mark it done.
+                if (isStaleError(message)) {
+                    confirmed.set(lane.laneHex, lane.lastDelivered);
+                    bridgeLogger.debug({
+                        lane: lane.laneHex
+                    }, 'confirmation already applied (stale); skipping');
+                } else {
+                    // Leave `confirmed` un-advanced so the next destination head retries.
+                    bridgeLogger.warn({
+                        err: message,
+                        lane: lane.laneHex
+                    }, 'confirmation failed; will retry');
+                }
+            }
+        }
+    };
+    // Delivery self-seeds (live `last_delivered` + `refreshGenerated` on the first source head), so
+    // only confirm needs a baseline: pin `confirmed` to the current `last_delivered` so a fork's
+    // pre-existing delivered-but-unconfirmed backlog isn't re-confirmed.
+    try {
+        const destHead = await destination.rpc.chain.getBlockHash();
+        for (const lane of (await readInboundLanes(await destination.at(destHead)))){
+            confirmed.set(lane.laneHex, lane.lastDelivered);
+        }
+    } catch (err) {
+        bridgeLogger.warn({
+            err: err.message
+        }, 'confirmation baseline seed failed; lanes baseline on first head');
+    }
+    // Delivery is serialized across both head streams (source heads update generated, destination
+    // heads observe applied chunks); confirmation is its own queue on destination heads.
+    const deliverQueue = serialChain('unexpected deliver error');
+    const confirmQueue = serialChain('unexpected confirm-pump error');
+    const unsubSource = await source.rpc.chain.subscribeNewHeads((header)=>{
+        deliverQueue.enqueue(async ()=>{
+            await refreshGenerated(header);
+            await syncDeliveries();
+        });
+    });
+    const unsubDest = await destination.rpc.chain.subscribeNewHeads((header)=>{
+        // A destination block may have applied an in-flight chunk → push the next one.
+        deliverQueue.enqueue(()=>syncDeliveries());
+        confirmQueue.enqueue(()=>pumpConfirm(header));
+    });
+    bridgeLogger.info({
+        sourceMessagesPallet,
+        destParachainsPallet,
+        destMessagesPallet,
+        sourceParaId,
+        sourceParachainsPallet,
+        destParaId
+    }, 'bridge connector started');
+    return {
+        async disconnect () {
+            unsubSource();
+            unsubDest();
+            await Promise.all([
+                deliverQueue.drain(),
+                confirmQueue.drain()
+            ]);
+            bridgeLogger.info('bridge connector stopped');
+        }
+    };
+};
+const rawRpc = async (api, method, params)=>{
+    const provider = api._rpcCore?.provider;
+    if (!provider?.send) throw new Error(`connectBridgeHubs: cannot access provider for ${method}`);
+    return provider.send(method, params);
+};
+/** Storage-shape predicate for a `pallet_bridge_messages` instance. */ const isBridgeMessagesPallet = (pallet)=>!!(pallet?.outboundLanes && pallet?.outboundMessages);
+/** Whether `api`'s runtime registers a `pallet_bridge_messages` instance. */ export const hasBridgeMessagesPallet = (api)=>Object.values(api.query).some(isBridgeMessagesPallet);
+/**
+ * Find the unique pallet in `namespace` matching `predicate`, returning its PascalCase
+ * name. Throws a remediation-pointing error on zero or multiple matches.
+ */ const detectPallet = (namespace, predicate, kind, label, overrideField)=>{
+    const matches = Object.keys(namespace).filter((key)=>predicate(namespace[key]));
+    if (matches.length === 0) throw new Error(`connectBridgeHubs: no pallet_bridge_${kind} instance on ${label}`);
+    if (matches.length > 1) {
+        const names = matches.map(stringPascalCase).join(', ');
+        throw new Error(`connectBridgeHubs: ${label} has multiple bridge-${kind} instances (${names}); set ${overrideField}`);
+    }
+    return stringPascalCase(matches[0]);
+};
+const detectSourceMessagesPallet = (api)=>detectPallet(api.query, isBridgeMessagesPallet, 'messages', 'source', 'sourceMessagesPallet');
+const detectDestMessagesPallet = (api)=>detectPallet(api.tx, (p)=>p?.receiveMessagesProof, 'messages', 'destination', 'destMessagesPallet');
+const detectBridgeParachainsPallet = (api, label)=>detectPallet(api.query, (p)=>p?.parasInfo && p?.importedParaHeads, 'parachains', label, label === 'source' ? 'sourceParachainsPallet' : 'destParachainsPallet');
+const detectParaId = async (api, label)=>{
+    const idCodec = await api.query.parachainInfo?.parachainId?.();
+    if (idCodec) return idCodec.toNumber();
+    throw new Error(`connectBridgeHubs: cannot auto-detect ${label === 'source' ? 'sourceParaId' : 'destParaId'}`);
+};

package/dist/esm/cli.js

@@ -1,13 +1,61 @@
 import { connectParachains, connectVertical, environment } from '@acala-network/chopsticks-core';
+import { ApiPromise, Keyring, WsProvider } from '@polkadot/api';
+import { cryptoWaitReady } from '@polkadot/util-crypto';
 import { config as dotenvConfig } from 'dotenv';
 import _ from 'lodash';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import { z } from 'zod';
+import { connectBridgeHubs, hasBridgeMessagesPallet } from './bridge.js';
 import { setupWithServer } from './index.js';
 import { loadRpcMethodsByScripts, pluginExtendCli } from './plugins/index.js';
 import { configSchema, fetchConfig, getYargsOptions } from './schema/index.js';
 dotenvConfig();
+/** Fork relay (optional) + parachains and wire them with UMP/DMP/HRMP — the `xcm` command's core. */ const setupNetwork = async (relayConfigRef, parachainConfigRefs)=>{
+    const parachains = [];
+    for (const configRef of parachainConfigRefs){
+        const { chain, addr } = await setupWithServer(await fetchConfig(configRef));
+        parachains.push({
+            chain,
+            addr,
+            configRef
+        });
+    }
+    if (parachains.length > 1) {
+        await connectParachains(parachains.map((c)=>c.chain), environment.DISABLE_AUTO_HRMP);
+    }
+    if (relayConfigRef) {
+        const { chain: relay } = await setupWithServer(await fetchConfig(relayConfigRef));
+        for (const c of parachains)await connectVertical(relay, c.chain);
+    }
+    return parachains;
+};
+/** One side of a bridged setup: an xcm network plus an `ApiPromise` per parachain. */ const setupBridgeSide = async (relayConfigRef, parachainConfigRefs)=>{
+    const parachains = await setupNetwork(relayConfigRef, parachainConfigRefs);
+    return Promise.all(parachains.map(async ({ chain, addr, configRef })=>{
+        const url = `ws://${addr}`;
+        const api = await ApiPromise.create({
+            provider: new WsProvider(url, 3_000),
+            noInitWarn: true
+        });
+        return {
+            chain,
+            api,
+            url,
+            configRef
+        };
+    }));
+};
+/** Pick the parachain whose runtime registers `pallet_bridge_messages`. */ const findBridgeHub = (side, label)=>{
+    const candidates = side.filter((c)=>hasBridgeMessagesPallet(c.api));
+    if (candidates.length === 0) {
+        throw new Error(`chopsticks bridge: no ${label}-side parachain hosts pallet_bridge_messages. ` + `Provided: ${side.map((c)=>c.configRef).join(', ')}. Include a bridge-hub config.`);
+    }
+    if (candidates.length > 1) {
+        throw new Error(`chopsticks bridge: multiple ${label}-side parachains host pallet_bridge_messages (${candidates.map((c)=>c.configRef).join(', ')}). Cannot disambiguate — provide only one bridge hub per side.`);
+    }
+    return candidates[0];
+};
 const processArgv = async (argv)=>{
     try {
         if (argv.unsafeRpcMethods) {
@@ -42,20 +90,61 @@ const commands = yargs(hideBin(process.argv)).scriptName('chopsticks').middlewar
             required: true
         }
     }).alias('relaychain', 'r').alias('parachain', 'p'), async (argv)=>{
-    const parachains = [];
-    for (const config of argv.parachain){
-        const { chain } = await setupWithServer(await fetchConfig(config));
-        parachains.push(chain);
-    }
-    if (parachains.length > 1) {
-        await connectParachains(parachains, environment.DISABLE_AUTO_HRMP);
-    }
-    if (argv.relaychain) {
-        const { chain: relaychain } = await setupWithServer(await fetchConfig(argv.relaychain));
-        for (const parachain of parachains){
-            await connectVertical(relaychain, parachain);
+    await setupNetwork(argv.relaychain, argv.parachain);
+}).command('bridge', 'Bridged-XCM setup: two ecosystems wired with pallet_bridge_messages in both directions', (yargs)=>yargs.options({
+        'left-relaychain': {
+            desc: 'Left-side relaychain config (named or path). Example: westend',
+            string: true
+        },
+        'left-parachain': {
+            desc: 'Left-side parachain config(s). One of them must host pallet_bridge_messages.',
+            type: 'array',
+            string: true,
+            required: true
+        },
+        'right-relaychain': {
+            desc: 'Right-side relaychain config (named or path). Example: rococo',
+            string: true
+        },
+        'right-parachain': {
+            desc: 'Right-side parachain config(s). One of them must host pallet_bridge_messages.',
+            type: 'array',
+            string: true,
+            required: true
+        },
+        'bridge-signer-uri': {
+            desc: 'Relayer URI for the forward direction (left → right). Submits receive_messages_proof / _delivery_proof.',
+            string: true,
+            default: '//Alice'
+        },
+        'bridge-reverse-signer-uri': {
+            desc: 'Relayer URI for the reverse direction (right → left). Defaults to <bridge-signer-uri>//reverse. Must differ from the forward relayer so their nonces on the shared hubs do not collide.',
+            string: true
         }
-    }
+    }).alias('left-relaychain', 'r').alias('left-parachain', 'p').alias('right-relaychain', 'R').alias('right-parachain', 'P'), async (argv)=>{
+    await cryptoWaitReady();
+    const left = await setupBridgeSide(argv['left-relaychain'], argv['left-parachain']);
+    const right = await setupBridgeSide(argv['right-relaychain'], argv['right-parachain']);
+    const leftBh = findBridgeHub(left, 'left');
+    const rightBh = findBridgeHub(right, 'right');
+    // Each direction needs its OWN relayer account. Both connectors submit relayer txs to the
+    // same two hubs (the forward direction's confirmations and the reverse direction's deliveries
+    // both land on a given hub), so a shared signer collides on its nonce and one direction's tx
+    // is silently dropped. Distinct accounts give each direction its own nonce sequence.
+    const keyring = new Keyring({
+        type: 'sr25519'
+    });
+    const forwardSigner = keyring.addFromUri(argv['bridge-signer-uri']);
+    const reverseSigner = keyring.addFromUri(argv['bridge-reverse-signer-uri'] ?? `${argv['bridge-signer-uri']}//reverse`);
+    await Promise.all([
+        connectBridgeHubs(leftBh.api, rightBh.api, {
+            signer: forwardSigner
+        }),
+        connectBridgeHubs(rightBh.api, leftBh.api, {
+            signer: reverseSigner
+        })
+    ]);
+    console.log(`Bridge connected:\n  left  bridge-hub @ ${leftBh.url}\n  right bridge-hub @ ${rightBh.url}\n` + `Relayers (fund BOTH on BOTH hubs): forward ${forwardSigner.address}, reverse ${reverseSigner.address}. ` + 'They push proofs to each hub; blocks are produced by the hubs (build mode) or by you (dev_newBlock).');
 }).strict().help().alias('help', 'h').alias('version', 'v').alias('config', 'c').alias('endpoint', 'e').alias('port', 'p').alias('block', 'b').alias('unsafe-rpc-methods', 'ur').alias('import-storage', 's').alias('wasm-override', 'w').usage('Usage: $0 <command> [options]').example('$0', '-c acala').showHelpOnFail(false);
 if (!environment.DISABLE_PLUGINS) {
     pluginExtendCli(commands.config('config', 'Path to config file with default options', ()=>({}))).then(()=>commands.parse());

package/dist/esm/index.d.ts

@@ -1,4 +1,5 @@
 import '@polkadot/api-augment';
 export * from '@acala-network/chopsticks-core';
+export * from './bridge.js';
 export { fetchConfig } from './schema/index.js';
 export { setupWithServer } from './setup-with-server.js';

package/dist/esm/index.js

@@ -1,4 +1,5 @@
 import '@polkadot/api-augment';
 export * from '@acala-network/chopsticks-core';
+export * from './bridge.js';
 export { fetchConfig } from './schema/index.js';
 export { setupWithServer } from './setup-with-server.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acala-network/chopsticks",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "author": "Acala Developers <hello@acala.network>",
   "license": "Apache-2.0",
   "bin": "./chopsticks.cjs",
@@ -15,8 +15,8 @@
     "depcheck": "npx depcheck --ignore-patterns='*.test.ts'"
   },
   "dependencies": {
-    "@acala-network/chopsticks-core": "1.4.2",
-    "@acala-network/chopsticks-db": "1.4.2",
+    "@acala-network/chopsticks-core": "1.5.0",
+    "@acala-network/chopsticks-db": "1.5.0",
     "@dmsnell/diff-match-patch": "^1.1.0",
     "@pnpm/npm-conf": "^3.0.0",
     "@polkadot/api": "^16.4.1",
@@ -29,10 +29,10 @@
     "comlink": "^4.4.2",
     "dotenv": "^16.6.1",
     "global-agent": "^3.0.0",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^4.2.0",
     "jsondiffpatch": "^0.7.3",
     "lodash": "^4.18.1",
-    "ws": "^8.20.1",
+    "ws": "^8.21.0",
     "yargs": "^18.0.0",
     "zod": "^3.25.76"
   },