@molpha/sdk 0.2.0-dev-20260913100330 → 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
@@ -746,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, Starknet `verify` calldata encoding and result decoding;
+- EVM and Starknet verifier argument building, `verify` calldata encoding and result decoding;
 - deployed testnet verifier address helpers.
 
 Known limitations:
@@ -779,6 +816,10 @@ Solana paths such as selection bitmap and `submit_attestation` remaining-account
 | `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