@molpha/sdk 0.2.0-dev-20260912150104 → 0.2.0-dev-20261001084453

package/README.md

@@ -45,8 +45,8 @@ Every signed attestation commits to the same message across chains:
 
 ```text
 message = keccak256(
-  keccak256("MOLPHA_MESSAGE_V1") || sourceId || u32be(registryVersion) ||
-  u32be(signaturesRequired) || signersBitmap || value || u64be(canonicalTimestamp)
+  keccak256("MOLPHA_MESSAGE_V1") || value || sourceId || u32be(registryVersion) ||
+  u8(signaturesRequired) || u64be(canonicalTimestamp) || signersBitmap
 )
 ```
 
@@ -290,6 +290,13 @@ The returned `DataUpdateResult` includes `sourceId`, the signed value, canonical
 const { signature, feed } = await sdk.solana.submitAttestation(result);
 ```
 
+If the signed 32-byte value is the keccak digest of a longer preimage, provide the
+preimage explicitly (up to 256 bytes). The SDK verifies the digest before sending:
+
+```ts
+const { signature, feed } = await sdk.solana.submitAttestation(result, { rawValue });
+```
+
 Then read the feed this wallet wrote for that source and quorum:
 
 ```ts
@@ -455,90 +462,120 @@ Supported network ids (selection helpers only): `evm-sepolia`, `arbitrum-sepolia
 
 ### Build verifier arguments
 
+The verifier's entrypoint is
+`verify(Attestation attestation, uint64 maxAge) returns (bool success, uint8 code)`.
+
 ```ts
 import { buildEvmVerifierArgs } from "@molpha/sdk";
 
 const result = await sdk.gateway.requestSignedData({ apiConfig, signaturesRequired });
 
-const { dataUpdate, signature } = buildEvmVerifierArgs(result);
+const { attestation, maxAge } = buildEvmVerifierArgs(result, { maxAge: 300 });
 ```
 
-The generated tuples match the Molpha EVM verifier ABI:
+`maxAge` is required. It is the freshness window in seconds: the verifier reports an older
+attestation as `STALE`, and one dated after `block.timestamp` as `MALFORMED`. `0` disables the
+check entirely — pass it only when your contract enforces freshness or ordering itself, because
+a stateless verifier otherwise accepts a correctly signed attestation forever.
 
-```ts
-// dataUpdate:
-// [bytes32 sourceId,
-//  uint32 registryVersion,
-//  uint32 signaturesRequired,
-//  bytes32 valuePacked,
-//  uint64 timestamp]
+The generated object matches the Solidity `IVerifier.Attestation` struct, using viem's
+primitive types so it passes straight into `readContract` or an ethers `Contract`. Member
+order is ABI order (and the signed message's order), so it differs from `DataUpdateResult`:
 
-// signature:
-// [bytes32 s,
-//  address commitment,
-//  uint256 signersBitmap]
+```ts
+attestation:
+{
+  payload: {
+    value: `0x${string}`,          // bytes32 (result.valuePacked)
+    sourceId: `0x${string}`,       // bytes32
+    registryVersion: number,       // uint32
+    signaturesRequired: number,    // uint8
+    canonicalTimestamp: bigint,    // uint64 (result.timestamp)
+  },
+  signature: {
+    signature: `0x${string}`,      // bytes32 (result.s)
+    commitment: `0x${string}`,     // address (result.commitmentAddr)
+    signersBitmap: bigint,         // uint256
+  },
+}
+maxAge: bigint                     // uint64
 ```
 
-Note: the deployed contract's source names the first struct field `jobId`; the SDK ABI names it `sourceId` (component names do not affect encoding) and the value is the 32-byte source id.
+The builder range-checks every integer against its Solidity type. Out-of-range calldata never
+reaches `verify`: the ABI decoder reverts on it instead of returning a result code.
 
-### ethers
+### viem
 
 ```ts
-import { Contract } from "ethers";
+import { createPublicClient, http } from "viem";
 import {
   buildEvmVerifierArgs,
+  MOLPHA_VERIFIER_ABI,
   MOLPHA_VERIFIER_ADDRESS,
+  parseEvmVerifyResult,
 } from "@molpha/sdk";
 
-const verifier = new Contract(
-  MOLPHA_VERIFIER_ADDRESS,
-  abi,
-  signer,
-);
+const client = createPublicClient({ chain, transport: http() });
+const { attestation, maxAge } = buildEvmVerifierArgs(result, { maxAge: 300 });
 
-const { dataUpdate, signature } = buildEvmVerifierArgs(result);
+const returned = await client.readContract({
+  address: MOLPHA_VERIFIER_ADDRESS,
+  abi: MOLPHA_VERIFIER_ABI,
+  functionName: "verify",
+  args: [attestation, maxAge],
+});
 
-await verifier.verify(dataUpdate, signature);
+const { success, code, reason } = parseEvmVerifyResult(returned);
+// { success: true, code: 0, reason: "OK" }
+// { success: false, code: 10, reason: "STALE" }
 ```
 
-### viem
+### ethers
 
 ```ts
-import { createPublicClient, http } from "viem";
+import { Contract } from "ethers";
 import {
   buildEvmVerifierArgs,
   MOLPHA_VERIFIER_ABI,
   MOLPHA_VERIFIER_ADDRESS,
+  parseEvmVerifyResult,
 } from "@molpha/sdk";
 
-const client = createPublicClient({
-  chain,
-  transport: http(),
-});
+const verifier = new Contract(MOLPHA_VERIFIER_ADDRESS, MOLPHA_VERIFIER_ABI, provider);
+const { attestation, maxAge } = buildEvmVerifierArgs(result, { maxAge: 300 });
 
-const { dataUpdate, signature } = buildEvmVerifierArgs(result);
+const { success, code, reason } = parseEvmVerifyResult(await verifier.verify(attestation, maxAge));
+```
 
-await client.readContract({
-  address: MOLPHA_VERIFIER_ADDRESS,
-  abi: MOLPHA_VERIFIER_ABI,
-  functionName: "verify",
-  args: [
-    {
-      sourceId: dataUpdate[0],
-      registryVersion: dataUpdate[1],
-      signaturesRequired: dataUpdate[2],
-      value: dataUpdate[3],
-      canonicalTimestamp: BigInt(dataUpdate[4]),
-    },
-    {
-      signature: signature[0],
-      commitment: signature[1],
-      signersBitmap: signature[2],
-    },
-  ],
-});
+### Raw `eth_call`
+
+`encodeEvmVerifyCalldata` produces the full calldata (selector `0x67e2907b` plus nine static
+words), and `parseEvmVerifyResult` also accepts the raw 64-byte return data:
+
+```ts
+import { buildEvmVerifierArgs, encodeEvmVerifyCalldata, parseEvmVerifyResult } from "@molpha/sdk";
+
+const args = buildEvmVerifierArgs(result, { maxAge: 300 });
+const returnData = await provider.call({ to: verifierAddress, data: encodeEvmVerifyCalldata(args) });
+
+const { success, code, reason } = parseEvmVerifyResult(returnData);
 ```
 
+`verify` never reverts; a rejection is a result code from the shared `VERIFY_CODES` table (see
+[the Starknet section](#call-verify-and-read-the-result) for the full list). The EVM verifier
+returns `MALFORMED` for a zero `signaturesRequired`, a zero or out-of-range signature scalar, a
+zero commitment, or fewer set bitmap bits than `signaturesRequired`. `parseEvmVerifyResult`
+throws when `success` and `code` disagree, which means the call did not reach a Molpha verifier
+of this interface.
+
+### Registry reads
+
+`MOLPHA_VERIFIER_ABI` also covers every read-only registry view — `getRegistryVersion`,
+`getTotalNodes`, `redundancyBuffer`, `getRegistryRoot` / `getRegistryPointer` (current or per
+version), `activatesAt`, `retiredAt`, `isLatestVersion`, `nodeStatus`, `isNode` — and the
+`InvalidRegistryVersion` error the per-version views revert with. Owner-only mutators are not
+included.
+
 Lower-level helpers are also exported for manual integrations:
 
 ```ts
@@ -578,40 +615,100 @@ const sepoliaDirect = MOLPHA_VERIFIER_STARKNET_SEPOLIA;
 
 ### Build verifier arguments
 
+The verifier's entrypoint is `verify(attestation: Attestation, max_age: u64) -> (bool, u8)`.
+
 ```ts
 import { buildStarknetVerifierArgs } from "@molpha/sdk";
 
 const result = await sdk.gateway.requestSignedData({ apiConfig, signaturesRequired });
 
-const { dataUpdate, signature } = buildStarknetVerifierArgs(result);
+const { attestation, maxAge } = buildStarknetVerifierArgs(result, { maxAge: 300 });
+```
+
+`maxAge` is required. It is the freshness window in seconds: the verifier reports an older
+attestation as `STALE`. `0` disables the check entirely — pass it only when your contract
+enforces freshness or ordering itself, because a stateless verifier otherwise accepts a
+correctly signed attestation forever.
+
+The generated object matches the Cairo `Attestation` struct. Member order is Cairo `Serde`
+order (and the signed message's order), so it differs from `DataUpdateResult`:
+
+```ts
+attestation:
+{
+  payload: {
+    value: u256,
+    source_id: u256,
+    registry_version: u32,
+    signatures_required: u8,
+    canonical_timestamp: u64,
+  },
+  signature: {
+    signature: u256,
+    commitment: felt252, // 20-byte address as felt
+    signers_bitmap: u256,
+  },
+}
 ```
 
-The generated objects match the Molpha Starknet verifier interface (the Cairo struct still names the first field `feed_id`; positional calldata is unchanged):
+The builder range-checks every integer against its Cairo type. Out-of-range calldata never
+reaches `verify`: Cairo `Serde` fails while decoding the arguments and the call reverts
+instead of returning a result code.
+
+### Call `verify` and read the result
+
+`encodeStarknetVerifyCalldata` flattens the arguments into the 13 felts a raw `starknet_call`
+takes, and `parseStarknetVerifyResult` decodes the `(bool, u8)` it returns. Any Starknet
+client works; with `starknet.js`:
 
 ```ts
-// dataUpdate:
-// {
-//   source_id: u256,
-//   registry_version: u32,
-//   signatures_required: u32,
-//   value: u256,
-//   canonical_timestamp: u64,
-// }
+import { RpcProvider } from "starknet";
+import {
+  buildStarknetVerifierArgs,
+  encodeStarknetVerifyCalldata,
+  parseStarknetVerifyResult,
+} from "@molpha/sdk";
+
+const provider = new RpcProvider({ nodeUrl: STARKNET_RPC_URL });
+const args = buildStarknetVerifierArgs(result, { maxAge: 300 });
+
+const response = await provider.callContract({
+  contractAddress: verifierAddress,
+  entrypoint: "verify",
+  calldata: encodeStarknetVerifyCalldata(args),
+});
 
-// signature:
-// {
-//   signature: u256,
-//   commitment: felt252, // EVM-style 20-byte address as felt
-//   signers_bitmap: u256,
-// }
+const { success, code, reason } = parseStarknetVerifyResult(response);
+// { success: true, code: 0, reason: "OK" }
+// { success: false, code: 10, reason: "STALE" }
 ```
 
+`verify` never reverts on well-formed calldata; a rejection is a result code. The codes are
+shared with the EVM verifier contract and exported as `VERIFY_CODES`:
+
+| Code | Name | Meaning |
+|---|---|---|
+| 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 |
+| 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 |
+| 9 | `BAD_SIGNATURE` | The aggregate Schnorr signature does not verify |
+| 10 | `STALE` | Older than `maxAge` |
+
+Codes 1 and 6 are reserved and never returned. Codes are append-only, so
+`parseStarknetVerifyResult` reports a code newer than your SDK as `reason: "UNKNOWN"` rather
+than throwing.
+
 Lower-level helpers are also exported:
 
 ```ts
 import {
   commitmentAddressToStarknetFelt,
   signersBitmapToStarknetUint256,
+  verifyCodeName,
 } from "@molpha/sdk";
 ```
 
@@ -686,7 +783,7 @@ Current scope:
 - 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);
-- EVM and Starknet verifier argument building;
+- EVM and Starknet verifier argument building, `verify` calldata encoding and result decoding;
 - deployed testnet verifier address helpers.
 
 Known limitations:
@@ -716,6 +813,13 @@ Solana paths such as selection bitmap and `submit_attestation` remaining-account
 | `result.feedId` / `NodeKeyVerifierArgs.feedId` | `.sourceId` |
 | EVM tuple `feedId`, ABI `jobId` | `sourceId` |
 | Starknet `feed_id` | `source_id` |
+| `buildStarknetVerifierArgs(result)` → `{ dataUpdate, signature }` | `buildStarknetVerifierArgs(result, { maxAge })` → `{ attestation, maxAge }` for `verify(attestation, max_age)` |
+| `StarknetDataUpdate` (`signatures_required: u32`) | `StarknetAttestationPayload` (`signatures_required: u8`, `value` first), nested in `StarknetAttestation` |
+| Starknet `verify` returns `bool` | returns `(bool, u8)` — decode with `parseStarknetVerifyResult` |
+| `buildEvmVerifierArgs(result)` → `{ dataUpdate, signature }` tuples | `buildEvmVerifierArgs(result, { maxAge })` → `{ attestation, maxAge }` for `verify(attestation, maxAge)` |
+| `EvmDataUpdateTuple` / `EvmSchnorrSignatureTuple` (positional) | `EvmAttestationPayload` / `EvmSchnorrSignature` objects (`value` first, `signaturesRequired: uint8`, `canonicalTimestamp: bigint`), nested in `EvmAttestation` |
+| EVM `verify(DataUpdate, SchnorrSignature)` returns `bool` | `verify(Attestation, uint64)` returns `(bool, uint8)` — decode with `parseEvmVerifyResult` |
+| `attestationMessageHash`: `sourceId ‖ u32 rv ‖ u32 sigReq ‖ bitmap ‖ value ‖ u64 ts` | `value ‖ sourceId ‖ u32 rv ‖ u8 sigReq ‖ u64 ts ‖ bitmap` (what nodes sign and every verifier checks) |
 | `resolveRegistryIndexForVersion`, `VIRTUAL_INDEX`, `nodePda(index)` | removed — signer accounts are `registry.nodes[bit]`; `nodePda(owner)` |
 
 ## Develop