@moon-x/solana-adapter 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# @moon-x/solana-adapter
+
+Chain-aware Solana signing helpers for MoonX **ephemeral signers**.
+
+The low-level `signWithEphemeralSigner` primitive in `@moon-x/core` signs
+arbitrary raw bytes for an ed25519 key — which means the integrator is
+responsible for producing the exact bytes (serializing the transaction
+message) and for attaching the returned signature to the transaction. This
+adapter does both: you pass **intent** and get back a ready-to-broadcast
+artifact.
+
+> Solana differs from EVM: ed25519 signs the raw message bytes directly —
+> there is no keccak / pre-hashing step. The adapter handles that correctly
+> so you don't have to think about it.
+
+## Install
+
+```sh
+pnpm add @moon-x/solana-adapter @solana/web3.js
+```
+
+`@solana/web3.js` is a peer dependency, so your app's single instance is the
+one used.
+
+## Usage
+
+```ts
+import { createSolanaSigner } from "@moon-x/solana-adapter";
+
+const signer = createSolanaSigner({
+  apiPubHex,        // from provisioning
+  apiPrivHex,       // never leaves your backend
+  walletId,         // the Solana wallet the agent was provisioned for
+  address,          // base58 wallet pubkey (needed to attach the signature)
+  baseUrl,          // wallets backend URL
+  publishableKey,   // moon_pk_…
+});
+
+// Arbitrary message → 64-byte ed25519 signature
+const sig = await signer.signMessage("gm");
+
+// Transaction (legacy or versioned) → wire-ready serialized bytes
+const raw = await signer.signTransaction(transaction);
+await connection.sendRawTransaction(raw);
+```
+
+## Scheme safety
+
+The adapter enforces that the target wallet is ed25519. Pointing it at a
+secp256k1 (EVM) wallet throws `SolanaSchemeMismatchError` instead of producing
+a valid-but-wrong signature — use `@moon-x/evm-adapter` for those.
+
+## Escape hatch
+
+For signing flows this adapter doesn't model, drop down to
+`signWithEphemeralSigner` from `@moon-x/core/sdk` and build the payload
+yourself.

package/dist/index.d.mts

@@ -0,0 +1,65 @@
+import { Transaction, VersionedTransaction } from '@solana/web3.js';
+
+/**
+ * Connection + identity for a Solana ephemeral signer. `apiPrivHex` is
+ * consumed locally to sign the request envelope and never crosses the
+ * network.
+ */
+interface SolanaSignerConfig {
+    /** Lowercase-hex 32-byte Ed25519 agent public key (no 0x prefix). */
+    apiPubHex: string;
+    /** Lowercase-hex 32-byte Ed25519 agent private key (no 0x prefix). */
+    apiPrivHex: string;
+    /**
+     * Wallet UUID (from `user.wallets[i].id`) to sign on behalf of. Must be
+     * a Solana (ed25519) wallet the agent was provisioned for — a scheme
+     * mismatch is detected and rejected on the first sign.
+     */
+    walletId: string;
+    /**
+     * Base58 Solana address (public key) of the wallet. Required to attach
+     * the produced signature to a transaction — Solana signatures are keyed
+     * by signer pubkey.
+     */
+    address: string;
+    /** Wallets backend base URL (no trailing slash). */
+    baseUrl: string;
+    /** MoonX publishable key (`moon_pk_…`). */
+    publishableKey: string;
+    /** Optional fetch override — e.g. for Next.js route handlers or test stubs. */
+    fetchImpl?: typeof fetch;
+}
+declare class SolanaSchemeMismatchError extends Error {
+    constructor(scheme: string);
+}
+/**
+ * Chain-aware Solana signer backed by a MoonX ephemeral signer. Construct
+ * once per (agent, wallet) and call the intent-level methods.
+ *
+ * All chain logic (message-bytes + signature attachment) lives in
+ * @moon-x/signing-codec/solana — this class is just the ephemeral-signer
+ * *backend* that supplies the `Ed25519SignFn`. The same signing-codec is
+ * driven by the user/MPC backend in the iframe.
+ */
+declare class MoonXSolanaSigner {
+    private readonly cfg;
+    constructor(cfg: SolanaSignerConfig);
+    /** Ephemeral-signer backend: sign raw bytes, return the 64-byte sig. */
+    private readonly sign;
+    /**
+     * Sign an arbitrary message. Accepts a UTF-8 string or raw bytes and
+     * returns the 64-byte ed25519 signature, verifiable against the wallet's
+     * public key (e.g. via `nacl.sign.detached.verify` or Web Crypto).
+     */
+    signMessage(message: string | Uint8Array): Promise<Uint8Array>;
+    /**
+     * Sign a transaction (legacy `Transaction` or `VersionedTransaction`)
+     * and return the wire-ready serialized bytes — pass straight to
+     * `connection.sendRawTransaction`.
+     */
+    signTransaction(transaction: Transaction | VersionedTransaction): Promise<Uint8Array>;
+}
+/** Convenience factory mirroring the class constructor. */
+declare function createSolanaSigner(cfg: SolanaSignerConfig): MoonXSolanaSigner;
+
+export { MoonXSolanaSigner, SolanaSchemeMismatchError, type SolanaSignerConfig, createSolanaSigner };

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+import { Transaction, VersionedTransaction } from '@solana/web3.js';
+
+/**
+ * Connection + identity for a Solana ephemeral signer. `apiPrivHex` is
+ * consumed locally to sign the request envelope and never crosses the
+ * network.
+ */
+interface SolanaSignerConfig {
+    /** Lowercase-hex 32-byte Ed25519 agent public key (no 0x prefix). */
+    apiPubHex: string;
+    /** Lowercase-hex 32-byte Ed25519 agent private key (no 0x prefix). */
+    apiPrivHex: string;
+    /**
+     * Wallet UUID (from `user.wallets[i].id`) to sign on behalf of. Must be
+     * a Solana (ed25519) wallet the agent was provisioned for — a scheme
+     * mismatch is detected and rejected on the first sign.
+     */
+    walletId: string;
+    /**
+     * Base58 Solana address (public key) of the wallet. Required to attach
+     * the produced signature to a transaction — Solana signatures are keyed
+     * by signer pubkey.
+     */
+    address: string;
+    /** Wallets backend base URL (no trailing slash). */
+    baseUrl: string;
+    /** MoonX publishable key (`moon_pk_…`). */
+    publishableKey: string;
+    /** Optional fetch override — e.g. for Next.js route handlers or test stubs. */
+    fetchImpl?: typeof fetch;
+}
+declare class SolanaSchemeMismatchError extends Error {
+    constructor(scheme: string);
+}
+/**
+ * Chain-aware Solana signer backed by a MoonX ephemeral signer. Construct
+ * once per (agent, wallet) and call the intent-level methods.
+ *
+ * All chain logic (message-bytes + signature attachment) lives in
+ * @moon-x/signing-codec/solana — this class is just the ephemeral-signer
+ * *backend* that supplies the `Ed25519SignFn`. The same signing-codec is
+ * driven by the user/MPC backend in the iframe.
+ */
+declare class MoonXSolanaSigner {
+    private readonly cfg;
+    constructor(cfg: SolanaSignerConfig);
+    /** Ephemeral-signer backend: sign raw bytes, return the 64-byte sig. */
+    private readonly sign;
+    /**
+     * Sign an arbitrary message. Accepts a UTF-8 string or raw bytes and
+     * returns the 64-byte ed25519 signature, verifiable against the wallet's
+     * public key (e.g. via `nacl.sign.detached.verify` or Web Crypto).
+     */
+    signMessage(message: string | Uint8Array): Promise<Uint8Array>;
+    /**
+     * Sign a transaction (legacy `Transaction` or `VersionedTransaction`)
+     * and return the wire-ready serialized bytes — pass straight to
+     * `connection.sendRawTransaction`.
+     */
+    signTransaction(transaction: Transaction | VersionedTransaction): Promise<Uint8Array>;
+}
+/** Convenience factory mirroring the class constructor. */
+declare function createSolanaSigner(cfg: SolanaSignerConfig): MoonXSolanaSigner;
+
+export { MoonXSolanaSigner, SolanaSchemeMismatchError, type SolanaSignerConfig, createSolanaSigner };

package/dist/index.js

@@ -0,0 +1,141 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  MoonXSolanaSigner: () => MoonXSolanaSigner,
+  SolanaSchemeMismatchError: () => SolanaSchemeMismatchError,
+  createSolanaSigner: () => createSolanaSigner
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/signer.ts
+var import_sdk = require("@moon-x/core/sdk");
+
+// ../signing-codec/dist/solana.mjs
+var import_web3 = require("@solana/web3.js");
+function isVersioned(tx) {
+  return "version" in tx;
+}
+function solanaTransactionMessageBytes(tx) {
+  return isVersioned(tx) ? tx.message.serialize() : tx.serializeMessage();
+}
+async function signSolanaMessage(sign, message) {
+  const bytes = typeof message === "string" ? new TextEncoder().encode(message) : message;
+  return sign(bytes);
+}
+function attachSolanaSignature(tx, signature, signerAddress) {
+  const pubkey = new import_web3.PublicKey(signerAddress);
+  if (isVersioned(tx)) {
+    const clone2 = import_web3.VersionedTransaction.deserialize(tx.serialize());
+    clone2.addSignature(pubkey, signature);
+    return clone2.serialize();
+  }
+  const clone = import_web3.Transaction.from(
+    tx.serialize({ requireAllSignatures: false, verifySignatures: false })
+  );
+  clone.addSignature(pubkey, Buffer.from(signature));
+  return clone.serialize({
+    requireAllSignatures: false,
+    verifySignatures: false
+  });
+}
+async function signSolanaTransaction(sign, tx, signerAddress) {
+  const sig = await sign(solanaTransactionMessageBytes(tx));
+  return attachSolanaSignature(tx, sig, signerAddress);
+}
+
+// src/signer.ts
+var SolanaSchemeMismatchError = class extends Error {
+  constructor(scheme) {
+    super(
+      `wallet returned scheme "${scheme}", not eddsa_ed25519 \u2014 this is not a Solana wallet. Use @moon-x/evm-adapter for secp256k1 wallets.`
+    );
+    this.name = "SolanaSchemeMismatchError";
+  }
+};
+function bytesToHex(bytes) {
+  let out = "";
+  for (const b of bytes) out += b.toString(16).padStart(2, "0");
+  return out;
+}
+function hexToBytes(hex) {
+  const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+  const out = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+function requireEd25519(result) {
+  if (result.scheme !== "eddsa_ed25519") {
+    throw new SolanaSchemeMismatchError(result.scheme);
+  }
+  const sigHex = result.signature.signature;
+  if (!sigHex) {
+    throw new Error(
+      "ephemeral signer returned an ed25519 scheme without a signature"
+    );
+  }
+  return hexToBytes(sigHex);
+}
+var MoonXSolanaSigner = class {
+  constructor(cfg) {
+    this.cfg = cfg;
+    /** Ephemeral-signer backend: sign raw bytes, return the 64-byte sig. */
+    this.sign = async (message) => {
+      const result = await (0, import_sdk.signWithEphemeralSigner)({
+        apiPubHex: this.cfg.apiPubHex,
+        apiPrivHex: this.cfg.apiPrivHex,
+        walletId: this.cfg.walletId,
+        rawSigningPayloadHex: bytesToHex(message),
+        baseUrl: this.cfg.baseUrl,
+        publishableKey: this.cfg.publishableKey,
+        fetchImpl: this.cfg.fetchImpl
+      });
+      return requireEd25519(result);
+    };
+  }
+  /**
+   * Sign an arbitrary message. Accepts a UTF-8 string or raw bytes and
+   * returns the 64-byte ed25519 signature, verifiable against the wallet's
+   * public key (e.g. via `nacl.sign.detached.verify` or Web Crypto).
+   */
+  signMessage(message) {
+    return signSolanaMessage(this.sign, message);
+  }
+  /**
+   * Sign a transaction (legacy `Transaction` or `VersionedTransaction`)
+   * and return the wire-ready serialized bytes — pass straight to
+   * `connection.sendRawTransaction`.
+   */
+  signTransaction(transaction) {
+    return signSolanaTransaction(this.sign, transaction, this.cfg.address);
+  }
+};
+function createSolanaSigner(cfg) {
+  return new MoonXSolanaSigner(cfg);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MoonXSolanaSigner,
+  SolanaSchemeMismatchError,
+  createSolanaSigner
+});

package/dist/index.mjs

@@ -0,0 +1,118 @@
+// src/signer.ts
+import {
+  signWithEphemeralSigner
+} from "@moon-x/core/sdk";
+
+// ../signing-codec/dist/solana.mjs
+import {
+  PublicKey,
+  Transaction,
+  VersionedTransaction
+} from "@solana/web3.js";
+function isVersioned(tx) {
+  return "version" in tx;
+}
+function solanaTransactionMessageBytes(tx) {
+  return isVersioned(tx) ? tx.message.serialize() : tx.serializeMessage();
+}
+async function signSolanaMessage(sign, message) {
+  const bytes = typeof message === "string" ? new TextEncoder().encode(message) : message;
+  return sign(bytes);
+}
+function attachSolanaSignature(tx, signature, signerAddress) {
+  const pubkey = new PublicKey(signerAddress);
+  if (isVersioned(tx)) {
+    const clone2 = VersionedTransaction.deserialize(tx.serialize());
+    clone2.addSignature(pubkey, signature);
+    return clone2.serialize();
+  }
+  const clone = Transaction.from(
+    tx.serialize({ requireAllSignatures: false, verifySignatures: false })
+  );
+  clone.addSignature(pubkey, Buffer.from(signature));
+  return clone.serialize({
+    requireAllSignatures: false,
+    verifySignatures: false
+  });
+}
+async function signSolanaTransaction(sign, tx, signerAddress) {
+  const sig = await sign(solanaTransactionMessageBytes(tx));
+  return attachSolanaSignature(tx, sig, signerAddress);
+}
+
+// src/signer.ts
+var SolanaSchemeMismatchError = class extends Error {
+  constructor(scheme) {
+    super(
+      `wallet returned scheme "${scheme}", not eddsa_ed25519 \u2014 this is not a Solana wallet. Use @moon-x/evm-adapter for secp256k1 wallets.`
+    );
+    this.name = "SolanaSchemeMismatchError";
+  }
+};
+function bytesToHex(bytes) {
+  let out = "";
+  for (const b of bytes) out += b.toString(16).padStart(2, "0");
+  return out;
+}
+function hexToBytes(hex) {
+  const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+  const out = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+function requireEd25519(result) {
+  if (result.scheme !== "eddsa_ed25519") {
+    throw new SolanaSchemeMismatchError(result.scheme);
+  }
+  const sigHex = result.signature.signature;
+  if (!sigHex) {
+    throw new Error(
+      "ephemeral signer returned an ed25519 scheme without a signature"
+    );
+  }
+  return hexToBytes(sigHex);
+}
+var MoonXSolanaSigner = class {
+  constructor(cfg) {
+    this.cfg = cfg;
+    /** Ephemeral-signer backend: sign raw bytes, return the 64-byte sig. */
+    this.sign = async (message) => {
+      const result = await signWithEphemeralSigner({
+        apiPubHex: this.cfg.apiPubHex,
+        apiPrivHex: this.cfg.apiPrivHex,
+        walletId: this.cfg.walletId,
+        rawSigningPayloadHex: bytesToHex(message),
+        baseUrl: this.cfg.baseUrl,
+        publishableKey: this.cfg.publishableKey,
+        fetchImpl: this.cfg.fetchImpl
+      });
+      return requireEd25519(result);
+    };
+  }
+  /**
+   * Sign an arbitrary message. Accepts a UTF-8 string or raw bytes and
+   * returns the 64-byte ed25519 signature, verifiable against the wallet's
+   * public key (e.g. via `nacl.sign.detached.verify` or Web Crypto).
+   */
+  signMessage(message) {
+    return signSolanaMessage(this.sign, message);
+  }
+  /**
+   * Sign a transaction (legacy `Transaction` or `VersionedTransaction`)
+   * and return the wire-ready serialized bytes — pass straight to
+   * `connection.sendRawTransaction`.
+   */
+  signTransaction(transaction) {
+    return signSolanaTransaction(this.sign, transaction, this.cfg.address);
+  }
+};
+function createSolanaSigner(cfg) {
+  return new MoonXSolanaSigner(cfg);
+}
+export {
+  MoonXSolanaSigner,
+  SolanaSchemeMismatchError,
+  createSolanaSigner
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@moon-x/solana-adapter",
+  "version": "0.1.0",
+  "description": "Chain-aware Solana signing helpers for MoonX ephemeral signers. Serializes the message bytes and assembles ready-to-broadcast transactions/signatures so integrators never hand-roll payload construction.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "moonx",
+    "moonpay",
+    "solana",
+    "ed25519",
+    "web3.js",
+    "signer",
+    "wallet",
+    "sdk"
+  ],
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@moon-x/core": "0.7.0"
+  },
+  "peerDependencies": {
+    "@solana/web3.js": "^1.98.0"
+  },
+  "devDependencies": {
+    "@noble/curves": "1.8.0",
+    "@solana/web3.js": "^1.98.4",
+    "bs58": "6.0.0",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "1.6.1",
+    "@moon-x/signing-codec": "0.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist .turbo node_modules"
+  }
+}