SDK overview - Molpha

@molpha/sdk is the TypeScript client for Molpha. This page covers installation, initialization and the main methods; for an end-to-end walkthrough, start with the backend quickstart. The SDK has three parts:

sdk.gateway (MolphaGateway) runs signing rounds and returns an Attestation.
sdk.solana (MolphaSolanaClient) manages subscriptions, submits attestations to Solana Feed accounts and reads them.
Verifier argument builders (buildEvmVerifierArgs, buildStarknetVerifierArgs) map an Attestation onto the EVM and Starknet verify calls, with no ethers, viem or starknet.js dependency.

Installation

npm install @molpha/sdk @anchor-lang/core bn.js

Requires Node.js >=20.19.0. The package is ESM-only and marked "sideEffects": false.
@anchor-lang/core and bn.js are peer dependencies used by the Solana client. You do not need @solana/web3.js, @coral-xyz/anchor or @solana/spl-token.
Node-only helpers (walletFromKeypairFile, loadKeypair) live in the @molpha/sdk/utils subpath so they stay out of browser bundles.

Initialize

import { homedir } from "node:os";
import { join } from "node:path";
import { web3 } from "@anchor-lang/core";
import { MolphaSDK } from "@molpha/sdk";
import { walletFromKeypairFile } from "@molpha/sdk/utils";

const sdk = new MolphaSDK({
  connection: new web3.Connection("https://api.devnet.solana.com", "confirmed"),
  wallet: walletFromKeypairFile(join(homedir(), ".config/solana/id.json")),
});

walletFromKeypairFile reads the path as given and does not expand ~.

Option	Default	Meaning
`connection`	required	Solana `web3.Connection`.
`wallet`	required	A `MolphaWallet`. Signs Solana transactions and gateway requests; its public key is the default subscription owner.
`endpoints`	`DEFAULT_GATEWAY_ENDPOINT` (`https://gateway.molpha.io/`)	A gateway URL, a `{ url, gatewayAuthority }` object, or an array of them for failover. See endpoints.
`programId`	`MOLPHA_PROGRAM_ID`	Molpha program. Also bound into gateway request auth.
`idl`	`MOLPHA_IDL`	Anchor IDL. Override only when pinning a different deployment.
`commitment`	Anchor default	Commitment for Solana reads and transactions.

Main methods

Method	What it does
`sdk.gateway.requestSignedData(opts)`	Run one gateway round and return an `Attestation`.
`sdk.gateway.prepareContext()`	Fetch registry inputs and nodes once, to reuse across rounds.
`sdk.requestAndSubmit(opts)`	Run a round and submit it to Solana. Returns `{ result, signature, feed }`.
`requestMany(sdk, feeds, opts?)`	Update many feeds with bounded, adaptive concurrency.
`sdk.solana.getPlan(plan)`	Read a plan’s on-chain price and limits.
`sdk.solana.subscribe(plan, { maxPriceUsdc })`	Buy a subscription in USDC, with a price ceiling.
`sdk.solana.submitAttestation(attestation, opts?)`	Verify and write one attestation to the submitter’s `Feed` account.
`sdk.solana.submitAttestations(attestations, opts?)`	Submit several attestations of one feed in one transaction.
`sdk.solana.readFeed(sourceId, signaturesRequired, submitter?)`	Read a `Feed` account, or `null` before its first submit.
`deriveSourceIdString(apiConfig)`	Compute the `sourceId` of an API config.
`buildEvmVerifierArgs(result, { maxAge })`	Arguments for the EVM verifier’s `verify`.
`buildStarknetVerifierArgs(result, { maxAge })`	Arguments for the Starknet verifier’s `verify`.

You can also construct MolphaGateway or MolphaSolanaClient on their own; see clients.

Wallet

MolphaWallet is an Anchor Wallet with an optional signAuthMessage. Every gateway request carries a signature over a RequestAuth digest (see gateways). A keypair wallet from walletFromKeypairFile signs it with its payer key automatically. A browser wallet adapter has no payer, so supply signAuthMessage:

import type { MolphaWallet } from "@molpha/sdk";

const wallet = {
  publicKey: adapter.publicKey,
  signTransaction: (tx) => adapter.signTransaction(tx),
  signAllTransactions: (txs) => adapter.signAllTransactions(txs),
  signAuthMessage: async (msg) => new Uint8Array(await adapter.signMessage(msg)),
} as MolphaWallet;

The as MolphaWallet assertion is needed because the Anchor Wallet type declares payer. A wallet with neither payer nor signAuthMessage sends an all-zero auth signature, which the gateway rejects with HTTP 401.

Backend quickstart

Subscribe, request and submit end to end.

Gateway client

Rounds, retries and errors.

Reference

Every exported type and function.

​Installation

​Initialize

​Main methods

​Wallet