@molpha/sdk 0.2.0-dev-20260913100330 → 0.2.0-dev-20261001125531

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, D as DataUpdateResult, f as SolanaAccountMeta, g as SolanaConnection, h as SolanaAddress, i as NodeKeyVerifierArgs, M as MolphaWallet } from './wallet-DwdBZgl1.js';
-export { j as EncKeyBundle, k as RegistryInfo, l as SchnorrSignature, m as gatewaySignerFromWallet, s as signerFromKeypair } from './wallet-DwdBZgl1.js';
+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 BN from 'bn.js';
 
 /**
@@ -105,7 +105,11 @@ interface RequestSignedDataOptions {
      * same config (including `{{secret.*}}` placeholders) every time.
      */
     apiConfig: APIConfig;
-    /** Requested quorum (u8, ≥ the protocol `min_signers`). */
+    /**
+     * Requested quorum (u8, ≥ the protocol `min_signers`). Median tolerance mode
+     * (`apiConfig.aggregation`) additionally requires `>= 3`; lower values are rejected
+     * before any request is made.
+     */
     signaturesRequired: number;
     /**
      * Solana pubkey (base58) of the subscription owner.
@@ -270,7 +274,7 @@ declare class MolphaGateway {
      * fund it; without that, such a source throws
      * {@link UpstreamPaymentRequiredError} carrying the gateway's quote.
      */
-    requestSignedData(opts: RequestSignedDataOptions): Promise<DataUpdateResult>;
+    requestSignedData(opts: RequestSignedDataOptions): Promise<Attestation>;
     /**
      * Resolve the round inputs, fetching only the fields absent from `cached`.
      * Registry version, redundancy buffer and node count are treated as a unit (one
@@ -286,8 +290,31 @@ declare class MolphaGateway {
     private fetchWithTimeout;
 }
 
+/** Affine coalition key, 32-byte big-endian coordinates (`CoalitionKey` in the program IDL). */
+interface CoalitionKey {
+    x: Uint8Array;
+    y: Uint8Array;
+}
+/** A signer's public key: SEC1 compressed / uncompressed (bytes or hex), or affine `(x, y)`. */
+type Secp256k1KeyInput = Uint8Array | string | {
+    x: Uint8Array | string;
+    y: Uint8Array | string;
+};
+/**
+ * Affine sum of `keys` as a {@link CoalitionKey}.
+ *
+ * @throws {Error} on an empty set, an invalid point, or a sum at infinity (the verifier
+ *   rejects both of the latter as `InvalidAggregateSignature`).
+ */
+declare function computeCoalitionKey(keys: Iterable<Secp256k1KeyInput>): CoalitionKey;
+
 /**
  * Account views and remaining-accounts construction for `submit_attestation`.
+ *
+ * `submit_attestation` (program 3d01170, `utils/attestation.rs::verify_attestation_core`)
+ * takes exactly one `Node` account per set signer bit, read-only, in ascending bit order
+ * (`remaining_accounts.len() == popcount(signersBitmap)`); the verifier requires
+ * `account == registry.nodes[bit]` and reads each signer's secp256k1 key from it.
  */
 
 /** On-chain `RegistryState` (Anchor camelCase): pointer to the current immutable snapshot. */
@@ -307,6 +334,8 @@ interface RegistryView {
     nodes: Address[];
     /** Unix seconds until which this superseded snapshot still verifies; `0n` while current. */
     graceActiveUntil: bigint;
+    /** Inclusive creation time (unix seconds): a version cannot verify a round dated before it existed. */
+    activeFrom: bigint;
 }
 /** Set-bit indices of a 32-byte big-endian bitmap (full 256-bit scan). */
 declare function bitmapToIndices(signersBitmapHex: string): number[];
@@ -342,7 +371,7 @@ declare function planIdFromVariant(variant: Record<string, unknown>): PlanId;
  * `MolphaSolanaClient` — consumer on-chain surface only (subscribe, extend,
  * submitAttestation, readFeed/readPlan/readSubscription/readRegistry,
  * getRegistrySelectionConfig, verifyNodeKeysForPrivateApi). Built from an Anchor
- * `Program` over the vendored IDL.
+ * `Program` over the vendored IDL (program `3d01170`, "Epoch settlements").
  */
 
 type Commitment$1 = NonNullable<ConstructorParameters<typeof AnchorProvider>[2]>["commitment"];
@@ -362,16 +391,17 @@ interface PlanInfo {
     privateApiEnabled: boolean;
     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
+ * gateway's off-chain outbox), so there is no on-chain "rounds used" figure to read.
+ */
 interface SubscriptionInfo {
     owner: Address;
     planType: PlanType;
-    /** USDC base units prepaid on the subscription vault. */
-    prepaidUsdc: bigint;
-    /** Locked subscription price in USDC base units for the current period. */
-    price: bigint;
     /** Unix timestamp (seconds) until which the subscription is valid. */
     validUntil: bigint;
-    usedRounds: bigint;
+    /** Round quota per plan snapshot — enforced by the gateway at admission, not on chain. */
     maxRounds: bigint;
     delegateCount: number;
     maxDelegates: number;
@@ -382,15 +412,22 @@ interface SubmitResult {
     /** Feed PDA written by this submit (`["molpha_feed", sourceId, [signaturesRequired], submitter]`). */
     feed: Address;
 }
+/**
+ * On-chain `Feed` (Anchor-decoded). `value` is always the signed
+ * `AttestationPayload.value` (32 bytes): the oracle value itself when `valueKind` is
+ * `value`, or `keccak256(rawValue)` when it is `hash` (the preimage travelled in the
+ * submitting instruction). For a tolerance-mode source it is a two's-complement `int256`
+ * (see `decodeInt256` / `formatInt256Decimal`).
+ */
 interface FeedAccount {
     sourceId: number[];
-    /** Stored payload: raw value (`valueKind.value`) or keccak digest (`valueKind.hash`), ≤ 32 bytes. */
     value: Uint8Array | number[];
     valueKind: {
         value: Record<string, never>;
     } | {
         hash: Record<string, never>;
     };
+    submitter: Address;
     /** u64 unix seconds. */
     canonicalTimestamp: BN;
     signaturesRequired: number;
@@ -400,14 +437,39 @@ interface FeedAccount {
 }
 /** Anchor-encoded `SubmitAttestationArgs` (camelCase field names). */
 interface SubmitAttestationArgs {
-    sourceId: number[];
-    registryVersion: number;
-    value: number[];
-    canonicalTimestamp: BN;
-    signaturesRequired: number;
-    aggSigS: number[];
-    commitment: number[];
-    signersBitmap: number[];
+    attestation: {
+        payload: {
+            value: number[];
+            sourceId: number[];
+            registryVersion: number;
+            signaturesRequired: number;
+            canonicalTimestamp: BN;
+        };
+        signature: {
+            aggSigS: number[];
+            commitment: number[];
+            signersBitmap: number[];
+        };
+    };
+    /** Optional preimage when `payload.value` is `keccak256(rawValue)`. */
+    rawValue: Uint8Array | null;
+    coalitionKey: {
+        x: number[];
+        y: number[];
+    };
+}
+interface SubmitAttestationOptions {
+    computeUnitLimit?: number;
+    /**
+     * Precomputed signer coalition key. When omitted, the client fetches signer `Node`
+     * accounts and sums their secp256k1 keys ({@link computeCoalitionKey}).
+     */
+    coalitionKey?: CoalitionKey;
+    /**
+     * Optional value preimage (maximum 256 bytes). Its keccak256 digest must equal
+     * `attestation.payload.value`; the program stores that digest with `valueKind.hash`.
+     */
+    rawValue?: Uint8Array;
 }
 interface CreateClientOpts {
     connection: SolanaConnection;
@@ -474,17 +536,21 @@ declare class MolphaSolanaClient {
     private confirmPlanPrice;
     /**
      * Submit a gateway attestation via `submit_attestation`. The feed account for
-     * `(sourceId, signaturesRequired, submitter)` is created on first use. Signer
-     * `Node` accounts are resolved from the registry snapshot the round was signed
-     * against and passed as remaining accounts.
-     */
-    submitAttestation(result: DataUpdateResult, opts?: {
-        computeUnitLimit?: number;
-    }): Promise<SubmitResult>;
-    /** @deprecated Renamed to {@link submitAttestation}. */
-    submitDataUpdate(result: DataUpdateResult, opts?: {
-        computeUnitLimit?: number;
-    }): Promise<SubmitResult>;
+     * `(sourceId, signaturesRequired, submitter)` is created on first use.
+     *
+     * Per the program, the instruction takes one read-only `Node` account per signer bit
+     * (ascending bit order, resolved from the registry snapshot the round was signed
+     * against) and a {@link CoalitionKey} argument. Unless `opts.coalitionKey` is given the
+     * SDK fetches those `Node` accounts and sums their secp256k1 keys client-side
+     * (`computeCoalitionKey`); the program only checks the key, so a wrong one fails the
+     * transaction and nothing else.
+     *
+     * `opts.rawValue` is for values longer than 32 bytes: the signed `payload.value` must be
+     * `keccak256(rawValue)`; {@link buildSubmitAttestationArgs} validates that before send.
+     */
+    submitAttestation(attestation: Attestation, opts?: SubmitAttestationOptions): Promise<SubmitResult>;
+    /** Sum of the signers' keys, read from their on-chain `Node` accounts (one batched fetch). */
+    private computeSignerCoalitionKey;
     /**
      * Read the feed written by `submitter` (default: this wallet) for
      * `(sourceId, signaturesRequired)`, or `null` before its first submit.
@@ -502,10 +568,59 @@ declare class MolphaSolanaClient {
     /** `usdc_mint` from `ProtocolConfig`; the treasury is its ATA owned by the config PDA. */
     private fetchProtocolTokens;
 }
-/** Build the Anchor `SubmitAttestationArgs` for a gateway result. */
-declare function buildSubmitAttestationArgs(result: DataUpdateResult): SubmitAttestationArgs;
+/**
+ * Build the Anchor `SubmitAttestationArgs` for a gateway result: `{ attestation: { payload,
+ * signature }, rawValue, coalitionKey }`. `coalitionKey` is the affine sum of the signers'
+ * keys (see `computeCoalitionKey`).
+ */
+declare function buildSubmitAttestationArgs(attestation: Attestation, coalitionKey: CoalitionKey, rawValue?: Uint8Array | null): SubmitAttestationArgs;
 
-/** Gateway wire shape — defaults applied before hash / encryption. */
+/**
+ * Aggregation (tolerance mode) config validation and canonicalization.
+ *
+ * `aggregation` is part of the API config and therefore part of `sourceId`. It is OMITTED
+ * for exact mode: a config carrying `mode: "exact"` would hash differently from the same
+ * config without the key, so it is rejected rather than silently normalized. The node
+ * (`new/tolerance.Validate`) is the reference.
+ */
+
+/** Tolerance mode needs at least this many signers (`signaturesRequired >= 3`). */
+declare const MIN_TOLERANCE_SIGNATURES = 3;
+/** Thrown for an unusable `aggregation` config. */
+declare class AggregationConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate an `aggregation` config and return a fresh object with the canonical key order
+ * (`mode`, `rule`, `maxDeviationBps`, `maxAgeMs`, `numeric{type, decimals}`) — the order
+ * the source hash and the node's JSON blob use.
+ *
+ * The result is built field by field: unknown or reordered keys on the input can never
+ * reach the hash or the wire. `undefined` / `null` mean exact mode and return `undefined`.
+ *
+ * @throws {AggregationConfigError} on `mode: "exact"`, an unsupported mode / rule / numeric
+ *   type, or an out-of-range number.
+ */
+declare function canonicalizeAggregation(aggregation: AggregationConfig | null | undefined): AggregationConfig | undefined;
+/**
+ * Tolerance mode needs `signaturesRequired >= 3`; the node rejects anything lower.
+ * A no-op for exact mode (`aggregation` omitted).
+ *
+ * @throws {AggregationConfigError}
+ */
+declare function assertAggregationQuorum(aggregation: AggregationConfig | null | undefined, signaturesRequired: number): void;
+
+/**
+ * Gateway wire shape — defaults applied before hash / encryption.
+ *
+ * Keys are emitted in the fixed order `url`, `method`, `headers`, `responseParser`,
+ * `valueTransform`, `aggregation`; `aggregation` is present only for tolerance mode and its
+ * nested keys are rebuilt in canonical order (`canonicalizeAggregation`), so no extra or
+ * reordered input key can reach the hash. A config without `aggregation` hashes exactly as
+ * before.
+ *
+ * @throws {AggregationConfigError} if `aggregation` is invalid (including `mode: "exact"`).
+ */
 declare function canonicalizeAPIConfig(apiConfig: APIConfig): APIConfig;
 /**
  * `sourceId = keccak256(JSON.stringify(canonical apiConfig))` — the 32-byte identity of a
@@ -516,15 +631,13 @@ declare function canonicalizeAPIConfig(apiConfig: APIConfig): APIConfig;
 declare function deriveSourceId(apiConfig: APIConfig): Uint8Array;
 /** Hex-encoded {@link deriveSourceId} (64 lowercase hex chars, no `0x`). */
 declare function deriveSourceIdString(apiConfig: APIConfig): string;
-/** @deprecated Renamed to {@link deriveSourceId}; identical bytes. */
-declare const deriveApiConfigHash: typeof deriveSourceId;
 
 /**
  * Protocol-wide constants that must stay in sync with the vendored IDL. Kept as plain
  * literals so gateway-only / browser bundles never pull in `idl/molpha.json`.
  */
 /** Molpha program id (`idl/molpha.json` → `address`). Asserted equal in `test/gateway-auth.test.ts`. */
-declare const MOLPHA_PROGRAM_ID = "MoLFnEbuMS5gWnXNfUMLAYSqRM3eQZKWRzjeMQfqbT3";
+declare const MOLPHA_PROGRAM_ID = "chivcFQgxzwkpLvW41PV431HQ4dYpaW3povQH3AdpQt";
 
 declare const utf8: (s: string) => Uint8Array;
 declare const concatBytes: (...arrays: Uint8Array[]) => Uint8Array;
@@ -534,6 +647,8 @@ declare const bytesToHex: (bytes: Uint8Array) => string;
 declare function hexToBytes(hex: string): Uint8Array;
 /** Hex with a leading `0x`. */
 declare const bytesToHex0x: (bytes: Uint8Array) => string;
+/** u8 → 1 byte. Range-checked: `Uint8Array.of` would silently wrap an out-of-range value. */
+declare function u8(value: number): Uint8Array;
 /** Big-endian u32 → 4 bytes. */
 declare function u32be(value: number): Uint8Array;
 /** Little-endian u32 → 4 bytes (used for PDA seeds like the registry index). */
@@ -558,13 +673,37 @@ declare function bytesToBase64(bytes: Uint8Array): string;
 /** Accepts padded or unpadded standard base64. */
 declare function base64ToBytes(value: string): Uint8Array;
 
+/** `2^255 - 1`. */
+declare const INT256_MAX: bigint;
+/** `-2^255`. */
+declare const INT256_MIN: bigint;
+/** Two's-complement `bytes32` (big-endian) of a signed integer in `[-2^255, 2^255)`. */
+declare function encodeInt256(value: bigint): Uint8Array;
+/** Signed integer of a two's-complement `bytes32` (bytes or hex, optional `0x`). */
+declare function decodeInt256(value: Uint8Array | string): bigint;
+/**
+ * Parse an ordinary decimal string (`[+-]digits[.digits]`, no exponent, no whitespace),
+ * scale by `10^decimals`, round half to even, and return the `int256` two's-complement
+ * `bytes32` the nodes sign for a tolerance-mode source.
+ *
+ * @throws {Error} `invalid decimal`, `decimal too long`, or `int256 overflow`.
+ */
+declare function encodeInt256Decimal(decimal: string, decimals: number): Uint8Array;
+/**
+ * Render a signed integer — a two's-complement `bytes32` (bytes or hex), or an already
+ * decoded `bigint` — at the source's scale: `decimals` fractional places with trailing zeros
+ * trimmed (`-1.2`, `42`, `0.00000005`). Inverse of {@link encodeInt256Decimal} up to
+ * rounding.
+ */
+declare function formatInt256Decimal(value: Uint8Array | string | bigint, decimals: number): string;
+
 /** `keccak256("MOLPHA_MESSAGE_V1")` domain separator. */
 declare const MESSAGE_PREFIX: Uint8Array;
 interface AttestationMessageFields {
     /** 32-byte source id (hex or bytes). */
     sourceId: string | Uint8Array;
     registryVersion: number;
-    /** Encoded as `uint32` in the message even though the program stores a `u8`. */
+    /** Encoded as a single byte (`uint8`); throws `RangeError` outside `0..255`. */
     signaturesRequired: number;
     /** 32-byte big-endian signers bitmap (hex or bytes). */
     signersBitmap: string | Uint8Array;
@@ -575,8 +714,8 @@ interface AttestationMessageFields {
 }
 /** Compute the attestation message hash (32 bytes). */
 declare function attestationMessageHash(fields: AttestationMessageFields): Uint8Array;
-/** Message hash of a completed gateway round (`valuePacked` is the signed value). */
-declare function attestationMessageHashFromResult(result: DataUpdateResult): Uint8Array;
+/** Message hash of a completed gateway attestation (`payload.value` is the signed word). */
+declare function attestationMessageHashFromAttestation(attestation: Attestation): Uint8Array;
 
 /**
  * Parse a secp256k1 public key and return canonical compressed lower-case hex.
@@ -648,51 +787,77 @@ type VerifyCode = (typeof VERIFY_CODES)[VerifyCodeName];
 declare function verifyCodeName(code: number): VerifyCodeName | undefined;
 
 /**
- * Minimal Molpha verifier ABI for `verify` and registry reads.
- * Matches the deployed `verify(DataUpdate, SchnorrSignature)` verifier. The first tuple
- * component carries the 32-byte source id (the contract source names it `jobId`;
- * component names do not affect ABI encoding).
+ * Molpha EVM verifier ABI: `verify(Attestation, uint64 maxAge) -> (bool, uint8)` plus every
+ * read-only registry view on `IVerifier`. Owner-only mutators (`addNode`, `removeNode`,
+ * `setRedundancyBuffer`) and `Ownable` plumbing are deliberately left out.
+ *
+ * Mirrors `IVerifier.sol` in `molpha-core-contracts`. Struct member order is ABI-significant
+ * and equals the signed message order, so it is not the flat gateway field order on `Attestation`.
  */
 declare const MOLPHA_VERIFIER_ABI: readonly [{
     readonly type: "function";
     readonly name: "verify";
     readonly stateMutability: "view";
     readonly inputs: readonly [{
-        readonly name: "dataUpdate";
+        readonly name: "attestation";
         readonly type: "tuple";
+        readonly internalType: "struct IVerifier.Attestation";
         readonly components: readonly [{
-            readonly name: "sourceId";
-            readonly type: "bytes32";
-        }, {
-            readonly name: "registryVersion";
-            readonly type: "uint32";
-        }, {
-            readonly name: "signaturesRequired";
-            readonly type: "uint32";
-        }, {
-            readonly name: "value";
-            readonly type: "bytes32";
+            readonly name: "payload";
+            readonly type: "tuple";
+            readonly internalType: "struct IVerifier.AttestationPayload";
+            readonly components: readonly [{
+                readonly name: "value";
+                readonly type: "bytes32";
+                readonly internalType: "bytes32";
+            }, {
+                readonly name: "sourceId";
+                readonly type: "bytes32";
+                readonly internalType: "bytes32";
+            }, {
+                readonly name: "registryVersion";
+                readonly type: "uint32";
+                readonly internalType: "uint32";
+            }, {
+                readonly name: "signaturesRequired";
+                readonly type: "uint8";
+                readonly internalType: "uint8";
+            }, {
+                readonly name: "canonicalTimestamp";
+                readonly type: "uint64";
+                readonly internalType: "uint64";
+            }];
         }, {
-            readonly name: "canonicalTimestamp";
-            readonly type: "uint64";
-        }];
-    }, {
-        readonly name: "schnorrData";
-        readonly type: "tuple";
-        readonly components: readonly [{
             readonly name: "signature";
-            readonly type: "bytes32";
-        }, {
-            readonly name: "commitment";
-            readonly type: "address";
-        }, {
-            readonly name: "signersBitmap";
-            readonly type: "uint256";
+            readonly type: "tuple";
+            readonly internalType: "struct IVerifier.SchnorrSignature";
+            readonly components: readonly [{
+                readonly name: "signature";
+                readonly type: "bytes32";
+                readonly internalType: "bytes32";
+            }, {
+                readonly name: "commitment";
+                readonly type: "address";
+                readonly internalType: "address";
+            }, {
+                readonly name: "signersBitmap";
+                readonly type: "uint256";
+                readonly internalType: "uint256";
+            }];
         }];
+    }, {
+        readonly name: "maxAge";
+        readonly type: "uint64";
+        readonly internalType: "uint64";
     }];
     readonly outputs: readonly [{
-        readonly name: "";
+        readonly name: "success";
         readonly type: "bool";
+        readonly internalType: "bool";
+    }, {
+        readonly name: "code";
+        readonly type: "uint8";
+        readonly internalType: "uint8";
     }];
 }, {
     readonly type: "function";
@@ -702,7 +867,150 @@ declare const MOLPHA_VERIFIER_ABI: readonly [{
     readonly outputs: readonly [{
         readonly name: "registryVersion";
         readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "getTotalNodes";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "totalNodes";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
     }];
+}, {
+    readonly type: "function";
+    readonly name: "redundancyBuffer";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "getRegistryRoot";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "root";
+        readonly type: "bytes32";
+        readonly internalType: "bytes32";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "getRegistryRoot";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "registryVersion";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "root";
+        readonly type: "bytes32";
+        readonly internalType: "bytes32";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "getRegistryPointer";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "registryPointer";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "getRegistryPointer";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "registryVersion";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "registryPointer";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "activatesAt";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "registryVersion";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "ts";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "retiredAt";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "registryVersion";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "ts";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "isLatestVersion";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "registryVersion";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "latest";
+        readonly type: "bool";
+        readonly internalType: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "nodeStatus";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "node";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint8";
+        readonly internalType: "uint8";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "isNode";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "node";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+        readonly internalType: "bool";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "InvalidRegistryVersion";
+    readonly inputs: readonly [];
 }];
 
 /**
@@ -748,23 +1056,63 @@ declare function evmAddressFromPrivateKey(privateKey: string | Uint8Array): stri
  */
 declare function createEvmSignerFromPrivateKey(privateKey: string | Uint8Array): EvmSigner;
 
-/** `(bytes32 sourceId, uint32 registryVersion, uint32 signaturesRequired, bytes32 valuePacked, uint64 timestamp)` */
-type EvmDataUpdateTuple = readonly [
-    sourceId: `0x${string}`,
-    registryVersion: number,
-    signaturesRequired: number,
-    valuePacked: `0x${string}`,
-    timestamp: number
-];
-/** `(bytes32 s, address commitment, uint256 signersBitmap)` */
-type EvmSchnorrSignatureTuple = readonly [
-    s: `0x${string}`,
-    commitment: `0x${string}`,
-    signersBitmap: bigint
-];
+/**
+ * `IVerifier.AttestationPayload` — the signed half of an attestation.
+ *
+ * Member order is the order of the signed message preimage and of the ABI tuple, so it is
+ * load bearing — it is not the flat gateway field order on {@link Attestation}.
+ */
+interface EvmAttestationPayload {
+    /** `bytes32` packed value. */
+    value: `0x${string}`;
+    /** `bytes32` source id. */
+    sourceId: `0x${string}`;
+    /** `uint32`. */
+    registryVersion: number;
+    /** `uint8`. */
+    signaturesRequired: number;
+    /** `uint64`, unix seconds. */
+    canonicalTimestamp: bigint;
+}
+/** `IVerifier.SchnorrSignature`. */
+interface EvmSchnorrSignature {
+    /** `bytes32` Schnorr scalar `s`. */
+    signature: `0x${string}`;
+    /** `address` of the nonce point `R`. */
+    commitment: `0x${string}`;
+    /** `uint256` signers bitmap; bit `i` is node `i` of the registry version. */
+    signersBitmap: bigint;
+}
+/** `IVerifier.Attestation`. */
+interface EvmAttestation {
+    payload: EvmAttestationPayload;
+    signature: EvmSchnorrSignature;
+}
+/** Positional arguments for `verify(attestation, maxAge)`. */
 interface EvmVerifierArgs {
-    dataUpdate: EvmDataUpdateTuple;
-    signature: EvmSchnorrSignatureTuple;
+    attestation: EvmAttestation;
+    /** Freshness window in seconds (`uint64`). `0n` disables the check. */
+    maxAge: bigint;
+}
+interface BuildEvmVerifierArgsOptions {
+    /**
+     * Freshness window in seconds. The verifier rejects the attestation with `STALE` when it
+     * is older than this, and as `MALFORMED` when it is dated in the future.
+     *
+     * Required on purpose. `0` disables the check entirely, and that is not a neutral
+     * default: the verifier is stateless, so without a window it accepts a correctly signed
+     * attestation forever. Pass `0` only when the consuming contract enforces freshness or
+     * ordering itself.
+     */
+    maxAge: number | bigint;
+}
+/** Decoded `verify` return value. */
+interface EvmVerifyResult {
+    success: boolean;
+    /** Raw result code — see `VERIFY_CODES`. */
+    code: number;
+    /** Name of `code`, or `"UNKNOWN"` for a code newer than this SDK. */
+    reason: VerifyCodeName | "UNKNOWN";
 }
 /**
  * Normalize hex to a fixed-size `0x`-prefixed value.
@@ -773,10 +1121,39 @@ interface EvmVerifierArgs {
 declare function toFixedHex(value: string, bytes: number, label: string): `0x${string}`;
 /** Convert a 32-byte hex bitmap to a `uint256` bigint (big-endian). */
 declare function signersBitmapToUint256(value: string): bigint;
-/** Build verifier `DataUpdate` and `SchnorrSignature` tuples from a gateway result. */
-declare function buildEvmVerifierArgs(result: DataUpdateResult): EvmVerifierArgs;
-/** Decimal string form of the signers bitmap — useful for JSON logging or legacy tooling. */
+/** Decimal string form of the signers bitmap — useful for JSON logging. */
 declare function signersBitmapToDecimal(value: string): string;
+/**
+ * Build the `verify(attestation, maxAge)` arguments from a gateway result.
+ *
+ * ```ts
+ * const { attestation, maxAge } = buildEvmVerifierArgs(result, { maxAge: 300 });
+ * await client.readContract({ abi: MOLPHA_VERIFIER_ABI, functionName: "verify", args: [attestation, maxAge], ... });
+ * ```
+ */
+declare function buildEvmVerifierArgs(attestation: Attestation, options: BuildEvmVerifierArgsOptions): EvmVerifierArgs;
+/**
+ * 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,
+ *  commitment, signersBitmap, maxAge`
+ *
+ * For a raw `eth_call` (`{ to: verifier, data }`).
+ */
+declare function encodeEvmVerifyCalldata(args: EvmVerifierArgs): `0x${string}`;
+/**
+ * Decode the `(bool, uint8)` returned by `verify`.
+ *
+ * Accepts the raw 64-byte return data from `eth_call`, or the tuple an ABI-aware client
+ * decodes (viem `readContract` returns `[true, 0]`; an ethers `Result` indexes the same way).
+ * Throws when the two halves disagree (`success` with a non-zero code, or failure with
+ * `OK`), which means the call did not reach a Molpha verifier of this interface.
+ */
+declare function parseEvmVerifyResult(result: string | {
+    readonly 0: boolean | number | bigint;
+    readonly 1: number | bigint;
+}): EvmVerifyResult;
 
 /**
  * Deployed Molpha verifier contract addresses on Starknet testnets.
@@ -794,7 +1171,7 @@ declare function getMolphaStarknetVerifierAddress(network: MolphaStarknetNetwork
  * Starknet calldata shape for `AttestationPayload`.
  *
  * Member order is the order of the signed message preimage and of Cairo `Serde`, so it is
- * load bearing — it is not the order of `DataUpdateResult`.
+ * load bearing — it is not the flat gateway field order on {@link Attestation}.
  */
 interface StarknetAttestationPayload {
     /** 32-byte packed value as `u256`. */
@@ -861,7 +1238,7 @@ declare function signersBitmapToStarknetUint256(value: string): bigint;
  * const { attestation, maxAge } = buildStarknetVerifierArgs(result, { maxAge: 300 });
  * ```
  */
-declare function buildStarknetVerifierArgs(result: DataUpdateResult, options: BuildStarknetVerifierArgsOptions): StarknetVerifierArgs;
+declare function buildStarknetVerifierArgs(attestation: Attestation, options: BuildStarknetVerifierArgsOptions): StarknetVerifierArgs;
 /**
  * Flat felt calldata for `verify(attestation, max_age)`, in Cairo `Serde` order — 13 felts:
  *
@@ -896,10 +1273,11 @@ declare const registryStatePda: (programId: SolanaAddress) => Address;
 /** Immutable, version-addressed registry snapshot: `["molpha_registry", version u32 LE]`. */
 declare const registryPda: (version: number, programId: SolanaAddress) => Address;
 /**
- * Owner-keyed `Node` account: `["molpha_node", owner]`. Registry snapshots store these
- * addresses directly in `nodes[i]`, so consumers rarely need to derive them.
+ * Authority-keyed `Node` account: `["molpha_node", authority]` (`Node.authority`). Registry
+ * snapshots store these addresses directly in `nodes[i]`, so consumers rarely need to
+ * derive them.
  */
-declare const nodePda: (owner: SolanaAddress, programId: SolanaAddress) => Address;
+declare const nodePda: (authority: SolanaAddress, programId: SolanaAddress) => Address;
 /** Bonded gateway account: `["molpha_gateway", gatewayAuthority]` — the `gateway` bound into `RequestAuth`. */
 declare const gatewayPda: (authority: SolanaAddress, programId: SolanaAddress) => Address;
 /** Plan PDA is `[b"molpha_plan", [planType as u8]]`. */
@@ -958,10 +1336,10 @@ declare class MolphaSDK {
      * on-chain registry version) and submit it via `submit_attestation`.
      */
     requestAndSubmit(opts: RequestSignedDataOptions): Promise<{
-        result: DataUpdateResult;
+        result: Attestation;
         signature: string;
         feed: Address;
     }>;
 }
 
-export { APIConfig, AssetDomain, type AttestationMessageFields, type BuildStarknetVerifierArgsOptions, DEFAULT_GATEWAY_ENDPOINT, DataUpdateResult, EIP712_DOMAIN_TYPEHASH, type Eip712Domain, type EvmDataUpdateTuple, type EvmSchnorrSignatureTuple, EvmSigner, type EvmVerifierArgs, type FeedAccount, type GatewayEndpoint, type GatewayEndpointInput, GatewayError, type GatewayInfo, MESSAGE_PREFIX, 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, Signer, SourcePaymentOptions, type StarknetAttestation, type StarknetAttestationPayload, type StarknetFeltLike, type StarknetSchnorrSignature, type StarknetVerifierArgs, type StarknetVerifyResult, type SubmitAttestationArgs, type SubmitResult, type SubscribeResult, type SubscriptionInfo, TRANSFER_WITH_AUTHORIZATION_TYPEHASH, type TransferAuthorization, UpstreamPaymentRequiredError, UpstreamQuote, UpstreamTerms, VERIFY_CODES, type VerifyCode, type VerifyCodeName, addressToBytes, attestationMessageHash, attestationMessageHashFromResult, base64ToBytes, bigIntFromBytesBe, bitmapBitSet, bitmapToIndices, buildEvmVerifierArgs, buildStarknetVerifierArgs, buildSubmitAttestationArgs, bytesToBase64, bytesToHex, bytesToHex0x, canonicalizeAPIConfig, commitmentAddressToStarknetFelt, concatBytes, createEvmSignerFromPrivateKey, deriveApiConfigHash, deriveGatewayPda, deriveGatewayPdaAddress, deriveGroupBitmap, deriveSelectionBitmap, deriveSelectionSeed, deriveSourceId, deriveSourceIdString, domainSeparator, effectiveSelectionSize, eligibleSetSize, encodeRequestAuth, encodeStarknetVerifyCalldata, ensureLength, evmAddressFromPrivateKey, feedPda, gatewayPda, getMolphaStarknetVerifierAddress, hashRequestAuth, hexToBytes, nodePda, normalizeEndpoint, normalizeSecp256k1PublicKeyHex, 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, utf8, validateSuppliedTerms, verifyCodeName };
+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 };