@mida-context/sdk 0.1.0

package/dist/types/chain/browser.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The browser-safe surface of @mida/chain for the owner page bundle. index.ts also exports
+ * local.ts (node:child_process, node:fs, node:net, node:os) and deployment.ts's loadDeployment
+ * (node:fs) — neither can exist in a browser bundle, so this entry names the safe modules
+ * explicitly. The bundle test in apps/owner-page scans the built output and fails on "node:".
+ *
+ * deployment.js is re-exported only partially on purpose: parseDeployment/chainFor/Deployment are
+ * pure data + viem chains, while loadDeployment and DEFAULT_DEPLOYMENTS_DIR touch the filesystem
+ * and are deliberately absent here so nothing can reach them transitively.
+ */
+export * from "./abis.js";
+export { LOCAL_CHAIN_ID, MONAD_TESTNET_CHAIN_ID, MULTICALL3_ADDRESS, chainFor, parseDeployment } from "./deployment.js";
+export type { Deployment } from "./deployment.js";
+export * from "./logs.js";
+export * from "./history.js";
+export * from "./registry.js";
+export * from "./gas.js";
+export * from "./writes.js";
+export * from "./sponsored.js";
+export * from "./transport.js";

package/dist/types/chain/deployment-fs.d.ts

@@ -0,0 +1,15 @@
+import type { Deployment } from "./deployment.js";
+/**
+ * The contracts/deployments directory, resolved on first use and cached. It must stay lazy: this module is
+ * bundled into the store Worker, where `import.meta.url` is not a parseable URL — evaluating
+ * fileURLToPath(new URL(…)) at module scope would throw on startup. The Worker never calls this.
+ */
+export declare function DEFAULT_DEPLOYMENTS_DIR(): string;
+/**
+ * The deployment record for a chain. An explicit `directory` always wins — that stays the
+ * local-Anvil override (its 31337.json is gitignored and is never embedded). Without one, the
+ * committed record compiled into this package answers first, so a bundled binary needs no
+ * contracts/deployments folder; a chain with no embedded record still falls back to the
+ * source-tree file (the repo's own dev runs).
+ */
+export declare function loadDeployment(chainId: bigint, directory?: string): Deployment;

package/dist/types/chain/deployment.d.ts

@@ -0,0 +1,33 @@
+import type { Address, Hex } from "../protocol/index.js";
+import type { Chain } from "viem";
+/** Contents of contracts/deployments/<chainId>.json, written by contracts/script/Deploy.s.sol (plan Task 20). */
+export interface Deployment {
+    chainId: bigint;
+    capabilityRegistry: Address;
+    contextRegistry: Address;
+    deploymentBlock: bigint;
+    policyHashV1: Hex;
+    vaultRpId: string;
+    vaultRpIdHash: Hex;
+    /** Set only after DeployBatchAnchor.s.sol has run beside the registries; both keys or neither. */
+    batchAnchor?: Address;
+    batchAnchorBlock?: bigint;
+}
+export declare const LOCAL_CHAIN_ID = 31337n;
+export declare const MONAD_TESTNET_CHAIN_ID = 10143n;
+export declare function parseDeployment(json: unknown): Deployment;
+/** Only the two networks Project 1 targets. Monad testnet comes from viem, never a hand-written object. */
+export declare function chainFor(chainId: bigint): Chain;
+/** The canonical Multicall3 deployment — present on Monad testnet (chain 10143) at this address. */
+export declare const MULTICALL3_ADDRESS: Address;
+/**
+ * The chain a standalone read client is built on when only the deployment's chain id is known —
+ * the hosted store learns its config from env vars, not a checked-in network file. viem engages
+ * `batch: { multicall: true }` only when the client's chain declares a Multicall3 contract; a
+ * chain-less client silently sends one eth_call per read (in-13 M-2 — the Sep 25 RPC-limit
+ * incident's root cause). Monad testnet pins the canonical Multicall3 here so the store and the
+ * explicit batch reader agree on one shared constant; the local Anvil chain (foundry) and any
+ * unknown chain id declare none — it is not verifiable from here whether such a chain carries
+ * the contract, so reads stay one-per-call there exactly as before instead of throwing.
+ */
+export declare function rpcChain(chainId: bigint): Chain;

package/dist/types/chain/deployments.generated.d.ts

@@ -0,0 +1 @@
+export declare const EMBEDDED_DEPLOYMENTS: Record<string, unknown>;

package/dist/types/chain/gas.d.ts

@@ -0,0 +1,47 @@
+import type { Abi, Address } from "viem";
+import type { WriteContext } from "./writes.js";
+/**
+ * Gas ceilings per transaction kind (M2 fix round 3, R3-1).
+ *
+ * Monad bills a transaction for the gas LIMIT it carries, not the gas it uses, and a reverted
+ * transaction still pays its full limit — so the limit attached to every send must be a number
+ * we chose. A send whose node estimate exceeds its kind's ceiling is refused, not sent.
+ *
+ * Measured basis: `bench/gas-measure.ts` on local Anvil, default and "prague" hardforks
+ * (prague forces the Solidity P256 fallback, so its numbers dominate for the P256 paths).
+ * "tx.gas" is the limit the node would attach; "gasUsed" is what the receipt reported.
+ * Those ceilings were measured on a local chain with Ethereum gas pricing — Monad prices cold
+ * reads about 4x higher (contract tests rose 8.5% overall, up to 26% for revoke-everywhere), so
+ * the Monad testnet figures are the ones to trust.
+ */
+export declare const GAS_CEILINGS: {
+    readonly funding: 50000n;
+    readonly "owner.key": 200000n;
+    readonly "owner.keyRotate": 900000n;
+    readonly "epoch.init": 150000n;
+    readonly "epoch.rotateExpired": 300000n;
+    readonly "agent.register": 450000n;
+    readonly "context.register": 650000n;
+    readonly "grant.batch": 1500000n;
+    readonly "revoke.capability": 150000n;
+    readonly "revoke.rotate": 450000n;
+    readonly "revoke.agent": 6000000n;
+    readonly "batch.submit": 28000000n;
+};
+/** The named kind every transaction send must declare; a send with no kind does not compile. */
+export type TxKind = keyof typeof GAS_CEILINGS;
+/**
+ * The gas limit for a contract write: the node's estimate, sent explicitly and unpadded, refused
+ * when it exceeds the kind's ceiling. An estimate call that fails surfaces its own error.
+ */
+export declare function contractGas(context: WriteContext, call: {
+    address: Address;
+    abi: Abi;
+    functionName: string;
+    args: readonly unknown[];
+}, kind: TxKind): Promise<bigint>;
+/** The gas limit for a plain value transfer, under the same ceiling rule as a contract write. */
+export declare function valueGas(context: WriteContext, transfer: {
+    to: Address;
+    value: bigint;
+}, kind: TxKind): Promise<bigint>;

package/dist/types/chain/history.d.ts

@@ -0,0 +1,52 @@
+import type { Address, Hex, OwnerAgentHistory } from "../protocol/index.js";
+import { capabilityRegistryAbi } from "./abis.js";
+import type { Deployment } from "./deployment.js";
+import type { LogClient } from "./logs.js";
+/**
+ * §14.6 PREVIOUSLY_REVOKED input. Built only from CapabilityRevoked and AgentRevoked events for exactly
+ * this (owner, agentId) pair. Topic filters narrow the query; the explicit comparison below guards against
+ * a provider that ignores them. Never consults reputation or access telemetry.
+ */
+/** A log client that can also read a contract view — viem's PublicClient is one. */
+export interface HistoryClient extends LogClient {
+    readContract?(parameters: {
+        address: Address;
+        abi: typeof capabilityRegistryAbi;
+        functionName: "agentEpoch" | "activeCapabilityIds";
+        args: readonly [Address, Hex];
+    }): Promise<unknown>;
+}
+/**
+ * Where the last successful scan stopped for one (owner, agentId) pair (R4-9). A cache of chain
+ * facts, never an authority: the caller supplies load/save (the CLI keeps it at
+ * `state/history/<agentId>.json`, keyed on chain id and registry) and a missing, malformed or
+ * wrong-chain answer from load() means a full scan, not a guess. `previouslyRevoked` is sticky —
+ * nothing on the chain un-revokes — so a saved true answers without any scan at all.
+ */
+export interface HistoryScanCursor {
+    load(): {
+        observedThroughBlock: bigint;
+        previouslyRevoked: boolean;
+    } | undefined | Promise<{
+        observedThroughBlock: bigint;
+        previouslyRevoked: boolean;
+    } | undefined>;
+    save(state: {
+        observedThroughBlock: bigint;
+        previouslyRevoked: boolean;
+    }): void | Promise<void>;
+}
+export declare function ownerHistory(input: {
+    client: HistoryClient;
+    deployment: Deployment;
+    owner: Address;
+    agentId: Hex;
+    toBlock?: bigint;
+    cursor?: HistoryScanCursor;
+    /** The window size the scan opens with — the CLI passes the resolved MIDA_LOG_BLOCK_RANGE. */
+    maxRange?: bigint;
+    /** Called once, before the log scan starts, with an ESTIMATE of the requests it will take. */
+    onScan?: (requests: number) => void;
+    /** Live progress for each log scan — (completed, planned) requests; planned is the same estimate. */
+    onProgress?: (done: number, total: number) => void;
+}): Promise<OwnerAgentHistory>;

package/dist/types/chain/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./abis.js";
+export * from "./deployment.js";
+export * from "./deployment-fs.js";
+export * from "./logs.js";
+export * from "./history.js";
+export * from "./placements.js";
+export * from "./registry.js";
+export * from "./local.js";
+export * from "./gas.js";
+export * from "./transport.js";
+export * from "./read-scope.js";
+export * from "./writes.js";
+export * from "./sponsored.js";

package/dist/types/chain/local.d.ts

@@ -0,0 +1,34 @@
+import type { Hex } from "../protocol/index.js";
+import type { Deployment } from "./deployment.js";
+/** Development tooling for tests and the CLI. Never used against a real network. */
+export declare const FOUNDRY_BIN: string;
+/**
+ * The contracts/ directory, resolved on first use and cached. It must stay lazy: this module is bundled
+ * into the store Worker, where `import.meta.url` is not a parseable URL — evaluating
+ * fileURLToPath(new URL(…)) at module scope would throw on startup. The Worker never calls this.
+ */
+export declare function CONTRACTS_DIR(): string;
+/** Anvil's public, pre-funded development keys (mnemonic "test test ... junk"). Never use on a real network. */
+export declare const ANVIL_PRIVATE_KEYS: readonly Hex[];
+export interface LocalNode {
+    rpcUrl: string;
+    hardfork: string;
+    stop(): Promise<void>;
+}
+/** Starts a fresh Anvil on a free port. hardfork "default" keeps Anvil's default (Osaka, native P256 at 0x100). */
+export declare function startAnvil(options?: {
+    hardfork?: string;
+}): Promise<LocalNode>;
+/**
+ * Deploys with contracts/script/Deploy.s.sol, then DeployBatchAnchor.s.sol beside it, and returns the
+ * parsed deployment file (batchAnchor + batchAnchorBlock set). Every local Anvil writes the same
+ * deployments/31337.json, so deployments from parallel test files are serialized with a directory lock.
+ */
+export declare function deployLocal(options: {
+    rpcUrl: string;
+    privateKey?: Hex;
+}): Promise<Deployment>;
+/** Anvil-only: sets an address balance so generated agent signers can pay gas in local tests. */
+export declare function fundLocal(rpcUrl: string, address: string, wei?: bigint): Promise<void>;
+/** Anvil-only: moves chain time forward and mines one block, for expiry tests. */
+export declare function increaseLocalTime(rpcUrl: string, seconds: bigint): Promise<void>;

package/dist/types/chain/logs.d.ts

@@ -0,0 +1,62 @@
+import type { Address, Hex } from "../protocol/index.js";
+import type { AbiEvent } from "viem";
+/** The largest window an eth_getLogs scan may open with — Quicknode's Monad endpoint serves 1,000-block ranges. */
+export declare const MAX_LOG_BLOCK_RANGE = 1000n;
+/**
+ * The window every provider is assumed to accept — Monad's public RPC caps eth_getLogs at 100
+ * blocks. The first range refusal drops the rest of a scan, and the refused window, to this size.
+ */
+export declare const SAFE_LOG_BLOCK_RANGE = 100n;
+export interface BlockWindow {
+    fromBlock: bigint;
+    toBlock: bigint;
+}
+export declare function blockWindows(fromBlock: bigint, toBlock: bigint, size?: bigint): BlockWindow[];
+/**
+ * The window size a scan opens with, clamped to 1..MAX_LOG_BLOCK_RANGE. `undefined` means the
+ * maximum. Callers pass an operator-chosen value through (MIDA_LOG_BLOCK_RANGE); a nonsense one
+ * is pulled inside the valid range rather than crashing the scan — the same way an unreadable
+ * env value is ignored instead of refused.
+ */
+export declare function clampLogRange(maxRange: bigint | undefined): bigint;
+export interface DecodedLog {
+    args: Record<string, unknown>;
+    blockNumber: bigint | null;
+    transactionHash: Hex | null;
+    logIndex: number | null;
+    /** The index of the transaction that emitted this log inside its block (in-13 M-5). */
+    transactionIndex: number | null;
+}
+/** Structural subset of viem's PublicClient used for log scans, so tests can pass a recording fake. */
+export interface LogClient {
+    getBlockNumber(parameters?: {
+        cacheTime?: number;
+    }): Promise<bigint>;
+    getLogs(parameters: {
+        address: Address;
+        event: AbiEvent;
+        args?: Record<string, unknown>;
+        fromBlock: bigint;
+        toBlock: bigint;
+        strict: true;
+    }): Promise<readonly unknown[]>;
+}
+export interface LogScanOptions {
+    /** The window size the scan opens with — clamped to 1..MAX_LOG_BLOCK_RANGE, default the maximum. */
+    maxRange?: bigint;
+    /**
+     * Scan progress as (completed, planned) requests. `total` grows when a range refusal splits a
+     * window into SAFE pieces, so it is an estimate, not a promise. Called at most about once per
+     * 5% of the plan, and always once at the end with (total, total).
+     */
+    onProgress?: (done: number, total: number) => void;
+}
+export declare function getLogsChunked(client: LogClient, parameters: {
+    address: Address;
+    event: AbiEvent;
+    args?: Record<string, unknown>;
+    fromBlock: bigint;
+    toBlock?: bigint;
+}, options?: LogScanOptions): Promise<DecodedLog[]>;
+/** How many windows are in flight at once. */
+export declare const LOG_SCAN_CONCURRENCY = 8;

package/dist/types/chain/placements.d.ts

@@ -0,0 +1,92 @@
+import type { Address, Hex } from "../protocol/index.js";
+import type { Deployment } from "./deployment.js";
+import type { LogClient } from "./logs.js";
+/**
+ * Where Monad placed one save: the block its anchoring event sits in, the anchoring
+ * transaction's index inside that block, and the save's own position inside the transaction
+ * — a batch position for a batched save, the log's index in the block for a direct one.
+ * `record.createdAt` already carries Monad's timestamp (the contract stores
+ * `block.timestamp`); the placement fields exist only in the event log, so a reader that
+ * needs them scans it. `index` is a different unit in each lane and must never be compared
+ * across them — one transaction never emits both events (in-13 M-5).
+ */
+export interface RecordPlacement {
+    block: bigint;
+    /** The anchoring transaction's index inside the block — absent when the log carried none. */
+    transaction?: number;
+    index: number;
+}
+/**
+ * contextId → the placement of its ContextRegistered log. The owner — and optionally the
+ * namespace — ride the indexed topics, so one bounded scan answers for every record a read is
+ * about to return. Keys are lower-cased contextIds; a record whose log is somehow absent simply
+ * has no entry — its callers still order on the chain-stored createdAt and degrade only the
+ * same-second tie-break, never the timestamp itself.
+ */
+export declare function recordPlacements(input: {
+    client: LogClient;
+    deployment: Deployment;
+    owner: Address;
+    namespaceId?: Hex;
+    toBlock?: bigint;
+    maxRange?: bigint;
+}): Promise<Map<string, RecordPlacement>>;
+/** The narrow slice of viem's PublicClient a block-time lookup needs. */
+export interface BlockClient {
+    getBlock(parameters: {
+        blockNumber: bigint;
+    }): Promise<{
+        timestamp: bigint;
+    }>;
+}
+/**
+ * The narrow slice of viem's PublicClient the tie-break scan needs: log windows, the latest
+ * block, and — since in-12 N-5 corrects the estimate with the chain's own observed block rate —
+ * a single numbered block's timestamp. A missing block answers `null`, never a throw.
+ */
+export interface TieScanClient extends LogClient {
+    getBlock(parameters?: {
+        blockTag: "latest";
+    } | {
+        blockNumber: bigint;
+    }): Promise<{
+        number: bigint | null;
+        timestamp: bigint;
+    } | null>;
+}
+/**
+ * Half the blocks a same-second tie scans around its corrected estimate — 50 each side, so the
+ * window is at most SAFE_LOG_BLOCK_RANGE (100) blocks wide and never exceeds the public RPC's
+ * getLogs cap. Kept exported under its in-9 name.
+ */
+export declare const PLACEMENT_TIE_SPAN: bigint;
+/**
+ * contextId → placement, recovered ONLY for records whose chain stamps share a second — the one
+ * case where `createdAt` alone cannot order them (in-9 R-1). The event sits in a block whose
+ * timestamp is that second; finding it costs at most three getBlock calls per tied second —
+ * the shared head, an estimate probe, and one correction — because the observed rate between
+ * two real blocks is a better ruler than viem's static blockTime (in-12 N-5: a chain running
+ * 410–500 ms instead of its nominal 400, or recovering from a stall, threw the old estimate
+ * tens of thousands of blocks off). The scan itself opens a window of at most 100 blocks around
+ * the corrected center — never wider, so the public RPC's getLogs cap cannot refuse it —
+ * and overlapping windows merge then re-slice into ≤100-block requests.
+ *
+ * Completeness is per tied second, not per record: if the scan finds only SOME of the records
+ * sharing a second, that second keeps no placements at all — a found record ordering before an
+ * unfound one on a partial answer is exactly the wrong-but-plausible outcome this exists to
+ * prevent, so the whole tie falls back to the contextId order together.
+ */
+export declare function recordPlacementsNear(input: {
+    client: TieScanClient;
+    deployment: Deployment;
+    owner: Address;
+    namespaceId?: Hex;
+    /** The tied second (the records' shared `createdAt`) → the contextIds stamped with it. */
+    tied: ReadonlyMap<bigint, readonly Hex[]>;
+}): Promise<Map<string, RecordPlacement>>;
+/**
+ * One `getBlock` per distinct block, shared across a whole call — a read that anchors many saves
+ * out of a handful of blocks asks once each. The in-flight promise is cached so concurrent
+ * callers share the request (and one another's failure).
+ */
+export declare function blockTimeCache(client: BlockClient): (block: bigint) => Promise<bigint>;

package/dist/types/chain/read-scope.d.ts

@@ -0,0 +1,66 @@
+import type { PublicClient } from "viem";
+/**
+ * in-9 R-5 — the per-operation read scope.
+ *
+ * One logical read (a handoff, a whats-new refresh) asks the chain the same questions many
+ * times: the agent record for every epoch key, the capability state for every object, the
+ * same block for every save it anchored. None of those answers can change inside one
+ * operation — the chain either held them when the operation started or the next operation
+ * will see the change. So the scope keeps one Map of `(method, args) → the in-flight wire
+ * call`, shared by every client built inside the operation: the runtime's own client and
+ * each agent's fresh one all hit the same entry, and an answer still on the wire is awaited
+ * once, not re-requested.
+ *
+ * The scope is a snapshot by design and dies with the operation. It is never process-wide:
+ * a revocation that lands between two handoffs is read fresh by the second one, because the
+ * second handoff builds a new scope.
+ *
+ * A scope can also carry a deadline: once it passes, no NEW chain read starts for the
+ * operation — an abandoned handoff stops spending the shared rate limit instead of finishing
+ * a read nobody will ever render. Calls already on the wire are left to finish; only new
+ * ones are refused with ReadDeadlineError.
+ */
+export interface ReadScope {
+    /**
+     * signer (lowercase address) → the read-scope token the store last issued for it (in-12 N-10).
+     * The token is the store's own HMAC-signed grant — client code never invents one — so this map
+     * is only ever filled from response headers, and an entry that has expired is replaced by the
+     * next response's token rather than stamped again.
+     */
+    readonly tokens: Map<string, string>;
+    /** `(method, serialized args)` → the one in-flight or settled wire call the operation shares. */
+    readonly memo: Map<string, Promise<unknown>>;
+    /** epoch ms after which the scope starts no new chain read; absent means no deadline. */
+    readonly deadlineAt?: number;
+}
+/** The error a read started after the scope's deadline gets — the operation ran out of time. */
+export declare class ReadDeadlineError extends Error {
+    readonly code: "read-deadline";
+    constructor();
+}
+/** Walks the cause chain — viem wraps fetch failures — for a scope-deadline refusal. */
+export declare function isReadDeadlineError(error: unknown): boolean;
+export declare function createReadScope(options?: {
+    deadlineMs?: number;
+}): ReadScope;
+/**
+ * The test-visible counter the transport probe is for requests: every memoized call records
+ * whether it hit an existing entry or started the wire call. Counters accumulate until reset —
+ * measure a window by resetting first.
+ */
+export declare const readScopeProbe: {
+    hits: number;
+    misses: number;
+    /** reads refused after the scope's deadline */
+    refused: number;
+    reset(): void;
+};
+/**
+ * A client whose memoized methods share the scope's wire calls. Only the whitelisted read
+ * methods are touched; every other property and method passes straight through, so a
+ * write-capable client wrapped here still sends, estimates and waits on receipts normally.
+ *
+ * A FAILED call is evicted from the memo: one transient refusal must not poison every later
+ * identical read in the operation — the next one tries again on its own request.
+ */
+export declare function memoizedReads(client: PublicClient, scope: ReadScope): PublicClient;

package/dist/types/chain/registry.d.ts

@@ -0,0 +1,16 @@
+import type { AgentRecord, Hex, MidaErrorCode } from "../protocol/index.js";
+import type { PublicClient } from "viem";
+import type { Deployment } from "./deployment.js";
+export interface ChainContext {
+    publicClient: PublicClient;
+    deployment: Deployment;
+}
+/** Contract custom-error names mapped to protocol codes (§12.6 first, plan decision 3 codes otherwise). */
+export declare const REVERT_CODES: Readonly<Record<string, MidaErrorCode>>;
+export declare function revertNameFromData(data: Hex): string | undefined;
+export declare function revertName(error: unknown): string | undefined;
+/** Returns a MidaError for a known contract revert; any other error is returned unchanged for rethrow. */
+export declare function toMidaError(error: unknown): unknown;
+export declare function readAgentRecord(context: ChainContext, agentId: Hex): Promise<AgentRecord>;
+/** Chain time, not wall-clock time, decides expiry so the API and the contracts use one clock (Part D note). */
+export declare function latestTimestamp(context: ChainContext): Promise<bigint>;

package/dist/types/chain/sponsored.d.ts

@@ -0,0 +1,93 @@
+import { MidaError } from "../protocol/index.js";
+import type { Abi, Address, Hex, LocalAccount } from "viem";
+import type { Deployment } from "./deployment.js";
+import type { TxKind } from "./gas.js";
+import type { SentReceipt } from "./writes.js";
+/**
+ * The account implementation the SDK's first sponsored operation delegates to — Pimlico's
+ * Simple7702Account, the default inside `to7702SimpleSmartAccount`. The sponsor endpoint's
+ * ALLOWED_IMPLEMENTATIONS must contain this address or every first operation is refused.
+ */
+export declare const SPONSORED_IMPLEMENTATION: Address;
+/** Phase 1 — up to the bundler answering with a hash — gets this long; past it the caller may fall back. */
+export declare const SPONSOR_TIMEOUT_MS = 20000;
+/** Phase 2 — waiting for the receipt of an ACCEPTED operation — gets its own, longer deadline. */
+export declare const SPONSOR_RECEIPT_TIMEOUT_MS = 120000;
+/**
+ * The gas the bundler's `callGasLimit` does NOT count: that field prices the inner execution
+ * only, while GAS_CEILINGS were measured as whole-transaction limits — verification,
+ * pre-verification and paymaster gas ride on top. Comparing the raw numbers let the sponsored
+ * path run tens of thousands of gas more permissive than the self-paid one (M3-D6 item 4), so
+ * the kind's ceiling minus this overhead is the bound `callGasLimit` is checked against —
+ * the same effective whole-transaction ceiling both paths enforce.
+ */
+export declare const CALL_OVERHEAD_GAS = 40000n;
+/** Once the receipt wait runs this long the owner hears one progress line — silence is not pending. */
+export declare const SPONSOR_RECEIPT_NOTICE_MS = 15000;
+/**
+ * Every way a sponsored send can fail before the operation lands: refusal, unreachable endpoint,
+ * timeout, malformed answer. `sendContract` falls back to self-pay only on this type — an operation
+ * that was included and reverted is a different outcome (the sponsor DID pay) and is never retried.
+ */
+export declare class SponsorDidNotPay extends MidaError {
+    /** The short human reason, surfaced on the fallback progress line. */
+    readonly reason: string;
+    constructor(reason: string);
+}
+/**
+ * The bundler accepted a user operation — a hash exists — but its receipt could not be confirmed
+ * inside the receipt deadline. The operation may still land, so this is deliberately NOT
+ * SponsorDidNotPay: `sendContract` falls back only on that type, and a self-paid copy of an
+ * accepted call is the exact double-send this error exists to prevent.
+ */
+export declare class SponsorPending extends MidaError {
+    /** The accepted operation's hash — surfaced to the owner so the outcome can be checked. */
+    readonly userOpHash: Hex;
+    constructor(userOpHash: Hex);
+}
+/**
+ * A sponsored send's answer, shaped like the self-paid `SentReceipt`: `transactionHash` is the
+ * bundle transaction, `gasLimit` the sum of the operation's gas fields (Monad bills the sponsor
+ * for the limit on every field, not the usage), plus the `userOpHash` the bundle carries.
+ */
+export type SponsoredReceipt = SentReceipt & {
+    userOpHash: Hex;
+};
+export interface SponsoredSender {
+    /**
+     * Sends one contract call as a sponsored user operation. `kind` carries the per-kind gas
+     * ceiling this sender enforces against the bundler's own `callGasLimit` estimate before the
+     * operation is sent (M3-D3) — the owner-side `eth_estimateGas` never runs on this path.
+     */
+    send(call: {
+        address: Address;
+        abi: Abi;
+        functionName: string;
+        args: readonly unknown[];
+    }, kind: TxKind): Promise<SponsoredReceipt>;
+}
+/**
+ * A sender whose gas is paid by the Mida sponsor endpoint while `sender` stays the user's own
+ * address — the contracts still see the user as msg.sender. `sponsorUrl` speaks the Pimlico
+ * bundler+paymaster JSON-RPC dialect our sponsor worker proxies (EntryPoint v0.8). The user's
+ * first operation signs an EIP-7702 authorization for `implementation`; later ones carry none,
+ * because the delegation is already on chain.
+ */
+export declare function createSponsoredSender(input: {
+    sponsorUrl: string;
+    rpcUrl: string;
+    account: LocalAccount;
+    deployment: Deployment;
+    /** Override the delegated implementation — must be on the endpoint's allow list. */
+    implementation?: Address;
+    /** Phase-1 deadline (paymaster + send, up to acceptance), default SPONSOR_TIMEOUT_MS; tests pass less. */
+    timeoutMs?: number;
+    /** Phase-2 deadline (receipt confirmation after acceptance), default SPONSOR_RECEIPT_TIMEOUT_MS. */
+    receiptTimeoutMs?: number;
+    /** Delay before the "still waiting" progress line, default SPONSOR_RECEIPT_NOTICE_MS. */
+    receiptNoticeMs?: number;
+    /** Receipt polling interval; viem's default when unset. */
+    pollingIntervalMs?: number;
+    /** Progress lines for the human running the command — fires once if the receipt wait runs long. */
+    progress?: (line: string) => void;
+}): SponsoredSender;

package/dist/types/chain/transport.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The chain RPC stayed rate-limited through every retry (250/500/1000 ms). Downstream callers
+ * surface this as reason `chain-busy` / code CHAIN_UNAVAILABLE — never "not approved": a busy
+ * chain could not be asked, it did not refuse.
+ */
+export declare class ChainBusyError extends Error {
+    readonly code = "CHAIN_BUSY";
+    constructor();
+}
+/**
+ * True when a ChainBusyError sits anywhere in the error's cause chain. viem wraps a fetchFn
+ * failure in HttpRequestError (and callers may wrap again), so instanceof alone is not enough.
+ */
+export declare function isChainBusy(error: unknown): boolean;
+/**
+ * What a thrown chain error actually is, so every surface names it honestly (in-11 R-8):
+ *
+ * - `busy` — the RPC could not answer: stayed rate-limited, answered 408/429/5xx, dropped the
+ *   connection (an HttpRequestError with no status), timed out, or reported an RPC-level
+ *   overload code (-32005 limit exceeded / -32603 provider-internal). Waiting and retrying is
+ *   honest advice — the same set the transport's own retry treats as transient.
+ * - `misconfigured` — the RPC answered but the call returned "0x" (no contract at the
+ *   configured address): a wrong-network rpcUrl or a stale deployment. The fix is
+ *   MONAD_TESTNET_RPC / network.json, not a retry.
+ * - `rpc-auth` — the provider refused the key (HTTP 401/403). The fix is the provider
+ *   credential, not a retry.
+ * - `undefined` — anything else: a real contract answer (a revert), a decode failure, a local
+ *   fault. Not renamed — callers keep their own fallback rather than lie.
+ *
+ * The walk also honours codes a store already computed: a CHAIN_UNAVAILABLE /
+ * CHAIN_MISCONFIGURED / RPC_AUTH_REJECTED answer classifies the same as the raw transport
+ * shape it was wrapped from, so a hosted store's answer and a local call get one name.
+ */
+export type ChainErrorKind = "busy" | "misconfigured" | "rpc-auth";
+export declare function chainErrorKind(error: unknown): ChainErrorKind | undefined;
+/**
+ * Test seam (in-6 R1/R2): the admission instant of every request the limiter released — one per
+ * wire send, so its length is the HTTP request count and its timestamps are what the limiter
+ * enforced (the fetch itself dispatches within the same event-loop turn). Module-global; tests
+ * call `reset()` and read `sentAt`.
+ */
+export declare const rpcTransportProbe: {
+    sentAt: number[];
+    reset(): void;
+};
+/**
+ * The transport to put in every public and wallet client: `rpcTransport(url)` in place of
+ * `http(url)`. The rate limit key is the URL's origin, so two transports aimed at one host share
+ * one bucket — inside ONE process. The bucket is per process, not global: a `mida` CLI running
+ * beside the daemon has its own, so N processes can still reach N× the host's allowance (in-11
+ * R-15 — the old comment claimed they could not).
+ */
+export declare function rpcTransport(url: string): import("viem").HttpTransport<undefined, false>;