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

package/README.md

@@ -23,10 +23,10 @@ At a high level:
 Consumer
   └─ subscribes (USDC) on Solana
   └─ derives sourceId = keccak256(canonical apiConfig)
-  └─ signs a RequestAuth bound to (programId, gateway, sourceId, signaturesRequired, timestamp)
+  └─ signs a RequestAuth bound to (programId, gateway, sourceId, signaturesRequired, authTimestamp)
 
 Gateway
-  └─ coordinates a signing round for (sourceId, signaturesRequired)
+  └─ assigns the round's timestamp (unix ms) from its own clock and coordinates a signing round
 
 Verifier nodes
   └─ fetch/recompute the API result independently
@@ -46,7 +46,7 @@ Every signed attestation commits to the same message across chains:
 ```text
 message = keccak256(
   keccak256("MOLPHA_MESSAGE_V1") || value || sourceId || u32be(registryVersion) ||
-  u8(signaturesRequired) || u64be(canonicalTimestamp) || signersBitmap
+  u8(signaturesRequired) || u64be(timestamp) || signersBitmap
 )
 ```
 
@@ -64,7 +64,7 @@ Runtime dependencies include `@solana/kit`, `@anchor-lang/core`, and `@noble/*`.
 
 | Import | Use |
 |---|---|
-| `@molpha/sdk` | Facade (`MolphaSDK`), `MolphaGateway`, `MolphaSolanaClient`, core hashing (`deriveSourceId`, `attestationMessageHash`, `hashRequestAuth`), EVM/Starknet helpers. Browser-safe; no `fs` in the main entry. |
+| `@molpha/sdk` | Facade (`MolphaSDK`), `MolphaGateway`, `MolphaSolanaClient`, core hashing (`deriveSourceId`, `attestationMessageHash`, `hashRequestAuth`, `timestampSeconds`), EVM/Starknet helpers. Browser-safe; no `fs` in the main entry. |
 | `@molpha/sdk/utils` | `walletFromKeypairFile`, `loadKeypair` — load a Solana CLI keypair as an Anchor `Wallet`. Node.js only. |
 
 The package is ESM with `"sideEffects": false`, so gateway-only or read-only apps can tree-shake unused paths.
@@ -149,11 +149,13 @@ Gateway request authorization binds the gateway's on-chain account, so the clien
 
 ```text
 requestAuthHash = keccak256(
-  "MOLPHA_REQAUTH_V1" || programId || gatewayPda || sourceId || u8(signaturesRequired) || u64le(timestamp)
+  "MOLPHA_REQAUTH_V1" || programId || gatewayPda || sourceId || u8(signaturesRequired) || u64le(authTimestamp)
 )
 gatewayPda = PDA(["molpha_gateway", gatewayAuthority], programId)
 ```
 
+`authTimestamp` is the caller's unix **seconds** at signing: a freshness stamp for the authorization only (the gateway rejects stamps outside its `request_auth.window_seconds`, 60 s by default). It is read from the SDK clock for every attempt, so a retry after a 409 signs a fresh one. It has nothing to do with the round's `timestamp`.
+
 Pass `gatewayAuthority` (the gateway's base58 signing pubkey) per endpoint to pin it. When omitted, the SDK calls `GET {url}/v1/info` once per endpoint and reads:
 
 ```json
@@ -162,6 +164,35 @@ Pass `gatewayAuthority` (the gateway's base58 signing pubkey) per endpoint to pi
 
 A `programId` that differs from the client's is rejected. Because the hash differs per gateway, the auth signature is recomputed for every endpoint actually tried during failover — with a browser wallet that means one signing prompt per endpoint tried. `/v1/info` is never contacted when no signer is configured (dev zero-signature path).
 
+### Round timestamp
+
+The request body carries `authSig` and `authTimestamp` but no round timestamp. The gateway assigns the
+round's `timestamp` from its own clock, in unix **milliseconds**, on a tick grid
+(`floor(now / tickMs) * tickMs`, one second by default), and the result carries it in
+`payload.timestamp`. Committee selection reads only the timestamp's one-second window, so
+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` 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
 
 `wallet` is a single `MolphaWallet` used across both protocol surfaces:
@@ -169,7 +200,7 @@ A `programId` that differs from the client's is rejected. Because the hash diffe
 | Layer | What it signs |
 |---|---|
 | Solana client | Transactions such as `subscribe`, `extendSubscription`, `submitAttestation` |
-| Gateway client | `hashRequestAuth({ programId, gateway, sourceId, signaturesRequired, timestamp })` for authenticated gateway requests |
+| Gateway client | `hashRequestAuth({ programId, gateway, sourceId, signaturesRequired, authTimestamp })` for authenticated gateway requests |
 
 Gateway auth is resolved automatically when you use `MolphaSDK`:
 
@@ -182,7 +213,8 @@ Gateway auth is resolved automatically when you use `MolphaSDK`:
 explicit `signer`. Standalone `new MolphaGateway(...)` omits auth unless you pass
 a `defaultSigner` (third constructor arg) or per-call `signer`.
 
-The all-zero `authSig` path is for development only. Production jobs should authenticate gateway requests.
+The all-zero `authSig` path is for development only: a gateway rejects it with 401. Production jobs should authenticate gateway requests.
+
 
 ### Node.js utility
 
@@ -276,7 +308,7 @@ const result = await sdk.gateway.requestSignedData({
 
 The gateway round uses the current on-chain registry version. Selected verifier nodes independently fetch/recompute the result and sign only if the observed value matches the canonical result.
 
-The returned `Attestation` matches the cross-VM struct (`payload` + `signature`), plus gateway-only `value` (human-readable) and `fresh`. `payload` carries `sourceId`, the signed 32-byte `value`, `canonicalTimestamp`, `registryVersion`, and `signaturesRequired`; `signature` carries the aggregate Schnorr material and `signersBitmap`. `signaturesRequired` must be at least the protocol's `min_signers` (currently 3) or the chain rejects the submit.
+The returned `Attestation` matches the cross-VM struct (`payload` + `signature`), plus gateway-only `value` (human-readable) and `fresh`. `payload` carries `sourceId`, the signed 32-byte `value`, `timestamp`, `registryVersion`, and `signaturesRequired`; `signature` carries the aggregate Schnorr material and `signersBitmap`. `signaturesRequired` must be at least the protocol's `min_signers` (currently 3) or the chain rejects the submit.
 
 A gateway response is a coordination result, not proof of settlement or of on-chain verification. Consumers still decide freshness, source, quorum and replay policy.
 
@@ -294,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
@@ -302,7 +338,7 @@ const feedState = await sdk.solana.readFeed(result.payload.sourceId, signaturesR
 
 `FeedAccount.value` is the 32 signed bytes (`valueKind.value`) or their keccak preimage hash (`valueKind.hash`); `submitter` is the wallet that created the feed.
 
-The subscription read no longer exposes usage. The program dropped `used_rounds` / `prepaid_usdc` / `price` from `Subscription`; round quota is counted by the gateway's off-chain outbox, so `SubscriptionInfo` carries only `owner`, `planType`, `validUntil`, `maxRounds`, `delegateCount`, `maxDelegates`, `maxSigners`.
+The subscription read does not expose usage: the program stores no `used_rounds` / `prepaid_usdc` / `price`, and round quota is counted by the gateway's off-chain outbox. `SubscriptionInfo` carries only `owner`, `planType`, `validUntil`, `maxRounds`, `delegateCount`, `maxDelegates`, `maxSigners`.
 
 ### One-call request + submit
 
@@ -320,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
@@ -540,7 +597,7 @@ attestation:
     sourceId: `0x${string}`,       // bytes32
     registryVersion: number,       // uint32
     signaturesRequired: number,    // uint8
-    canonicalTimestamp: bigint,    // uint64
+    timestamp: bigint,    // uint64
   },
   signature: {
     signature: `0x${string}`,      // bytes32 (Attestation.signature.s)
@@ -692,7 +749,7 @@ attestation:
     source_id: u256,
     registry_version: u32,
     signatures_required: u8,
-    canonical_timestamp: u64,
+    timestamp: u64,
   },
   signature: {
     signature: u256,
@@ -742,7 +799,7 @@ shared with the EVM verifier contract and exported as `VERIFY_CODES`:
 | 0 | `OK` | Verified |
 | 2 | `BAD_REGISTRY_VERSION` | `registryVersion` does not exist on this verifier |
 | 3 | `MALFORMED` | Structurally invalid input, or dated in the future when `maxAge != 0` |
-| 4 | `NOT_YET_ACTIVE` | `canonicalTimestamp` predates the registry version's activation |
+| 4 | `NOT_YET_ACTIVE` | `timestamp` predates the registry version's activation |
 | 5 | `VERSION_EXPIRED` | Registry version superseded more than the grace window earlier |
 | 7 | `BAD_QUORUM` | Signers are not within the round's derived selection group |
 | 8 | `BAD_AGGREGATE` | The signers' aggregate key is the point at infinity |
@@ -770,7 +827,7 @@ A Molpha attestation is valid only if the verifier can confirm:
 - the update targets the expected `sourceId`;
 - the result was signed against a specific `registryVersion` (an immutable node-set snapshot);
 - the quorum satisfies `signaturesRequired`;
-- the signer bitmap is a subset of the deterministic selection for `(sourceId, registryVersion, canonicalTimestamp)`;
+- the signer bitmap is a subset of the deterministic selection for `(sourceId, registryVersion, timestamp)`;
 - the aggregate Schnorr signature over `attestationMessageHash(...)` is valid;
 - the timestamp is within the accepted freshness bounds;
 - on Solana, the signer `Node` accounts passed as remaining accounts are exactly `registry.nodes[bit]` for every set bit, and the supplied coalition key matches the sum of their keys.
@@ -834,7 +891,7 @@ Current scope:
 
 - Solana subscription and extend flow;
 - deterministic source id and attestation message hashing;
-- gateway signed-data requests (failover, retries, per-gateway request auth, context cache);
+- gateway signed-data requests (failover, tick-aware retries, per-gateway request auth, context cache);
 - Solana attestation submission and feed/registry reads;
 - private API encryption helpers (pre-production);
 - caller-funded x402 payments for paywalled API sources (Base USDC, pre-production);

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"]}