@molpha/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Molpha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,270 @@
+# Molpha MCP
+
+[![CI](https://github.com/Molpha/mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Molpha/mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-339933?logo=node.js&logoColor=white)](package.json)
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that lets AI agents create, fetch, verify, and publish [Molpha](https://docs.molpha.io/) oracle data.
+
+Molpha turns HTTP API responses into threshold-signed payloads that can be verified on Solana, EVM, and Starknet. This server exposes that workflow as a small set of MCP tools and keeps signing behind a local, Privy, or Turnkey-backed wallet.
+
+> [!WARNING]
+> This release targets Solana Devnet and Sepolia verifier networks. Treat it as testnet software, not a production security boundary. Write tools spend SOL and may consume subscription quota unless dry-run mode is enabled.
+
+## What you can do
+
+- Discover the active registry, oracle nodes, gateways, and verifier deployments.
+- Derive a feedId locally from a declarative API spec — no transaction, no subscription required. Feeds are created lazily on first settle.
+- Request a threshold-signed result and build verifier arguments for multiple chains, paid for either by an active USDC subscription or a self-funded [x402](#x402-pay-per-request) round.
+- Build EVM/Starknet verifier call args, or submit a verified update to a Solana feed.
+- Use a local keypair, Privy server wallet, or Turnkey wallet without changing the MCP tool surface.
+- Put daily caps and a global dry-run default around agent-initiated writes and x402 spend.
+
+## MCP tools
+
+| Tool | Access | Description |
+| --- | --- | --- |
+| `molpha_get_capabilities` | Read | Return the registry version, node set, gateways, chains, verifier metadata, and x402 caps. |
+| `molpha_describe_feed` | Read | Read a feed's on-chain state and subscription status. Pass `feedId`, or `apiConfig` + `signaturesRequired` to derive it. |
+| `molpha_derive_feed` | Read | Locally derive a feedId from `apiConfig` + `signaturesRequired`. No transaction. |
+| `molpha_agent_status` | Read | Read the x402 agent escrow (USDC balance, committed amount, quoted next price) for the current signer. |
+| `molpha_fetch_verified` | Read/quota/spend | Run a signing round and return the signed artifact plus verifier arguments. `payment: "subscription" \| "x402" \| "auto"` selects how the round is paid for; `autoSubmit: true` settles the Solana leg in the same call. |
+| `molpha_get_latest` | Read | Read the latest value stored in a Solana feed account. |
+| `molpha_verify` | Read | Build EVM/Starknet verifier address and call arguments (calldata only, by design). |
+| `molpha_execute` | Write | Submit a signed data update to Solana. Accepts the `molpha_fetch_verified` output unmodified. |
+
+`molpha_verify` stops at calldata **by design**: the Molpha verifier is stateless, so the agent executes `verify()` itself and the server never submits an EVM/Starknet transaction or vouches for a result it did not verify on-chain. Solana is the one leg this server settles — via `molpha_execute` or `molpha_fetch_verified`'s `autoSubmit` — and there is no standalone Solana verify-simulation path; submit, then read the result back with `molpha_get_latest`.
+
+`molpha_execute` and `molpha_verify` take the `molpha_fetch_verified` response as-is: no field remapping between calls, and short hex fields (the gateway emits a one-signer `signersBitmap` as `"4"`) are zero-padded to their canonical widths server-side.
+
+## Quick start
+
+### Requirements
+
+- Node.js 20 or later
+- A Solana wallet funded with Devnet SOL
+- Devnet USDC if you plan to use an active subscription or the x402 pay-per-request path
+- An MCP client such as Cursor, Claude Desktop, or Codex
+
+### 1. Install and build
+
+```bash
+git clone https://github.com/Molpha/mcp.git
+cd mcp
+npm ci
+cp .env.example .env
+npm run build
+```
+
+### 2. Configure a signer
+
+For local development, point `OWNER_KEYPAIR` at a Solana JSON keypair. Use an absolute path when an MCP client launches the server.
+
+```dotenv
+SIGNER_BACKEND=memory
+OWNER_KEYPAIR=/absolute/path/to/owner-keypair.json
+SOLANA_RPC=https://api.devnet.solana.com
+GATEWAY_ENDPOINTS=
+```
+
+The same wallet owns feeds and any x402 escrow, authenticates gateway requests, and signs Solana transactions. Do not commit `.env`, wallet files, or credentials.
+
+Other supported signer configurations:
+
+| Backend | Required configuration |
+| --- | --- |
+| Local keypair | `SIGNER_BACKEND=memory`, `OWNER_KEYPAIR` |
+| Privy | `SIGNER_BACKEND=keychain`, `KEYCHAIN_BACKEND=privy`, `PRIVY_APP_ID`, `PRIVY_APP_SECRET`, `PRIVY_WALLET_ID`, `PRIVY_WALLET_ADDRESS` |
+| Turnkey | `SIGNER_BACKEND=keychain`, `KEYCHAIN_BACKEND=turnkey`, `TURNKEY_API_PUBLIC_KEY`, `TURNKEY_API_PRIVATE_KEY`, `TURNKEY_ORGANIZATION_ID`, `TURNKEY_WALLET_ADDRESS` |
+
+See [.env.example](.env.example) and the ready-to-edit files in [examples](examples) for every backend.
+
+### 3. Check the setup
+
+```bash
+npm run doctor
+```
+
+The doctor checks the compiled entry point, signer configuration, wallet availability, and Solana RPC. It also prints configuration snippets with resolved absolute paths.
+
+### 4. Bootstrap a subscription
+
+Subscription operations debit USDC, so they are deliberately kept out of the MCP tool surface. Run the provisioning CLI once with the same signer configuration used by the server:
+
+```bash
+# Preview without sending a transaction
+npm run provision -- subscribe --plan Basic --max-price-usdc 20000000 --dry-run
+
+# Subscribe, with a maximum approved price of 20 USDC (6 decimals)
+npm run provision -- subscribe --plan Basic --max-price-usdc 20000000
+```
+
+Extend an existing subscription with:
+
+```bash
+npm run provision -- extend --max-price-usdc 20000000
+```
+
+`--max-price-usdc` is a safety cap in raw USDC base units, not a quoted plan price. The transaction aborts if the live on-chain price exceeds the cap.
+
+### 5. Connect an MCP client
+
+Pick one of the install paths below. In both cases the server speaks stdio JSON-RPC and needs the same signer settings from step 2.
+
+#### Claude Desktop (MCPB)
+
+Package the built tree into an [MCP Bundle](https://github.com/modelcontextprotocol/mcpb) and install it as a desktop extension. The repo already includes a [`manifest.json`](manifest.json) that declares the Node entry point, tools, and user-config fields.
+
+```bash
+npm run build
+npx @anthropic-ai/mcpb pack . molpha-mcp.mcpb
+```
+
+That writes `molpha-mcp.mcpb` in the repo root. Install it in Claude Desktop by any of:
+
+- Double-click the `.mcpb` file
+- Drag it into the Claude Desktop window
+- Settings → Extensions → Advanced settings → Install Extension… → select the `.mcpb` file
+
+During install, set the signer backend and related fields (local keypair path, Privy, or Turnkey). Those map to the same env vars as `.env.example`.
+
+#### Cursor, Codex, or manual Claude Desktop config
+
+Point the client at the built server (`dist/src/server.js`), not at `src/server.ts`:
+
+```json
+{
+  "mcpServers": {
+    "molpha": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp/dist/src/server.js"],
+      "env": {
+        "SIGNER_BACKEND": "memory",
+        "OWNER_KEYPAIR": "/absolute/path/to/owner-keypair.json",
+        "SOLANA_RPC": "https://api.devnet.solana.com"
+      }
+    }
+  }
+}
+```
+
+- Cursor: save the JSON under `mcpServers` in `.cursor/mcp.json` or `~/.cursor/mcp.json`. Ready-to-edit copies live in [examples](examples) (`cursor-memory.mcp.json`, `cursor-privy.mcp.json`, `cursor-turnkey.mcp.json`).
+- Claude Desktop: add the same block to `claude_desktop_config.json` and restart, or prefer the MCPB path above.
+- Codex: use one of the [Codex TOML examples](examples/codex-memory.toml), or run `codex mcp add molpha -- node /absolute/path/to/mcp/dist/src/server.js` and then add the signer variables to `config.toml`.
+
+Restart the client after changing configuration or rebuilding. A direct `node dist/src/server.js` invocation waits silently for JSON-RPC on stdin; that is expected for a stdio server.
+
+## Example prompts
+
+Once the server is connected, these prompts exercise the main workflows.
+
+### Discover the network
+
+> Use Molpha to inspect the current oracle capabilities. Summarize the registry version, node count, supported chains, gateway endpoints, and verifier addresses. Do not make any writes.
+
+### Preview a feed
+
+> Derive a Molpha feedId for `https://api.example.com/v1/finalized/price` using the JSON path `$.price` and 3 required signatures. Show me the API config hash, the derived feedId, and any determinism warnings. Do not send a transaction.
+
+Replace the example URL with a public endpoint that returns stable, independently reproducible data. Live ticker endpoints may produce different values across oracle nodes and fail to reach quorum.
+
+### Fetch and verify a result
+
+> For that same feed, fetch a signed result with `payment: "auto"` and a maximum age of 60 seconds, for the EVM chain. Summarize the signed value, timestamp, registry version, quorum, and EVM verifier call, and tell me whether it was paid for via subscription or x402. Treat the signed artifact as the trust anchor; do not trust the value by itself.
+
+### Check x402 spend before paying
+
+> Call `molpha_agent_status` for 3 required signatures. Tell me the escrow's USDC balance, committed amount, and quoted next price before I authorize any x402 spend.
+
+### Publish with an approval checkpoint
+
+> Read the latest value for Molpha feed `<FEED_ID>`. If I provide a newer signed result, preview `molpha_execute` with `dryRun: true`, explain the fee-paying wallet and exact write, and wait for my confirmation before submitting it to Solana.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    Client["MCP client<br/>Cursor · Claude · Codex"] <-->|"stdio / JSON-RPC"| Server["Molpha MCP server"]
+    Server --> Guardrails["Write guardrails<br/>dry-run · daily caps · x402 spend caps"]
+    Server --> Signer["Signer adapter"]
+    Signer --> Memory["Local keypair"]
+    Signer --> Keychain["Privy or Turnkey"]
+    Server --> SDK["Molpha SDK"]
+    Server --> X402["x402 client<br/>escrow funding · AgentRequestAuth"]
+    SDK --> Gateway["Molpha gateway<br/>subscription round"]
+    X402 --> Gateway2["Molpha gateway<br/>x402 agent round"]
+    Gateway <--> Nodes["Oracle node quorum"]
+    Gateway2 <--> Nodes
+    SDK <--> Solana["Solana program<br/>feeds · subscriptions · agent escrows"]
+    X402 <--> Solana
+    Gateway --> Artifact["Threshold-signed<br/>data update"]
+    Gateway2 --> Artifact
+    Artifact --> Server
+    Server --> Args["EVM / Starknet verifier args,<br/>or submit_data_update on Solana"]
+```
+
+The server is an adapter and policy boundary, not a new source of truth:
+
+1. The MCP client invokes a typed tool over stdio.
+2. The signer authenticates gateway requests and owner transactions.
+3. Oracle nodes independently fetch the committed API configuration and produce one aggregate signature after reaching quorum.
+4. The server returns the self-contained signed artifact. Solana can verify or store it; EVM and Starknet consumers receive contract-ready verifier arguments.
+5. Consumers trust a value only after verifying the signed payload against its registry version.
+
+Provisioning is a separate CLI path because subscribing or extending debits USDC. It is never available to an autonomous MCP tool call.
+
+## Configuration
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `SIGNER_BACKEND` | `memory` | `memory` or `keychain` |
+| `KEYCHAIN_BACKEND` | — | `privy` or `turnkey` for a keychain signer |
+| `OWNER_KEYPAIR` | — | Local Solana JSON keypair path |
+| `SOLANA_RPC` | `https://api.devnet.solana.com` | Solana RPC endpoint |
+| `GATEWAY_ENDPOINTS` | `https://dev-gateway.molpha.io` | Comma-separated **Molpha gateway** base URLs (not your Solana RPC). Must expose `/v1/nodes` and signing routes (`/v1/agent/execute` for x402, `/v1/round/execute` for subscription). Run `npm run doctor` to verify. |
+| `MOLPHA_EVM_NETWORKS` | `evm-sepolia` | Comma-separated EVM verifier networks |
+| `MOLPHA_STARKNET_NETWORKS` | `starknet-sepolia` | Comma-separated Starknet verifier networks |
+| `MOLPHA_MAX_EXECUTES_PER_DAY` | `100` | Process-local daily Solana-submit cap |
+| `MOLPHA_DRY_RUN` | `false` | Preview all writes when set to `true` |
+| `MOLPHA_X402_MAX_PRICE_USDC` | `1` | Refuse to fund an x402 round priced above this (decimal USDC) |
+| `MOLPHA_X402_MAX_SPEND_PER_DAY_USDC` | `10` | Process-local daily x402 spend cap (decimal USDC) |
+| `MOLPHA_X402_GATEWAY_PDA` | — | Optional: skip the x402 discovery round-trip when the gateway's PDA is known out of band |
+
+The daily counters are process-local and reset when the server restarts. They are safety rails, not durable rate limits.
+
+## x402 pay-per-request
+
+`molpha_fetch_verified` accepts a `payment` argument:
+
+- `"subscription"` — use the caller's active USDC subscription (see [Bootstrap a subscription](#4-bootstrap-a-subscription)). Fails if the subscription is inactive or out of quota.
+- `"x402"` — self-fund the round from a per-signer escrow account, with no subscription required. If the escrow is underfunded, the MCP server funds it from the signer's own USDC balance (creating the escrow's associated token account if needed) up to `MOLPHA_X402_MAX_PRICE_USDC` per round and `MOLPHA_X402_MAX_SPEND_PER_DAY_USDC` per day, then refuses with a clear error above those caps.
+- `"auto"` (default) — use the subscription when active, otherwise fall back to `"x402"`.
+
+Call `molpha_agent_status` to inspect the escrow (USDC balance, amount already committed to unsettled rounds, and the quoted price for a given quorum) before spending, or to confirm a round settled. `encryptSecrets` (private API secrets) is not yet supported on the x402 path — use `payment: "subscription"` for feeds with encrypted secrets.
+
+## Development
+
+```bash
+npm run dev        # start from TypeScript for local development
+npm run typecheck  # validate types without emitting files
+npm test           # run the Vitest suite
+npm run build      # compile src/, cli/, and tests into dist/
+```
+
+Before opening a pull request, run:
+
+```bash
+npm run typecheck && npm test && npm run build
+```
+
+Bug reports and focused pull requests are welcome. For security issues, use [GitHub's private vulnerability reporting](https://github.com/Molpha/mcp/security/advisories/new) instead of a public issue.
+
+## Documentation
+
+- [Molpha protocol documentation](https://docs.molpha.io/)
+- [Client configuration examples](examples)
+- [MCPB manifest](manifest.json) for Claude Desktop / `.mcpb` packaging
+
+## License
+
+Released under the [MIT License](LICENSE).

package/dist/cli/doctor.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import "../src/env.js";
+import { buildCodexTomlSnippet, buildMcpJsonSnippet, checkBuildArtifact, checkGatewayEndpoints, checkSignerAvailability, checkSolanaRpc, validateSignerEnv } from "../src/setup-validation.js";
+import { loadConfig } from "../src/config.js";
+const config = loadConfig();
+const checks = [
+    checkBuildArtifact(),
+    ...validateSignerEnv(),
+    await checkSignerAvailability(),
+    await checkSolanaRpc(config.solanaRpc),
+    await checkGatewayEndpoints(config.gatewayEndpoints)
+];
+const failed = checks.filter((check) => !check.ok);
+console.log("Molpha MCP setup check\n");
+for (const check of checks) {
+    const status = check.ok ? "ok" : "FAIL";
+    console.log(`[${status}] ${check.name}: ${check.message}`);
+}
+if (failed.length > 0) {
+    console.error(`\n${failed.length} check(s) failed. Fix env vars or key material, then re-run npm run doctor.`);
+    process.exit(1);
+}
+console.log("\nSuggested MCP JSON (Cursor / Claude Desktop):\n");
+console.log(buildMcpJsonSnippet());
+console.log("Suggested Codex config.toml snippet:\n");
+console.log(buildCodexTomlSnippet());
+console.log("Next: add the JSON to ~/.cursor/mcp.json or Claude Desktop config, restart the client, and call molpha_get_capabilities.");

package/dist/cli/provision.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import "../src/env.js";
+import { parseArgs } from "node:util";
+import { createSolanaClient, requireMethod } from "../src/clients.js";
+import { loadConfig } from "../src/config.js";
+import { getSdkExport } from "../src/sdk.js";
+import { createSigner } from "../src/signer/factory.js";
+const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+        plan: { type: "string", default: process.env.MOLPHA_PLAN ?? "Basic" },
+        "max-price-usdc": { type: "string", default: process.env.MAX_PRICE_USDC },
+        "dry-run": { type: "boolean", default: false }
+    }
+});
+const command = positionals[0] ?? "subscribe";
+if (command !== "subscribe" && command !== "extend") {
+    throw new Error("usage: molpha-provision <subscribe|extend> [--plan Basic] [--max-price-usdc <amount>] [--dry-run]");
+}
+const config = loadConfig();
+const signer = await createSigner(config);
+const solana = createSolanaClient(config, signer);
+const planName = values.plan ?? "Basic";
+const plan = resolvePlanId(planName);
+const maxPriceUsdc = values["max-price-usdc"];
+if (!values["dry-run"] && !maxPriceUsdc) {
+    throw new Error("--max-price-usdc or MAX_PRICE_USDC is required for non-dry-run bootstrap");
+}
+const summary = {
+    command,
+    owner: signer.publicKey,
+    plan: planName,
+    maxPriceUsdc,
+    gatewayEndpoints: config.gatewayEndpoints,
+    solanaRpc: config.solanaRpc,
+    note: "Bootstrap only — fetch and execute run in the MCP runtime with the same OWNER_KEYPAIR. A subscription is optional: molpha_fetch_verified falls back to the self-funded x402 path when unsubscribed."
+};
+if (values["dry-run"]) {
+    console.log(JSON.stringify({ dryRun: true, ...summary }, null, 2));
+    process.exit(0);
+}
+const getPlan = requireMethod(solana, "getPlan");
+const selectedPlan = await getPlan(plan);
+if (command === "subscribe") {
+    const subscribe = requireMethod(solana, "subscribe");
+    const subscription = await subscribe(plan, { maxPriceUsdc });
+    console.log(stringifyJson({ ...summary, selectedPlan, subscription }));
+}
+else {
+    const extendSubscription = requireMethod(solana, "extendSubscription");
+    const subscription = await extendSubscription({ maxPriceUsdc });
+    console.log(stringifyJson({ ...summary, selectedPlan, subscription }));
+}
+function resolvePlanId(plan) {
+    const normalized = plan.trim().toLowerCase();
+    const byName = {
+        basic: 0,
+        standard: 1,
+        professional: 2,
+        enterprise: 3
+    };
+    const bySdkEnum = getSdkExport("PlanType")?.[plan];
+    const numeric = byName[normalized] ?? bySdkEnum ?? Number.parseInt(plan, 10);
+    if (!Number.isInteger(numeric) || Number(numeric) < 0 || Number(numeric) > 3) {
+        throw new Error(`unsupported plan "${plan}"; expected Basic, Standard, Professional, Enterprise, or 0-3`);
+    }
+    return Number(numeric);
+}
+function stringifyJson(value) {
+    return JSON.stringify(value, jsonReplacer, 2);
+}
+function jsonReplacer(_key, value) {
+    if (typeof value === "bigint") {
+        return value.toString();
+    }
+    if (value &&
+        typeof value === "object" &&
+        value.constructor.name === "PublicKey" &&
+        "toBase58" in value &&
+        typeof value.toBase58 === "function") {
+        return value.toBase58();
+    }
+    return value;
+}

package/dist/src/apiconfig.js

@@ -0,0 +1,47 @@
+import { getAddressEncoder } from "@solana/kit";
+import { requireSdkExport } from "./sdk.js";
+/**
+ * apiConfig canonicalization shared by feed derivation and the x402 client.
+ *
+ * The gateway's Go canonicalizer (`CanonicalAPIConfigHash`) marshals the
+ * `headers` map with `encoding/json`, which always sorts map keys
+ * alphabetically. The SDK's `canonicalizeAPIConfig`/`deriveApiConfigHash`
+ * hash `JSON.stringify` of a plain JS object, which preserves insertion
+ * order instead. Any caller that derives a feedId or apiConfigHash
+ * client-side (feed derivation preview, x402 AgentRequestAuth signing) must
+ * byte-match the gateway's hash, so headers are sorted here before handing
+ * the config to the SDK's canonicalizer.
+ */
+export function sortApiConfigHeaders(apiConfig) {
+    if (!apiConfig.headers) {
+        return apiConfig;
+    }
+    const headers = apiConfig.headers;
+    const sorted = {};
+    for (const key of Object.keys(headers).sort()) {
+        const value = headers[key];
+        if (value !== undefined) {
+            sorted[key] = value;
+        }
+    }
+    return { ...apiConfig, headers: sorted };
+}
+/** Sorts headers, then hands the config to the SDK's canonicalizer (see above for why). */
+export function canonicalizeApiConfig(apiConfig) {
+    const canonicalize = requireSdkExport("canonicalizeAPIConfig");
+    return canonicalize(sortApiConfigHeaders(apiConfig));
+}
+export function deriveApiConfigHash(canonicalApiConfig) {
+    return requireSdkExport("deriveApiConfigHash")(canonicalApiConfig);
+}
+export function deriveFeedIdString(owner, apiConfigHash, signaturesRequired) {
+    const derive = requireSdkExport("deriveFeedIdString");
+    return derive(Buffer.from(getAddressEncoder().encode(owner)), apiConfigHash, signaturesRequired);
+}
+/** Full feedId derivation: canonicalize -> hash -> feedId, for a given owner + quorum. */
+export function deriveFeedId(apiConfig, signaturesRequired, owner) {
+    const canonicalApiConfig = canonicalizeApiConfig(apiConfig);
+    const apiConfigHash = deriveApiConfigHash(canonicalApiConfig);
+    const feedId = deriveFeedIdString(owner, apiConfigHash, signaturesRequired);
+    return { feedId, apiConfigHash, canonicalApiConfig };
+}

package/dist/src/artifacts.js

@@ -0,0 +1,80 @@
+/** Shape a gateway DataUpdateResult into the spec-friendly signed artifact. */
+import { toCanonicalHex } from "./hex.js";
+/** Fixed byte widths the SDK and the Solana program enforce on the flat result. */
+const HEX_WIDTHS = {
+    feedId: 32,
+    valuePacked: 32,
+    s: 32,
+    commitmentAddr: 20,
+    signersBitmap: 32
+};
+/**
+ * Canonicalize every fixed-width hex field on a flat signed result. `value` is a
+ * decimal string, not hex, and the numeric fields are left alone.
+ */
+export function normalizeSignedResult(raw) {
+    const out = { ...raw };
+    for (const [field, bytes] of Object.entries(HEX_WIDTHS)) {
+        const value = raw[field];
+        if (value !== undefined && value !== null && value !== "") {
+            out[field] = toCanonicalHex(String(value), bytes, field);
+        }
+    }
+    return out;
+}
+/**
+ * Accept either shape a caller can plausibly hold: the artifact this server
+ * emits from `molpha_fetch_verified` (`{ dataUpdate, signature }`) or the flat
+ * SDK/gateway shape (`{ s, commitmentAddr, timestamp }`). Returns the flat shape
+ * with hex fields canonicalized, so no tool needs a hand-written remap.
+ */
+export function toSignedResult(input) {
+    const dataUpdate = asRecord(input.dataUpdate);
+    const signature = asRecord(input.signature);
+    if (!dataUpdate && !signature) {
+        return normalizeSignedResult(input);
+    }
+    const du = dataUpdate ?? {};
+    const sig = signature ?? {};
+    return normalizeSignedResult({
+        feedId: du.feedId ?? input.feedId,
+        value: du.value ?? input.value,
+        valuePacked: du.valuePacked ?? input.valuePacked,
+        timestamp: du.canonicalTimestamp ?? du.timestamp ?? input.timestamp,
+        registryVersion: du.registryVersion ?? input.registryVersion,
+        signaturesRequired: du.signaturesRequired ?? input.signaturesRequired,
+        signersBitmap: sig.signersBitmap ?? input.signersBitmap,
+        s: sig.signature ?? sig.s ?? input.s,
+        commitmentAddr: sig.commitment ?? sig.commitmentAddr ?? input.commitmentAddr,
+        fresh: input.fresh ?? true
+    });
+}
+export function toDataUpdateArtifact(result) {
+    // Normalize on the way out so the artifact this server emits is byte-for-byte
+    // acceptable to molpha_execute / molpha_verify without caller-side padding.
+    const normalized = normalizeSignedResult(result);
+    return {
+        value: String(normalized.value ?? ""),
+        fresh: Boolean(normalized.fresh ?? true),
+        dataUpdate: {
+            feedId: String(normalized.feedId ?? ""),
+            registryVersion: Number(normalized.registryVersion ?? 0),
+            signaturesRequired: Number(normalized.signaturesRequired ?? 0),
+            value: String(normalized.value ?? ""),
+            ...(normalized.valuePacked !== undefined
+                ? { valuePacked: String(normalized.valuePacked) }
+                : {}),
+            canonicalTimestamp: Number(normalized.timestamp ?? 0)
+        },
+        signature: {
+            signature: String(normalized.s ?? ""),
+            commitment: String(normalized.commitmentAddr ?? ""),
+            signersBitmap: String(normalized.signersBitmap ?? "")
+        }
+    };
+}
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}

package/dist/src/clients.js

@@ -0,0 +1,51 @@
+import { Connection } from "@solana/web3.js";
+import { loadConfig } from "./config.js";
+import { parseSolanaPubkey } from "./solana-address.js";
+import { toLegacyPublicKey } from "./solana-compat.js";
+import { getSdkExport, requireSdkExport } from "./sdk.js";
+import { createSigner } from "./signer/factory.js";
+let cachedContextPromise;
+export function getMolphaContext() {
+    cachedContextPromise ??= createMolphaContext(loadConfig());
+    return cachedContextPromise;
+}
+export async function createMolphaContext(config) {
+    const signer = await createSigner(config);
+    const connection = new Connection(config.solanaRpc, "confirmed");
+    const solana = createSolanaClient(config, signer, connection);
+    return {
+        config,
+        gateway: createGateway(config, solana, signer),
+        solana,
+        signer,
+        connection
+    };
+}
+export function createGateway(config, solana, signer) {
+    const Gateway = requireSdkExport("MolphaGateway");
+    // SDK Signer type = (message: Uint8Array) => Promise<Uint8Array>
+    const defaultSigner = (msg) => signer.signMessage(msg);
+    return new Gateway(config.gatewayEndpoints, () => requireMethod(solana, "getRegistrySelectionConfig")(), defaultSigner, signer.publicKey);
+}
+export function createSolanaClient(config, signer, connection = new Connection(config.solanaRpc, "confirmed")) {
+    const SolanaClient = requireSdkExport("MolphaSolanaClient");
+    const wallet = {
+        publicKey: toLegacyPublicKey(signer.publicKey),
+        signTransaction: (tx) => signer.signTransaction(tx),
+        signAllTransactions: (txs) => signer.signAllTransactions(txs),
+    };
+    return SolanaClient.create({
+        connection,
+        wallet
+    });
+}
+export function getMolphaProgramId() {
+    return parseSolanaPubkey(requireSdkExport("MOLPHA_PROGRAM_ADDRESS"), "MOLPHA_PROGRAM_ADDRESS");
+}
+export function requireMethod(target, methodName) {
+    const method = target[methodName];
+    if (typeof method !== "function") {
+        throw new Error(`Molpha SDK client is missing ${methodName}()`);
+    }
+    return method.bind(target);
+}