@bananapus/nana-sdk-core 2.16.0 → 2.18.0

package/dist/esm/safeService.js

@@ -1,3 +1,6 @@
+import { getAddress, hashTypedData, isAddress, isAddressEqual, zeroAddress, } from "viem";
+import { encodeMultiSend, isRecognizedSafeDeployment, MULTI_SEND_CALL_ONLY, } from "./safe.js";
+import { isBytes32, isHexBytes, uint256 } from "./untrusted.js";
 /**
  * Safe's per-chain app URL prefix. Wider than {@link SAFE_SERVICE_PREFIX}:
  * Safe app links work on chains without a hosted transaction service.
@@ -85,6 +88,9 @@ export function isSafeWalletPeer(url) {
 function noHostedService(chainId) {
     return new Error(`Safe does not host a transaction service on chain ${chainId}, so this proposal cannot be tracked here. Execute it from the Safe app; the action takes effect once it is executed there.`);
 }
+/** A service answer the wait cannot get past: it ends the wait, unlike a network error. */
+class SafeExecutionRecordError extends Error {
+}
 /**
  * Resolve a Safe proposal identifier to its actual onchain execution hash.
  * A safeTxHash is not a transaction hash and must never be receipt-polled.
@@ -99,6 +105,9 @@ function noHostedService(chainId) {
  * the execution's own hash when the owner executes at once.
  */
 export async function waitForSafeExecutionHash(chainId, safeTxHash, options = {}) {
+    if (!isBytes32(safeTxHash)) {
+        throw new Error(`Invalid Safe proposal hash: ${String(safeTxHash)}.`);
+    }
     const base = safeServiceBase(chainId);
     const { client } = options;
     if (!base && !client)
@@ -127,24 +136,25 @@ export async function waitForSafeExecutionHash(chainId, safeTxHash, options = {}
                     consecutiveNotFound = 0;
                     const transaction = (await response.json());
                     if (transaction.isExecuted && transaction.isSuccessful === false) {
-                        throw new Error("Safe executed the proposal, but the onchain transaction failed.");
+                        throw new SafeExecutionRecordError("Safe executed the proposal, but the onchain transaction failed.");
                     }
                     if (transaction.isExecuted && transaction.transactionHash) {
+                        if (!isBytes32(transaction.transactionHash)) {
+                            throw new SafeExecutionRecordError(`Safe’s transaction service reported ${safeTxHash} executed in a malformed transaction hash: ${String(transaction.transactionHash)}. Check the proposal in the Safe app.`);
+                        }
                         return transaction.transactionHash;
                     }
                 }
                 else if (response.status === 404) {
                     consecutiveNotFound += 1;
                     if (consecutiveNotFound >= SAFE_EXECUTION_NOT_FOUND_LIMIT) {
-                        throw new Error("Safe’s transaction service has no record of this proposal. Tracking cannot continue here — check the proposal in the Safe app; if it exists there, it will still take effect once executed.");
+                        throw new SafeExecutionRecordError("Safe’s transaction service has no record of this proposal. Tracking cannot continue here — check the proposal in the Safe app; if it exists there, it will still take effect once executed.");
                     }
                 }
             }
             catch (error) {
-                if (error instanceof Error &&
-                    /executed the proposal.*failed|no record of this proposal/i.test(error.message)) {
+                if (error instanceof SafeExecutionRecordError)
                     throw error;
-                }
                 // Other service/network failures are transient. Keep the already-created
                 // proposal pending instead of inviting a duplicate submission.
             }
@@ -164,4 +174,807 @@ export async function waitForSafeExecutionHash(chainId, safeTxHash, options = {}
         });
     }
 }
+// ── Safe transactions ────────────────────────────────────────────────────────
+/** The EIP-712 types a Safe transaction is signed and hashed with. */
+export const SAFE_TX_TYPES = {
+    SafeTx: [
+        { name: "to", type: "address" },
+        { name: "value", type: "uint256" },
+        { name: "data", type: "bytes" },
+        { name: "operation", type: "uint8" },
+        { name: "safeTxGas", type: "uint256" },
+        { name: "baseGas", type: "uint256" },
+        { name: "gasPrice", type: "uint256" },
+        { name: "gasToken", type: "address" },
+        { name: "refundReceiver", type: "address" },
+        { name: "nonce", type: "uint256" },
+    ],
+};
+/** `execTransaction` and `approveHash`, and the execution events of Safe 1.4. */
+export const SAFE_EXEC_ABI = [
+    {
+        type: "function",
+        name: "execTransaction",
+        stateMutability: "payable",
+        inputs: [
+            { name: "to", type: "address" },
+            { name: "value", type: "uint256" },
+            { name: "data", type: "bytes" },
+            { name: "operation", type: "uint8" },
+            { name: "safeTxGas", type: "uint256" },
+            { name: "baseGas", type: "uint256" },
+            { name: "gasPrice", type: "uint256" },
+            { name: "gasToken", type: "address" },
+            { name: "refundReceiver", type: "address" },
+            { name: "signatures", type: "bytes" },
+        ],
+        outputs: [{ name: "success", type: "bool" }],
+    },
+    {
+        type: "function",
+        name: "approveHash",
+        stateMutability: "nonpayable",
+        inputs: [{ name: "hashToApprove", type: "bytes32" }],
+        outputs: [],
+    },
+    {
+        type: "event",
+        name: "ExecutionSuccess",
+        anonymous: false,
+        inputs: [
+            { name: "txHash", type: "bytes32", indexed: true },
+            { name: "payment", type: "uint256", indexed: false },
+        ],
+    },
+    {
+        type: "event",
+        name: "ExecutionFailure",
+        anonymous: false,
+        inputs: [
+            { name: "txHash", type: "bytes32", indexed: true },
+            { name: "payment", type: "uint256", indexed: false },
+        ],
+    },
+];
+function invalidField(name, value) {
+    return new Error(`The Safe transaction's ${name} is invalid: ${String(value)}.`);
+}
+function fieldAddress(name, value) {
+    if (typeof value !== "string" || !isAddress(value)) {
+        throw invalidField(name, value);
+    }
+    return getAddress(value);
+}
+function fieldUint(name, value) {
+    const parsed = uint256(value);
+    if (parsed === null)
+        throw invalidField(name, value);
+    return parsed;
+}
+/** A nonce as a number: apps order and compare them. */
+function nonceOf(value) {
+    const parsed = uint256(value);
+    if (parsed === null || parsed > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw invalidField("nonce", value);
+    }
+    return Number(parsed);
+}
+/**
+ * The exact EIP-712 message of `tx`. Every field is required and read
+ * strictly: addresses checksummed, amounts as uint256 in any form, operation 0
+ * (CALL) or 1 (DELEGATECALL), null data as empty, and a null gas token or
+ * refund receiver as the zero address. Throws naming the first field that is
+ * not.
+ */
+export function safeTransactionMessage(tx) {
+    if (!tx || typeof tx !== "object")
+        throw invalidField("record", tx);
+    const operation = fieldUint("operation", tx.operation);
+    if (operation > 1n)
+        throw invalidField("operation", tx.operation);
+    const data = tx.data ?? "0x";
+    if (!isHexBytes(data))
+        throw invalidField("data", tx.data);
+    return {
+        to: fieldAddress("to", tx.to),
+        value: fieldUint("value", tx.value),
+        data,
+        operation: operation === 1n ? 1 : 0,
+        safeTxGas: fieldUint("safeTxGas", tx.safeTxGas),
+        baseGas: fieldUint("baseGas", tx.baseGas),
+        gasPrice: fieldUint("gasPrice", tx.gasPrice),
+        // The service stores an omitted gas token or refund receiver as null and
+        // hashes it as the zero address, as Safe does; nothing else may be absent.
+        gasToken: tx.gasToken === null
+            ? zeroAddress
+            : fieldAddress("gasToken", tx.gasToken),
+        refundReceiver: tx.refundReceiver === null
+            ? zeroAddress
+            : fieldAddress("refundReceiver", tx.refundReceiver),
+        nonce: BigInt(nonceOf(tx.nonce)),
+    };
+}
+function requireChainId(chainId) {
+    if (!Number.isSafeInteger(chainId) || chainId <= 0) {
+        throw new Error(`Invalid chain ID: ${String(chainId)}.`);
+    }
+    return chainId;
+}
+function requireSafe(safe) {
+    if (typeof safe !== "string" || !isAddress(safe)) {
+        throw new Error(`Invalid Safe address: ${String(safe)}.`);
+    }
+    return getAddress(safe);
+}
+/** The EIP-712 hash `safe` signs and executes `tx` under on `chainId`. */
+export function safeTransactionHash(chainId, safe, tx) {
+    return hashTypedData({
+        domain: {
+            chainId: requireChainId(chainId),
+            verifyingContract: requireSafe(safe),
+        },
+        types: SAFE_TX_TYPES,
+        primaryType: "SafeTx",
+        message: safeTransactionMessage(tx),
+    });
+}
+/**
+ * The hash of `tx`'s exact fields, refusing a record that names another Safe,
+ * advertises a different `safeTxHash` or `contractTransactionHash`, or, given
+ * `expected`, no longer hashes to the reviewed hash.
+ */
+export function canonicalSafeTxHash(chainId, safe, tx, expected) {
+    const address = requireSafe(safe);
+    if (tx?.safe !== undefined &&
+        tx.safe !== null &&
+        (typeof tx.safe !== "string" ||
+            !isAddress(tx.safe) ||
+            !isAddressEqual(tx.safe, address))) {
+        throw new Error(`The Safe transaction belongs to ${String(tx.safe)}, not ${address}.`);
+    }
+    const computed = safeTransactionHash(chainId, address, tx);
+    for (const [name, advertised] of [
+        ["safeTxHash", tx.safeTxHash],
+        ["contractTransactionHash", tx.contractTransactionHash],
+    ]) {
+        if (advertised === undefined || advertised === null)
+            continue;
+        if (!isBytes32(advertised) ||
+            advertised.toLowerCase() !== computed.toLowerCase()) {
+            throw new Error(`The Safe transaction's ${name} ${String(advertised)} does not match its fields, which hash to ${computed}.`);
+        }
+    }
+    if (expected !== undefined && !isBytes32(expected)) {
+        throw new Error(`Invalid reviewed Safe transaction hash: ${String(expected)}.`);
+    }
+    if (expected !== undefined &&
+        expected.toLowerCase() !== computed.toLowerCase()) {
+        throw new Error(`The Safe transaction changed: it hashes to ${computed}, not the reviewed ${expected}.`);
+    }
+    return computed;
+}
+// ── Execution results ────────────────────────────────────────────────────────
+/** `ExecutionSuccess(bytes32,uint256)` and `ExecutionFailure(bytes32,uint256)`, the same in Safe 1.3 and 1.4. */
+const EXECUTION_SUCCESS_TOPIC = "0x442e715f626346e8c54381002da614f62bee8d27386535b2521ec8540898556e";
+const EXECUTION_FAILURE_TOPIC = "0x23428b18acfb3ea64b08dc0c1d296ea9c09702c09083ca5272e64d115b687d23";
+const ZERO_WORD = "0000000000000000000000000000000000000000000000000000000000000000";
+/**
+ * A Safe execution event in exactly the Safe 1.4 layout (txHash indexed) or
+ * the Safe 1.3 layout (txHash the first data word), with its payment. Null for
+ * another event; a string naming what is wrong for a malformed one.
+ */
+function safeExecutionEvent(log) {
+    const topics = Array.isArray(log.topics) ? log.topics : [];
+    const topic = typeof topics[0] === "string" ? topics[0].toLowerCase() : "";
+    if (topic !== EXECUTION_SUCCESS_TOPIC && topic !== EXECUTION_FAILURE_TOPIC) {
+        return null;
+    }
+    const failed = topic === EXECUTION_FAILURE_TOPIC;
+    const name = failed ? "ExecutionFailure" : "ExecutionSuccess";
+    const data = typeof log.data === "string" ? log.data.toLowerCase() : "";
+    if (topics.length === 2) {
+        if (!isBytes32(topics[1]) || !/^0x[\da-f]{64}$/.test(data)) {
+            return `a malformed ${name} event`;
+        }
+        return {
+            failed,
+            txHash: topics[1].toLowerCase(),
+            payment: BigInt(data),
+        };
+    }
+    if (topics.length === 1) {
+        if (!/^0x[\da-f]{128}$/.test(data))
+            return `a malformed ${name} event`;
+        return {
+            failed,
+            txHash: data.slice(0, 66),
+            payment: BigInt(`0x${data.slice(66)}`),
+        };
+    }
+    return `a malformed ${name} event`;
+}
+/**
+ * What `receipt` proves about the Safe transaction `hash` on `safe`. `hash` is
+ * what the wallet returned: the safeTxHash, or, when Safe{Wallet} executed the
+ * proposal at once, the execution's own transaction hash. Then the receipt
+ * must carry exactly one execution event of `safe`, whatever its hash.
+ * Otherwise exactly one event for `hash`, so another proposal in the same
+ * batch cannot stand in for this one, and another proposal's event, refund
+ * included, never decides this one. Any malformed execution event of `safe`
+ * leaves the result unproven, since it cannot be told apart from this one.
+ *
+ * `receipt` is viem's parsed receipt: a raw RPC receipt (status "0x1") reads
+ * unproven.
+ *
+ * The at-once reading proves only that the Safe ran one transaction in that
+ * receipt. A caller who holds the executing transaction's input should also
+ * bind it to the reviewed call, as an `execTransaction` with exactly the
+ * reviewed fields.
+ */
+export function safeExecutionResult(receipt, safe, hash) {
+    const address = requireSafe(safe).toLowerCase();
+    if (!isBytes32(hash)) {
+        throw new Error(`Invalid Safe transaction hash: ${String(hash)}.`);
+    }
+    if (receipt?.status === "reverted")
+        return { status: "reverted" };
+    const unproven = (reason) => ({
+        status: "unproven",
+        reason,
+    });
+    if (receipt?.status !== "success" || !Array.isArray(receipt.logs)) {
+        return unproven(`The receipt has no success status and logs to prove ${hash} on Safe ${safe}.`);
+    }
+    const atOnce = typeof receipt.transactionHash === "string" &&
+        receipt.transactionHash.toLowerCase() === hash.toLowerCase();
+    const events = [];
+    for (const log of receipt.logs) {
+        if (typeof log?.address !== "string" ||
+            log.address.toLowerCase() !== address) {
+            continue;
+        }
+        const event = safeExecutionEvent(log);
+        if (typeof event === "string") {
+            return unproven(`Safe ${safe} logged ${event}.`);
+        }
+        if (event && (atOnce || event.txHash === hash.toLowerCase())) {
+            events.push(event);
+        }
+    }
+    const subject = atOnce ? `transaction ${hash}` : `Safe transaction ${hash}`;
+    if (events.length === 0) {
+        return unproven(`The receipt has no ExecutionSuccess or ExecutionFailure from Safe ${safe} for ${subject}.`);
+    }
+    if (events.length > 1) {
+        return unproven(`Safe ${safe} logged ${events.length} execution results (${events.map((event) => (event.failed ? "ExecutionFailure" : "ExecutionSuccess")).join(", ")}) for ${subject}, so the receipt proves none of them.`);
+    }
+    const [event] = events;
+    return {
+        status: event.failed ? "failed" : "success",
+        payment: event.payment,
+    };
+}
+/** Throws unless `receipt` proves the Safe transaction `hash` ran and succeeded ({@link safeExecutionResult}). */
+export function requireSafeExecutionSuccess(receipt, safe, hash) {
+    const result = safeExecutionResult(receipt, safe, hash);
+    if (result.status === "success")
+        return;
+    if (result.status === "reverted") {
+        throw new Error(`The transaction executing ${hash} on Safe ${safe} reverted, so the Safe ran nothing.`);
+    }
+    if (result.status === "failed") {
+        throw new Error(`Safe ${safe} ran ${hash}, but its call failed (ExecutionFailure).`);
+    }
+    throw new Error(result.reason);
+}
+// ── Signatures ───────────────────────────────────────────────────────────────
+/**
+ * One confirmation's part of Safe's `signatures` bytes, without 0x:
+ *
+ * - none at all: the `approveHash` form (v = 1) naming the owner, a head;
+ * - an ECDSA, eth_sign or approved-hash signature: exactly 65 bytes, a head;
+ *   an approved hash (v = 1) must name its own owner;
+ * - an EIP-1271 contract signature in the transaction service's standalone
+ *   form: r = owner, s = 65, v = 0, then a length word and the signature,
+ *   optionally zero-padded to a word. Its dynamic part becomes a tail that
+ *   {@link safeExecutionSignatures} places after every head.
+ *
+ * Null for anything else, which never counts as a confirmation.
+ */
+function signaturePart(owner, signature) {
+    const word = owner.slice(2).toLowerCase().padStart(64, "0");
+    if (signature === undefined || signature === null || signature === "") {
+        return { head: `${word}${ZERO_WORD}01` };
+    }
+    if (!isHexBytes(signature) || signature.length < 132)
+        return null;
+    const bytes = signature.slice(2).toLowerCase();
+    const v = bytes.slice(128, 130);
+    if (v !== "00") {
+        if (bytes.length !== 130 || (v === "01" && bytes.slice(0, 64) !== word)) {
+            return null;
+        }
+        return { head: bytes };
+    }
+    if (bytes.length < 194 ||
+        bytes.slice(0, 64) !== word ||
+        BigInt(`0x${bytes.slice(64, 128)}`) !== 65n) {
+        return null;
+    }
+    const end = 194n + 2n * BigInt(`0x${bytes.slice(130, 194)}`);
+    if (end > BigInt(bytes.length) ||
+        BigInt(bytes.length) - end >= 64n ||
+        /[^0]/.test(bytes.slice(Number(end)))) {
+        return null;
+    }
+    return { contract: bytes.slice(194, Number(end)) };
+}
+function requireOwners(owners) {
+    if (!Array.isArray(owners)) {
+        throw new Error(`Invalid Safe owners: ${String(owners)}.`);
+    }
+    return new Set(owners.map((owner) => {
+        if (typeof owner !== "string" || !isAddress(owner)) {
+            throw new Error(`Invalid Safe owner: ${String(owner)}.`);
+        }
+        return owner.toLowerCase();
+    }));
+}
+/**
+ * The confirmations of `tx` that count: one per current owner in `owners`,
+ * with a well-formed signature or none (an onchain approval), a signature
+ * preferred, in ascending numeric owner order as Safe requires (a string sort
+ * disagrees and reverts with GS026). Owners are checksummed.
+ */
+export function usableSafeConfirmations(tx, owners) {
+    const allowed = requireOwners(owners);
+    const byOwner = new Map();
+    for (const confirmation of Array.isArray(tx?.confirmations)
+        ? tx.confirmations
+        : []) {
+        const owner = confirmation?.owner;
+        if (typeof owner !== "string" ||
+            !isAddress(owner) ||
+            !allowed.has(owner.toLowerCase()) ||
+            signaturePart(owner, confirmation.signature) === null) {
+            continue;
+        }
+        const key = owner.toLowerCase();
+        const existing = byOwner.get(key);
+        if (!existing || (!existing.signature && confirmation.signature)) {
+            byOwner.set(key, {
+                owner: getAddress(owner),
+                signature: confirmation.signature ?? null,
+            });
+        }
+    }
+    // Owners are unique here, so no two compare equal.
+    return [...byOwner.values()].sort((left, right) => BigInt(left.owner) < BigInt(right.owner) ? -1 : 1);
+}
+/**
+ * The `signatures` bytes for `execTransaction`, as Safe's checkNSignatures
+ * reads them: one 65-byte head per {@link usableSafeConfirmations} entry, in
+ * owner order, then each contract signature's length and bytes. A contract
+ * signature's head points at its tail by byte offset, which is never below
+ * the heads' total length, so it passes Safe's GS021 check.
+ */
+export function safeExecutionSignatures(tx, owners) {
+    const parts = usableSafeConfirmations(tx, owners).map(({ owner, signature }) => ({
+        owner,
+        part: signaturePart(owner, signature),
+    }));
+    let head = "";
+    let tail = "";
+    for (const { owner, part } of parts) {
+        if ("head" in part) {
+            head += part.head;
+            continue;
+        }
+        const offset = parts.length * 65 + tail.length / 2;
+        head += `${owner.slice(2).toLowerCase().padStart(64, "0")}${offset.toString(16).padStart(64, "0")}00`;
+        tail += `${(part.contract.length / 2).toString(16).padStart(64, "0")}${part.contract}`;
+    }
+    return `0x${head}${tail}`;
+}
+/** `execTransaction`'s arguments for `tx`, signed by its usable confirmations from `owners`. */
+export function safeExecutionArgs(tx, owners) {
+    const message = safeTransactionMessage(tx);
+    return [
+        message.to,
+        message.value,
+        message.data,
+        message.operation,
+        message.safeTxGas,
+        message.baseGas,
+        message.gasPrice,
+        message.gasToken,
+        message.refundReceiver,
+        safeExecutionSignatures(tx, owners),
+    ];
+}
+/**
+ * Whether executing `tx` pays its executor a refund out of the Safe: Safe pays
+ * one only when gasPrice is above zero (in the gas token, or ETH, to the refund
+ * receiver or the executor). This SDK never proposes one. A queue card shows
+ * or refuses such a transaction before executing it. Throws on a malformed
+ * record, as {@link safeTransactionMessage} does.
+ */
+export function safeTransactionHasRefund(tx) {
+    return safeTransactionMessage(tx).gasPrice > 0n;
+}
+// ── Proposals ────────────────────────────────────────────────────────────────
+/** The zero-refund Safe transaction this SDK proposes: one CALL, no gas fields. */
+export function safeProposalFor(call, nonce) {
+    const tx = {
+        to: fieldAddress("to", call?.to),
+        value: fieldUint("value", call?.value ?? 0n).toString(),
+        data: call?.data,
+        operation: 0,
+        safeTxGas: "0",
+        baseGas: "0",
+        gasPrice: "0",
+        gasToken: zeroAddress,
+        refundReceiver: zeroAddress,
+        nonce: nonceOf(nonce),
+        confirmations: [],
+    };
+    safeTransactionMessage(tx);
+    return tx;
+}
+/**
+ * One Safe transaction for a batch: a DELEGATECALL into MultiSendCallOnly,
+ * which runs each call from the Safe, in order, or reverts them all.
+ */
+export function safeBatchProposalFor(calls, nonce) {
+    return {
+        ...safeProposalFor({ to: MULTI_SEND_CALL_ONLY, data: encodeMultiSend(calls) }, nonce),
+        operation: 1,
+    };
+}
+/**
+ * Whether `tx` is exactly `call` as a zero-refund proposal: the same target,
+ * value, data and operation, and no safeTxGas, baseGas, gasPrice, gas token or
+ * refund receiver. A malformed `tx` never matches.
+ */
+export function safeTransactionMatchesCall(tx, call) {
+    let message;
+    try {
+        message = safeTransactionMessage(tx);
+    }
+    catch {
+        return false;
+    }
+    return (typeof call?.to === "string" &&
+        isAddress(call.to) &&
+        isAddressEqual(message.to, call.to) &&
+        message.value === (call.value ?? 0n) &&
+        message.data.toLowerCase() === String(call.data).toLowerCase() &&
+        message.operation === (call.operation ?? 0) &&
+        message.safeTxGas === 0n &&
+        message.baseGas === 0n &&
+        message.gasPrice === 0n &&
+        isAddressEqual(message.gasToken, zeroAddress) &&
+        isAddressEqual(message.refundReceiver, zeroAddress));
+}
+/**
+ * The nonce a new proposal takes: after everything already queued, never below
+ * the Safe's own. Reusing a queued nonce would offer a replacement instead.
+ */
+export function nextProposalNonce(currentNonce, pending) {
+    return pending.reduce((next, tx) => Math.max(next, nonceOf(tx?.nonce) + 1), nonceOf(currentNonce));
+}
+/**
+ * The next onchain step for `account` on a chain with no Safe service. Safe
+ * counts the executing owner as a signature, so the owner who would complete
+ * the threshold executes instead of approving first.
+ */
+export function onchainApprovalStep({ account, approved, threshold, }) {
+    const others = approved.filter((owner) => !isAddressEqual(owner, account));
+    if (others.length + 1 >= threshold) {
+        return { kind: "execute", signers: [...others, account] };
+    }
+    return others.length === approved.length
+        ? { kind: "approve" }
+        : { kind: "waiting" };
+}
+const PENDING_PAGE_SIZE = 50;
+const MAX_PENDING = 250;
+const SERVICE_DETAIL_CHARACTERS = 200;
+/** Whether Safe hosts a transaction service for `chainId`; without one, owners approve onchain. */
+export function hasSafeService(chainId) {
+    return safeServiceBase(chainId) !== null;
+}
+/** The Safe app's page for one queued transaction. */
+export function safeTransactionUrl(chainId, safe, safeTxHash) {
+    const prefix = SAFE_PREFIX[chainId];
+    if (!prefix || typeof safe !== "string" || !isAddress(safe))
+        return null;
+    if (!isBytes32(safeTxHash))
+        return null;
+    const address = getAddress(safe);
+    return `https://app.safe.global/transactions/tx?safe=${prefix}:${address}&id=multisig_${address}_${safeTxHash}`;
+}
+function serviceOrThrow(chainId) {
+    const base = safeServiceBase(chainId);
+    if (!base) {
+        throw new Error(`Safe does not host a transaction service on chain ${chainId}.`);
+    }
+    return base;
+}
+/** The optional `jb-safe-api-key` from local storage, as a bearer token. */
+function serviceHeaders(json = false) {
+    const headers = { accept: "application/json" };
+    if (json)
+        headers["content-type"] = "application/json";
+    try {
+        const key = globalThis.localStorage?.getItem("jb-safe-api-key");
+        if (key)
+            headers.authorization = `Bearer ${key}`;
+    }
+    catch {
+        // The key is optional.
+    }
+    return headers;
+}
+/** One service request. A 429 is refused before processing, so it waits and repeats, up to three times. */
+async function serviceFetch(url, init, options) {
+    const request = options.fetch ?? fetch;
+    for (let attempt = 0;; attempt += 1) {
+        const response = await request(url, init);
+        if (response.status !== 429 || attempt >= 3)
+            return response;
+        const retryAfter = Number(response.headers.get("retry-after"));
+        await new Promise((resolve) => setTimeout(resolve, Number.isFinite(retryAfter) && retryAfter > 0
+            ? retryAfter * 1000
+            : 1000 * (attempt + 1)));
+    }
+}
+async function serviceDetail(response) {
+    const text = await response.text().catch(() => "");
+    return text ? `: ${text.slice(0, SERVICE_DETAIL_CHARACTERS)}` : "";
+}
+/** The most confirmations a service row may carry; each must be an owner's. */
+const MAX_ROW_CONFIRMATIONS = 100;
+/**
+ * Every field of a service row read strictly, its advertised hash required and
+ * checked, its confirmations bounded: the row with its nonce as a number and
+ * its own Safe and hash, or a refusal naming what is wrong.
+ */
+function checkedRow(chainId, safe, row) {
+    try {
+        const tx = row;
+        if ((tx?.safeTxHash === undefined || tx.safeTxHash === null) &&
+            (tx?.contractTransactionHash === undefined ||
+                tx.contractTransactionHash === null)) {
+            throw new Error("It advertises no safeTxHash.");
+        }
+        if (tx.confirmations !== undefined &&
+            tx.confirmations !== null &&
+            (!Array.isArray(tx.confirmations) ||
+                tx.confirmations.length > MAX_ROW_CONFIRMATIONS)) {
+            throw new Error(`Its confirmations are not a list of at most ${MAX_ROW_CONFIRMATIONS}.`);
+        }
+        const hash = canonicalSafeTxHash(chainId, safe, tx);
+        return { ...tx, safe, safeTxHash: hash, nonce: nonceOf(tx.nonce) };
+    }
+    catch (error) {
+        throw new Error(`Safe's transaction service listed a transaction for Safe ${safe} on chain ${chainId} that cannot be trusted. ${error.message}`);
+    }
+}
+/**
+ * Every queued, unexecuted transaction of `safe` from nonce `currentNonce`
+ * on, read from the chain's transaction service. Each row must belong to
+ * `safe` and hash to its advertised safeTxHash. Throws when the chain has no
+ * service or the service fails, so an outage never reads as an empty queue,
+ * and when more than 250 are queued.
+ */
+export async function listPendingSafeTransactions(chainId, safe, currentNonce, options = {}) {
+    const base = serviceOrThrow(chainId);
+    const address = requireSafe(safe);
+    const fromNonce = nonceOf(currentNonce);
+    const rows = [];
+    for (let offset = 0; offset < MAX_PENDING; offset += PENDING_PAGE_SIZE) {
+        const url = `${base}/api/v1/safes/${address}/multisig-transactions/` +
+            `?executed=false&trusted=true&ordering=nonce&limit=${PENDING_PAGE_SIZE}` +
+            `&offset=${offset}&nonce__gte=${fromNonce}`;
+        let response = await serviceFetch(url, { headers: serviceHeaders() }, options);
+        if (!response.ok) {
+            // A failed page is retried once before the listing gives up.
+            await new Promise((resolve) => setTimeout(resolve, 500));
+            response = await serviceFetch(url, { headers: serviceHeaders() }, options);
+        }
+        if (!response.ok) {
+            throw new Error(`Safe's transaction service answered ${response.status} listing the queue of Safe ${address} on chain ${chainId}${await serviceDetail(response)}`);
+        }
+        const body = (await response.json());
+        if (!body || !Array.isArray(body.results)) {
+            throw new Error(`Safe's transaction service returned no transaction list for Safe ${address} on chain ${chainId}.`);
+        }
+        if (body.results.length > PENDING_PAGE_SIZE) {
+            throw new Error(`Safe's transaction service returned ${body.results.length} transactions in a page of ${PENDING_PAGE_SIZE} for Safe ${address} on chain ${chainId}.`);
+        }
+        rows.push(...body.results.map((row) => checkedRow(chainId, address, row)));
+        if (body.results.length < PENDING_PAGE_SIZE || !body.next) {
+            return rows.filter((row) => row.isExecuted !== true && row.nonce >= fromNonce);
+        }
+    }
+    throw new Error(`Safe ${address} has more than ${MAX_PENDING} queued transactions on chain ${chainId}. Nothing was proposed; execute or replace older ones first.`);
+}
+/** The queued zero-refund proposal of exactly `call`, so a retry can confirm it instead of proposing it twice. */
+export async function findPendingSafeTransaction(chainId, safe, currentNonce, call, options = {}) {
+    const pending = await listPendingSafeTransactions(chainId, safe, currentNonce, options);
+    return pending.find((tx) => safeTransactionMatchesCall(tx, call)) ?? null;
+}
+/**
+ * The service's record of the proposal `safeTxHash`, authenticated: it must
+ * belong to `safe` and its fields must hash to `safeTxHash`.
+ */
+export async function readSafeTransaction(chainId, safe, safeTxHash, options = {}) {
+    const base = serviceOrThrow(chainId);
+    const address = requireSafe(safe);
+    if (!isBytes32(safeTxHash)) {
+        throw new Error(`Invalid Safe transaction hash: ${String(safeTxHash)}.`);
+    }
+    const response = await serviceFetch(`${base}/api/v1/multisig-transactions/${safeTxHash}/`, { headers: serviceHeaders() }, options);
+    if (!response.ok) {
+        throw new Error(`Safe's transaction service answered ${response.status} for proposal ${safeTxHash} on chain ${chainId}. Try again when it is available.`);
+    }
+    const record = (await response.json());
+    try {
+        if (record?.safe === undefined || record.safe === null) {
+            throw new Error("The record names no Safe.");
+        }
+        canonicalSafeTxHash(chainId, address, record, safeTxHash);
+    }
+    catch (error) {
+        throw new Error(`Safe's record of proposal ${safeTxHash} does not match Safe ${address} on chain ${chainId}. ${error.message}`);
+    }
+    return record;
+}
+async function postToService(url, body, what, options) {
+    const response = await serviceFetch(url, {
+        method: "POST",
+        headers: serviceHeaders(true),
+        body: JSON.stringify(body),
+    }, options);
+    if (!response.ok && response.status !== 201) {
+        throw new Error(`Safe's transaction service refused ${what} (${response.status})${await serviceDetail(response)}`);
+    }
+}
+function requireSignature(signature) {
+    if (!isHexBytes(signature) || signature.length < 132) {
+        throw new Error(`Invalid Safe signature: ${String(signature)}.`);
+    }
+    return signature;
+}
+/**
+ * Queue `tx`, signed by `sender`, with the transaction service so the Safe's
+ * other owners can confirm and execute it. The body is built from the exact
+ * fields, checksummed as the service requires, and the hash is recomputed,
+ * never taken from the record. Returns the safeTxHash.
+ */
+export async function proposeSafeTransaction(chainId, safe, tx, { sender, signature, origin, }, options = {}) {
+    const base = serviceOrThrow(chainId);
+    const address = requireSafe(safe);
+    const safeTxHash = canonicalSafeTxHash(chainId, address, tx);
+    const message = safeTransactionMessage(tx);
+    if (typeof origin !== "string" || !origin.trim()) {
+        throw new Error("A Safe proposal needs an origin naming the app.");
+    }
+    await postToService(`${base}/api/v1/safes/${address}/multisig-transactions/`, {
+        to: message.to,
+        value: message.value.toString(),
+        data: message.data,
+        operation: message.operation,
+        safeTxGas: message.safeTxGas.toString(),
+        baseGas: message.baseGas.toString(),
+        gasPrice: message.gasPrice.toString(),
+        gasToken: message.gasToken,
+        refundReceiver: message.refundReceiver,
+        nonce: message.nonce.toString(),
+        contractTransactionHash: safeTxHash,
+        sender: fieldAddress("sender", sender),
+        signature: requireSignature(signature),
+        origin,
+    }, `the proposal ${safeTxHash} for Safe ${address} on chain ${chainId}`, options);
+    return safeTxHash;
+}
+/**
+ * Add an owner's signature to the queued `tx`. The confirmation is posted to
+ * the hash of `tx`'s exact fields, never to a hash the record advertises.
+ */
+export async function submitSafeConfirmation(chainId, safe, tx, signature, options = {}) {
+    const base = serviceOrThrow(chainId);
+    const safeTxHash = canonicalSafeTxHash(chainId, safe, tx);
+    await postToService(`${base}/api/v1/multisig-transactions/${safeTxHash}/confirmations/`, { signature: requireSignature(signature) }, `the confirmation of ${safeTxHash} on chain ${chainId}`, options);
+}
+/** The most Safes listed for one owner on one chain; the rest are not read. */
+const MAX_OWNED_SAFES = 200;
+/**
+ * Every Safe `owner` signs for on `chainIds`, from each chain's transaction
+ * service, at most 200 per chain. A chain without a service, a failed request
+ * or a malformed answer contributes nothing; listed Safes are checksummed and
+ * others dropped.
+ */
+export async function fetchSafesOwnedBy(owner, chainIds, options = {}) {
+    if (typeof owner !== "string" || !isAddress(owner))
+        return [];
+    const account = getAddress(owner);
+    const perChain = await Promise.all(chainIds.map(async (chainId) => {
+        const base = safeServiceBase(chainId);
+        if (!base)
+            return [];
+        try {
+            const response = await serviceFetch(`${base}/api/v1/owners/${account}/safes/`, { headers: serviceHeaders() }, options);
+            if (!response.ok)
+                return [];
+            const body = (await response.json());
+            return Array.isArray(body?.safes)
+                ? body.safes
+                    .slice(0, MAX_OWNED_SAFES)
+                    .flatMap((safe) => typeof safe === "string" && isAddress(safe)
+                    ? [{ chainId, safe: getAddress(safe) }]
+                    : [])
+                : [];
+        }
+        catch {
+            return [];
+        }
+    }));
+    return perChain.flat();
+}
+/** The source chain's service URL for a Safe's creation record, or null. */
+export function safeCreationUrl(chainId, safe) {
+    const base = safeServiceBase(chainId);
+    if (!base || typeof safe !== "string" || !isAddress(safe))
+        return null;
+    return `${base}/api/v1/safes/${getAddress(safe)}/creation/`;
+}
+/**
+ * A service creation record read strictly: the factory and singleton as
+ * addresses of one recognized Safe release, whole-hex setup data with at
+ * least a selector, and a decimal uint256 salt. Null for anything else.
+ */
+export function parseSafeCreationPayload(payload) {
+    if (!payload || typeof payload !== "object")
+        return null;
+    const record = payload;
+    const { factoryAddress, masterCopy, setupData, saltNonce } = record;
+    if (typeof factoryAddress !== "string" ||
+        typeof masterCopy !== "string" ||
+        !isAddress(factoryAddress) ||
+        !isAddress(masterCopy) ||
+        !isHexBytes(setupData) ||
+        setupData.length < 10 ||
+        typeof saltNonce !== "string" ||
+        !/^\d+$/.test(saltNonce) ||
+        uint256(saltNonce) === null ||
+        !isRecognizedSafeDeployment(factoryAddress, masterCopy)) {
+        return null;
+    }
+    return {
+        factory: getAddress(factoryAddress),
+        singleton: getAddress(masterCopy),
+        initializer: setupData,
+        saltNonce: BigInt(saltNonce),
+    };
+}
+/**
+ * The Safe's creation record from its source chain's service only: a record
+ * for the same address from another chain could replay unrelated setup data.
+ * Null when the chain has no service, the request fails, or the record is
+ * not {@link parseSafeCreationPayload strictly valid}.
+ */
+export async function fetchSafeCreation(safe, sourceChainId, options = {}) {
+    const url = safeCreationUrl(sourceChainId, safe);
+    if (!url)
+        return null;
+    try {
+        const response = await serviceFetch(url, { headers: serviceHeaders() }, options);
+        return response.ok ? parseSafeCreationPayload(await response.json()) : null;
+    }
+    catch {
+        return null;
+    }
+}
 //# sourceMappingURL=safeService.js.map