@molpha/sdk 0.1.0

package/dist/chunk-MFELBWSL.js

@@ -0,0 +1,51 @@
+import { web3 } from '@anchor-lang/core';
+import { address, getAddressEncoder } from '@solana/kit';
+import { ed25519 } from '@noble/curves/ed25519.js';
+
+// src/solana/kit.ts
+var TOKEN_PROGRAM_ADDRESS = address("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");
+var ASSOCIATED_TOKEN_PROGRAM_ADDRESS = address(
+  "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL"
+);
+var SYSTEM_PROGRAM_ADDRESS = address("11111111111111111111111111111111");
+var addressEncoder = getAddressEncoder();
+function toSolanaAddress(value) {
+  return address(typeof value === "string" ? value : value.toBase58());
+}
+function toPublicKey(value) {
+  return value instanceof web3.PublicKey ? value : new web3.PublicKey(value);
+}
+function addressBytes(value) {
+  return Uint8Array.from(addressEncoder.encode(toSolanaAddress(value)));
+}
+function findProgramAddressSync(seeds, programAddress) {
+  const [pda] = web3.PublicKey.findProgramAddressSync(seeds, toPublicKey(programAddress));
+  return toSolanaAddress(pda);
+}
+function getAssociatedTokenAddressSync(mint, owner, tokenProgram = TOKEN_PROGRAM_ADDRESS) {
+  return findProgramAddressSync(
+    [addressBytes(owner), addressBytes(tokenProgram), addressBytes(mint)],
+    ASSOCIATED_TOKEN_PROGRAM_ADDRESS
+  );
+}
+function setComputeUnitLimit(units) {
+  return web3.ComputeBudgetProgram.setComputeUnitLimit({ units });
+}
+function keypairFromSecretKey(secretKey) {
+  return web3.Keypair.fromSecretKey(secretKey);
+}
+var isKeypair = (value) => typeof value === "object" && value !== null && "secretKey" in value && value.secretKey instanceof Uint8Array;
+function signerFromKeypair(keypair) {
+  const seed = keypair.secretKey.slice(0, 32);
+  return async (message) => ed25519.sign(message, seed);
+}
+function gatewaySignerFromWallet(wallet) {
+  const molpha = wallet;
+  if (molpha.signAuthMessage) return molpha.signAuthMessage;
+  if ("payer" in wallet && isKeypair(wallet.payer)) return signerFromKeypair(wallet.payer);
+  return void 0;
+}
+
+export { SYSTEM_PROGRAM_ADDRESS, TOKEN_PROGRAM_ADDRESS, addressBytes, findProgramAddressSync, gatewaySignerFromWallet, getAssociatedTokenAddressSync, keypairFromSecretKey, setComputeUnitLimit, signerFromKeypair, toPublicKey, toSolanaAddress };
+//# sourceMappingURL=chunk-MFELBWSL.js.map
+//# sourceMappingURL=chunk-MFELBWSL.js.map

package/dist/chunk-MFELBWSL.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/solana/kit.ts","../src/wallet.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;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;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,qBAAqB,SAAA,EAAsC;AACzE,EAAA,OAAO,IAAA,CAAK,OAAA,CAAQ,aAAA,CAAc,SAAS,CAAA;AAC7C;ACjDA,IAAM,SAAA,GAAY,CAAC,KAAA,KACjB,OAAO,KAAA,KAAU,QAAA,IACjB,KAAA,KAAU,IAAA,IACV,WAAA,IAAe,KAAA,IACf,KAAA,CAAM,SAAA,YAAqB,UAAA;AAGtB,SAAS,kBAAkB,OAAA,EAAgC;AAChE,EAAA,MAAM,IAAA,GAAO,OAAA,CAAQ,SAAA,CAAU,KAAA,CAAM,GAAG,EAAE,CAAA;AAC1C,EAAA,OAAO,OAAO,OAAA,KAA6C,OAAA,CAAQ,IAAA,CAAK,SAAS,IAAI,CAAA;AACvF;AAGO,SAAS,wBAAwB,MAAA,EAAoC;AAC1E,EAAA,MAAM,MAAA,GAAS,MAAA;AACf,EAAA,IAAI,MAAA,CAAO,eAAA,EAAiB,OAAO,MAAA,CAAO,eAAA;AAC1C,EAAA,IAAI,OAAA,IAAW,UAAU,SAAA,CAAU,MAAA,CAAO,KAAK,CAAA,EAAG,OAAO,iBAAA,CAAkB,MAAA,CAAO,KAAK,CAAA;AACvF,EAAA,OAAO,MAAA;AACT","file":"chunk-MFELBWSL.js","sourcesContent":["import { web3 } from \"@anchor-lang/core\";\nimport { address, 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();\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\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 keypairFromSecretKey(secretKey: Uint8Array): SolanaKeypair {\n  return web3.Keypair.fromSecretKey(secretKey);\n}\n\nexport function generateKeypair(): SolanaKeypair {\n  return web3.Keypair.generate();\n}\n","/**\n * Unified wallet surface: Anchor txs + optional gateway authSig signing.\n */\nimport type { Wallet } from \"@anchor-lang/core\";\nimport { ed25519 } from \"@noble/curves/ed25519.js\";\nimport type { Signer } from \"./core/types.js\";\nimport type { SolanaKeypair } from \"./solana/kit.js\";\n\n/** Anchor `Wallet` plus optional gateway auth override. */\nexport type MolphaWallet = Wallet & {\n  /**\n   * Signs gateway `authMessage` payloads. When omitted, derived from Anchor\n   * `Wallet.payer` when the keypair secret is available (Node `Wallet`, etc.).\n   */\n  signAuthMessage?: Signer;\n};\n\nconst isKeypair = (value: unknown): value is SolanaKeypair =>\n  typeof value === \"object\" &&\n  value !== null &&\n  \"secretKey\" in value &&\n  value.secretKey instanceof Uint8Array;\n\n/** ed25519 gateway signer from a Solana keypair's 32-byte seed. */\nexport function signerFromKeypair(keypair: SolanaKeypair): Signer {\n  const seed = keypair.secretKey.slice(0, 32);\n  return async (message: Uint8Array): Promise<Uint8Array> => ed25519.sign(message, seed);\n}\n\n/** Resolve the gateway auth signer for a Molpha wallet, if available. */\nexport function gatewaySignerFromWallet(wallet: Wallet): Signer | undefined {\n  const molpha = wallet as MolphaWallet;\n  if (molpha.signAuthMessage) return molpha.signAuthMessage;\n  if (\"payer\" in wallet && isKeypair(wallet.payer)) return signerFromKeypair(wallet.payer);\n  return undefined;\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,584 @@
+import { Address } from '@solana/kit';
+import { Wallet, Idl, AnchorProvider } from '@anchor-lang/core';
+import { R as RegistrySelectionConfig, S as Signer, N as NodeKeyVerifier, a as Node, A as APIConfig, D as DataUpdateResult, b as SolanaConnection, c as SolanaAddress, d as NodeKeyVerifierArgs, e as SolanaAccountMeta, M as MolphaWallet } from './wallet-CbpYQO4l.js';
+export { E as EncKeyBundle, f as SchnorrSignature, g as gatewaySignerFromWallet, s as signerFromKeypair } from './wallet-CbpYQO4l.js';
+import BN from 'bn.js';
+
+interface RequestSignedDataOptions {
+    feedId: string;
+    signaturesRequired: number;
+    apiConfig: APIConfig;
+    /**
+     * Solana pubkey (base58) of the subscription owner.
+     * Overrides the gateway's `defaultSubscriptionOwner` when set.
+     */
+    subscriptionOwner?: string;
+    /**
+     * Solana pubkey (base58) of the consumer authority that signs gateway auth.
+     * Overrides the gateway's `defaultConsumerAuthority` when set.
+     */
+    consumerAuthority?: string;
+    /**
+     * Signs `authMessage(feedId, timestamp)`. Overrides the gateway's
+     * `defaultSigner` when set. When both are omitted, sends all-zero authSig
+     * (dev only).
+     */
+    signer?: Signer;
+    encrypt?: {
+        secrets: Record<string, string>;
+    };
+    /** Max accepted value age in seconds. Default 60. */
+    maxAge?: number;
+    /** Each retry re-rolls the timestamp. Default 15. */
+    maxRetries?: number;
+    /** Per-request timeout in ms. Default 5000. */
+    timeoutMs?: number;
+    /**
+     * Pre-fetched round inputs. Any field present here skips its network/on-chain
+     * fetch, so a fully-populated context turns `requestSignedData` into a single
+     * POST round (the "short" flow). Build a reusable one with
+     * {@link MolphaGateway.prepareContext}.
+     *
+     * Caching is opt-in because these inputs can drift: a stale `registryVersion`,
+     * `redundancyBuffer`, or `nodes` set produces a result the chain will reject.
+     * Refresh the context when the on-chain registry version changes.
+     */
+    context?: Partial<RoundContext>;
+    /**
+     * Authenticates selected gateway node encryption keys before private API
+     * secrets are encrypted. Overrides the gateway-level verifier when set.
+     */
+    verifyNodeKeys?: NodeKeyVerifier;
+    /**
+     * Unsafe development escape hatch for standalone gateway usage. When true,
+     * encrypted private API requests may use gateway-provided node keys without
+     * authentication. Defaults to false.
+     */
+    allowUnverifiedNodeKeysForPrivateApi?: boolean;
+}
+interface MolphaGatewayOptions {
+    /** Solana pubkey (base58) of the subscription owner used when a request omits it. */
+    defaultSubscriptionOwner?: string;
+    /** Solana pubkey (base58) of the consumer authority used when a request omits it. */
+    defaultConsumerAuthority?: string;
+    /**
+     * Authenticates selected gateway node encryption keys before private API
+     * secrets are encrypted.
+     */
+    verifyNodeKeys?: NodeKeyVerifier;
+    /**
+     * Unsafe development escape hatch. When true, encrypted private API requests
+     * may use gateway-provided node keys without authentication. Defaults to false.
+     */
+    allowUnverifiedNodeKeysForPrivateApi?: boolean;
+}
+/**
+ * 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 derive the selection bitmap. */
+    nodes: Node[];
+}
+/** 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. */
+declare class GatewayError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+declare class MolphaGateway {
+    private readonly endpoints;
+    private readonly getRegistrySelectionConfig;
+    private readonly defaultSigner?;
+    private readonly defaultSubscriptionOwner?;
+    private readonly defaultConsumerAuthority?;
+    private readonly verifyNodeKeys?;
+    private readonly allowUnverifiedNodeKeysForPrivateApi;
+    constructor(endpoints?: string | string[], 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.
+     */
+    defaultSubscriptionOwnerOrOptions?: string | MolphaGatewayOptions, defaultConsumerAuthority?: string);
+    /** Tries endpoints in order; returns the first node list it can fetch. */
+    getNodes(): Promise<Node[]>;
+    isHealthy(): Promise<boolean>;
+    /**
+     * Fetch the slow-changing round inputs (registry version, redundancy buffer,
+     * node set) once so they can be reused across many {@link requestSignedData}
+     * calls. Pass the result back via `requestSignedData({ ..., context })` to
+     * skip the prelude and run a single-round "short" flow.
+     *
+     * Both fetches run in parallel. Registry version and redundancy buffer come
+     * from a single on-chain `RegistryState` read.
+     */
+    prepareContext(_feedId: string): 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.
+     *
+     * By default this fetches the registry selection config and node set up front
+     * (in parallel). Supply `opts.context` (e.g. from {@link prepareContext}) to
+     * reuse cached inputs and skip those fetches — a fully-populated context
+     * collapses the call to a single POST round.
+     */
+    requestSignedData(opts: RequestSignedDataOptions): Promise<DataUpdateResult>;
+    /**
+     * Resolve the round inputs, fetching only the fields absent from `cached`.
+     * Registry version and redundancy buffer are treated as a unit (one account
+     * read). Whatever fetching remains runs in parallel.
+     */
+    private resolveContext;
+    private firstReachableData;
+    private post;
+}
+
+/** On-chain subscription plan (`PlanType` in the Molpha program IDL). */
+declare enum PlanType {
+    Basic = 0
+}
+/** Numeric plan index used for PDA derivation and on-chain reads. */
+type PlanId = 0 | 1 | 2 | 3;
+declare const PLAN_VARIANTS: readonly [{
+    readonly basic: {};
+}, {
+    readonly standard: {};
+}, {
+    readonly professional: {};
+}, {
+    readonly enterprise: {};
+}];
+declare function planVariant(planId: PlanId): (typeof PLAN_VARIANTS)[number];
+declare function planIdFromVariant(variant: Record<string, unknown>): PlanId;
+
+/**
+ * `MolphaSolanaClient` — consumer on-chain surface only (subscribe, extend,
+ * submitDataUpdate, readFeed/readPlan/readSubscription,
+ * getRegistrySelectionConfig, verifyNodeKeysForPrivateApi). Built from an
+ * Anchor `Program` over the vendored IDL.
+ */
+
+type Commitment$1 = NonNullable<ConstructorParameters<typeof AnchorProvider>[2]>["commitment"];
+interface SubscribeResult {
+    signature: string;
+    /** USDC base units actually debited from the owner for this subscription. */
+    pricePaid: bigint;
+}
+interface PlanInfo {
+    planType: PlanType;
+    /** Subscription price in USDC base units (raw u64, e.g. 1_000_000 = 1 USDC at 6 decimals). */
+    subscriptionPrice: bigint;
+    maxSigners: number;
+    maxDelegates: number;
+    privateApiEnabled: boolean;
+    isActive: boolean;
+}
+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;
+    maxRounds: bigint;
+    delegateCount: number;
+    maxDelegates: number;
+    maxSigners: number;
+}
+interface SubmitResult {
+    signature: string;
+}
+interface FeedAccount {
+    feedId: number[];
+    value: number[];
+    valueKind: {
+        value: Record<string, never>;
+    } | {
+        hash: Record<string, never>;
+    };
+    canonicalTimestamp: BN;
+    signaturesRequired: number;
+    signersBitmap: number[];
+    registryVersion: number;
+    bump: number;
+}
+interface CreateClientOpts {
+    connection: SolanaConnection;
+    wallet: Wallet;
+    programId?: SolanaAddress;
+    idl?: Idl;
+    commitment?: Commitment$1;
+}
+declare class MolphaSolanaClient {
+    private readonly program;
+    private readonly provider;
+    readonly programId: Address;
+    private constructor();
+    static create(opts: CreateClientOpts): MolphaSolanaClient;
+    private get wallet();
+    /** Anchor's method/account namespaces are untyped without an IDL type param. */
+    private get methods();
+    private get accounts();
+    /**
+     * Current registry version and selection `redundancy_buffer` from a single
+     * `RegistryState` account read. Prefer this over {@link getRegistryVersion}
+     * when deriving gateway selection bitmaps.
+     */
+    getRegistrySelectionConfig(): Promise<RegistrySelectionConfig>;
+    getRegistryVersion(): Promise<number>;
+    /** Fetch a plan's on-chain terms, including the USDC `subscriptionPrice` charged on `subscribe`. */
+    getPlan(plan: PlanType): Promise<PlanInfo>;
+    /** Read a plan account, or `null` if it has not been initialized. */
+    readPlan(plan: PlanType): Promise<PlanInfo | null>;
+    /** Read an owner's subscription, or `null` if they have not subscribed. */
+    readSubscription(owner?: SolanaAddress): Promise<SubscriptionInfo | null>;
+    /**
+     * Subscribe to a plan. This **debits USDC** from the owner: the plan's
+     * `subscriptionPrice` is transferred to the protocol treasury on-chain.
+     *
+     * Payment is explicit and must be confirmed: pass `maxPriceUsdc` (USDC base
+     * units) as the most you agree to pay. The SDK reads the live on-chain price
+     * and aborts before sending the transaction if it exceeds that amount, so a
+     * price change between display and confirmation can never silently overcharge.
+     * The amount actually paid is returned as `pricePaid`.
+     *
+     * Use {@link getPlan} to display the current price to the user beforehand.
+     */
+    subscribe(plan: PlanType, opts: {
+        maxPriceUsdc: bigint | number | BN;
+        ownerUsdc?: SolanaAddress;
+    }): Promise<SubscribeResult>;
+    /**
+     * Extend the current subscription for another period. Like {@link subscribe}
+     * this **debits USDC** (the plan's `subscriptionPrice`) and requires explicit
+     * payment confirmation via `maxPriceUsdc`.
+     */
+    extendSubscription(opts: {
+        maxPriceUsdc: bigint | number | BN;
+        ownerUsdc?: SolanaAddress;
+    }): Promise<SubscribeResult>;
+    /**
+     * Read the live on-chain plan price and verify it does not exceed the amount
+     * the caller agreed to pay. Returns the price (USDC base units) on success.
+     */
+    private confirmPlanPrice;
+    submitDataUpdate(result: DataUpdateResult, opts?: {
+        computeUnitLimit?: number;
+    }): Promise<SubmitResult>;
+    readFeed(feedId: string): Promise<FeedAccount | null>;
+    /**
+     * Authenticate gateway-provided private API encryption keys against the
+     * on-chain Node accounts for the round's registry version.
+     */
+    verifyNodeKeysForPrivateApi(args: NodeKeyVerifierArgs): Promise<void>;
+    private buildSubmitArgs;
+    private decodePlan;
+    private fetchRegistry;
+    private fetchNodeAccount;
+    private fetchProtocolTokens;
+}
+
+/** Gateway wire shape — defaults applied before hash / encryption. */
+declare function canonicalizeAPIConfig(apiConfig: APIConfig): APIConfig;
+/**
+ * `apiConfigHash = keccak256(JSON.stringify(canonical apiConfig))`.
+ * Pass the same config (including `{{secret.*}}` placeholders) you will send to
+ * `MolphaGateway.requestSignedData` when deriving a feed id.
+ */
+declare function deriveApiConfigHash(apiConfig: APIConfig): Uint8Array;
+
+declare const utf8: (s: string) => Uint8Array;
+declare const concatBytes: (...arrays: Uint8Array[]) => Uint8Array;
+/** Lower-case hex, no `0x` prefix. */
+declare const bytesToHex: (bytes: Uint8Array) => string;
+/** Accepts an optional leading `0x`; case-insensitive. */
+declare function hexToBytes(hex: string): Uint8Array;
+/** Hex with a leading `0x`. */
+declare const bytesToHex0x: (bytes: Uint8Array) => string;
+/** Big-endian u32 → 4 bytes. */
+declare function u32be(value: number): Uint8Array;
+/** Little-endian u32 → 4 bytes (used for PDA seeds like the registry index). */
+declare function u32le(value: number): Uint8Array;
+/** Big-endian u64 → 8 bytes. Accepts `number` or `bigint`. */
+declare function u64be(value: number | bigint): Uint8Array;
+/** Little-endian u64 → 8 bytes. Accepts `number` or `bigint`. */
+declare function u64le(value: number | bigint): Uint8Array;
+/** Big-endian 32-byte word ← bigint (0 ≤ v < 2^256). */
+declare function u256beFromBigInt(value: bigint): Uint8Array;
+/** bigint ← big-endian byte word (any length). */
+declare function bigIntFromBytesBe(bytes: Uint8Array): bigint;
+/** Throw unless `bytes.length === len`. Returns the input for chaining. */
+declare function ensureLength(bytes: Uint8Array, len: number, label: string): Uint8Array;
+/** Coerce hex string or bytes to a fixed-length byte array. */
+declare function toFixedBytes(value: string | Uint8Array, len: number, label: string): Uint8Array;
+
+/**
+ * `feedId = keccak256(FEED_ID_PREFIX || owner || apiConfigHash || [signaturesRequired])`.
+ * @param owner 32-byte owner pubkey.
+ * @param apiConfigHash 32-byte API config hash.
+ * @param signaturesRequired Per-feed quorum threshold (u8 on-chain).
+ */
+declare function deriveFeedId(owner: Uint8Array, apiConfigHash: Uint8Array, signaturesRequired: number): Uint8Array;
+/** Hex-encoded `deriveFeedId` (64 lowercase hex chars). */
+declare function deriveFeedIdString(owner: Uint8Array, apiConfigHash: Uint8Array, signaturesRequired: number): string;
+
+/**
+ * Parse a secp256k1 public key and return canonical compressed lower-case hex.
+ * Accepts compressed or uncompressed SEC1 public keys with an optional `0x`.
+ */
+declare function normalizeSecp256k1PublicKeyHex(publicKeyHex: string, label?: string): string;
+/** Reconstruct a compressed secp256k1 public key from 32-byte affine X/Y coordinates. */
+declare function secp256k1PublicKeyFromCoordinates(x: Uint8Array, y: Uint8Array, label?: string): string;
+
+/**
+ * `seed = keccak256(keccak256("MOLPHA_SELECTION_V1") || feedId || be32(rv) || be64(ts))`.
+ */
+declare function deriveSelectionSeed(feedId: Uint8Array, registryVersion: number, canonicalTimestamp: 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`? */
+declare function bitmapBitSet(bitmap: Uint8Array, bit: number): boolean;
+/** Indices of set bits in `[0, nodeCount)`, ascending. */
+declare function selectedIndices(bitmap: Uint8Array, nodeCount: number): number[];
+/**
+ * Rejection-sample `groupSize` distinct indices out of `nodeCount` from `seed`,
+ * returning a 32-byte big-endian bitmap. Uses the complement optimization when
+ * `groupSize > nodeCount / 2` (sample the smaller set, then invert).
+ */
+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.
+ */
+declare function deriveSelectionBitmap(feedId: Uint8Array, registryVersion: number, nodeCount: number, signaturesRequired: number, redundancy?: number, ts?: number | bigint): Uint8Array;
+
+/**
+ * Minimal Molpha verifier ABI for `verify` and registry reads.
+ * Matches `IValidator` in the Molpha EVM contracts repo.
+ */
+declare const MOLPHA_VERIFIER_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "verify";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "dataUpdate";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "jobId";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "registryVersion";
+            readonly type: "uint32";
+        }, {
+            readonly name: "signaturesRequired";
+            readonly type: "uint32";
+        }, {
+            readonly name: "value";
+            readonly type: "bytes32";
+        }, {
+            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 outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "getRegistryVersion";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "registryVersion";
+        readonly type: "uint256";
+    }];
+}];
+
+/**
+ * Deployed Molpha verifier contract address on EVM chains.
+ * Deployed via CREATE2 for the same address on every supported chain.
+ */
+/** Supported EVM testnet identifiers (chain selection only). */
+type MolphaEvmNetwork = "evm-sepolia" | "arbitrum-sepolia" | "avalanche-fuji" | "bsc-testnet";
+/** CREATE2 Molpha verifier address — identical on all supported EVM chains. */
+declare const MOLPHA_VERIFIER_ADDRESS: "0xE1fd792b7E54e0C8F0Cd1c8055E446ff36d233eB";
+
+/** `(bytes32 feedId, uint32 registryVersion, uint32 signaturesRequired, bytes32 valuePacked, uint64 timestamp)` */
+type EvmDataUpdateTuple = readonly [
+    feedId: `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
+];
+interface EvmVerifierArgs {
+    dataUpdate: EvmDataUpdateTuple;
+    signature: EvmSchnorrSignatureTuple;
+}
+/**
+ * Normalize hex to a fixed-size `0x`-prefixed value.
+ * Accepts optional `0x` prefix and surrounding quotes.
+ */
+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. */
+declare function signersBitmapToDecimal(value: string): string;
+
+/**
+ * Deployed Molpha verifier contract addresses on Starknet testnets.
+ */
+/** Supported Starknet testnet identifiers. */
+type MolphaStarknetNetwork = "starknet-sepolia";
+/** Deployed verifier address on Starknet Sepolia. */
+declare const MOLPHA_VERIFIER_STARKNET_SEPOLIA: "0x0378df4dbecf8f0c7daa801282932f7011c7a5e5773bab9eaf68f5fa5e7530ef";
+/** Network id -> deployed verifier address. */
+declare const MOLPHA_VERIFIER_STARKNET_ADDRESSES: Record<MolphaStarknetNetwork, `0x${string}`>;
+/** Resolve the deployed verifier address for a supported Starknet network. */
+declare function getMolphaStarknetVerifierAddress(network: MolphaStarknetNetwork): `0x${string}`;
+
+/** Starknet calldata shape for `DataUpdate`. */
+interface StarknetDataUpdate {
+    feed_id: bigint;
+    registry_version: number;
+    signatures_required: number;
+    value: bigint;
+    canonical_timestamp: number;
+}
+/** Starknet calldata shape for `SchnorrSignature`. */
+interface StarknetSchnorrSignature {
+    signature: bigint;
+    commitment: bigint;
+    signers_bitmap: bigint;
+}
+interface StarknetVerifierArgs {
+    dataUpdate: StarknetDataUpdate;
+    signature: StarknetSchnorrSignature;
+}
+/** Convert a 20-byte EVM-style address hex to a Starknet felt-compatible bigint. */
+declare function commitmentAddressToStarknetFelt(value: string): bigint;
+/** Convert a 32-byte bitmap hex to a Starknet/Cairo `u256` bigint. */
+declare function signersBitmapToStarknetUint256(value: string): bigint;
+/** Build verifier `DataUpdate` and `SchnorrSignature` structs from a gateway result. */
+declare function buildStarknetVerifierArgs(result: DataUpdateResult): StarknetVerifierArgs;
+
+/**
+ * Consumer PDA derivations (no node PDA). Seed byte strings are cross-checked
+ * against the IDL const seeds.
+ */
+
+/** Virtual registry index used for a removed slot during a version transition. */
+declare const VIRTUAL_INDEX = 4294967295;
+declare const protocolConfigPda: (programId: SolanaAddress) => Address;
+declare const registryStatePda: (programId: SolanaAddress) => Address;
+/** Slot-keyed `Node` account PDA: `["molpha_node", index u32 LE]`. */
+declare const nodePda: (index: number, programId: SolanaAddress) => Address;
+/** Plan PDA is `[b"molpha_plan", [planType as u8]]` in `subscribe`. */
+declare const planPda: (planId: number, programId: SolanaAddress) => Address;
+declare const subscriptionPda: (owner: SolanaAddress, programId: SolanaAddress) => Address;
+declare const feedPda: (feedId: Uint8Array, programId: SolanaAddress) => Address;
+
+/** The subset of on-chain `RegistryState` the client needs (Anchor camelCase). */
+interface RegistryStateView {
+    currentVersion: number;
+    previousVersion: number;
+    previousExpiresAt: bigint;
+    /** On-chain selection padding: `signatures_required + redundancy_buffer`. */
+    redundancyBuffer: number;
+    lastTransitionType: {
+        none: Record<string, never>;
+    } | {
+        add: Record<string, never>;
+    } | {
+        removeTail: Record<string, never>;
+    } | {
+        removeSwap: Record<string, never>;
+    };
+    removedOldIndex: number;
+    movedOldIndex: number;
+}
+/** Set-bit indices of a 32-byte big-endian bitmap (full 256-bit scan). */
+declare function bitmapToIndices(signersBitmapHex: string): number[];
+/**
+ * Build the registry-index remaining accounts for a submit. Valid only
+ * against the current or previous registry version (else thrown client-side).
+ */
+declare function resolveRemainingAccounts(result: DataUpdateResult, registry: RegistryStateView, programId: SolanaAddress): SolanaAccountMeta[];
+/** Map a selected node index to its registry-index PDA index for a registry version. */
+declare function resolveRegistryIndexForVersion(index: number, registryVersion: number, registry: RegistryStateView): number;
+
+/**
+ * Vendored Molpha Anchor IDL (`target/idl/molpha.json` from the program repo).
+ *
+ * Re-exported as `MOLPHA_IDL` and used as the default in `MolphaSDK` /
+ * `MolphaSolanaClient.create`. Pass `idl` / `programId` only when pinning a
+ * different deployment. Keep this copy aligned with the on-chain program you target.
+ */
+declare const MOLPHA_IDL: Idl;
+/** Program address baked into the vendored IDL. */
+declare const MOLPHA_PROGRAM_ADDRESS: string;
+
+/**
+ * `@molpha/sdk` — Consumer SDK public surface.
+ *
+ * The `MolphaSDK` facade wires the gateway and Solana clients together; consumers
+ * who only read or only run gateway rounds can use `sdk.gateway` / `sdk.solana`
+ * directly (or import `MolphaGateway` / `MolphaSolanaClient` standalone).
+ */
+
+type Commitment = NonNullable<ConstructorParameters<typeof AnchorProvider>[2]>["commitment"];
+
+interface MolphaSDKOptions {
+    /** Defaults to `DEFAULT_GATEWAY_ENDPOINT`. Pass multiple URLs for failover. */
+    endpoints?: string | string[];
+    connection: SolanaConnection;
+    /** On-chain txs + gateway auth (see `MolphaWallet`). */
+    wallet: MolphaWallet;
+    /** Defaults to the vendored IDL's program address. */
+    programId?: Address | string;
+    /** Defaults to `MOLPHA_IDL`. Override when pinning a different deployment. */
+    idl?: Idl;
+    commitment?: Commitment;
+}
+declare class MolphaSDK {
+    readonly gateway: MolphaGateway;
+    readonly solana: MolphaSolanaClient;
+    constructor(opts: MolphaSDKOptions);
+    /**
+     * Request a threshold-signed data update from the gateway (against the current
+     * on-chain registry version) and submit it to the feed.
+     */
+    requestAndSubmit(feedId: string, opts: Omit<RequestSignedDataOptions, "feedId">): Promise<{
+        result: DataUpdateResult;
+        signature: string;
+    }>;
+}
+
+export { APIConfig, DEFAULT_GATEWAY_ENDPOINT, DataUpdateResult, type EvmDataUpdateTuple, type EvmSchnorrSignatureTuple, type EvmVerifierArgs, type FeedAccount, GatewayError, MOLPHA_IDL, MOLPHA_PROGRAM_ADDRESS, 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, type PlanId, type PlanInfo, PlanType, RegistrySelectionConfig, type RegistryStateView, type RequestSignedDataOptions, type RoundContext, Signer, type StarknetDataUpdate, type StarknetSchnorrSignature, type StarknetVerifierArgs, type SubmitResult, type SubscribeResult, type SubscriptionInfo, VIRTUAL_INDEX, bigIntFromBytesBe, bitmapBitSet, bitmapToIndices, buildEvmVerifierArgs, buildStarknetVerifierArgs, bytesToHex, bytesToHex0x, canonicalizeAPIConfig, commitmentAddressToStarknetFelt, concatBytes, deriveApiConfigHash, deriveFeedId, deriveFeedIdString, deriveGroupBitmap, deriveSelectionBitmap, deriveSelectionSeed, effectiveSelectionSize, ensureLength, feedPda, getMolphaStarknetVerifierAddress, hexToBytes, nodePda, normalizeSecp256k1PublicKeyHex, planIdFromVariant, planPda, planVariant, protocolConfigPda, registryStatePda, resolveRegistryIndexForVersion, resolveRemainingAccounts, secp256k1PublicKeyFromCoordinates, selectedIndices, signersBitmapToDecimal, signersBitmapToStarknetUint256, signersBitmapToUint256, subscriptionPda, toFixedBytes, toFixedHex, u256beFromBigInt, u32be, u32le, u64be, u64le, utf8 };