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

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-HfGXPpOp.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-HfGXPpOp.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. */
@@ -48,8 +54,8 @@ interface RequestAuthFields {
     sourceId: Uint8Array | string;
     /** u8 — the per-request quorum. */
     signaturesRequired: number;
-    /** u64 unix seconds. */
-    timestamp: number | bigint;
+    /** u64 unix SECONDS at signing (the auth freshness stamp, not the round's timestamp). */
+    authTimestamp: number | bigint;
 }
 /** Borsh encoding of `RequestAuth` — the hash body, without the domain. */
 declare function encodeRequestAuth(fields: RequestAuthFields): Uint8Array;
@@ -117,15 +123,16 @@ interface RequestSignedDataOptions {
      */
     subscriptionOwner?: string;
     /**
-     * Solana pubkey (base58) of the consumer authority that signs gateway auth.
+     * Solana pubkey (base58) of the consumer: the subscription owner, or a delegate of it.
      * Overrides the gateway's `defaultConsumerAuthority` when set.
      */
     consumerAuthority?: string;
     /**
-     * Signs `hashRequestAuth({ programId, gateway, sourceId, signaturesRequired, timestamp })`.
+     * Signs `hashRequestAuth({ programId, gateway, sourceId, signaturesRequired, authTimestamp })`.
      * The hash binds the gateway's on-chain account, so it is computed — and the signer
-     * invoked — once per endpoint actually tried. Overrides the gateway's `defaultSigner`
-     * when set. When both are omitted, sends an all-zero authSig (dev only).
+     * invoked — once per endpoint actually tried, with a fresh `authTimestamp` each time.
+     * Overrides the gateway's `defaultSigner` when set. When both are omitted, sends an all-zero
+     * authSig (a gateway rejects it with 401; for tests and local tooling only).
      */
     signer?: Signer;
     encrypt?: {
@@ -144,9 +151,23 @@ interface RequestSignedDataOptions {
     sourcePayment?: SourcePaymentOptions;
     /** Max accepted value age in seconds. Default 60. */
     maxAge?: number;
-    /** Each retry re-rolls the timestamp. 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;
-    /** Per-request timeout in ms. Default 5000. */
+    /**
+     * 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: the gateway's
+     * advertised `tickMs` (read once, on the first retry), else 1000.
+     */
+    tickMs?: number;
+    /**
+     * 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
@@ -177,8 +198,9 @@ interface MolphaGatewayOptions {
     /** Solana pubkey (base58) of the consumer authority used when a request omits it. */
     defaultConsumerAuthority?: string;
     /**
-     * Molpha program id the request authorization is bound to. Defaults to the vendored
-     * `MOLPHA_PROGRAM_ID`; must match the gateway's deployment.
+     * Molpha program id the request authorization is bound to (and that `fetchGatewayInfo`
+     * checks the gateway settles against). Defaults to the vendored `MOLPHA_PROGRAM_ID`;
+     * must match the gateway's deployment.
      */
     programId?: string;
     /**
@@ -191,15 +213,53 @@ 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
  * {@link MolphaGateway.prepareContext} and reuse across many rounds.
  */
 interface RoundContext extends RegistrySelectionConfig {
-    /** Full node set used to encrypt private API secrets for the selected nodes. */
+    /** Full registry node set: private API secrets are encrypted for every node in it. */
     nodes: Node[];
 }
+/** 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. */
@@ -220,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
-     * keeps the previous positional form used by standalone callers/tests.
+     * 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[]>;
     /**
@@ -233,7 +298,7 @@ declare class MolphaGateway {
      * selection policy, which sizes the eligible set a paid source must fund.
      *
      * The `registry` block is advisory: it is whatever the gateway read from the
-     * chain, and is absent on older gateways or when that read failed. Prefer the
+     * chain, and is absent when that read failed. Prefer the
      * on-chain read (`MolphaSolanaClient.getRegistrySelectionConfig`) whenever a
      * Solana connection is available — `requestSignedData` already does.
      */
@@ -257,12 +322,23 @@ declare class MolphaGateway {
     prepareContext(): Promise<RoundContext>;
     /**
      * Request a threshold-signed data update from the gateway, with retry +
-     * failover. Per attempt a fresh timestamp yields a fresh selection bitmap; the
-     * body is POSTed to each endpoint in order until one `completed`s.
+     * failover. The body is POSTed to each endpoint in order until one `completed`s.
+     *
+     * The round's `sourceId` is derived from `apiConfig`. The request carries no round timestamp:
+     * the gateway assigns the round's `timestamp` (unix milliseconds) from its own clock
+     * on a tick grid, and the committee follows from it. The result carries the assigned
+     * timestamp and the signers' bitmap. A retry waits for a later tick, because a round that was
+     * already reserved or dispatched cannot run again in the same one (HTTP 409).
      *
-     * The round's `sourceId` is derived from `apiConfig`. The request authorization
-     * binds the program id and each gateway's on-chain account, so the auth signature
-     * is recomputed for every endpoint tried.
+     * The request is authorized by a `RequestAuth` signature (`authSig`) over the program id, the
+     * endpoint's Gateway PDA, the source id, the quorum and `authTimestamp` (unix seconds, read
+     * from the local clock for every attempt). It only proves the caller may spend the
+     * subscription's rounds; it is not part of the round, so the signature is recomputed for every
+     * endpoint tried.
+     *
+     * Because the committee is unknown until the gateway stamps the round, private API
+     * secrets are encrypted for **every** node of the registry; the gateway forwards only the
+     * selected nodes' envelopes.
      *
      * By default this fetches the registry selection config up front and the node
      * set only when the round needs it (private API encryption, or when the registry
@@ -282,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;
@@ -374,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;
@@ -392,8 +485,7 @@ interface PlanInfo {
     isActive: boolean;
 }
 /**
- * On-chain `Subscription`. The program no longer tracks usage: `used_rounds`,
- * `prepaid_usdc` and the locked `price` were removed (round quota is counted by the
+ * On-chain `Subscription`. The program does not track usage (round quota is counted by the
  * gateway's off-chain outbox), so there is no on-chain "rounds used" figure to read.
  */
 interface SubscriptionInfo {
@@ -428,8 +520,8 @@ interface FeedAccount {
         hash: Record<string, never>;
     };
     submitter: Address;
-    /** u64 unix seconds. */
-    canonicalTimestamp: BN;
+    /** u64 unix MILLISECONDS (the round's gateway-assigned timestamp). */
+    timestamp: BN;
     signaturesRequired: number;
     signersBitmap: number[];
     registryVersion: number;
@@ -443,7 +535,7 @@ interface SubmitAttestationArgs {
             sourceId: number[];
             registryVersion: number;
             signaturesRequired: number;
-            canonicalTimestamp: BN;
+            timestamp: BN;
         };
         signature: {
             aggSigS: number[];
@@ -459,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}).
@@ -482,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();
@@ -549,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.
@@ -709,8 +820,8 @@ interface AttestationMessageFields {
     signersBitmap: string | Uint8Array;
     /** 32-byte packed value (hex or bytes). */
     value: string | Uint8Array;
-    /** Unix seconds (u64). */
-    canonicalTimestamp: number | bigint;
+    /** Unix milliseconds (u64), assigned by the gateway. */
+    timestamp: number | bigint;
 }
 /** Compute the attestation message hash (32 bytes). */
 declare function attestationMessageHash(fields: AttestationMessageFields): Uint8Array;
@@ -726,9 +837,17 @@ declare function normalizeSecp256k1PublicKeyHex(publicKeyHex: string, label?: st
 declare function secp256k1PublicKeyFromCoordinates(x: Uint8Array, y: Uint8Array, label?: string): string;
 
 /**
- * `seed = keccak256(keccak256("MOLPHA_SELECTION_V1") || sourceId || be32(rv) || be64(ts))`.
+ * Width in milliseconds of the window selection reads from the timestamp. The timestamp
+ * is unix milliseconds; the seed uses `floor(timestamp / SELECTION_WINDOW_MS)`, so
+ * sub-second precision never changes the committee. Changing it is a consensus break and must
+ * bump the selection prefix.
  */
-declare function deriveSelectionSeed(sourceId: Uint8Array, registryVersion: number, canonicalTimestamp: number | bigint): Uint8Array;
+declare const SELECTION_WINDOW_MS = 1000n;
+/**
+ * `seed = keccak256(keccak256("MOLPHA_SELECTION_V1") || sourceId || be32(rv) || be64(ts / 1000))`,
+ * where `ts` is the timestamp in unix MILLISECONDS (its 1 s window index is hashed).
+ */
+declare function deriveSelectionSeed(sourceId: Uint8Array, registryVersion: number, timestamp: number | bigint): Uint8Array;
 /** `min(signaturesRequired + redundancyBuffer, nodeCount)`. */
 declare function effectiveSelectionSize(signaturesRequired: number, redundancyBuffer: number, nodeCount: number): number;
 /** Is bit `bit` set in the 32-byte big-endian `bitmap`? */
@@ -743,10 +862,24 @@ declare function selectedIndices(bitmap: Uint8Array, nodeCount: number): number[
 declare function deriveGroupBitmap(seed: Uint8Array, nodeCount: number, groupSize: number): Uint8Array;
 /**
  * Convenience orchestrator: derive the selection bitmap end-to-end.
- * `redundancy` defaults to 0; `ts` defaults to the current unix second.
+ * `redundancy` defaults to 0; `ts` is the timestamp in unix MILLISECONDS and defaults
+ * to now. The gateway assigns the real timestamp of a round, so this is for tests and tools.
  */
 declare function deriveSelectionBitmap(sourceId: Uint8Array, registryVersion: number, nodeCount: number, signaturesRequired: number, redundancy?: number, ts?: number | bigint): Uint8Array;
 
+/**
+ * `timestamp` is unix MILLISECONDS, assigned by the gateway. Chain clocks (Solana `Clock`,
+ * EVM `block.timestamp`), epoch windows and `maxAge`/staleness are measured in SECONDS, so
+ * anything that compares the two must go through {@link timestampSeconds}.
+ */
+/** `timestamp` (unix ms) as whole unix seconds, floored. */
+declare function timestampSeconds(timestamp: number | bigint): number;
+/**
+ * Age in whole seconds of a timestamp against `nowSeconds`, saturating at 0 so a
+ * timestamp slightly ahead of the local clock never goes negative.
+ */
+declare function timestampAgeSeconds(timestamp: number | bigint, nowSeconds: number): number;
+
 /**
  * Result codes returned by Molpha's stateless verifier contracts (`verify` on EVM and
  * Starknet). Shared across VMs: the same attestation yields the same code on every chain.
@@ -761,11 +894,11 @@ declare const VERIFY_CODES: {
     readonly FEED_WITNESS: 1;
     /** The payload's `registryVersion` does not exist on this verifier. */
     readonly BAD_REGISTRY_VERSION: 2;
-    /** Structurally invalid input, or a `canonicalTimestamp` in the future when `maxAge != 0`. */
+    /** Structurally invalid input, or a `timestamp` in the future when `maxAge != 0`. */
     readonly MALFORMED: 3;
-    /** `canonicalTimestamp` predates the registry version's activation. */
+    /** `timestamp` predates the registry version's activation. */
     readonly NOT_YET_ACTIVE: 4;
-    /** The registry version was superseded more than the grace window before `canonicalTimestamp`. */
+    /** The registry version was superseded more than the grace window before `timestamp`. */
     readonly VERSION_EXPIRED: 5;
     /** Reserved. Never returned. */
     readonly COMPROMISED_QUORUM: 6;
@@ -823,7 +956,7 @@ declare const MOLPHA_VERIFIER_ABI: readonly [{
                 readonly type: "uint8";
                 readonly internalType: "uint8";
             }, {
-                readonly name: "canonicalTimestamp";
+                readonly name: "timestamp";
                 readonly type: "uint64";
                 readonly internalType: "uint64";
             }];
@@ -1071,8 +1204,8 @@ interface EvmAttestationPayload {
     registryVersion: number;
     /** `uint8`. */
     signaturesRequired: number;
-    /** `uint64`, unix seconds. */
-    canonicalTimestamp: bigint;
+    /** `uint64`, unix MILLISECONDS (`timestamp / 1000` is the seconds the verifier's `maxAge` uses). */
+    timestamp: bigint;
 }
 /** `IVerifier.SchnorrSignature`. */
 interface EvmSchnorrSignature {
@@ -1136,7 +1269,7 @@ declare function buildEvmVerifierArgs(attestation: Attestation, options: BuildEv
  * ABI calldata for `verify(attestation, maxAge)`: the 4-byte selector followed by nine
  * 32-byte words. Both structs are static, so they encode inline with no offsets:
  *
- * `value, sourceId, registryVersion, signaturesRequired, canonicalTimestamp, signature,
+ * `value, sourceId, registryVersion, signaturesRequired, timestamp, signature,
  *  commitment, signersBitmap, maxAge`
  *
  * For a raw `eth_call` (`{ to: verifier, data }`).
@@ -1182,8 +1315,8 @@ interface StarknetAttestationPayload {
     registry_version: number;
     /** `u8`. */
     signatures_required: number;
-    /** `u64`, unix seconds. */
-    canonical_timestamp: number;
+    /** `u64`, unix MILLISECONDS (`/ 1000` is the seconds the verifier's `max_age` uses). */
+    timestamp: number;
 }
 /** Starknet calldata shape for `SchnorrSignature`. */
 interface StarknetSchnorrSignature {
@@ -1243,7 +1376,7 @@ declare function buildStarknetVerifierArgs(attestation: Attestation, options: Bu
  * Flat felt calldata for `verify(attestation, max_age)`, in Cairo `Serde` order — 13 felts:
  *
  * `value.low, value.high, source_id.low, source_id.high, registry_version,
- *  signatures_required, canonical_timestamp, signature.low, signature.high, commitment,
+ *  signatures_required, timestamp, signature.low, signature.high, commitment,
  *  signers_bitmap.low, signers_bitmap.high, max_age`
  *
  * For a raw `starknet_call` with `entry_point_selector = selector("verify")`.
@@ -1290,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).
  *
@@ -1327,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;
@@ -1342,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, 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, nodePda, normalizeEndpoint, normalizeSecp256k1PublicKeyHex, parseEvmVerifyResult, parseGatewayInfo, parseStarknetVerifyResult, parseUpstreamQuote, planIdFromVariant, planPda, planVariant, probeSource, protocolConfigPda, registryPda, registryStatePda, resolveRemainingAccounts, secp256k1PublicKeyFromCoordinates, selectedIndices, signSourcePayments, signersBitmapToDecimal, signersBitmapToStarknetUint256, signersBitmapToUint256, subscriptionPda, 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 };