@bananapus/nana-sdk-core 1.2.0 → 1.4.0

package/dist/cjs/v6/suckers.js

@@ -1,18 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.jbSuckerV6Abi = void 0;
+exports.NATIVE_SUCKER_TRANSPORT_VALUES = exports.CCIP_SUCKER_TRANSPORT_VALUES = exports.SUCKER_EMPTY_TREE_ROOT = exports.SUCKER_MERKLE_DEPTH = exports.jbSuckerV6Abi = exports.jbNativeSuckerV6ProbeAbi = exports.jbCcipSuckerV6Abi = exports.insertToSuckerOutboxEvent = exports.jbSuckerV6ViewAbi = void 0;
+exports.suckerLeafHash = suckerLeafHash;
+exports.suckerHashPair = suckerHashPair;
+exports.suckerZeroHashes = suckerZeroHashes;
+exports.suckerLeafProof = suckerLeafProof;
+exports.suckerBranchRoot = suckerBranchRoot;
+exports.suckerBytes32ToAddress = suckerBytes32ToAddress;
+exports.getSuckerOutboxLeaves = getSuckerOutboxLeaves;
+exports.classifySuckerMovement = classifySuckerMovement;
+exports.getSuckerMovements = getSuckerMovements;
+exports.claimFromSuckerMovement = claimFromSuckerMovement;
+exports.findSuckerTransportValue = findSuckerTransportValue;
+exports.assertSuckerTransportValue = assertSuckerTransportValue;
+exports.classifySuckerTransport = classifySuckerTransport;
+exports.buildSyncAccountingDataTx = buildSyncAccountingDataTx;
+exports.relativeSuckerDrift = relativeSuckerDrift;
+exports.suckerTimestampSeconds = suckerTimestampSeconds;
 exports.buildBridgePrepareTx = buildBridgePrepareTx;
 exports.buildBridgeClaimTx = buildBridgeClaimTx;
 exports.buildToRemoteTx = buildToRemoteTx;
 exports.getV6SuckerPairs = getV6SuckerPairs;
+exports.getAllV6SuckerPairs = getAllV6SuckerPairs;
 const viem_1 = require("viem");
 const juicebox_js_1 = require("../generated/juicebox.js");
 const types_js_1 = require("./types.js");
-/**
- * Minimal v6 JBSucker ABI. v6 identifies remote beneficiaries as bytes32 (for cross-VM
- * compatibility) and adds an opaque `metadata` attribution payload to prepared leaves.
- */
-exports.jbSuckerV6Abi = [
+const jbSuckerV6WriteAbi = [
     {
         type: "function",
         name: "prepare",
@@ -50,8 +63,16 @@ exports.jbSuckerV6Abi = [
                         components: [
                             { name: "index", type: "uint256", internalType: "uint256" },
                             { name: "beneficiary", type: "bytes32", internalType: "bytes32" },
-                            { name: "projectTokenCount", type: "uint256", internalType: "uint256" },
-                            { name: "terminalTokenAmount", type: "uint256", internalType: "uint256" },
+                            {
+                                name: "projectTokenCount",
+                                type: "uint256",
+                                internalType: "uint256",
+                            },
+                            {
+                                name: "terminalTokenAmount",
+                                type: "uint256",
+                                internalType: "uint256",
+                            },
                             { name: "metadata", type: "bytes32", internalType: "bytes32" },
                         ],
                     },
@@ -63,6 +84,593 @@ exports.jbSuckerV6Abi = [
         stateMutability: "nonpayable",
     },
 ];
+/** Common v6 sucker view surface used to reconstruct and verify bridge state. */
+exports.jbSuckerV6ViewAbi = [
+    {
+        type: "function",
+        name: "peer",
+        stateMutability: "view",
+        inputs: [],
+        outputs: [{ name: "", type: "bytes32" }],
+    },
+    {
+        type: "function",
+        name: "peerChainId",
+        stateMutability: "view",
+        inputs: [],
+        outputs: [{ name: "", type: "uint256" }],
+    },
+    {
+        type: "function",
+        name: "projectId",
+        stateMutability: "view",
+        inputs: [],
+        outputs: [{ name: "", type: "uint256" }],
+    },
+    {
+        type: "function",
+        name: "outboxOf",
+        stateMutability: "view",
+        inputs: [{ name: "token", type: "address" }],
+        outputs: [
+            {
+                name: "outbox",
+                type: "tuple",
+                components: [
+                    { name: "nonce", type: "uint64" },
+                    { name: "numberOfClaimsSent", type: "uint192" },
+                    { name: "balance", type: "uint256" },
+                    {
+                        name: "tree",
+                        type: "tuple",
+                        components: [
+                            { name: "branch", type: "bytes32[32]" },
+                            { name: "count", type: "uint256" },
+                        ],
+                    },
+                ],
+            },
+        ],
+    },
+    {
+        type: "function",
+        name: "inboxOf",
+        stateMutability: "view",
+        inputs: [{ name: "token", type: "address" }],
+        outputs: [
+            {
+                name: "inbox",
+                type: "tuple",
+                components: [
+                    { name: "nonce", type: "uint64" },
+                    { name: "root", type: "bytes32" },
+                ],
+            },
+        ],
+    },
+    {
+        type: "function",
+        name: "executedLeafHashOf",
+        stateMutability: "view",
+        inputs: [
+            { name: "token", type: "address" },
+            { name: "index", type: "uint256" },
+        ],
+        outputs: [{ name: "hash", type: "bytes32" }],
+    },
+    {
+        type: "function",
+        name: "remoteTokenFor",
+        stateMutability: "view",
+        inputs: [{ name: "token", type: "address" }],
+        outputs: [
+            {
+                name: "remoteToken",
+                type: "tuple",
+                components: [
+                    { name: "enabled", type: "bool" },
+                    { name: "emergencyHatch", type: "bool" },
+                    { name: "minGas", type: "uint32" },
+                    { name: "addr", type: "bytes32" },
+                ],
+            },
+        ],
+    },
+];
+/** Event carrying the complete v6 outbox leaf preimage and resulting root. */
+exports.insertToSuckerOutboxEvent = {
+    type: "event",
+    name: "InsertToOutboxTree",
+    inputs: [
+        { name: "beneficiary", type: "bytes32", indexed: true },
+        { name: "token", type: "address", indexed: true },
+        { name: "hashed", type: "bytes32", indexed: false },
+        { name: "index", type: "uint256", indexed: false },
+        { name: "root", type: "bytes32", indexed: false },
+        { name: "projectTokenCount", type: "uint256", indexed: false },
+        { name: "terminalTokenAmount", type: "uint256", indexed: false },
+        { name: "metadata", type: "bytes32", indexed: false },
+        { name: "caller", type: "address", indexed: false },
+    ],
+};
+/** CCIP-only probe used to distinguish fee-bearing sucker transports. */
+exports.jbCcipSuckerV6Abi = [
+    {
+        type: "function",
+        name: "CCIP_ROUTER",
+        stateMutability: "view",
+        inputs: [],
+        outputs: [{ name: "", type: "address" }],
+    },
+];
+/** Native-bridge-only probes used to positively identify sucker transports. */
+exports.jbNativeSuckerV6ProbeAbi = [
+    {
+        type: "function",
+        name: "OPMESSENGER",
+        stateMutability: "view",
+        inputs: [],
+        outputs: [{ name: "", type: "address" }],
+    },
+    {
+        type: "function",
+        name: "ARBINBOX",
+        stateMutability: "view",
+        inputs: [],
+        outputs: [{ name: "", type: "address" }],
+    },
+];
+/**
+ * Reusable v6 JBSucker ABI: transaction builders, bridge-state views, the
+ * outbox event, and the permissionless accounting-sync entrypoint.
+ */
+exports.jbSuckerV6Abi = [
+    ...exports.jbSuckerV6ViewAbi,
+    exports.insertToSuckerOutboxEvent,
+    ...jbSuckerV6WriteAbi,
+    {
+        type: "function",
+        name: "syncAccountingData",
+        stateMutability: "payable",
+        inputs: [],
+        outputs: [],
+    },
+];
+/** Reproduce the exact leaf hash committed by a v6 sucker. */
+function suckerLeafHash({ projectTokenCount, terminalTokenAmount, beneficiary, metadata, }) {
+    return (0, viem_1.keccak256)((0, viem_1.encodeAbiParameters)([
+        { type: "uint256" },
+        { type: "uint256" },
+        { type: "bytes32" },
+        { type: "bytes32" },
+    ], [projectTokenCount, terminalTokenAmount, beneficiary, metadata]));
+}
+/** Fixed depth used by the v6 suckers' incremental Merkle trees. */
+exports.SUCKER_MERKLE_DEPTH = 32;
+/** MerkleLib's root for an empty depth-32 tree. */
+exports.SUCKER_EMPTY_TREE_ROOT = "0x27ae5ba08d7291c96c8cbddcc148bf48a6d68c7974b94356f53754ef6171d757";
+/** Hash a MerkleLib node pair (`keccak256(abi.encode(bytes32, bytes32))`). */
+function suckerHashPair(left, right) {
+    return (0, viem_1.keccak256)((0, viem_1.encodeAbiParameters)([{ type: "bytes32" }, { type: "bytes32" }], [left, right]));
+}
+let suckerZeroHashesCache = null;
+/** Empty-subtree hashes for depths 0 through 32, self-checked at depth 32. */
+function suckerZeroHashes() {
+    if (suckerZeroHashesCache)
+        return suckerZeroHashesCache;
+    const hashes = [viem_1.zeroHash];
+    for (let depth = 0; depth < exports.SUCKER_MERKLE_DEPTH; depth++) {
+        hashes.push(suckerHashPair(hashes[depth], hashes[depth]));
+    }
+    if (hashes[exports.SUCKER_MERKLE_DEPTH] !== exports.SUCKER_EMPTY_TREE_ROOT) {
+        throw new Error("The sucker Merkle zero-hash self-check failed.");
+    }
+    suckerZeroHashesCache = hashes;
+    return hashes;
+}
+/**
+ * Build the fixed 32-sibling inclusion path for a dense outbox leaf array.
+ * Missing right-hand subtrees are filled with MerkleLib's canonical zero hash.
+ */
+function suckerLeafProof(leafHashes, index) {
+    if (!Number.isSafeInteger(index) || index < 0 || index >= leafHashes.length) {
+        throw new Error("The requested sucker leaf is outside the outbox.");
+    }
+    const zeroHashes = suckerZeroHashes();
+    let level = leafHashes.slice();
+    const proof = [];
+    let position = index;
+    for (let depth = 0; depth < exports.SUCKER_MERKLE_DEPTH; depth++) {
+        const sibling = position ^ 1;
+        proof.push(sibling < level.length ? level[sibling] : zeroHashes[depth]);
+        const next = [];
+        for (let offset = 0; offset < level.length; offset += 2) {
+            next.push(suckerHashPair(level[offset], offset + 1 < level.length ? level[offset + 1] : zeroHashes[depth]));
+        }
+        level = next;
+        position = Math.floor(position / 2);
+    }
+    return proof;
+}
+/** Recompute a sucker root from one leaf hash and its inclusion proof. */
+function suckerBranchRoot(leafHash, proof, index) {
+    if (!Number.isSafeInteger(index) || index < 0) {
+        throw new Error("A sucker leaf index must be a non-negative safe integer.");
+    }
+    if (proof.length !== exports.SUCKER_MERKLE_DEPTH) {
+        throw new Error(`A sucker proof must contain ${exports.SUCKER_MERKLE_DEPTH} sibling hashes.`);
+    }
+    let current = leafHash;
+    let position = index;
+    for (let depth = 0; depth < exports.SUCKER_MERKLE_DEPTH; depth++) {
+        current =
+            position & 1
+                ? suckerHashPair(proof[depth], current)
+                : suckerHashPair(current, proof[depth]);
+        position = Math.floor(position / 2);
+    }
+    return current;
+}
+function safeSuckerCount(value, label) {
+    const count = Number(value);
+    if (!Number.isSafeInteger(count) || count < 0) {
+        throw new Error(`The sucker returned an invalid ${label}.`);
+    }
+    return count;
+}
+/** Convert a low-20-byte EVM address stored in bytes32 into a checksum address. */
+function suckerBytes32ToAddress(value) {
+    if (value.toLowerCase() === viem_1.zeroHash) {
+        throw new Error("The sucker bytes32 value does not contain an address.");
+    }
+    if (!/^0x0{24}[0-9a-fA-F]{40}$/.test(value)) {
+        throw new Error("The sucker bytes32 value is not an EVM address.");
+    }
+    return (0, viem_1.getAddress)((0, viem_1.sliceHex)(value, 12));
+}
+/**
+ * Read every dense outbox leaf for a sucker/token and verify the reconstructed
+ * latest root against the root emitted on-chain.
+ *
+ * A wide log request is attempted first. Providers that reject it fall back to
+ * bounded reverse scans, avoiding the subtly truncated histories which would
+ * otherwise produce invalid claim proofs.
+ */
+async function getSuckerOutboxLeaves(client, { sucker, token, count: requestedCount, fromBlock = 0n, toBlock, blockRange = 45000n, maxBlockRanges = 512, }) {
+    if (fromBlock < 0n)
+        throw new Error("fromBlock cannot be negative.");
+    if (blockRange <= 0n)
+        throw new Error("blockRange must be positive.");
+    if (!Number.isSafeInteger(maxBlockRanges) || maxBlockRanges < 1) {
+        throw new Error("maxBlockRanges must be a positive safe integer.");
+    }
+    const count = requestedCount ??
+        safeSuckerCount((await client.readContract({
+            address: sucker,
+            abi: exports.jbSuckerV6ViewAbi,
+            functionName: "outboxOf",
+            args: [token],
+        })).tree.count, "outbox count");
+    if (!Number.isSafeInteger(count) || count < 0) {
+        throw new Error("count must be a non-negative safe integer.");
+    }
+    if (count === 0)
+        return [];
+    const latest = toBlock ?? (await client.getBlockNumber());
+    if (latest < fromBlock)
+        throw new Error("toBlock cannot precede fromBlock.");
+    const byIndex = new Map();
+    const collect = (logs) => {
+        for (const log of logs) {
+            const index = safeSuckerCount(log.args.index, "outbox leaf index");
+            if (index >= count)
+                continue;
+            const hashed = suckerLeafHash({
+                beneficiary: log.args.beneficiary,
+                projectTokenCount: log.args.projectTokenCount,
+                terminalTokenAmount: log.args.terminalTokenAmount,
+                metadata: log.args.metadata,
+            });
+            if (hashed.toLowerCase() !== log.args.hashed.toLowerCase()) {
+                throw new Error(`The sucker outbox event's leaf preimage does not match leaf ${index}.`);
+            }
+            byIndex.set(index, {
+                index,
+                hashed,
+                root: log.args.root,
+                beneficiary: log.args.beneficiary,
+                projectTokenCount: log.args.projectTokenCount,
+                terminalTokenAmount: log.args.terminalTokenAmount,
+                metadata: log.args.metadata,
+                blockNumber: log.blockNumber,
+            });
+        }
+    };
+    let wideScanFailed = false;
+    try {
+        collect((await client.getLogs({
+            address: sucker,
+            event: exports.insertToSuckerOutboxEvent,
+            args: { token },
+            fromBlock,
+            toBlock: latest,
+            strict: true,
+        })));
+    }
+    catch {
+        wideScanFailed = true;
+    }
+    if (wideScanFailed || byIndex.size !== count) {
+        byIndex.clear();
+        let cursor = latest;
+        let ranges = 0;
+        while (cursor >= fromBlock &&
+            byIndex.size < count &&
+            ranges < maxBlockRanges) {
+            const rangeStart = cursor - fromBlock + 1n > blockRange
+                ? cursor - blockRange + 1n
+                : fromBlock;
+            collect((await client.getLogs({
+                address: sucker,
+                event: exports.insertToSuckerOutboxEvent,
+                args: { token },
+                fromBlock: rangeStart,
+                toBlock: cursor,
+                strict: true,
+            })));
+            ranges += 1;
+            if (rangeStart === fromBlock)
+                break;
+            cursor = rangeStart - 1n;
+        }
+    }
+    const leaves = [];
+    for (let index = 0; index < count; index++) {
+        const leaf = byIndex.get(index);
+        if (!leaf) {
+            throw new Error(`The RPC did not return the complete sucker outbox history (missing leaf ${index}).`);
+        }
+        leaves.push(leaf);
+    }
+    const last = leaves[count - 1];
+    const latestRoot = suckerBranchRoot(last.hashed, suckerLeafProof(leaves.map((leaf) => leaf.hashed), count - 1), count - 1);
+    if (latestRoot.toLowerCase() !== last.root.toLowerCase()) {
+        throw new Error("The reconstructed sucker outbox does not match its latest emitted root.");
+    }
+    return leaves;
+}
+/** Pure status classification shared by bridge movement lists. */
+function classifySuckerMovement({ executed, index, deliveredCount, sentCount, }) {
+    if (executed)
+        return { status: "claimed", canExecute: false };
+    if (index < deliveredCount) {
+        return { status: "claimable", canExecute: false };
+    }
+    return { status: "pending", canExecute: index >= sentCount };
+}
+/**
+ * Reconstruct all movements for one source sucker/token, verify the outbox and
+ * destination inbox roots, and attach a claim proof only to claimable leaves.
+ */
+async function getSuckerMovements(sourceClient, destinationClient, { sourceSucker, destinationSucker, sourceToken, remoteToken: requestedRemoteToken, ...scanOptions }) {
+    const [outbox, remoteMapping] = await Promise.all([
+        sourceClient.readContract({
+            address: sourceSucker,
+            abi: exports.jbSuckerV6ViewAbi,
+            functionName: "outboxOf",
+            args: [sourceToken],
+        }),
+        sourceClient.readContract({
+            address: sourceSucker,
+            abi: exports.jbSuckerV6ViewAbi,
+            functionName: "remoteTokenFor",
+            args: [sourceToken],
+        }),
+    ]);
+    const count = safeSuckerCount(outbox.tree.count, "outbox count");
+    const sentCount = safeSuckerCount(outbox.numberOfClaimsSent, "sent-claims count");
+    if (sentCount > count) {
+        throw new Error("The sucker sent-claims count exceeds its outbox count.");
+    }
+    if (count === 0)
+        return [];
+    const mappedRemoteToken = remoteMapping.addr.toLowerCase() === viem_1.zeroHash
+        ? null
+        : suckerBytes32ToAddress(remoteMapping.addr);
+    if (mappedRemoteToken &&
+        requestedRemoteToken &&
+        mappedRemoteToken.toLowerCase() !== requestedRemoteToken.toLowerCase()) {
+        throw new Error("The supplied historical token does not match the sucker's live mapping.");
+    }
+    const remoteToken = mappedRemoteToken ?? requestedRemoteToken;
+    if (!remoteToken) {
+        throw new Error("The sucker's historical remote token mapping must be supplied explicitly.");
+    }
+    const leaves = await getSuckerOutboxLeaves(sourceClient, {
+        sucker: sourceSucker,
+        token: sourceToken,
+        count,
+        ...scanOptions,
+    });
+    const leafHashes = leaves.map((leaf) => leaf.hashed);
+    const [inbox, executedHashes] = await Promise.all([
+        destinationClient.readContract({
+            address: destinationSucker,
+            abi: exports.jbSuckerV6ViewAbi,
+            functionName: "inboxOf",
+            args: [remoteToken],
+        }),
+        Promise.all(leaves.map((leaf) => destinationClient.readContract({
+            address: destinationSucker,
+            abi: exports.jbSuckerV6ViewAbi,
+            functionName: "executedLeafHashOf",
+            args: [remoteToken, BigInt(leaf.index)],
+        }))),
+    ]);
+    let deliveredCount = 0;
+    if (inbox.root.toLowerCase() !== viem_1.zeroHash) {
+        for (let index = leaves.length - 1; index >= 0; index--) {
+            if (leaves[index].root.toLowerCase() === inbox.root.toLowerCase()) {
+                deliveredCount = index + 1;
+                break;
+            }
+        }
+        if (deliveredCount === 0) {
+            throw new Error("The destination sucker inbox root is absent from the reconstructed outbox.");
+        }
+    }
+    return leaves.map((outboxLeaf, index) => {
+        const executedHash = executedHashes[index];
+        if (executedHash.toLowerCase() !== viem_1.zeroHash &&
+            executedHash.toLowerCase() !== outboxLeaf.hashed.toLowerCase()) {
+            throw new Error("The destination sucker's executed leaf does not match the reconstructed outbox.");
+        }
+        const { status, canExecute } = classifySuckerMovement({
+            executed: executedHash.toLowerCase() !== viem_1.zeroHash,
+            index,
+            deliveredCount,
+            sentCount,
+        });
+        const proof = status === "claimable"
+            ? suckerLeafProof(leafHashes.slice(0, deliveredCount), index)
+            : null;
+        if (proof &&
+            suckerBranchRoot(outboxLeaf.hashed, proof, index).toLowerCase() !==
+                inbox.root.toLowerCase()) {
+            throw new Error("The reconstructed sucker proof does not match the destination inbox.");
+        }
+        return {
+            sourceToken,
+            remoteToken,
+            leaf: {
+                index: BigInt(index),
+                beneficiary: outboxLeaf.beneficiary,
+                projectTokenCount: outboxLeaf.projectTokenCount,
+                terminalTokenAmount: outboxLeaf.terminalTokenAmount,
+                metadata: outboxLeaf.metadata,
+            },
+            leafHash: outboxLeaf.hashed,
+            outboxRoot: outboxLeaf.root,
+            blockNumber: outboxLeaf.blockNumber,
+            status,
+            canExecute,
+            proof,
+        };
+    });
+}
+/** Build a claim object from a movement whose proof was verified by the SDK. */
+function claimFromSuckerMovement(movement) {
+    if (movement.status !== "claimable" || !movement.proof) {
+        throw new Error("Only a claimable sucker movement has a verified proof.");
+    }
+    return {
+        token: movement.remoteToken,
+        leaf: movement.leaf,
+        proof: movement.proof,
+    };
+}
+/** Common escalating native-value candidates for CCIP sucker simulations. */
+exports.CCIP_SUCKER_TRANSPORT_VALUES = [
+    1000000000000000n,
+    5000000000000000n,
+    20000000000000000n,
+    50000000000000000n,
+    200000000000000000n,
+    500000000000000000n,
+];
+/** Common escalating native-value candidates for native bridge simulations. */
+exports.NATIVE_SUCKER_TRANSPORT_VALUES = [
+    0n,
+    1000000000000000n,
+    10000000000000000n,
+    50000000000000000n,
+];
+/** Return the first value whose exact transaction simulation succeeds. */
+async function findSuckerTransportValue(values, simulate) {
+    for (const value of values) {
+        try {
+            await simulate(value);
+            return value;
+        }
+        catch {
+            // Try the next fee tier.
+        }
+    }
+    return null;
+}
+/** Refuse the CCIP zero-transport path, which would switch fees to LINK. */
+function assertSuckerTransportValue(transport, value, baseFee = 0n) {
+    if (transport === "unknown") {
+        throw new Error("The sucker transport could not be verified.");
+    }
+    if (transport === "ccip" && value - baseFee <= 0n) {
+        throw new Error("A CCIP sucker message requires a positive native transport budget.");
+    }
+}
+/**
+ * Positively identify a sucker's bridge family. RPC failures and unfamiliar
+ * implementations return `unknown`; callers must not assume they are native.
+ */
+async function classifySuckerTransport(client, sucker) {
+    try {
+        const router = await client.readContract({
+            address: sucker,
+            abi: exports.jbCcipSuckerV6Abi,
+            functionName: "CCIP_ROUTER",
+        });
+        if (router.toLowerCase() !== "0x0000000000000000000000000000000000000000") {
+            return "ccip";
+        }
+    }
+    catch {
+        // Probe the native bridge families below.
+    }
+    for (const functionName of ["OPMESSENGER", "ARBINBOX"]) {
+        try {
+            const bridge = await client.readContract({
+                address: sucker,
+                abi: exports.jbNativeSuckerV6ProbeAbi,
+                functionName,
+            });
+            if (bridge.toLowerCase() !== viem_1.zeroAddress)
+                return "native";
+        }
+        catch {
+            // Keep probing; an RPC error must not be treated as a positive match.
+        }
+    }
+    return "unknown";
+}
+/** Build a payable JBSucker.syncAccountingData transaction request. */
+function buildSyncAccountingDataTx(args) {
+    return {
+        chainId: args.chainId,
+        address: args.sucker,
+        abi: exports.jbSuckerV6Abi,
+        functionName: "syncAccountingData",
+        args: [],
+        value: args.value ?? 0n,
+    };
+}
+/** Relative absolute drift between two unsigned bigint values, from 0 to 1. */
+function relativeSuckerDrift(left, right) {
+    if (left < 0n || right < 0n) {
+        throw new Error("Sucker accounting values cannot be negative.");
+    }
+    const larger = left > right ? left : right;
+    if (larger === 0n)
+        return 0;
+    const difference = left > right ? left - right : right - left;
+    return Number((difference * 1000000n) / larger) / 1_000_000;
+}
+/** Unpack a sucker freshness key (`timestamp << 128 | sequence`). */
+function suckerTimestampSeconds(value) {
+    const timestamp = Number(value >> 128n);
+    if (!Number.isSafeInteger(timestamp) || timestamp < 0) {
+        throw new Error("The sucker timestamp is outside JavaScript's safe range.");
+    }
+    return timestamp;
+}
 /**
  * Builds a `prepare` transaction on a v6 sucker, locking project tokens into an outbox
  * leaf destined for the remote chain.
@@ -160,4 +768,35 @@ async function getV6SuckerPairs(client, { chainId, projectId }) {
         remoteChainId: pair.remoteChainId,
     }));
 }
+/**
+ * Read active and deprecated suckers for a project. Historical suckers remain
+ * relevant because their already-delivered leaves can still be claimed.
+ */
+async function getAllV6SuckerPairs(client, { chainId, projectId }) {
+    const suckers = await client.readContract({
+        address: (0, types_js_1.v6Address)("JBSuckerRegistry", chainId),
+        abi: juicebox_js_1.jbSuckerRegistryAbi,
+        functionName: "allSuckersOf",
+        args: [projectId],
+    });
+    return Promise.all(suckers.map(async (local) => {
+        const [remote, remoteChainId] = await Promise.all([
+            client.readContract({
+                address: local,
+                abi: exports.jbSuckerV6ViewAbi,
+                functionName: "peer",
+            }),
+            client.readContract({
+                address: local,
+                abi: exports.jbSuckerV6ViewAbi,
+                functionName: "peerChainId",
+            }),
+        ]);
+        return {
+            local,
+            remote: suckerBytes32ToAddress(remote),
+            remoteChainId,
+        };
+    }));
+}
 //# sourceMappingURL=suckers.js.map