@molpha/mcp 0.1.0

package/dist/src/setup-validation.js

@@ -0,0 +1,340 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { createSolanaRpc } from "@solana/kit";
+import { formatUsdcAtomic, isInlineKeypair, loadConfig, loadKeypair, resolveEnvString, resolvePath } from "./config.js";
+import { createSigner } from "./signer/factory.js";
+import { validateSolanaPubkey } from "./solana-address.js";
+export function validateSignerEnv(env = process.env) {
+    const backend = resolveEnvString(env.SIGNER_BACKEND) ?? "memory";
+    const checks = [
+        {
+            name: "signer_backend",
+            ok: backend === "memory" || backend === "keychain",
+            message: backend === "memory" || backend === "keychain"
+                ? `SIGNER_BACKEND=${backend}`
+                : `unsupported SIGNER_BACKEND="${backend}" (expected memory or keychain)`
+        }
+    ];
+    if (backend === "memory") {
+        const ownerKeypair = resolveEnvString(env.OWNER_KEYPAIR ?? env.AGENT_KEYPAIR);
+        if (!ownerKeypair?.trim()) {
+            checks.push({
+                name: "owner_keypair",
+                ok: false,
+                message: "OWNER_KEYPAIR is required for SIGNER_BACKEND=memory"
+            });
+            return appendOptionalPubkeyChecks(checks, env);
+        }
+        if (isInlineKeypair(ownerKeypair)) {
+            try {
+                loadKeypair(ownerKeypair);
+                checks.push({
+                    name: "owner_keypair",
+                    ok: true,
+                    message: "OWNER_KEYPAIR=<inline-json-keypair>"
+                });
+            }
+            catch (error) {
+                checks.push({
+                    name: "owner_keypair",
+                    ok: false,
+                    message: error instanceof Error
+                        ? `OWNER_KEYPAIR inline JSON is invalid: ${error.message}`
+                        : "OWNER_KEYPAIR inline JSON is invalid"
+                });
+            }
+            return appendOptionalPubkeyChecks(checks, env);
+        }
+        const resolved = resolveKeypairPath(ownerKeypair);
+        if (!existsSync(resolved)) {
+            checks.push({
+                name: "owner_keypair",
+                ok: false,
+                message: `OWNER_KEYPAIR file not found: ${resolved}`
+            });
+            return appendOptionalPubkeyChecks(checks, env);
+        }
+        checks.push({
+            name: "owner_keypair",
+            ok: true,
+            message: `OWNER_KEYPAIR=${resolved}`
+        });
+        return appendOptionalPubkeyChecks(checks, env);
+    }
+    const provider = resolveEnvString(env.KEYCHAIN_BACKEND);
+    if (provider !== "privy" && provider !== "turnkey") {
+        checks.push({
+            name: "keychain_backend",
+            ok: false,
+            message: `KEYCHAIN_BACKEND must be privy or turnkey for SIGNER_BACKEND=keychain (got "${provider ?? ""}")`
+        });
+        return checks;
+    }
+    checks.push({
+        name: "keychain_backend",
+        ok: true,
+        message: `KEYCHAIN_BACKEND=${provider}`
+    });
+    const required = provider === "privy"
+        ? ["PRIVY_APP_ID", "PRIVY_APP_SECRET", "PRIVY_WALLET_ID", "PRIVY_WALLET_ADDRESS"]
+        : [
+            "TURNKEY_API_PUBLIC_KEY",
+            "TURNKEY_API_PRIVATE_KEY",
+            "TURNKEY_ORGANIZATION_ID",
+            "TURNKEY_WALLET_ADDRESS"
+        ];
+    const walletAddressVar = provider === "privy" ? "PRIVY_WALLET_ADDRESS" : "TURNKEY_WALLET_ADDRESS";
+    for (const name of required) {
+        const value = resolveEnvString(env[name]);
+        if (name === walletAddressVar) {
+            if (!value?.trim()) {
+                checks.push({
+                    name: name.toLowerCase(),
+                    ok: false,
+                    message: `${name} is required for ${provider}`
+                });
+                continue;
+            }
+            const validation = validateSolanaPubkey(value, name);
+            checks.push({
+                name: name.toLowerCase(),
+                ok: validation.ok,
+                message: validation.ok ? `${name} is a valid Solana address` : validation.message
+            });
+            continue;
+        }
+        checks.push({
+            name: name.toLowerCase(),
+            ok: Boolean(value && value.trim().length > 0),
+            message: value && value.trim().length > 0 ? `${name} is set` : `${name} is required for ${provider}`
+        });
+    }
+    for (const [name, value] of [["MOLPHA_X402_GATEWAY_PDA", resolveEnvString(env.MOLPHA_X402_GATEWAY_PDA)]]) {
+        if (!value?.trim()) {
+            continue;
+        }
+        const validation = validateSolanaPubkey(value, name);
+        checks.push({
+            name: name.toLowerCase(),
+            ok: validation.ok,
+            message: validation.ok ? `${name} is a valid Solana address` : validation.message
+        });
+    }
+    return checks;
+}
+export async function checkSignerAvailability() {
+    try {
+        const signer = await createSigner(loadConfig());
+        const available = await signer.isAvailable();
+        return {
+            name: "signer",
+            ok: available,
+            message: available
+                ? `signer ready for ${signer.publicKey}`
+                : "signer backend is not available"
+        };
+    }
+    catch (error) {
+        return {
+            name: "signer",
+            ok: false,
+            message: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+function looksLikeSolanaRpc(endpoint) {
+    try {
+        const host = new URL(endpoint).hostname.toLowerCase();
+        return (host.includes("helius") ||
+            host.includes("quicknode") ||
+            host.includes("alchemy") ||
+            host.endsWith("solana.com") ||
+            host.includes("rpc."));
+    }
+    catch {
+        return false;
+    }
+}
+export async function checkGatewayEndpoints(endpoints) {
+    if (endpoints.length === 0) {
+        return {
+            name: "gateway_endpoints",
+            ok: false,
+            message: "no gateway endpoints configured"
+        };
+    }
+    const solanaRpcEndpoint = endpoints.find(looksLikeSolanaRpc);
+    if (solanaRpcEndpoint) {
+        return {
+            name: "gateway_endpoints",
+            ok: false,
+            message: `${solanaRpcEndpoint} looks like a Solana RPC URL — set GATEWAY_ENDPOINTS to a Molpha gateway (not SOLANA_RPC)`
+        };
+    }
+    let lastError = "no reachable gateway";
+    for (const endpoint of endpoints) {
+        const base = endpoint.replace(/\/$/, "");
+        try {
+            const nodesRes = await fetch(`${base}/v1/nodes`, { method: "GET", signal: AbortSignal.timeout(8_000) });
+            if (!nodesRes.ok) {
+                lastError = `GET /v1/nodes failed (${nodesRes.status}) at ${base}`;
+                continue;
+            }
+            const probeRes = await fetch(`${base}/v1/agent/execute`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({}),
+                signal: AbortSignal.timeout(8_000)
+            });
+            const probeText = (await probeRes.text()).trim();
+            if (probeText.includes('"jsonrpc"') && probeText.includes("Method not found")) {
+                lastError = `${base} returned a Solana JSON-RPC error for POST /v1/agent/execute — this is not a Molpha gateway`;
+                continue;
+            }
+            if (probeRes.status === 404 && probeText.includes("page not found")) {
+                lastError = `${base} serves /v1/nodes but not /v1/agent/execute (signing routes missing — use https://dev-gateway.molpha.io)`;
+                continue;
+            }
+            if (probeRes.status === 400 || probeRes.status === 401 || probeRes.status === 402) {
+                return {
+                    name: "gateway_endpoints",
+                    ok: true,
+                    message: `${base} reachable (nodes + signing routes)`
+                };
+            }
+            lastError = `${base} unexpected POST /v1/agent/execute response (${probeRes.status})`;
+        }
+        catch (error) {
+            lastError = error instanceof Error ? `${base}: ${error.message}` : `${base}: unreachable`;
+        }
+    }
+    return {
+        name: "gateway_endpoints",
+        ok: false,
+        message: lastError
+    };
+}
+export async function checkSolanaRpc(rpc) {
+    try {
+        const version = await createSolanaRpc(rpc).getVersion().send();
+        return {
+            name: "solana_rpc",
+            ok: true,
+            message: `reachable (${version["solana-core"] ?? "ok"})`
+        };
+    }
+    catch (error) {
+        return {
+            name: "solana_rpc",
+            ok: false,
+            message: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+export function checkBuildArtifact(repoRoot = process.cwd()) {
+    const built = resolve(repoRoot, "dist/src/server.js");
+    return {
+        name: "build",
+        ok: existsSync(built),
+        message: existsSync(built)
+            ? `server entry found at ${built}`
+            : `missing ${built} — run npm run build`
+    };
+}
+export function resolveServerEntry(repoRoot = process.cwd()) {
+    return resolve(repoRoot, "dist/src/server.js");
+}
+export function buildMcpEnvBlock(env = process.env) {
+    const config = loadConfig(env);
+    const out = {
+        SOLANA_RPC: config.solanaRpc,
+        GATEWAY_ENDPOINTS: config.gatewayEndpoints.join(","),
+        MOLPHA_EVM_NETWORKS: config.evmNetworks.join(","),
+        MOLPHA_STARKNET_NETWORKS: config.starknetNetworks.join(","),
+        MOLPHA_MAX_EXECUTES_PER_DAY: String(config.guardrails.maxExecutesPerDay),
+        MOLPHA_X402_MAX_PRICE_USDC: formatUsdcAtomic(config.x402.maxPriceUsdcAtomic),
+        MOLPHA_X402_MAX_SPEND_PER_DAY_USDC: formatUsdcAtomic(config.x402.maxSpendPerDayUsdcAtomic)
+    };
+    if (config.x402.gatewayPda) {
+        out.MOLPHA_X402_GATEWAY_PDA = config.x402.gatewayPda;
+    }
+    const backend = resolveEnvString(env.SIGNER_BACKEND) ?? "memory";
+    if (backend === "memory") {
+        out.SIGNER_BACKEND = "memory";
+        const ownerKeypair = resolveEnvString(env.OWNER_KEYPAIR ?? env.AGENT_KEYPAIR);
+        if (ownerKeypair) {
+            out.OWNER_KEYPAIR = resolveKeypairPath(ownerKeypair);
+        }
+    }
+    else {
+        out.SIGNER_BACKEND = "keychain";
+        const provider = resolveEnvString(env.KEYCHAIN_BACKEND);
+        if (provider) {
+            out.KEYCHAIN_BACKEND = provider;
+        }
+        const passthrough = provider === "privy"
+            ? ["PRIVY_APP_ID", "PRIVY_APP_SECRET", "PRIVY_WALLET_ID", "PRIVY_WALLET_ADDRESS"]
+            : provider === "turnkey"
+                ? [
+                    "TURNKEY_API_PUBLIC_KEY",
+                    "TURNKEY_API_PRIVATE_KEY",
+                    "TURNKEY_ORGANIZATION_ID",
+                    "TURNKEY_WALLET_ADDRESS"
+                ]
+                : [];
+        for (const name of passthrough) {
+            const value = resolveEnvString(env[name]);
+            if (value) {
+                out[name] = value;
+            }
+        }
+    }
+    if (config.guardrails.dryRunDefault) {
+        out.MOLPHA_DRY_RUN = "true";
+    }
+    return out;
+}
+export function buildMcpJsonSnippet(repoRoot = process.cwd(), env = process.env) {
+    const serverPath = resolveServerEntry(repoRoot);
+    return JSON.stringify({
+        mcpServers: {
+            molpha: {
+                command: "node",
+                args: [serverPath],
+                env: buildMcpEnvBlock(env)
+            }
+        }
+    }, null, 2);
+}
+export function buildCodexTomlSnippet(repoRoot = process.cwd(), env = process.env) {
+    const serverPath = resolveServerEntry(repoRoot);
+    const envBlock = buildMcpEnvBlock(env);
+    const lines = [
+        "[mcp_servers.molpha]",
+        `command = "node"`,
+        `args = ["${serverPath}"]`,
+        "",
+        "[mcp_servers.molpha.env]"
+    ];
+    for (const [key, value] of Object.entries(envBlock)) {
+        lines.push(`${key} = "${value.replaceAll('"', '\\"')}"`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function appendOptionalPubkeyChecks(checks, env) {
+    for (const [name, value] of [["MOLPHA_X402_GATEWAY_PDA", resolveEnvString(env.MOLPHA_X402_GATEWAY_PDA)]]) {
+        if (!value?.trim()) {
+            continue;
+        }
+        const validation = validateSolanaPubkey(value, name);
+        checks.push({
+            name: name.toLowerCase(),
+            ok: validation.ok,
+            message: validation.ok ? `${name} is a valid Solana address` : validation.message
+        });
+    }
+    return checks;
+}
+function resolveKeypairPath(path) {
+    return isInlineKeypair(path) ? "<inline-json-keypair>" : resolvePath(path);
+}

package/dist/src/signer/backends/memory.js

@@ -0,0 +1,41 @@
+import { createKeyPairFromBytes, getAddressFromPublicKey, signBytes } from "@solana/kit";
+import { Transaction, VersionedTransaction } from "@solana/web3.js";
+import { toLegacyPublicKey } from "../../solana-compat.js";
+export class MemorySigner {
+    publicKey;
+    keyPair;
+    constructor(keyPair, address) {
+        this.keyPair = keyPair;
+        this.publicKey = address;
+    }
+    static async fromSecretKey(secretKey) {
+        const keyPair = await createKeyPairFromBytes(secretKey);
+        const address = await getAddressFromPublicKey(keyPair.publicKey);
+        return new MemorySigner(keyPair, address);
+    }
+    async isAvailable() {
+        return true;
+    }
+    async signTransaction(tx) {
+        const messageBytes = tx instanceof VersionedTransaction ? tx.message.serialize() : tx.serializeMessage();
+        const signature = await signBytes(this.keyPair.privateKey, toExactUint8Array(messageBytes));
+        tx.addSignature(toLegacyPublicKey(this.publicKey), Buffer.from(signature));
+        return tx;
+    }
+    async signAllTransactions(txs) {
+        return Promise.all(txs.map((tx) => this.signTransaction(tx)));
+    }
+    async signMessage(message) {
+        return new Uint8Array(await signBytes(this.keyPair.privateKey, toExactUint8Array(message)));
+    }
+}
+/**
+ * Node's Buffer pooling means small buffers (e.g. `Transaction.serializeMessage()`,
+ * `Buffer.concat(...)`) are frequently views into a much larger shared ArrayBuffer.
+ * WebCrypto's `subtle.sign` reads the view's backing buffer rather than respecting
+ * its byteOffset/byteLength, which silently signs the wrong bytes. Always copy into
+ * a tightly-sized Uint8Array before signing.
+ */
+function toExactUint8Array(bytes) {
+    return bytes.byteLength === bytes.buffer.byteLength ? bytes : Uint8Array.from(bytes);
+}

package/dist/src/signer/backends/privy.js

@@ -0,0 +1,48 @@
+import { createRequire } from "node:module";
+import { Transaction, VersionedTransaction } from "@solana/web3.js";
+import { parseSolanaPubkey } from "../../solana-address.js";
+const require = createRequire(import.meta.url);
+export class PrivySigner {
+    publicKey;
+    walletId;
+    wallets;
+    constructor(config) {
+        this.publicKey = parseSolanaPubkey(config.address, "PRIVY_WALLET_ADDRESS");
+        this.walletId = config.walletId;
+        let PrivyClient;
+        try {
+            ({ PrivyClient } = require("@privy-io/node"));
+        }
+        catch (error) {
+            throw new Error("@privy-io/node is not installed. Run `npm install @privy-io/node` to use SIGNER_BACKEND=keychain with KEYCHAIN_BACKEND=privy.", { cause: error });
+        }
+        const privy = new PrivyClient({ appId: config.appId, appSecret: config.appSecret });
+        this.wallets = privy.wallets();
+    }
+    async isAvailable() {
+        try {
+            await this.wallets.get(this.walletId);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async signTransaction(tx) {
+        const transaction = tx instanceof VersionedTransaction
+            ? tx.serialize()
+            : tx.serialize({ requireAllSignatures: false, verifySignatures: false });
+        const { signed_transaction: signedTransaction } = await this.wallets.solana().signTransaction(this.walletId, {
+            transaction,
+        });
+        const decoded = Buffer.from(signedTransaction, "base64");
+        return (tx instanceof VersionedTransaction ? VersionedTransaction.deserialize(decoded) : Transaction.from(decoded));
+    }
+    async signAllTransactions(txs) {
+        return Promise.all(txs.map((tx) => this.signTransaction(tx)));
+    }
+    async signMessage(message) {
+        const { signature } = await this.wallets.solana().signMessage(this.walletId, { message });
+        return new Uint8Array(Buffer.from(signature, "base64"));
+    }
+}

package/dist/src/signer/backends/turnkey.js

@@ -0,0 +1,53 @@
+import { createRequire } from "node:module";
+import { Transaction, VersionedTransaction } from "@solana/web3.js";
+import { parseSolanaPubkey } from "../../solana-address.js";
+const require = createRequire(import.meta.url);
+export class TurnkeySigner {
+    publicKey;
+    address;
+    signer;
+    constructor(config) {
+        this.publicKey = parseSolanaPubkey(config.address, "TURNKEY_WALLET_ADDRESS");
+        this.address = config.address;
+        let TurnkeyClass;
+        let TurnkeySignerClass;
+        try {
+            ({ Turnkey: TurnkeyClass } = require("@turnkey/sdk-server"));
+            ({ TurnkeySigner: TurnkeySignerClass } = require("@turnkey/solana"));
+        }
+        catch (error) {
+            throw new Error("@turnkey/sdk-server and @turnkey/solana are not installed. Run `npm install @turnkey/sdk-server @turnkey/solana`.", { cause: error });
+        }
+        const client = new TurnkeyClass({
+            apiBaseUrl: "https://api.turnkey.com",
+            apiPublicKey: config.apiPublicKey,
+            apiPrivateKey: config.apiPrivateKey,
+            defaultOrganizationId: config.organizationId,
+        });
+        this.signer = new TurnkeySignerClass({
+            organizationId: config.organizationId,
+            client: client.apiClient(),
+        });
+    }
+    async isAvailable() {
+        try {
+            const signature = await this.signer.signMessage(new Uint8Array(1), this.address);
+            return signature instanceof Uint8Array && signature.length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    async signTransaction(tx) {
+        await this.signer.addSignature(tx, this.address);
+        return tx;
+    }
+    async signAllTransactions(txs) {
+        await Promise.all(txs.map((tx) => this.signer.addSignature(tx, this.address)));
+        return txs;
+    }
+    async signMessage(message) {
+        const signature = await this.signer.signMessage(message, this.address);
+        return signature instanceof Uint8Array ? signature : new Uint8Array(signature);
+    }
+}

package/dist/src/signer/factory.js

@@ -0,0 +1,37 @@
+import { loadOwnerKeypair } from "../config.js";
+import { MemorySigner } from "./backends/memory.js";
+import { PrivySigner } from "./backends/privy.js";
+import { TurnkeySigner } from "./backends/turnkey.js";
+export async function createSigner(config) {
+    const backend = process.env["SIGNER_BACKEND"] ?? "memory";
+    if (backend === "keychain") {
+        return createKeychainSigner();
+    }
+    return MemorySigner.fromSecretKey(loadOwnerKeypair(config));
+}
+function createKeychainSigner() {
+    const provider = process.env["KEYCHAIN_BACKEND"];
+    if (provider === "privy") {
+        return new PrivySigner({
+            appId: requireEnv("PRIVY_APP_ID"),
+            appSecret: requireEnv("PRIVY_APP_SECRET"),
+            walletId: requireEnv("PRIVY_WALLET_ID"),
+            address: requireEnv("PRIVY_WALLET_ADDRESS"),
+        });
+    }
+    if (provider === "turnkey") {
+        return new TurnkeySigner({
+            apiPublicKey: requireEnv("TURNKEY_API_PUBLIC_KEY"),
+            apiPrivateKey: requireEnv("TURNKEY_API_PRIVATE_KEY"),
+            organizationId: requireEnv("TURNKEY_ORGANIZATION_ID"),
+            address: requireEnv("TURNKEY_WALLET_ADDRESS"),
+        });
+    }
+    throw new Error(`Unknown KEYCHAIN_BACKEND="${provider ?? ""}". Supported values: privy, turnkey`);
+}
+function requireEnv(name) {
+    const value = process.env[name];
+    if (!value)
+        throw new Error(`${name} is required for SIGNER_BACKEND=keychain`);
+    return value;
+}

package/dist/src/signer/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/solana-address.js

@@ -0,0 +1,29 @@
+import { address } from "@solana/kit";
+export function parseSolanaPubkey(value, envVar) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new Error(`${envVar} is required`);
+    }
+    try {
+        return address(trimmed);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`${envVar} must be a valid Solana address (base58 pubkey), got ${JSON.stringify(value)}: ${message}`, { cause: error });
+    }
+}
+export function validateSolanaPubkey(value, envVar) {
+    if (!value?.trim()) {
+        return { ok: false, message: `${envVar} is required` };
+    }
+    try {
+        parseSolanaPubkey(value, envVar);
+        return { ok: true };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: error instanceof Error ? error.message : String(error)
+        };
+    }
+}

package/dist/src/solana-compat.js

@@ -0,0 +1,22 @@
+import { isSignerRole, isWritableRole } from "@solana/kit";
+import { PublicKey, TransactionInstruction } from "@solana/web3.js";
+/**
+ * Isolated legacy-interop boundary: @molpha-oracle/sdk, @turnkey/solana, and
+ * connection.sendRawTransaction/confirmTransaction still require classic web3.js
+ * types. Everything else in this codebase works in terms of @solana/kit's
+ * `Address`/`Instruction`.
+ */
+export function toLegacyPublicKey(address) {
+    return new PublicKey(address);
+}
+export function toLegacyInstruction(instruction) {
+    return new TransactionInstruction({
+        programId: toLegacyPublicKey(instruction.programAddress),
+        keys: (instruction.accounts ?? []).map((account) => ({
+            pubkey: toLegacyPublicKey(account.address),
+            isSigner: isSignerRole(account.role),
+            isWritable: isWritableRole(account.role)
+        })),
+        data: Buffer.from(instruction.data ?? new Uint8Array())
+    });
+}

package/dist/src/submit.js

@@ -0,0 +1,46 @@
+/**
+ * The single Solana settle path, shared by `molpha_execute` and
+ * `molpha_fetch_verified`'s `autoSubmit` leg — one guardrail check, one shape
+ * normalization, one place that knows what `submit_data_update` requires.
+ */
+import { toSignedResult } from "./artifacts.js";
+import { getMolphaContext, requireMethod } from "./clients.js";
+import { enforceExecuteCap, previewWrite } from "./guardrails.js";
+/**
+ * Accepts the `molpha_fetch_verified` artifact or the flat signed result, and
+ * returns the flat shape `submitDataUpdate` expects.
+ */
+export function prepareSignedResult(input) {
+    const result = toSignedResult(input);
+    if (!result.feedId) {
+        throw new Error("signed result is missing `feedId`");
+    }
+    // `buildSubmitArgs` packs `valuePacked` as the on-chain value; `value` is the
+    // decimal rendering and is not interchangeable with it.
+    if (!result.valuePacked) {
+        throw new Error("signed result is missing `valuePacked` (the on-chain encoding of `value`); re-run molpha_fetch_verified and pass its output through unmodified");
+    }
+    return result;
+}
+export function previewSubmit(action, result, submitter) {
+    return previewWrite(action, {
+        chain: "solana",
+        action: "submit_data_update",
+        feedId: result.feedId,
+        registryVersion: result.registryVersion,
+        submitter
+    });
+}
+/** Enforces the daily execute cap, then submits. Callers must pass a prepared result. */
+export async function submitSignedResult(result) {
+    const { config, solana } = await getMolphaContext();
+    enforceExecuteCap(config.guardrails);
+    const submitDataUpdate = requireMethod(solana, "submitDataUpdate");
+    const tx = await submitDataUpdate(result);
+    return {
+        chain: "solana",
+        action: "submit_data_update",
+        feedId: String(result.feedId),
+        signature: tx.signature
+    };
+}

package/dist/src/subscription.js

@@ -0,0 +1,48 @@
+import { requireMethod } from "./clients.js";
+export async function readSubscriptionStatus(solana) {
+    const readSubscription = requireMethod(solana, "readSubscription");
+    try {
+        const subscription = await readSubscription();
+        if (!subscription) {
+            return {
+                active: false,
+                message: "No active subscription found. Run `npm run provision -- subscribe` (or molpha-provision bootstrap) with OWNER_KEYPAIR, or use payment: \"x402\" for a self-funded pay-per-request round."
+            };
+        }
+        const validUntil = BigInt(String(subscription.validUntil ?? 0));
+        const now = BigInt(Math.floor(Date.now() / 1000));
+        const usedRounds = BigInt(String(subscription.usedRounds ?? 0));
+        const maxRounds = BigInt(String(subscription.maxRounds ?? 0));
+        const active = validUntil > now && (maxRounds === 0n || usedRounds < maxRounds);
+        return {
+            active,
+            owner: subscription.owner?.toString?.() ?? String(subscription.owner ?? ""),
+            planType: subscription.planType,
+            prepaidUsdc: String(subscription.prepaidUsdc ?? ""),
+            price: String(subscription.price ?? ""),
+            validUntil: validUntil.toString(),
+            usedRounds: Number(usedRounds),
+            maxRounds: Number(maxRounds),
+            ...(active
+                ? {}
+                : {
+                    message: validUntil <= now
+                        ? "Subscription expired. Extend via the bootstrap CLI before requesting data."
+                        : "Subscription round quota exhausted for this period. Extend via the bootstrap CLI, or use payment: \"x402\"."
+                })
+        };
+    }
+    catch (error) {
+        return {
+            active: false,
+            message: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+export async function assertActiveSubscription(solana) {
+    const status = await readSubscriptionStatus(solana);
+    if (!status.active) {
+        throw new Error(status.message ?? "Subscription is inactive or missing");
+    }
+    return status;
+}