uvd-x402-sdk 2.34.0 → 2.36.0

package/README.md

@@ -12,6 +12,7 @@ Users sign a message or transaction, and the Ultravioleta facilitator handles on
 - **Gasless**: Facilitator pays all network fees
 - **Type-Safe**: Full TypeScript support
 - **React & Wagmi**: First-class integrations
+- **Signing Wallet Adapters**: EnvKeyAdapter (server/CLI), OWSWalletAdapter (Open Wallet Standard), or bring your own
 - **ERC-8004 Trustless Agents**: On-chain reputation and identity (EVM + Solana)
 - **Escrow & Refunds**: Hold payments with dispute resolution
 - **`/accepts` Negotiation**: Discover facilitator capabilities before constructing payments
@@ -476,6 +477,80 @@ function PayButton() {
 }
 ```
 
+## Signing Wallet Adapters
+
+Low-level signing primitives for server-side agents, CLI tools, and Open Wallet Standard wallets. These adapters implement EIP-191, EIP-712, and EIP-3009 (gasless USDC transfers).
+
+### EnvKeyAdapter (Server / CLI / Agents)
+
+Signs with a raw private key from the environment or constructor. **Never use in browser contexts.**
+
+```typescript
+import { EnvKeyAdapter } from 'uvd-x402-sdk';
+
+// Option 1: Reads process.env.WALLET_PRIVATE_KEY
+const wallet = new EnvKeyAdapter();
+
+// Option 2: Explicit key
+const wallet = new EnvKeyAdapter(process.env.MY_AGENT_KEY!);
+
+console.log(wallet.getAddress()); // 0x...
+
+// Sign EIP-3009 gasless USDC transfer
+const auth = await wallet.signEIP3009({
+  to: '0xRecipient...',
+  amountUsdc: 1.00,
+  network: 'base',
+});
+// auth contains: from, to, value, nonce, v, r, s, signature
+
+// Sign arbitrary message (EIP-191)
+const sig = await wallet.signMessage('Hello x402');
+
+// Sign EIP-712 typed data
+const result = await wallet.signTypedData(JSON.stringify({
+  domain: { name: 'MyApp', version: '1', chainId: 8453 },
+  types: { Order: [{ name: 'id', type: 'uint256' }] },
+  primaryType: 'Order',
+  message: { id: 42 },
+}));
+```
+
+### OWSWalletAdapter (Open Wallet Standard)
+
+Delegates signing to any wallet that implements the [Open Wallet Standard](https://github.com/open-wallet-standard/open-wallet-standard). Works with browser wallets, agent vaults, and hardware-backed signers.
+
+```bash
+npm install @open-wallet-standard/core  # optional peer dependency
+```
+
+```typescript
+import { OWSWalletAdapter } from 'uvd-x402-sdk';
+
+const wallet = new OWSWalletAdapter(owsWalletInstance);
+
+const auth = await wallet.signEIP3009({
+  to: '0xRecipient...',
+  amountUsdc: 0.50,
+  network: 'base',
+});
+```
+
+### Custom Adapter
+
+Implement the `SigningWalletAdapter` interface for your own signer:
+
+```typescript
+import type { SigningWalletAdapter, EIP3009Params, EIP3009Authorization } from 'uvd-x402-sdk';
+
+class MyAdapter implements SigningWalletAdapter {
+  getAddress(): string { /* ... */ }
+  async signMessage(message: string): Promise<string> { /* ... */ }
+  async signTypedData(typedData: string): Promise<{ signature: string; v: number; r: string; s: string }> { /* ... */ }
+  async signEIP3009(params: EIP3009Params): Promise<EIP3009Authorization> { /* ... */ }
+}
+```
+
 ## Multi-Stablecoin (EVM)
 
 ```typescript

package/dist/adapters/index.d.mts

@@ -1,4 +1,6 @@
 import { L as X402Version, k as PaymentResult } from '../index-MNVg3WMv.mjs';
+export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from '../ows-CYIVd4xO.mjs';
+import '../wallet-0cX9Pw2F.mjs';
 
 /**
  * uvd-x402-sdk - Wagmi/Viem Adapter

package/dist/adapters/index.d.ts

@@ -1,4 +1,6 @@
 import { L as X402Version, k as PaymentResult } from '../index-MNVg3WMv.js';
+export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from '../ows-DTDixPzO.js';
+import '../wallet-0cX9Pw2F.js';
 
 /**
  * uvd-x402-sdk - Wagmi/Viem Adapter

package/dist/adapters/index.js

@@ -1,5 +1,7 @@
 'use strict';
 
+var ethers = require('ethers');
+
 // src/chains/index.ts
 var DEFAULT_FACILITATOR_URL = "https://facilitator.ultravioletadao.xyz";
 var SUPPORTED_CHAINS = {
@@ -1077,7 +1079,344 @@ function useX402Wagmi(walletClient) {
     createPaymentFull
   };
 }
+var EnvKeyAdapter = class {
+  wallet;
+  /**
+   * Create an EnvKeyAdapter.
+   *
+   * @param privateKey - Hex-encoded private key (with or without 0x prefix).
+   *   If omitted, reads from `process.env.WALLET_PRIVATE_KEY`.
+   * @throws {X402Error} if no private key is available
+   */
+  constructor(privateKey) {
+    const key = privateKey || (typeof process !== "undefined" ? process.env.WALLET_PRIVATE_KEY : void 0);
+    if (!key) {
+      throw new X402Error(
+        "No private key provided. Pass it to the constructor or set WALLET_PRIVATE_KEY env var.",
+        "WALLET_NOT_CONNECTED"
+      );
+    }
+    this.wallet = new ethers.ethers.Wallet(key);
+  }
+  /**
+   * Get the checksummed EVM wallet address.
+   */
+  getAddress() {
+    return this.wallet.address;
+  }
+  /**
+   * Sign a message using EIP-191 personal_sign.
+   *
+   * @param message - The message string to sign
+   * @returns Hex-encoded signature
+   */
+  async signMessage(message) {
+    return this.wallet.signMessage(message);
+  }
+  /**
+   * Sign EIP-712 typed structured data.
+   *
+   * @param typedData - JSON string with `domain`, `types`, `primaryType`, and `message` fields
+   * @returns Object with signature and v/r/s components
+   */
+  async signTypedData(typedData) {
+    const parsed = JSON.parse(typedData);
+    const { domain, types, message } = parsed;
+    const cleanTypes = { ...types };
+    delete cleanTypes["EIP712Domain"];
+    const signature = await this.wallet.signTypedData(domain, cleanTypes, message);
+    const sig = ethers.ethers.Signature.from(signature);
+    return {
+      signature,
+      v: sig.v,
+      r: sig.r,
+      s: sig.s
+    };
+  }
+  /**
+   * Sign a serialized EVM transaction.
+   *
+   * Uses the raw private key via ethers.Wallet.signTransaction().
+   * Used by AdvancedEscrowClient for on-chain operations (release,
+   * refund, charge) when constructed with a SigningWalletAdapter.
+   *
+   * @param unsignedTx - Hex-encoded unsigned transaction (ethers serialized)
+   * @returns Hex-encoded signed raw transaction, ready for broadcast
+   */
+  async signTransaction(unsignedTx) {
+    const tx = ethers.ethers.Transaction.from(unsignedTx);
+    return this.wallet.signTransaction(tx);
+  }
+  /**
+   * Sign an EIP-3009 ReceiveWithAuthorization for USDC.
+   *
+   * @param params - EIP-3009 parameters
+   * @returns Signed authorization ready for facilitator relay
+   */
+  async signEIP3009(params) {
+    const chain = getChainByName(params.network);
+    if (!chain) {
+      throw new X402Error(`Unsupported network: ${params.network}`, "CHAIN_NOT_SUPPORTED");
+    }
+    if (chain.networkType !== "evm") {
+      throw new X402Error(
+        `EIP-3009 is only supported on EVM chains. ${params.network} is ${chain.networkType}.`,
+        "CHAIN_NOT_SUPPORTED"
+      );
+    }
+    const chainId = params.chainId ?? chain.chainId;
+    const usdcAddress = params.usdcContract ?? chain.usdc.address;
+    const from = this.wallet.address;
+    const to = ethers.ethers.getAddress(params.to);
+    const value = ethers.ethers.parseUnits(params.amountUsdc.toString(), chain.usdc.decimals);
+    const validAfter = params.validAfter ?? 0;
+    const validBefore = params.validBefore ?? Math.floor(Date.now() / 1e3) + 300;
+    const nonce = ethers.ethers.hexlify(ethers.ethers.randomBytes(32));
+    const domain = {
+      name: chain.usdc.name,
+      version: chain.usdc.version,
+      chainId,
+      verifyingContract: usdcAddress
+    };
+    const types = {
+      TransferWithAuthorization: [
+        { name: "from", type: "address" },
+        { name: "to", type: "address" },
+        { name: "value", type: "uint256" },
+        { name: "validAfter", type: "uint256" },
+        { name: "validBefore", type: "uint256" },
+        { name: "nonce", type: "bytes32" }
+      ]
+    };
+    const message = {
+      from,
+      to,
+      value,
+      validAfter,
+      validBefore,
+      nonce
+    };
+    let signature;
+    try {
+      signature = await this.wallet.signTypedData(domain, types, message);
+    } catch (error) {
+      throw new X402Error(
+        `Failed to sign EIP-3009 authorization: ${error instanceof Error ? error.message : "Unknown error"}`,
+        "PAYMENT_FAILED",
+        error
+      );
+    }
+    const sig = ethers.ethers.Signature.from(signature);
+    return {
+      from,
+      to,
+      value: value.toString(),
+      validAfter: validAfter.toString(),
+      validBefore: validBefore.toString(),
+      nonce,
+      v: sig.v,
+      r: sig.r,
+      s: sig.s,
+      signature
+    };
+  }
+};
+var OWSWalletAdapter = class {
+  owsWallet;
+  address;
+  /**
+   * Create an OWSWalletAdapter.
+   *
+   * @param owsWallet - An object implementing the OWSWallet interface
+   *   (typically from @open-wallet-standard/core or a compatible provider)
+   * @param accountIndex - Which account to use if the wallet has multiple (default: 0)
+   * @throws {X402Error} if the wallet has no accounts
+   */
+  constructor(owsWallet, accountIndex = 0) {
+    if (!owsWallet || !owsWallet.accounts || owsWallet.accounts.length === 0) {
+      throw new X402Error(
+        "OWS wallet has no accounts. Create or import a wallet first.",
+        "WALLET_NOT_CONNECTED"
+      );
+    }
+    const account = owsWallet.accounts[accountIndex];
+    if (!account) {
+      throw new X402Error(
+        `OWS wallet account index ${accountIndex} does not exist. Wallet has ${owsWallet.accounts.length} account(s).`,
+        "WALLET_NOT_CONNECTED"
+      );
+    }
+    this.owsWallet = owsWallet;
+    this.address = ethers.ethers.getAddress(account.address);
+  }
+  /**
+   * Get the checksummed EVM wallet address.
+   */
+  getAddress() {
+    return this.address;
+  }
+  /**
+   * Sign a message using EIP-191 personal_sign.
+   *
+   * @param message - The message string to sign
+   * @returns Hex-encoded signature
+   */
+  async signMessage(message) {
+    try {
+      const result = await this.owsWallet.signMessage({
+        account: { address: this.address },
+        message
+      });
+      return result.signature;
+    } catch (error) {
+      throw new X402Error(
+        `OWS signMessage failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+        "PAYMENT_FAILED",
+        error
+      );
+    }
+  }
+  /**
+   * Sign EIP-712 typed structured data.
+   *
+   * @param typedData - JSON string with `domain`, `types`, `primaryType`, and `message` fields
+   * @returns Object with signature and v/r/s components
+   */
+  async signTypedData(typedData) {
+    const parsed = JSON.parse(typedData);
+    try {
+      const result = await this.owsWallet.signTypedData({
+        account: { address: this.address },
+        domain: parsed.domain,
+        types: parsed.types,
+        primaryType: parsed.primaryType,
+        message: parsed.message
+      });
+      const sig = ethers.ethers.Signature.from(result.signature);
+      return {
+        signature: result.signature,
+        v: sig.v,
+        r: sig.r,
+        s: sig.s
+      };
+    } catch (error) {
+      throw new X402Error(
+        `OWS signTypedData failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+        "PAYMENT_FAILED",
+        error
+      );
+    }
+  }
+  /**
+   * Sign a serialized EVM transaction.
+   *
+   * Delegates to the OWS wallet's signTransaction method.
+   * Used by AdvancedEscrowClient for on-chain operations (release,
+   * refund, charge) where the wallet signs instead of a raw private key.
+   *
+   * @param unsignedTx - Hex-encoded unsigned transaction
+   * @returns Hex-encoded signed raw transaction
+   */
+  async signTransaction(unsignedTx) {
+    try {
+      const result = await this.owsWallet.signTransaction({
+        account: { address: this.address },
+        transaction: unsignedTx,
+        chainId: "1"
+        // chainId is embedded in the serialized TX; this is a hint
+      });
+      return result.signedTransaction;
+    } catch (error) {
+      throw new X402Error(
+        `OWS signTransaction failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+        "PAYMENT_FAILED",
+        error
+      );
+    }
+  }
+  /**
+   * Sign an EIP-3009 ReceiveWithAuthorization for USDC.
+   *
+   * @param params - EIP-3009 parameters
+   * @returns Signed authorization ready for facilitator relay
+   */
+  async signEIP3009(params) {
+    const chain = getChainByName(params.network);
+    if (!chain) {
+      throw new X402Error(`Unsupported network: ${params.network}`, "CHAIN_NOT_SUPPORTED");
+    }
+    if (chain.networkType !== "evm") {
+      throw new X402Error(
+        `EIP-3009 is only supported on EVM chains. ${params.network} is ${chain.networkType}.`,
+        "CHAIN_NOT_SUPPORTED"
+      );
+    }
+    const chainId = params.chainId ?? chain.chainId;
+    const usdcAddress = params.usdcContract ?? chain.usdc.address;
+    const from = this.address;
+    const to = ethers.ethers.getAddress(params.to);
+    const value = ethers.ethers.parseUnits(params.amountUsdc.toString(), chain.usdc.decimals);
+    const validAfter = params.validAfter ?? 0;
+    const validBefore = params.validBefore ?? Math.floor(Date.now() / 1e3) + 300;
+    const nonce = ethers.ethers.hexlify(ethers.ethers.randomBytes(32));
+    const domain = {
+      name: chain.usdc.name,
+      version: chain.usdc.version,
+      chainId,
+      verifyingContract: usdcAddress
+    };
+    const types = {
+      TransferWithAuthorization: [
+        { name: "from", type: "address" },
+        { name: "to", type: "address" },
+        { name: "value", type: "uint256" },
+        { name: "validAfter", type: "uint256" },
+        { name: "validBefore", type: "uint256" },
+        { name: "nonce", type: "bytes32" }
+      ]
+    };
+    const message = {
+      from,
+      to,
+      value: value.toString(),
+      validAfter: validAfter.toString(),
+      validBefore: validBefore.toString(),
+      nonce
+    };
+    let signatureResult;
+    try {
+      signatureResult = await this.owsWallet.signTypedData({
+        account: { address: this.address },
+        domain,
+        types,
+        primaryType: "TransferWithAuthorization",
+        message
+      });
+    } catch (error) {
+      throw new X402Error(
+        `OWS signEIP3009 failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+        "PAYMENT_FAILED",
+        error
+      );
+    }
+    const sig = ethers.ethers.Signature.from(signatureResult.signature);
+    return {
+      from,
+      to,
+      value: value.toString(),
+      validAfter: validAfter.toString(),
+      validBefore: validBefore.toString(),
+      nonce,
+      v: sig.v,
+      r: sig.r,
+      s: sig.s,
+      signature: signatureResult.signature
+    };
+  }
+};
 
+exports.EnvKeyAdapter = EnvKeyAdapter;
+exports.OWSWalletAdapter = OWSWalletAdapter;
 exports.createPaymentFromWalletClient = createPaymentFromWalletClient;
 exports.createPaymentWithResult = createPaymentWithResult;
 exports.useX402Wagmi = useX402Wagmi;