@molpha/sdk 0.2.0-dev-20261005112114 → 0.2.0-dev-20261005191253

package/README.md

@@ -175,7 +175,22 @@ nobody can pick a committee by picking a time.
 - The message the nodes sign is `keccak256(MOLPHA_MESSAGE_V1 || value || sourceId || u32be(registryVersion) || u8(quorum) || u64be(timestamp) || signersBitmap)`.
 - Chain clocks, epochs and `maxAge`/staleness are in **seconds**: compare with
   `timestampSeconds(payload.timestamp)` (floored `ts / 1000`). `timestampAgeSeconds(ts, nowSeconds)` saturates at 0.
-- A round that was already reserved for this consumer, or dispatched to the nodes, cannot run again in the same tick (HTTP 409), so a retry waits for the next one (`tickMs`, default 1000: set it to the gateway's `round.tick_ms`).
+- A round that was already reserved for this consumer, or dispatched to the nodes, cannot run again in the same tick (HTTP 409), so a retry waits for the next one. `tickMs` defaults to the gateway's advertised `tickMs` (read once, on the first retry, from `GET /v1/info`), else 1000.
+
+### Retries and timeouts
+
+`requestSignedData` makes up to `maxRetries` attempts (default 6) and chooses the wait before each by why the last one failed (`retryDelayMs`). Every wait reaches at least the next tick, then adds jitter so clients that failed together do not retry together:
+
+| Last attempt | Wait before the next |
+| --- | --- |
+| 409 (this consumer already has a round for the source in this tick) | next tick, plus up to half a tick |
+| 503 or 429 (gateway at capacity, or nodes unavailable) | the later of the next tick and the gateway's `Retry-After`, plus up to a tick |
+| timeout, network error, other 5xx | capped exponential backoff (250 ms up to 5 s), half of it randomized |
+| 400, 401, 402, 403 | none: terminal. 403 means the subscription is inactive or its round quota for the term is spent |
+
+A 400 saying the `registryVersion` is not the current one (a cached context, or a registry roll between your read and the request) is the exception: the SDK reads the registry afresh and retries once, without spending an attempt.
+
+`timeoutMs` defaults to 35 s, above the gateway's own wait for a round (`roundTimeoutSeconds` in `/v1/info`, 30 s by default). A shorter timeout abandons a round the gateway is still running, and the retry then starts another. A source that cannot be fetched is reported as soon as enough nodes have failed (usually well under a second), not after the wait.
 - Private API secrets are encrypted for every node of the registry (the committee is unknown until the gateway stamps the round); the gateway forwards only the selected nodes' envelopes. `verifyNodeKeys` therefore authenticates all of them.
 
 ## Wallet
@@ -311,6 +326,10 @@ If the signed 32-byte value is the keccak digest of a longer preimage, pass `{ r
 const { signature, feed } = await sdk.solana.submitAttestation(result, { rawValue });
 ```
 
+**Compute budget and fees.** The transaction requests `estimateSubmitComputeUnits(signers)` compute units (about `43k + 9.2k` per signer, plus 15% and 10k of margin: roughly 140k at 8 signers), not the 1.4M maximum the old default asked for, which mattered once a priority fee is priced per requested unit. Pass `{ computeUnitLimit }` to override it. No priority fee is attached unless you ask: `{ priorityFeeMicroLamports: 2_000 }` sets a price in micro-lamports per unit, and `{ priorityFeeMicroLamports: "auto" }` uses the 75th percentile of the fees recently paid by writers of that feed (capped at 1 lamport per unit; an unreadable fee market means no fee). Use one of them when submits are dropped under load.
+
+**Many feeds.** The client caches what feeds sharing a registry version have in common: the registry read (30 s), each signer `Node` key (never changes) and the coalition key of each signer set, and concurrent submits share one read. Submitting a fleet of feeds therefore costs one registry read and one `Node` read per distinct signer, not per submit. A stale or duplicate round is refused by the program in about 17-20k compute units, before it verifies the signature.
+
 Then read the feed this wallet wrote for that source and quorum:
 
 ```ts
@@ -337,6 +356,27 @@ const result = await sdk.gateway.requestSignedData({ apiConfig, signaturesRequir
 const { signature, feed } = await sdk.solana.submitAttestation(result);
 ```
 
+If the round succeeds but submitting fails, `requestAndSubmit` throws a `SubmitFailedError` that carries the signed attestation (`error.result`). The round already consumed quota and the attestation is valid, so submit `error.result` again instead of requesting a new round.
+
+### Many feeds
+
+For a large set of feeds use `requestMany` (also exported from the package root) instead of looping over `requestAndSubmit`:
+
+```ts
+import { requestMany } from "@molpha/sdk";
+
+const results = await requestMany(sdk, feeds, {
+  spreadMs: 1000, // spread starts by source hash so feeds due together do not arrive together
+  request: { maxRetries: 6 },
+});
+for (const r of results) {
+  if (!r.ok) console.error(r.label, r.error);
+  else if (r.submitError) console.warn(r.label, "round ok, submit failed", r.submitError);
+}
+```
+
+It reads the registry inputs once for the whole batch; bounds concurrency, starting from half the gateway's advertised `maxInflightRounds` (at most 64, else 32) and adapting (halving on a busy answer, growing back while requests succeed); runs Solana submits on their own smaller limiter (`submitConcurrency`, default 8); never discards the signed attestation of a round whose submit failed; and returns one result per feed in input order, so a failing feed does not stop the others. Pass `submit: false` to collect attestations only. Throughput is limited by the submit path (one transaction per attestation) long before it is limited by the gateway.
+
 ### Fast requests with a cached context
 
 By default every `requestSignedData` call reads the on-chain registry up front

package/dist/{chunk-2X22JY7Q.js → chunk-H77BBZOL.js}

@@ -34,10 +34,13 @@ function getAssociatedTokenAddressSync(mint, owner, tokenProgram = TOKEN_PROGRAM
 function setComputeUnitLimit(units) {
   return web3.ComputeBudgetProgram.setComputeUnitLimit({ units });
 }
+function setComputeUnitPrice(microLamports) {
+  return web3.ComputeBudgetProgram.setComputeUnitPrice({ microLamports });
+}
 function keypairFromSecretKey(secretKey) {
   return web3.Keypair.fromSecretKey(secretKey);
 }
 
-export { SYSTEM_PROGRAM_ADDRESS, TOKEN_PROGRAM_ADDRESS, addressBytes, addressFromBytes, findProgramAddressSync, getAssociatedTokenAddressSync, keypairFromSecretKey, setComputeUnitLimit, toPublicKey, toSolanaAddress };
-//# sourceMappingURL=chunk-2X22JY7Q.js.map
-//# sourceMappingURL=chunk-2X22JY7Q.js.map
+export { SYSTEM_PROGRAM_ADDRESS, TOKEN_PROGRAM_ADDRESS, addressBytes, addressFromBytes, findProgramAddressSync, getAssociatedTokenAddressSync, keypairFromSecretKey, setComputeUnitLimit, setComputeUnitPrice, toPublicKey, toSolanaAddress };
+//# sourceMappingURL=chunk-H77BBZOL.js.map
+//# sourceMappingURL=chunk-H77BBZOL.js.map

package/dist/chunk-H77BBZOL.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/solana/kit.ts"],"names":[],"mappings":";;;;AAaO,IAAM,qBAAA,GAAwB,QAAQ,6CAA6C;AACnF,IAAM,gCAAA,GAAmC,OAAA;AAAA,EAC9C;AACF,CAAA;AACO,IAAM,sBAAA,GAAyB,QAAQ,kCAAkC;AAEhF,IAAM,iBAAiB,iBAAA,EAAkB;AACzC,IAAM,iBAAiB,iBAAA,EAAkB;AAElC,SAAS,gBAAgB,KAAA,EAA+B;AAC7D,EAAA,OAAO,QAAQ,OAAO,KAAA,KAAU,WAAW,KAAA,GAAQ,KAAA,CAAM,UAAU,CAAA;AACrE;AAEO,SAAS,YAAY,KAAA,EAA2D;AACrF,EAAA,OAAO,iBAAiB,IAAA,CAAK,SAAA,GAAY,QAAQ,IAAI,IAAA,CAAK,UAAU,KAAK,CAAA;AAC3E;AAEO,SAAS,aAAa,KAAA,EAAkC;AAC7D,EAAA,OAAO,WAAW,IAAA,CAAK,cAAA,CAAe,OAAO,eAAA,CAAgB,KAAK,CAAC,CAAC,CAAA;AACtE;AAGO,SAAS,iBAAiB,KAAA,EAA4B;AAC3D,EAAA,OAAO,cAAA,CAAe,OAAO,KAAK,CAAA;AACpC;AAEO,SAAS,sBAAA,CACd,OACA,cAAA,EACS;AACT,EAAA,MAAM,CAAC,GAAG,CAAA,GAAI,IAAA,CAAK,UAAU,sBAAA,CAAuB,KAAA,EAAO,WAAA,CAAY,cAAc,CAAC,CAAA;AACtF,EAAA,OAAO,gBAAgB,GAAG,CAAA;AAC5B;AAUO,SAAS,6BAAA,CACd,IAAA,EACA,KAAA,EACA,YAAA,GAA8B,qBAAA,EACrB;AACT,EAAA,OAAO,sBAAA;AAAA,IACL,CAAC,aAAa,KAAK,CAAA,EAAG,aAAa,YAAY,CAAA,EAAG,YAAA,CAAa,IAAI,CAAC,CAAA;AAAA,IACpE;AAAA,GACF;AACF;AAEO,SAAS,oBAAoB,KAAA,EAAkC;AACpE,EAAA,OAAO,IAAA,CAAK,oBAAA,CAAqB,mBAAA,CAAoB,EAAE,OAAO,CAAA;AAChE;AAEO,SAAS,oBAAoB,aAAA,EAA0C;AAC5E,EAAA,OAAO,IAAA,CAAK,oBAAA,CAAqB,mBAAA,CAAoB,EAAE,eAAe,CAAA;AACxE;AAEO,SAAS,qBAAqB,SAAA,EAAsC;AACzE,EAAA,OAAO,IAAA,CAAK,OAAA,CAAQ,aAAA,CAAc,SAAS,CAAA;AAC7C","file":"chunk-H77BBZOL.js","sourcesContent":["import { web3 } from \"@anchor-lang/core\";\nimport { address, getAddressDecoder, getAddressEncoder, type Address } from \"@solana/kit\";\n\nexport type SolanaAddress = Address | string | InstanceType<typeof web3.PublicKey>;\nexport type SolanaConnection = InstanceType<typeof web3.Connection>;\nexport type SolanaKeypair = InstanceType<typeof web3.Keypair>;\nexport type SolanaInstruction = InstanceType<typeof web3.TransactionInstruction>;\nexport type SolanaAccountMeta = {\n  pubkey: InstanceType<typeof web3.PublicKey>;\n  isSigner: boolean;\n  isWritable: boolean;\n};\n\nexport const TOKEN_PROGRAM_ADDRESS = address(\"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA\");\nexport const ASSOCIATED_TOKEN_PROGRAM_ADDRESS = address(\n  \"ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL\",\n);\nexport const SYSTEM_PROGRAM_ADDRESS = address(\"11111111111111111111111111111111\");\n\nconst addressEncoder = getAddressEncoder();\nconst addressDecoder = getAddressDecoder();\n\nexport function toSolanaAddress(value: SolanaAddress): Address {\n  return address(typeof value === \"string\" ? value : value.toBase58());\n}\n\nexport function toPublicKey(value: SolanaAddress): InstanceType<typeof web3.PublicKey> {\n  return value instanceof web3.PublicKey ? value : new web3.PublicKey(value);\n}\n\nexport function addressBytes(value: SolanaAddress): Uint8Array {\n  return Uint8Array.from(addressEncoder.encode(toSolanaAddress(value)));\n}\n\n/** Base58 `Address` from 32 raw bytes (e.g. a `Registry.nodes[i]` entry). */\nexport function addressFromBytes(bytes: Uint8Array): Address {\n  return addressDecoder.decode(bytes);\n}\n\nexport function findProgramAddressSync(\n  seeds: Uint8Array[],\n  programAddress: SolanaAddress,\n): Address {\n  const [pda] = web3.PublicKey.findProgramAddressSync(seeds, toPublicKey(programAddress));\n  return toSolanaAddress(pda);\n}\n\nexport function findProgramPublicKeySync(\n  seeds: Uint8Array[],\n  programAddress: SolanaAddress,\n): InstanceType<typeof web3.PublicKey> {\n  const [pda] = web3.PublicKey.findProgramAddressSync(seeds, toPublicKey(programAddress));\n  return pda;\n}\n\nexport function getAssociatedTokenAddressSync(\n  mint: SolanaAddress,\n  owner: SolanaAddress,\n  tokenProgram: SolanaAddress = TOKEN_PROGRAM_ADDRESS,\n): Address {\n  return findProgramAddressSync(\n    [addressBytes(owner), addressBytes(tokenProgram), addressBytes(mint)],\n    ASSOCIATED_TOKEN_PROGRAM_ADDRESS,\n  );\n}\n\nexport function setComputeUnitLimit(units: number): SolanaInstruction {\n  return web3.ComputeBudgetProgram.setComputeUnitLimit({ units });\n}\n\nexport function setComputeUnitPrice(microLamports: number): SolanaInstruction {\n  return web3.ComputeBudgetProgram.setComputeUnitPrice({ microLamports });\n}\n\nexport function keypairFromSecretKey(secretKey: Uint8Array): SolanaKeypair {\n  return web3.Keypair.fromSecretKey(secretKey);\n}\n\nexport function generateKeypair(): SolanaKeypair {\n  return web3.Keypair.generate();\n}\n"]}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { Address } from '@solana/kit';
 import { Wallet, Idl, AnchorProvider } from '@anchor-lang/core';
-import { U as UpstreamQuote, A as APIConfig, a as AssetDomain, b as UpstreamTerms, E as EvmSigner, R as RegistrySelectionConfig, S as Signer, N as NodeKeyVerifier, c as Node, d as NodesInfo, e as SourcePaymentOptions, f as Attestation, g as SolanaAccountMeta, h as SolanaConnection, i as SolanaAddress, j as NodeKeyVerifierArgs, k as AggregationConfig, M as MolphaWallet } from './wallet-LqCFWwV4.js';
-export { l as AttestationPayload, m as EncKeyBundle, n as NumericConfig, o as RegistryInfo, p as SchnorrSignature, q as gatewaySignerFromWallet, s as signerFromKeypair } from './wallet-LqCFWwV4.js';
+import { U as UpstreamQuote, A as APIConfig, a as AssetDomain, b as UpstreamTerms, E as EvmSigner, S as Signer, c as SourcePaymentOptions, R as RegistrySelectionConfig, N as Node, d as NodeKeyVerifier, e as NodesInfo, f as Attestation, g as SolanaAccountMeta, h as SolanaConnection, i as SolanaAddress, j as NodeKeyVerifierArgs, k as AggregationConfig, M as MolphaWallet } from './wallet--IGHoCtG.js';
+export { l as AttestationPayload, m as EncKeyBundle, n as NumericConfig, o as RegistryInfo, p as SchnorrSignature, q as gatewaySignerFromWallet, s as signerFromKeypair } from './wallet--IGHoCtG.js';
 import BN from 'bn.js';
 
 /**
@@ -27,6 +27,12 @@ interface GatewayInfo {
     gatewayAuthority: string;
     /** Program id the gateway settles against; must match the client's when present. */
     programId?: string;
+    /** The gateway's round timestamp grid in milliseconds (`round.tick_ms`), when advertised. */
+    tickMs?: number;
+    /** Longest the gateway waits for a round, in seconds (`node.agg_wait_seconds`), when advertised. */
+    roundTimeoutSeconds?: number;
+    /** Rounds the gateway runs at once (`limits.max_inflight_rounds`); 0 or absent: not advertised. */
+    maxInflightRounds?: number;
 }
 declare function normalizeEndpoint(input: GatewayEndpointInput): GatewayEndpoint;
 /** 32-byte form of a base58 address. */
@@ -145,14 +151,23 @@ interface RequestSignedDataOptions {
     sourcePayment?: SourcePaymentOptions;
     /** Max accepted value age in seconds. Default 60. */
     maxAge?: number;
-    /** Max attempts; each retry waits for a later gateway tick. Default 15. */
+    /**
+     * Max attempts. Each retry waits for a later gateway tick, plus jitter, and for longer after a
+     * busy answer (`Retry-After`) or a failure that is not a conflict (capped exponential backoff);
+     * see {@link retryDelayMs}. Default {@link DEFAULT_MAX_RETRIES}.
+     */
     maxRetries?: number;
     /**
      * The gateway's tick grid in milliseconds (its `round.tick_ms`). A retry waits for the start of
-     * the next tick so it is a new round, not a duplicate of the last. Default 1000.
+     * the next tick so it is a new round, not a duplicate of the last. Default: the gateway's
+     * advertised `tickMs` (read once, on the first retry), else 1000.
      */
     tickMs?: number;
-    /** Per-request timeout in ms. Default 5000. */
+    /**
+     * Per-request timeout in ms. Default {@link DEFAULT_ROUND_TIMEOUT_MS}, above the gateway's own
+     * wait for a round: a shorter timeout abandons rounds the gateway is still running and the retry
+     * then starts another.
+     */
     timeoutMs?: number;
     /**
      * Pre-fetched round inputs. Any field present here skips its network/on-chain
@@ -198,6 +213,8 @@ interface MolphaGatewayOptions {
      * may use gateway-provided node keys without authentication. Defaults to false.
      */
     allowUnverifiedNodeKeysForPrivateApi?: boolean;
+    /** Source of randomness in [0, 1) for retry jitter; defaults to `Math.random` (tests only). */
+    random?: () => number;
 }
 /**
  * The slow-changing inputs a `requestSignedData` round binds to. Fetch once with
@@ -209,6 +226,40 @@ interface RoundContext extends RegistrySelectionConfig {
 }
 /** Milliseconds from `nowMs` to the start of the next tick, plus a millisecond of margin. */
 declare function msUntilNextTick(nowMs: number, tickMs: number): number;
+/**
+ * Default per-request timeout: above the gateway's own wait for a round (`node.agg_wait_seconds`,
+ * 30 s by default), so the client does not abandon a round the gateway is still running and then
+ * start a second one. A gateway advertises its value as `roundTimeoutSeconds` in `GET /v1/info`.
+ */
+declare const DEFAULT_ROUND_TIMEOUT_MS = 35000;
+/** Default number of attempts. */
+declare const DEFAULT_MAX_RETRIES = 6;
+/**
+ * Why an attempt failed, as far as it decides how long to wait before the next one:
+ *  - `conflict`: HTTP 409, this consumer already has a round for the source in this tick;
+ *  - `busy`: HTTP 503 or 429, the gateway is at capacity or a node set is unavailable, optionally
+ *    with the gateway's `Retry-After`;
+ *  - `error`: anything else that may be transient (timeout, network, other 5xx).
+ */
+type RetryCause = {
+    kind: "conflict";
+} | {
+    kind: "busy";
+    retryAfterMs?: number;
+} | {
+    kind: "error";
+};
+/**
+ * How long to wait before the next attempt, in ms. Every delay reaches at least the start of the
+ * next tick (a retry inside the tick that just failed would be a duplicate round), then adds jitter
+ * so clients that failed together do not retry together:
+ *  - conflict: the next tick plus up to half a tick;
+ *  - busy: the later of the next tick and the gateway's `Retry-After` (a tick if absent), plus up to
+ *    a tick;
+ *  - error: capped exponential backoff (250 ms, 500 ms, ... 5 s) with half of it randomized.
+ * `failures` is the number of attempts that have failed so far (1 after the first).
+ */
+declare function retryDelayMs(cause: RetryCause, failures: number, nowMs: number, tickMs: number, random?: () => number): number;
 /** Default gateway base URL when `endpoints` is omitted. */
 declare const DEFAULT_GATEWAY_ENDPOINT = "https://dev-gateway.molpha.io/";
 /** Thrown for terminal gateway errors (400/401) — never retried. */
@@ -229,12 +280,17 @@ declare class MolphaGateway {
     private readonly programIdBytes;
     /** Gateway PDA per endpoint URL; resolved once per client lifetime. */
     private readonly gatewayPdas;
+    /** Advertised timing per endpoint URL, read lazily on the first retry. */
+    private readonly advertisedInfo;
+    private readonly random;
     constructor(endpoints?: GatewayEndpointInput | GatewayEndpointInput[], getRegistrySelectionConfig?: () => Promise<RegistrySelectionConfig>, defaultSigner?: Signer, 
     /**
      * Either a default subscription owner (base58) or gateway options. A string is the
      * shorthand for `{ defaultSubscriptionOwner }` used by standalone callers/tests.
      */
     defaultSubscriptionOwnerOrOptions?: string | MolphaGatewayOptions, defaultConsumerAuthority?: string);
+    /** The configured gateway base URLs, in failover order. */
+    endpointUrls(): string[];
     /** Tries endpoints in order; returns the first node list it can fetch. */
     getNodes(): Promise<Node[]>;
     /**
@@ -302,6 +358,12 @@ declare class MolphaGateway {
      * encryption) or when nothing else can tell us the node count.
      */
     private resolveContext;
+    /**
+     * The gateway's advertised tick grid, read once per endpoint and only when a retry needs it. Any
+     * failure (an old gateway without `/v1/info`, a timeout) means "not advertised", so the caller
+     * falls back to the default; a failure is not cached.
+     */
+    private advertisedTickMs;
     /** Gateway PDA bytes for an endpoint, cached per URL. A failed lookup is not cached. */
     private resolveGatewayPda;
     private lookupGatewayPda;
@@ -394,6 +456,17 @@ declare function planIdFromVariant(variant: Record<string, unknown>): PlanId;
  * `Program` over the vendored IDL (program `3d01170`, "Epoch settlements").
  */
 
+/**
+ * Compute units to request for a `submit_attestation` carrying `signerCount` signatures.
+ *
+ * The program's LiteSVM benchmark measures the whole transaction at about `43k + 9.1k` units per
+ * signer (119k at 8 signers, 155k at 12, 208k at 18), so the old flat 1.4M request was 7-10 times
+ * what a typical aggregate uses. That matters once a priority fee is attached, because it is
+ * priced per requested unit, and for how the scheduler packs blocks. The estimate adds 15% and a
+ * fixed 10k: the program's selection check costs a little more on some registries than the
+ * benchmark's, and a limit that is hit fails the transaction for good.
+ */
+declare function estimateSubmitComputeUnits(signerCount: number): number;
 type Commitment$1 = NonNullable<ConstructorParameters<typeof AnchorProvider>[2]>["commitment"];
 interface SubscribeResult {
     signature: string;
@@ -478,7 +551,18 @@ interface SubmitAttestationArgs {
     };
 }
 interface SubmitAttestationOptions {
+    /**
+     * Compute-unit limit. Defaults to {@link estimateSubmitComputeUnits} for the aggregate's signer
+     * count, not the 1.4M maximum.
+     */
     computeUnitLimit?: number;
+    /**
+     * Priority fee in micro-lamports per compute unit. A number is used as given; `"auto"` takes the
+     * 75th percentile of the fees recently paid by transactions that wrote the feed, capped at 1
+     * lamport per unit. Omitted: no priority fee, which is right on a quiet cluster. Raise it (or
+     * use `"auto"`) when submits are dropped under load.
+     */
+    priorityFeeMicroLamports?: number | "auto";
     /**
      * Precomputed signer coalition key. When omitted, the client fetches signer `Node`
      * accounts and sums their secp256k1 keys ({@link computeCoalitionKey}).
@@ -501,6 +585,10 @@ declare class MolphaSolanaClient {
     private readonly program;
     private readonly provider;
     readonly programId: Address;
+    private readonly registryCache;
+    private readonly nodeKeyCache;
+    private readonly coalitionCache;
+    private priorityFeeCache?;
     private constructor();
     static create(opts: CreateClientOpts): MolphaSolanaClient;
     private get wallet();
@@ -568,8 +656,12 @@ declare class MolphaSolanaClient {
      * `keccak256(rawValue)`; {@link buildSubmitAttestationArgs} validates that before send.
      */
     submitAttestation(attestation: Attestation, opts?: SubmitAttestationOptions): Promise<SubmitResult>;
+    /** The registry for `version`, reused for {@link REGISTRY_CACHE_MS}. */
+    private fetchRegistryCached;
+    private resolvePriorityFee;
     /** Sum of the signers' keys, read from their on-chain `Node` accounts (one batched fetch). */
     private computeSignerCoalitionKey;
+    private sumSignerKeys;
     /**
      * Read the feed written by `submitter` (default: this wallet) for
      * `(sourceId, signaturesRequired)`, or `null` before its first submit.
@@ -1331,6 +1423,98 @@ declare const subscriptionPda: (owner: SolanaAddress, programId: SolanaAddress)
  */
 declare function feedPda(sourceId: Uint8Array, signaturesRequired: number, submitter: SolanaAddress, programId: SolanaAddress): Address;
 
+/**
+ * Drive many feeds through the gateway (and optionally on to Solana) without overloading it.
+ *
+ * The consumer is the party that pushes updates and pays for them, so the cost and the burst
+ * behaviour of a large set of feeds is the consumer's to control. {@link requestMany} does the parts
+ * that matter at volume:
+ *
+ *  - the registry inputs are read once and shared by every request, not once per feed;
+ *  - concurrency is bounded and adapts: it starts from the gateway's advertised capacity, halves
+ *    when the gateway answers busy (503/429) and creeps back up while requests succeed (AIMD);
+ *  - request starts are spread over a window by a hash of each feed's source id, so feeds that fall
+ *    due together do not arrive together, and the same feed always lands at the same offset;
+ *  - submitting to Solana runs on its own, smaller limiter, pipelined behind the requests;
+ *  - a failed submit never discards the signed attestation the gateway returned (and quota paid for).
+ *
+ * Each request still has the single-request retry policy (backoff with jitter, `Retry-After`, a stale
+ * registry refreshed once; see {@link retryDelayMs}).
+ */
+
+/** One feed to update. */
+interface BulkFeed {
+    apiConfig: APIConfig;
+    signaturesRequired: number;
+    /** Echoed in the result; for the caller's own bookkeeping. */
+    label?: string;
+}
+interface BulkOptions {
+    /**
+     * Most gateway requests in flight. The limit adapts below this ceiling. Default: half the gateway's
+     * advertised `maxInflightRounds` (at most 64), or 32 when it advertises none.
+     */
+    concurrency?: number;
+    /**
+     * Spread request starts over this many ms by a hash of the feed's source id. Feeds that are due on
+     * the same tick otherwise arrive together and queue at the gateway. Default 0 (no spreading).
+     */
+    spreadMs?: number;
+    /** Submit each attestation to Solana after its round. Default true. */
+    submit?: boolean;
+    /** Most Solana submits in flight. Default 8. */
+    submitConcurrency?: number;
+    /**
+     * Options applied to every request (subscription owner, signer, `maxRetries`, `timeoutMs`, ...).
+     * `apiConfig`, `signaturesRequired` and `context` are set per feed.
+     */
+    request?: Omit<RequestSignedDataOptions, "apiConfig" | "signaturesRequired" | "context">;
+    /** Called as each feed finishes, in completion order. */
+    onResult?: (result: BulkResult) => void;
+    /** Stops starting new feeds; those already started finish. */
+    signal?: AbortSignal;
+}
+interface BulkResult {
+    /** Position in the input array. */
+    index: number;
+    label?: string;
+    /** The gateway round succeeded (submitting is reported separately in `submitError`). */
+    ok: boolean;
+    /** The signed attestation, whenever the round succeeded, including when the submit failed. */
+    attestation?: Attestation;
+    /** Transaction signature and feed account, when submitted. */
+    signature?: string;
+    feedAddress?: Address;
+    /** Why the round failed. */
+    error?: unknown;
+    /** Why submitting failed after a successful round; `attestation` is still valid. */
+    submitError?: unknown;
+}
+/**
+ * An adaptive concurrency limit: additive increase on success, multiplicative decrease on a busy
+ * answer. Waiters are served in arrival order.
+ */
+declare class AdaptiveLimiter {
+    private readonly max;
+    private readonly now;
+    private limit_;
+    private inFlight;
+    private successes;
+    private lastCut;
+    private readonly waiters;
+    constructor(initial: number, max: number, now?: () => number);
+    get limit(): number;
+    acquire(): Promise<void>;
+    /** Release a slot. `busy` reports that the gateway answered at capacity. */
+    release(outcome: "ok" | "busy" | "other"): void;
+}
+/** Deterministic start offset for a feed: the same source id always lands at the same point. */
+declare function spreadOffsetMs(sourceIdHex: string, spreadMs: number): number;
+/**
+ * Update many feeds. Results are returned in input order; a feed that fails does not stop the others.
+ */
+declare function requestMany(sdk: MolphaSDK, feeds: BulkFeed[], opts?: BulkOptions): Promise<BulkResult[]>;
+
 /**
  * Vendored Molpha Anchor IDL (`target/idl/molpha.json` from the program repo).
  *
@@ -1368,6 +1552,20 @@ interface MolphaSDKOptions {
     idl?: Idl;
     commitment?: Commitment;
 }
+/**
+ * Thrown by {@link MolphaSDK.requestAndSubmit} when the gateway round succeeded but submitting the
+ * attestation to Solana failed. The round consumed subscription quota and the signed attestation is
+ * valid, so it is carried here: submit `error.result` again (it stays valid until its freshness
+ * window passes, and re-submitting it is safe) instead of requesting, and paying for, a new round.
+ */
+declare class SubmitFailedError extends Error {
+    /** The signed attestation the gateway returned. */
+    readonly result: Attestation;
+    readonly cause: unknown;
+    constructor(
+    /** The signed attestation the gateway returned. */
+    result: Attestation, cause: unknown);
+}
 declare class MolphaSDK {
     readonly gateway: MolphaGateway;
     readonly solana: MolphaSolanaClient;
@@ -1383,4 +1581,4 @@ declare class MolphaSDK {
     }>;
 }
 
-export { APIConfig, AggregationConfig, AggregationConfigError, AssetDomain, Attestation, type AttestationMessageFields, type BuildEvmVerifierArgsOptions, type BuildStarknetVerifierArgsOptions, type CoalitionKey, DEFAULT_GATEWAY_ENDPOINT, EIP712_DOMAIN_TYPEHASH, type Eip712Domain, type EvmAttestation, type EvmAttestationPayload, type EvmSchnorrSignature, EvmSigner, type EvmVerifierArgs, type EvmVerifyResult, type FeedAccount, type GatewayEndpoint, type GatewayEndpointInput, GatewayError, type GatewayInfo, INT256_MAX, INT256_MIN, MESSAGE_PREFIX, MIN_TOLERANCE_SIGNATURES, MOLPHA_IDL, MOLPHA_PROGRAM_ADDRESS, MOLPHA_PROGRAM_ID, MOLPHA_VERIFIER_ABI, MOLPHA_VERIFIER_ADDRESS, MOLPHA_VERIFIER_STARKNET_ADDRESSES, MOLPHA_VERIFIER_STARKNET_SEPOLIA, type MolphaEvmNetwork, MolphaGateway, type MolphaGatewayOptions, MolphaSDK, type MolphaSDKOptions, MolphaSolanaClient, type MolphaStarknetNetwork, MolphaWallet, Node, NodeKeyVerifier, NodeKeyVerifierArgs, NodesInfo, type PlanId, type PlanInfo, PlanType, REQUEST_AUTH_DOMAIN, RegistrySelectionConfig, type RegistryStateView, type RegistryView, type RequestAuthFields, type RequestSignedDataOptions, type RoundContext, SELECTION_WINDOW_MS, type Secp256k1KeyInput, Signer, SourcePaymentOptions, type StarknetAttestation, type StarknetAttestationPayload, type StarknetFeltLike, type StarknetSchnorrSignature, type StarknetVerifierArgs, type StarknetVerifyResult, type SubmitAttestationArgs, type SubmitAttestationOptions, type SubmitResult, type SubscribeResult, type SubscriptionInfo, TRANSFER_WITH_AUTHORIZATION_TYPEHASH, type TransferAuthorization, UpstreamPaymentRequiredError, UpstreamQuote, UpstreamTerms, VERIFY_CODES, type VerifyCode, type VerifyCodeName, addressToBytes, assertAggregationQuorum, attestationMessageHash, attestationMessageHashFromAttestation, base64ToBytes, bigIntFromBytesBe, bitmapBitSet, bitmapToIndices, buildEvmVerifierArgs, buildStarknetVerifierArgs, buildSubmitAttestationArgs, bytesToBase64, bytesToHex, bytesToHex0x, canonicalizeAPIConfig, canonicalizeAggregation, commitmentAddressToStarknetFelt, computeCoalitionKey, concatBytes, createEvmSignerFromPrivateKey, decodeInt256, deriveGatewayPda, deriveGatewayPdaAddress, deriveGroupBitmap, deriveSelectionBitmap, deriveSelectionSeed, deriveSourceId, deriveSourceIdString, domainSeparator, effectiveSelectionSize, eligibleSetSize, encodeEvmVerifyCalldata, encodeInt256, encodeInt256Decimal, encodeRequestAuth, encodeStarknetVerifyCalldata, ensureLength, evmAddressFromPrivateKey, feedPda, formatInt256Decimal, gatewayPda, getMolphaStarknetVerifierAddress, hashRequestAuth, hexToBytes, msUntilNextTick, nodePda, normalizeEndpoint, normalizeSecp256k1PublicKeyHex, parseEvmVerifyResult, parseGatewayInfo, parseStarknetVerifyResult, parseUpstreamQuote, planIdFromVariant, planPda, planVariant, probeSource, protocolConfigPda, registryPda, registryStatePda, resolveRemainingAccounts, secp256k1PublicKeyFromCoordinates, selectedIndices, signSourcePayments, signersBitmapToDecimal, signersBitmapToStarknetUint256, signersBitmapToUint256, subscriptionPda, timestampAgeSeconds, timestampSeconds, toChecksumAddress, toFixedBytes, toFixedHex, transferWithAuthorizationDigest, transferWithAuthorizationHash, u256beFromBigInt, u32be, u32le, u64be, u64le, u8, utf8, validateSuppliedTerms, verifyCodeName };
+export { APIConfig, AdaptiveLimiter, AggregationConfig, AggregationConfigError, AssetDomain, Attestation, type AttestationMessageFields, type BuildEvmVerifierArgsOptions, type BuildStarknetVerifierArgsOptions, type BulkFeed, type BulkOptions, type BulkResult, type CoalitionKey, DEFAULT_GATEWAY_ENDPOINT, DEFAULT_MAX_RETRIES, DEFAULT_ROUND_TIMEOUT_MS, EIP712_DOMAIN_TYPEHASH, type Eip712Domain, type EvmAttestation, type EvmAttestationPayload, type EvmSchnorrSignature, EvmSigner, type EvmVerifierArgs, type EvmVerifyResult, type FeedAccount, type GatewayEndpoint, type GatewayEndpointInput, GatewayError, type GatewayInfo, INT256_MAX, INT256_MIN, MESSAGE_PREFIX, MIN_TOLERANCE_SIGNATURES, MOLPHA_IDL, MOLPHA_PROGRAM_ADDRESS, MOLPHA_PROGRAM_ID, MOLPHA_VERIFIER_ABI, MOLPHA_VERIFIER_ADDRESS, MOLPHA_VERIFIER_STARKNET_ADDRESSES, MOLPHA_VERIFIER_STARKNET_SEPOLIA, type MolphaEvmNetwork, MolphaGateway, type MolphaGatewayOptions, MolphaSDK, type MolphaSDKOptions, MolphaSolanaClient, type MolphaStarknetNetwork, MolphaWallet, Node, NodeKeyVerifier, NodeKeyVerifierArgs, NodesInfo, type PlanId, type PlanInfo, PlanType, REQUEST_AUTH_DOMAIN, RegistrySelectionConfig, type RegistryStateView, type RegistryView, type RequestAuthFields, type RequestSignedDataOptions, type RetryCause, type RoundContext, SELECTION_WINDOW_MS, type Secp256k1KeyInput, Signer, SourcePaymentOptions, type StarknetAttestation, type StarknetAttestationPayload, type StarknetFeltLike, type StarknetSchnorrSignature, type StarknetVerifierArgs, type StarknetVerifyResult, type SubmitAttestationArgs, type SubmitAttestationOptions, SubmitFailedError, type SubmitResult, type SubscribeResult, type SubscriptionInfo, TRANSFER_WITH_AUTHORIZATION_TYPEHASH, type TransferAuthorization, UpstreamPaymentRequiredError, UpstreamQuote, UpstreamTerms, VERIFY_CODES, type VerifyCode, type VerifyCodeName, addressToBytes, assertAggregationQuorum, attestationMessageHash, attestationMessageHashFromAttestation, base64ToBytes, bigIntFromBytesBe, bitmapBitSet, bitmapToIndices, buildEvmVerifierArgs, buildStarknetVerifierArgs, buildSubmitAttestationArgs, bytesToBase64, bytesToHex, bytesToHex0x, canonicalizeAPIConfig, canonicalizeAggregation, commitmentAddressToStarknetFelt, computeCoalitionKey, concatBytes, createEvmSignerFromPrivateKey, decodeInt256, deriveGatewayPda, deriveGatewayPdaAddress, deriveGroupBitmap, deriveSelectionBitmap, deriveSelectionSeed, deriveSourceId, deriveSourceIdString, domainSeparator, effectiveSelectionSize, eligibleSetSize, encodeEvmVerifyCalldata, encodeInt256, encodeInt256Decimal, encodeRequestAuth, encodeStarknetVerifyCalldata, ensureLength, estimateSubmitComputeUnits, evmAddressFromPrivateKey, feedPda, formatInt256Decimal, gatewayPda, getMolphaStarknetVerifierAddress, hashRequestAuth, hexToBytes, msUntilNextTick, nodePda, normalizeEndpoint, normalizeSecp256k1PublicKeyHex, parseEvmVerifyResult, parseGatewayInfo, parseStarknetVerifyResult, parseUpstreamQuote, planIdFromVariant, planPda, planVariant, probeSource, protocolConfigPda, registryPda, registryStatePda, requestMany, resolveRemainingAccounts, retryDelayMs, secp256k1PublicKeyFromCoordinates, selectedIndices, signSourcePayments, signersBitmapToDecimal, signersBitmapToStarknetUint256, signersBitmapToUint256, spreadOffsetMs, subscriptionPda, timestampAgeSeconds, timestampSeconds, toChecksumAddress, toFixedBytes, toFixedHex, transferWithAuthorizationDigest, transferWithAuthorizationHash, u256beFromBigInt, u32be, u32le, u64be, u64le, u8, utf8, validateSuppliedTerms, verifyCodeName };