@temporalabs/treasury 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,429 @@
+import { type HttpTransport, type PublicClient } from "viem";
+export declare const chains: {
+    readonly 8453: {
+        blockExplorers: {
+            readonly default: {
+                readonly name: "Basescan";
+                readonly url: "https://basescan.org";
+                readonly apiUrl: "https://api.basescan.org/api";
+            };
+        };
+        blockTime: 2000;
+        contracts: {
+            readonly disputeGameFactory: {
+                readonly 1: {
+                    readonly address: "0x43edB88C4B80fDD2AdFF2412A7BebF9dF42cB40e";
+                };
+            };
+            readonly l2OutputOracle: {
+                readonly 1: {
+                    readonly address: "0x56315b90c40730925ec5485cf004d835058518A0";
+                };
+            };
+            readonly multicall3: {
+                readonly address: "0xca11bde05977b3631167028862be2a173976ca11";
+                readonly blockCreated: 5022;
+            };
+            readonly portal: {
+                readonly 1: {
+                    readonly address: "0x49048044D57e1C92A77f79988d21Fa8fAF74E97e";
+                    readonly blockCreated: 17482143;
+                };
+            };
+            readonly l1StandardBridge: {
+                readonly 1: {
+                    readonly address: "0x3154Cf16ccdb4C6d922629664174b904d80F2C35";
+                    readonly blockCreated: 17482143;
+                };
+            };
+            readonly gasPriceOracle: {
+                readonly address: "0x420000000000000000000000000000000000000F";
+            };
+            readonly l1Block: {
+                readonly address: "0x4200000000000000000000000000000000000015";
+            };
+            readonly l2CrossDomainMessenger: {
+                readonly address: "0x4200000000000000000000000000000000000007";
+            };
+            readonly l2Erc721Bridge: {
+                readonly address: "0x4200000000000000000000000000000000000014";
+            };
+            readonly l2StandardBridge: {
+                readonly address: "0x4200000000000000000000000000000000000010";
+            };
+            readonly l2ToL1MessagePasser: {
+                readonly address: "0x4200000000000000000000000000000000000016";
+            };
+        };
+        ensTlds?: readonly string[] | undefined;
+        id: 8453;
+        name: "Base";
+        nativeCurrency: {
+            readonly name: "Ether";
+            readonly symbol: "ETH";
+            readonly decimals: 18;
+        };
+        experimental_preconfirmationTime?: number | undefined | undefined;
+        rpcUrls: {
+            readonly default: {
+                readonly http: readonly ["https://mainnet.base.org"];
+            };
+        };
+        sourceId: 1;
+        supportsTransactionReplacementDetection?: boolean | undefined | undefined;
+        testnet?: boolean | undefined | undefined;
+        custom?: Record<string, unknown> | undefined;
+        extendSchema?: Record<string, unknown> | undefined;
+        fees?: import("viem").ChainFees<undefined> | undefined;
+        formatters: {
+            readonly block: {
+                exclude: [] | undefined;
+                format: (args: import("viem/chains").OpStackRpcBlock, action?: string | undefined) => {
+                    baseFeePerGas: bigint | null;
+                    blobGasUsed: bigint;
+                    difficulty: bigint;
+                    excessBlobGas: bigint;
+                    extraData: import("viem").Hex;
+                    gasLimit: bigint;
+                    gasUsed: bigint;
+                    hash: `0x${string}` | null;
+                    logsBloom: `0x${string}` | null;
+                    miner: import("viem").Address;
+                    mixHash: import("viem").Hash;
+                    nonce: `0x${string}` | null;
+                    number: bigint | null;
+                    parentBeaconBlockRoot?: `0x${string}` | undefined;
+                    parentHash: import("viem").Hash;
+                    receiptsRoot: import("viem").Hex;
+                    sealFields: import("viem").Hex[];
+                    sha3Uncles: import("viem").Hash;
+                    size: bigint;
+                    stateRoot: import("viem").Hash;
+                    timestamp: bigint;
+                    totalDifficulty: bigint | null;
+                    transactions: `0x${string}`[] | import("viem/chains").OpStackTransaction<boolean>[];
+                    transactionsRoot: import("viem").Hash;
+                    uncles: import("viem").Hash[];
+                    withdrawals?: import("viem").Withdrawal[] | undefined | undefined;
+                    withdrawalsRoot?: `0x${string}` | undefined;
+                } & {};
+                type: "block";
+            };
+            readonly transaction: {
+                exclude: [] | undefined;
+                format: (args: import("viem/chains").OpStackRpcTransaction, action?: string | undefined) => ({
+                    blockHash: `0x${string}` | null;
+                    blockNumber: bigint | null;
+                    blockTimestamp?: bigint | undefined;
+                    from: import("viem").Address;
+                    gas: bigint;
+                    hash: import("viem").Hash;
+                    input: import("viem").Hex;
+                    nonce: number;
+                    r: import("viem").Hex;
+                    s: import("viem").Hex;
+                    to: import("viem").Address | null;
+                    transactionIndex: number | null;
+                    typeHex: import("viem").Hex | null;
+                    v: bigint;
+                    value: bigint;
+                    yParity: number;
+                    gasPrice?: undefined | undefined;
+                    maxFeePerBlobGas?: undefined | undefined;
+                    maxFeePerGas: bigint;
+                    maxPriorityFeePerGas: bigint;
+                    isSystemTx?: boolean;
+                    mint?: bigint | undefined | undefined;
+                    sourceHash: import("viem").Hex;
+                    type: "deposit";
+                } | {
+                    r: import("viem").Hex;
+                    s: import("viem").Hex;
+                    v: bigint;
+                    to: import("viem").Address | null;
+                    from: import("viem").Address;
+                    gas: bigint;
+                    nonce: number;
+                    value: bigint;
+                    blockHash: `0x${string}` | null;
+                    blockNumber: bigint | null;
+                    blockTimestamp?: bigint | undefined;
+                    hash: import("viem").Hash;
+                    input: import("viem").Hex;
+                    transactionIndex: number | null;
+                    typeHex: import("viem").Hex | null;
+                    accessList?: undefined | undefined;
+                    authorizationList?: undefined | undefined;
+                    blobVersionedHashes?: undefined | undefined;
+                    chainId?: number | undefined;
+                    yParity?: undefined | undefined;
+                    type: "legacy";
+                    gasPrice: bigint;
+                    maxFeePerBlobGas?: undefined | undefined;
+                    maxFeePerGas?: undefined | undefined;
+                    maxPriorityFeePerGas?: undefined | undefined;
+                    isSystemTx?: undefined | undefined;
+                    mint?: undefined | undefined;
+                    sourceHash?: undefined | undefined;
+                } | {
+                    blockHash: `0x${string}` | null;
+                    blockNumber: bigint | null;
+                    blockTimestamp?: bigint | undefined;
+                    from: import("viem").Address;
+                    gas: bigint;
+                    hash: import("viem").Hash;
+                    input: import("viem").Hex;
+                    nonce: number;
+                    r: import("viem").Hex;
+                    s: import("viem").Hex;
+                    to: import("viem").Address | null;
+                    transactionIndex: number | null;
+                    typeHex: import("viem").Hex | null;
+                    v: bigint;
+                    value: bigint;
+                    yParity: number;
+                    accessList: import("viem").AccessList;
+                    authorizationList?: undefined | undefined;
+                    blobVersionedHashes?: undefined | undefined;
+                    chainId: number;
+                    type: "eip2930";
+                    gasPrice: bigint;
+                    maxFeePerBlobGas?: undefined | undefined;
+                    maxFeePerGas?: undefined | undefined;
+                    maxPriorityFeePerGas?: undefined | undefined;
+                    isSystemTx?: undefined | undefined;
+                    mint?: undefined | undefined;
+                    sourceHash?: undefined | undefined;
+                } | {
+                    blockHash: `0x${string}` | null;
+                    blockNumber: bigint | null;
+                    blockTimestamp?: bigint | undefined;
+                    from: import("viem").Address;
+                    gas: bigint;
+                    hash: import("viem").Hash;
+                    input: import("viem").Hex;
+                    nonce: number;
+                    r: import("viem").Hex;
+                    s: import("viem").Hex;
+                    to: import("viem").Address | null;
+                    transactionIndex: number | null;
+                    typeHex: import("viem").Hex | null;
+                    v: bigint;
+                    value: bigint;
+                    yParity: number;
+                    accessList: import("viem").AccessList;
+                    authorizationList?: undefined | undefined;
+                    blobVersionedHashes?: undefined | undefined;
+                    chainId: number;
+                    type: "eip1559";
+                    gasPrice?: undefined | undefined;
+                    maxFeePerBlobGas?: undefined | undefined;
+                    maxFeePerGas: bigint;
+                    maxPriorityFeePerGas: bigint;
+                    isSystemTx?: undefined | undefined;
+                    mint?: undefined | undefined;
+                    sourceHash?: undefined | undefined;
+                } | {
+                    blockHash: `0x${string}` | null;
+                    blockNumber: bigint | null;
+                    blockTimestamp?: bigint | undefined;
+                    from: import("viem").Address;
+                    gas: bigint;
+                    hash: import("viem").Hash;
+                    input: import("viem").Hex;
+                    nonce: number;
+                    r: import("viem").Hex;
+                    s: import("viem").Hex;
+                    to: import("viem").Address | null;
+                    transactionIndex: number | null;
+                    typeHex: import("viem").Hex | null;
+                    v: bigint;
+                    value: bigint;
+                    yParity: number;
+                    accessList: import("viem").AccessList;
+                    authorizationList?: undefined | undefined;
+                    blobVersionedHashes: readonly import("viem").Hex[];
+                    chainId: number;
+                    type: "eip4844";
+                    gasPrice?: undefined | undefined;
+                    maxFeePerBlobGas: bigint;
+                    maxFeePerGas: bigint;
+                    maxPriorityFeePerGas: bigint;
+                    isSystemTx?: undefined | undefined;
+                    mint?: undefined | undefined;
+                    sourceHash?: undefined | undefined;
+                } | {
+                    blockHash: `0x${string}` | null;
+                    blockNumber: bigint | null;
+                    blockTimestamp?: bigint | undefined;
+                    from: import("viem").Address;
+                    gas: bigint;
+                    hash: import("viem").Hash;
+                    input: import("viem").Hex;
+                    nonce: number;
+                    r: import("viem").Hex;
+                    s: import("viem").Hex;
+                    to: import("viem").Address | null;
+                    transactionIndex: number | null;
+                    typeHex: import("viem").Hex | null;
+                    v: bigint;
+                    value: bigint;
+                    yParity: number;
+                    accessList: import("viem").AccessList;
+                    authorizationList: import("viem").SignedAuthorizationList;
+                    blobVersionedHashes?: undefined | undefined;
+                    chainId: number;
+                    type: "eip7702";
+                    gasPrice?: undefined | undefined;
+                    maxFeePerBlobGas?: undefined | undefined;
+                    maxFeePerGas: bigint;
+                    maxPriorityFeePerGas: bigint;
+                    isSystemTx?: undefined | undefined;
+                    mint?: undefined | undefined;
+                    sourceHash?: undefined | undefined;
+                }) & {};
+                type: "transaction";
+            };
+            readonly transactionReceipt: {
+                exclude: [] | undefined;
+                format: (args: import("viem/chains").OpStackRpcTransactionReceipt, action?: string | undefined) => {
+                    blobGasPrice?: bigint | undefined;
+                    blobGasUsed?: bigint | undefined;
+                    blockHash: import("viem").Hash;
+                    blockNumber: bigint;
+                    blockTimestamp?: bigint | undefined;
+                    contractAddress: import("viem").Address | null | undefined;
+                    cumulativeGasUsed: bigint;
+                    effectiveGasPrice: bigint;
+                    from: import("viem").Address;
+                    gasUsed: bigint;
+                    logs: import("viem").Log<bigint, number, false>[];
+                    logsBloom: import("viem").Hex;
+                    root?: `0x${string}` | undefined;
+                    status: "success" | "reverted";
+                    to: import("viem").Address | null;
+                    transactionHash: import("viem").Hash;
+                    transactionIndex: number;
+                    type: import("viem").TransactionType;
+                    depositNonce?: bigint | undefined | undefined;
+                    depositReceiptVersion?: number | undefined | undefined;
+                    l1GasPrice: bigint | null;
+                    l1GasUsed: bigint | null;
+                    l1Fee: bigint | null;
+                    l1FeeScalar: number | null;
+                } & {};
+                type: "transactionReceipt";
+            };
+        };
+        prepareTransactionRequest?: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+            client: import("viem").Client;
+            phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+        }) => Promise<import("viem").PrepareTransactionRequestParameters>) | [fn: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+            client: import("viem").Client;
+            phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+        }) => Promise<import("viem").PrepareTransactionRequestParameters>) | undefined, options: {
+            runAt: readonly ("beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters")[];
+        }] | undefined;
+        serializers: {
+            readonly transaction: typeof import("viem/chains").serializeTransactionOpStack;
+        };
+        verifyHash?: ((client: import("viem").Client, parameters: import("viem").VerifyHashActionParameters) => Promise<import("viem").VerifyHashActionReturnType>) | undefined;
+    };
+};
+export type SupportedChainId = keyof typeof chains;
+export declare function isSupportedChainId(id: number): id is SupportedChainId;
+/**
+ * Read-only client. This module constructs exactly one kind of thing — a public (unsigned)
+ * client from an RPC URL. It never constructs a wallet client: the signer is the consumer's,
+ * handed in from outside if at all (see `build.ts`, which emits unsigned calls only).
+ */
+export type ReadClient = PublicClient<HttpTransport, (typeof chains)[SupportedChainId]>;
+/** The public endpoint used when nothing is configured, and the fallback for event scans. */
+export declare const PUBLIC_RPC: Record<SupportedChainId, string>;
+/**
+ * A `fetch` that waits out HTTP 429 instead of failing the tool. Measured 2026-09-14: a free-tier
+ * keyed Base RPC answered an `earn_quote` read with 429 and the tool failed outright, because viem's
+ * own retries (3, from 150 ms) are spent in under a second. Only a 429 is retried here, up to 5 times,
+ * honouring `Retry-After` when present and otherwise backing off from 500 ms, with the sleeps capped at
+ * `RATE_LIMIT_WAIT_MS` in total whatever the headers say.
+ *
+ * The transport's deadline (`RPC_TIMEOUT_MS`, viem's own 10 s) wraps this whole loop and is enforced by
+ * ABORT: viem only reports its `TimeoutError` when the fetch throws an abort error, and resolves a value
+ * returned after the abort as-is. So the sleep races the abort signal, and on abort the LAST 429 is
+ * handed back — the caller then sees the provider's 429, never "The request took too long to respond".
+ * Measured 2026-09-17 before this: a keyed provider at its monthly cap answered 429 in 77 ms, the loop
+ * slept through the deadline, and a whole live tier read as "the RPC is slow" when the key was out of
+ * quota. The deadline itself is NOT raised: a host that accepts and never answers must still fail at
+ * 10 s (measured in review: 25.5 s made `earn_status` 2.5× slower on exactly that case).
+ *
+ * A 429 whose body carries the one measured exhausted-plan sentence is returned at once — it resets
+ * next period, not in seconds. ONLY that sentence: a bare /capacity/ also matched Alchemy's per-second
+ * throttle body ("exceeded its compute units per second capacity") and a "temporarily at capacity"
+ * message, and would have disabled the wait on the exact case it exists for (measured in review).
+ * An unrecognised body is waited out and then reported plainly — the safe direction.
+ * An unreachable host is deliberately NOT stretched out: that is a fault to report, not a limit to
+ * wait for, and `earn_status` must answer quickly when the RPC is down.
+ */
+export declare const RATE_LIMIT_WAIT_MS = 15500;
+/** The transport's whole-call deadline — viem's default, set explicitly because the wrapper's design depends on it. */
+export declare const RPC_TIMEOUT_MS = 10000;
+export declare function makeRateLimitedFetch(base?: typeof fetch, sleep?: (ms: number) => Promise<void>): typeof fetch;
+export declare function makePublicClient(chainId: SupportedChainId, rpcUrl: string): ReadClient;
+/**
+ * An env value counts as an RPC URL only if it parses as one with an http(s) scheme. Anything else —
+ * empty, whitespace, a non-URL, and in particular an UNEXPANDED placeholder like `${TREASURY_RPC_BASE}` —
+ * is treated as unset. Measured 2026-09-12: Claude Code forwards the plugin's `.mcp.json` value
+ * `${TREASURY_RPC_BASE}` verbatim when the host variable is unset, and with the old `if (v)` test every
+ * RPC-touching tool died on "Failed to parse URL from ${TREASURY_RPC_BASE}". `.mcp.json` now also uses
+ * `${VAR:-}`, but this guard is what makes the server independent of any host's expansion rules.
+ */
+export declare function rpcUrlFromEnvValue(v: string | undefined): string | undefined;
+/**
+ * Resolves the RPC URL for a chain from the environment. ⚠️ A keyed provider URL IS a secret: it must
+ * never appear in tool output — every error crossing the tool boundary goes through `describeError`
+ * (`src/redact.ts`), which strips endpoints. Fallback names after `TREASURY_RPC_BASE`:
+ * `BASE_RPC_URL`; the plugin's `.mcp.json` passes only the `TREASURY_*` pair through, so under the
+ * packaged path the fallback is unreachable.
+ * `TREASURY_LOGS_RPC_BASE`, if set, is preferred for log scans (providers cap eth_getLogs ranges very
+ * differently: Alchemy free 10 blocks, Base public 2,000) — see `position.ts`.
+ */
+export declare function rpcUrlFromEnv(chainId: SupportedChainId): string;
+/**
+ * The endpoint an event scan falls back to when the configured logs RPC cannot cover the range — and
+ * the operator's opt-out from it. `TREASURY_LOGS_FALLBACK` unset ⇒ Base's public endpoint; an http(s)
+ * URL ⇒ that endpoint; ANY other value — `off`, `none`, `disabled`, a typo — ⇒ no fallback at all, and
+ * the scan degrades to a cut-short window as it did before the fallback existed. It exists because the fallback
+ * otherwise sends a query to a third party the operator never named, which some
+ * deployments cannot accept — and it fails CLOSED for the same reason.
+ */
+export declare function logsFallbackUrlFromEnv(chainId: SupportedChainId, logsUrl: string): string | undefined;
+/** RPC to use for eth_getLogs scans: a dedicated one if configured, else the general one. */
+export declare function logsRpcUrlFromEnv(chainId: SupportedChainId): string;
+/**
+ * Which environment variable supplied the RPC URL — the NAME only, never the value. A keyed provider
+ * URL is a secret, so `earn_status` reports provenance and nothing else. `configured: false` means
+ * no variable resolved and the public endpoint is in use (rate-limited, never a failure).
+ */
+export declare function rpcSourceForEnv(chainId: SupportedChainId): {
+    source: string;
+    configured: boolean;
+};
+/**
+ * Every RPC secret VALUE this process could be holding — the resolved URLs plus the parts of them
+ * that carry the credential (path segments, query values, and a subdomain-keyed provider's first
+ * label). Fed to `registerSecretSource` so the redactor masks the literal wherever it appears,
+ * including inside a provider's own error body, where no shape rule can reach it.
+ *
+ * ⚠️ Returns VALUES, and is used only to mask them. It must never be logged or returned by a tool.
+ */
+export declare function resolvedRpcSecrets(): string[];
+/**
+ * The one sentence a caller needs when the public endpoint is what broke them.
+ *
+ * 🔴 Measured 2026-09-12 through the installed plugin with no configuration: the deposit pre-flight
+ * returns UNRESOLVED 3/3 on `mainnet.base.org` ("RPC Request failed") and NEEDS_APPROVAL 3/3 on a
+ * keyed URL. So zero-config can browse vaults and read terms but CANNOT complete a deposit — and the
+ * message it fails with reads as "this product is broken" rather than "you need a key". Returns
+ * undefined when a keyed RPC resolved, so a real chain fault is never mislabelled as a setup problem.
+ */
+export declare function publicRpcHint(chainId: SupportedChainId): string | undefined;