SDK Overview - Molpha

@molpha/sdk is the recommended way to integrate Molpha from TypeScript. MolphaSDK wires the gateway client and the Solana client together behind a single wallet, and the package also ships framework-agnostic EVM/Starknet argument builders. For AI agent workflows in Cursor, Claude Desktop, or Codex, use the Molpha MCP server — it wraps this SDK behind typed MCP tools. For the fastest path by audience, see the Backend quickstart or AI agent quickstart.

What you can build

Workflow	SDK path
Request one signed payload	`sdk.gateway.requestSignedData(...)`
Maintain a Solana feed	Derive `feedId`, then `sdk.requestAndSubmit(...)`
Read a maintained feed	`sdk.solana.readFeed(feedId)`
Verify directly in Rust	Use `molpha-verifier` with registry/node data
Call EVM/Starknet verifiers	`buildEvmVerifierArgs(result)` / `buildStarknetVerifierArgs(result)`

Installation

Install the package along with the Solana peer dependencies (required for MolphaSDK / MolphaSolanaClient):

pnpm
npm
yarn

pnpm add @molpha/sdk @anchor-lang/core bn.js

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

yarn add @molpha/sdk @anchor-lang/core bn.js

ESM, browser-first, with "sideEffects": false
Tree-shakeable Solana path — gateway-only or read-only apps that skip the Solana imports can tree-shake the Anchor-heavy path entirely
Node.js >=20.19.0
Node-only helpers (e.g. walletFromKeypairFile) live under the @molpha/sdk/utils subpath so they never enter browser bundles

@anchor-lang/core provides the Anchor Wallet / Connection types the Solana client expects. bn.js is used by the Solana / Anchor path. The SDK pulls in @solana/kit and @noble/* as direct dependencies — you do not need @solana/web3.js, @coral-xyz/anchor, or @solana/spl-token for the consumer flow.

Initialize

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("~/.config/solana/id.json"),
});

By default the SDK talks to https://dev-gateway.molpha.io/. Override with endpoints (string or array for failover):

import { DEFAULT_GATEWAY_ENDPOINT } from "@molpha/sdk";

const sdk = new MolphaSDK({
  connection,
  wallet,
  endpoints: [DEFAULT_GATEWAY_ENDPOINT, "https://backup.example.com"],
});

walletFromKeypairFile is Node.js-only. In the browser, pass a MolphaWallet backed by a wallet adapter:

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

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

Gateway execution requires a real Ed25519 authSig. Keypair-backed wallets (walletFromKeypairFile) derive auth from Wallet.payer automatically. Browser adapters should provide signAuthMessage. The gateway rejects all-zero signatures.

Facade surface

Member	Purpose
`sdk.requestAndSubmit(feedId, { apiConfig, signaturesRequired })`	Run a gateway round against the current registry version and submit the signed result to Solana in one call. Returns `{ result, signature }`.
`sdk.gateway`	The gateway client: `requestSignedData`, `prepareContext`, …
`sdk.solana`	The Solana client (below): `getPlan`, `subscribe`, `extendSubscription`, `submitDataUpdate`, `readFeed`, `getRegistrySelectionConfig`, …

requestAndSubmit is equivalent to:

const result = await sdk.gateway.requestSignedData({
  feedId,
  apiConfig,
  signaturesRequired,
});
const { signature } = await sdk.solana.submitDataUpdate(result);

Solana client (`sdk.solana`)

All methods target the Molpha program (MoLFGDpFoVnQgwbkTNScKPohCxhbfd61JjFrnotuwzh on devnet); PDAs are derived internally from the documented seeds.

Plans and subscriptions

import { PlanType } from "@molpha/sdk";

const plan = await sdk.solana.getPlan(PlanType.Basic);

const { pricePaid } = await sdk.solana.subscribe(PlanType.Basic, {
  maxPriceUsdc: plan.subscriptionPrice,
});

// Renew for another period (same maxPriceUsdc safety bound)
await sdk.solana.extendSubscription({
  maxPriceUsdc: plan.subscriptionPrice,
});

maxPriceUsdc is a safety bound: the transaction aborts if the on-chain price is higher than what the user approved. The SDK currently exports PlanType.Basic (0). On-chain plan ordinals remain Basic = 0, Standard = 1, Professional = 2, Enterprise = 3.

Derive a feed ID

import { deriveApiConfigHash, deriveFeedIdString } from "@molpha/sdk";

const signaturesRequired = 3;
const apiConfigHash = deriveApiConfigHash(apiConfig);
const feedId = deriveFeedIdString(
  wallet.publicKey.toBytes(),
  apiConfigHash,
  signaturesRequired,
);

There is no separate create instruction. The first successful submitDataUpdate creates the Solana Feed account if it does not exist. Settlement writes round receipts only.

Request

// Optional: fetch registry + nodes once, then reuse across rounds
const context = await sdk.gateway.prepareContext(feedId);

const result = await sdk.gateway.requestSignedData({
  feedId,
  apiConfig,
  signaturesRequired,
  context,
});

Live gateway rounds return fresh: true. Gateway execution is authenticated via signAuthMessage (or a keypair-derived signer); the HTTP gateway rejects all-zero authSig values. For private APIs, pass encrypt: { secrets: { ... } } — MolphaSDK authenticates gateway node keys against on-chain Node accounts before encrypting. See the SDK gateway API.

Submission and reads

// Verify + write the signed result to the Feed account
const { signature } = await sdk.solana.submitDataUpdate(result);

// Read the finalized on-chain feed account (bytes + metadata)
const feed = await sdk.solana.readFeed(feedId);
console.log(feed?.value, feed?.canonicalTimestamp);

feed.value is the on-chain byte array (number[]), not the human-readable DataUpdateResult.value string. Decode it per your feed schema (see Read and verify). submit_data_update is permissionless on-chain — the program re-verifies the aggregate signature on every write and only accepts a value whose canonical_timestamp is strictly greater than the stored one.

Direct verification

For Solana, use one of two paths:

submit through submitDataUpdate, then read the Feed account;
verify directly in Rust with molpha-verifier.

For EVM and Starknet, build verifier arguments with the helpers in SDK Reference.

​What you can build

​Installation

​Initialize

​Facade surface

​Solana client (sdk.solana)

​Plans and subscriptions

​Derive a feed ID

​Request

​Submission and reads

​Direct verification

What you can build

Installation

Initialize

Facade surface

Solana client (`sdk.solana`)

Plans and subscriptions

Derive a feed ID

Request

Submission and reads

Direct verification