@armory-sh/client-ethers 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sawyer Cutler
+
+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,30 @@
+# @armory-sh/client-ethers
+
+Ethers v6 client for creating and signing Armory payments.
+
+## Install
+
+```bash
+bun add @armory-sh/client-ethers
+```
+
+## Use
+
+```typescript
+import { ethers } from 'ethers'
+import { createArmoryPayment } from '@armory-sh/client-ethers'
+
+const provider = new ethers.JsonRpcProvider('https://mainnet.base.org')
+const signer = await provider.getSigner()
+
+const payment = await createArmoryPayment(signer, {
+  to: '0x...',
+  amount: 1000000n,
+  chainId: 'eip155:8453',
+  assetId: 'eip155:8453/erc20:0x...'
+})
+```
+
+---
+
+MIT License | Sawyer Cutler 2026 | Provided "AS IS" without warranty

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+import { PaymentRequirements, CAIP2ChainId, CAIPAssetId, CustomToken } from '@armory-sh/base';
+export { Address, BalanceOfParams, CAIP2ChainId, CAIPAssetId, EIP712_TYPES, ERC20_ABI, Extensions, NETWORKS, NetworkConfig, PayToV2, PaymentPayload, PaymentPayloadV1, PaymentPayloadV2, PaymentRequirements, PaymentRequirementsV1, PaymentRequirementsV2, SettlementResponse, SettlementResponseV1, SettlementResponseV2, Signature, TransferWithAuthorizationParams, V1_HEADERS, V2_HEADERS, createEIP712Domain, createTransferWithAuthorization, decodePayment, decodePaymentPayload, decodePaymentV1, decodePaymentV2, decodeSettlement, decodeSettlementResponse, decodeSettlementV1, decodeSettlementV2, detectPaymentVersion, encodePaymentPayload, encodePaymentV1, encodePaymentV2, encodeSettlementResponse, encodeSettlementV1, encodeSettlementV2, getMainnets, getNetworkByChainId, getNetworkConfig, getPaymentHeaderName, getPaymentRequiredHeaderName, getPaymentResponseHeaderName, getPaymentVersionFromPayload, getRequirementsVersion, getSettlementVersion, getTestnets, getTxHash, isAddress, isCAIP2ChainId, isCAIPAssetId, isPaymentV1, isPaymentV2, isSettlementSuccessful, isSettlementV1, isSettlementV2, isV1, isV2, validateTransferWithAuthorization } from '@armory-sh/base';
+import { Signer, Provider } from 'ethers';
+export { Signer } from 'ethers';
+
+declare function createPaymentPayloadV1(params: {
+    signer: Signer;
+    from: string;
+    to: string;
+    amount: string;
+    nonce: string;
+    expiry: number;
+    chainId: number;
+    contractAddress: string;
+    network: string;
+    domainName?: string;
+    domainVersion?: string;
+}): Promise<string>;
+declare function createPaymentPayloadV2(params: {
+    signer: Signer;
+    from: `0x${string}`;
+    to: `0x${string}` | {
+        role?: string;
+        callback?: string;
+    };
+    amount: string;
+    nonce: string;
+    expiry: number;
+    chainId: CAIP2ChainId;
+    assetId: CAIPAssetId;
+    extensions?: Record<string, unknown>;
+    domainName?: string;
+    domainVersion?: string;
+}): Promise<string>;
+declare function detectProtocolVersion(requirements: PaymentRequirements): 1 | 2;
+declare function createPaymentPayload(requirements: PaymentRequirements, signer: Signer, from: string): Promise<[string, string]>;
+declare function parsePaymentRequirements(response: Response): Promise<PaymentRequirements>;
+
+/** Token configuration - can use pre-configured tokens from @armory-sh/tokens */
+type Token = CustomToken;
+interface X402ClientConfig {
+    protocolVersion?: 1 | 2 | "auto";
+    defaultExpiry?: number;
+    nonceGenerator?: () => string;
+    network?: string;
+    usdcAddress?: `0x${string}`;
+    rpcUrl?: string;
+    /** Pre-configured token object (overrides individual fields below) */
+    token?: Token;
+    /** Override EIP-712 domain name for custom tokens */
+    domainName?: string;
+    /** Override EIP-712 domain version for custom tokens */
+    domainVersion?: string;
+}
+interface SignerClientConfig extends X402ClientConfig {
+    signer: Signer;
+}
+interface ProviderClientConfig extends X402ClientConfig {
+    provider: Provider;
+    signer?: never;
+}
+type ClientConfig = SignerClientConfig | ProviderClientConfig;
+interface X402TransportConfig {
+    baseURL?: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+    autoPay?: boolean;
+    maxRetries?: number;
+    retryDelay?: number;
+    onPaymentRequired?: (requirements: unknown) => boolean | Promise<boolean>;
+    onPaymentSuccess?: (settlement: unknown) => void;
+    onPaymentError?: (error: Error) => void;
+}
+interface X402RequestInit extends Omit<RequestInit, "headers"> {
+    headers?: Record<string, string> | Headers;
+    skipAutoPay?: boolean;
+    forceProtocolVersion?: 1 | 2;
+}
+
+interface X402Transport {
+    fetch(url: string, init?: X402RequestInit): Promise<Response>;
+    get(url: string, init?: X402RequestInit): Promise<Response>;
+    post(url: string, body?: unknown, init?: X402RequestInit): Promise<Response>;
+    put(url: string, body?: unknown, init?: X402RequestInit): Promise<Response>;
+    del(url: string, init?: X402RequestInit): Promise<Response>;
+    patch(url: string, body?: unknown, init?: X402RequestInit): Promise<Response>;
+    setSigner(signer: Signer): void;
+    getSigner(): Signer | undefined;
+}
+declare const createX402Transport: (config?: X402TransportConfig) => X402Transport;
+
+export { type ClientConfig, type X402ClientConfig, createPaymentPayload, createPaymentPayloadV1, createPaymentPayloadV2, createX402Transport, detectProtocolVersion, parsePaymentRequirements };

package/dist/index.js

@@ -0,0 +1,412 @@
+// src/index.ts
+import {
+  V1_HEADERS as V1_HEADERS2,
+  encodePaymentPayload,
+  decodePaymentPayload,
+  encodeSettlementResponse,
+  decodeSettlementResponse
+} from "@armory-sh/base";
+import {
+  V2_HEADERS as V2_HEADERS2,
+  isCAIP2ChainId,
+  isCAIPAssetId,
+  isAddress
+} from "@armory-sh/base";
+import {
+  isV1,
+  isV2,
+  getPaymentVersionFromPayload,
+  getRequirementsVersion,
+  getSettlementVersion,
+  getPaymentHeaderName,
+  getPaymentResponseHeaderName,
+  getPaymentRequiredHeaderName,
+  isSettlementSuccessful,
+  getTxHash
+} from "@armory-sh/base";
+import {
+  NETWORKS,
+  getNetworkConfig,
+  getNetworkByChainId as getNetworkByChainId2,
+  getMainnets,
+  getTestnets
+} from "@armory-sh/base";
+import { ERC20_ABI } from "@armory-sh/base";
+import {
+  encodePaymentV1 as encodePaymentV12,
+  decodePaymentV1,
+  encodeSettlementV1,
+  decodeSettlementV1,
+  encodePaymentV2 as encodePaymentV22,
+  decodePaymentV2,
+  encodeSettlementV2,
+  decodeSettlementV2,
+  detectPaymentVersion,
+  decodePayment,
+  decodeSettlement as decodeSettlement2,
+  isPaymentV1,
+  isPaymentV2,
+  isSettlementV1,
+  isSettlementV2
+} from "@armory-sh/base";
+import {
+  EIP712_TYPES,
+  createEIP712Domain as createEIP712Domain2,
+  createTransferWithAuthorization,
+  validateTransferWithAuthorization
+} from "@armory-sh/base";
+
+// src/protocol.ts
+import {
+  encodePaymentV1,
+  encodePaymentV2,
+  V1_HEADERS,
+  V2_HEADERS,
+  getNetworkByChainId
+} from "@armory-sh/base";
+
+// src/eip3009.ts
+import {
+  createEIP712Domain
+} from "@armory-sh/base";
+
+// src/types.ts
+var X402ClientError = class extends Error {
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.name = "X402ClientError";
+    this.cause = cause;
+  }
+};
+var SignerRequiredError = class extends X402ClientError {
+  constructor(message = "Signer is required for this operation") {
+    super(message);
+    this.name = "SignerRequiredError";
+  }
+};
+var AuthorizationError = class extends X402ClientError {
+  constructor(message, cause) {
+    super(`Authorization failed: ${message}`, cause);
+    this.name = "AuthorizationError";
+  }
+};
+
+// src/eip3009.ts
+var EIP712_TYPES_ETHERS = {
+  TransferWithAuthorization: [
+    { name: "from", type: "address" },
+    { name: "to", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "validAfter", type: "uint256" },
+    { name: "validBefore", type: "uint256" },
+    { name: "nonce", type: "uint256" }
+  ]
+};
+async function signEIP3009(signer, params, domain) {
+  try {
+    const message = {
+      from: params.from,
+      to: params.to,
+      value: BigInt(params.value),
+      validAfter: BigInt(params.validAfter),
+      validBefore: BigInt(params.validBefore),
+      nonce: BigInt(params.nonce)
+    };
+    const signature = await signer.signTypedData(domain, EIP712_TYPES_ETHERS, message);
+    const { v, r, s } = ethers.Signature.from(signature);
+    return { v: Number(v), r, s };
+  } catch (error) {
+    throw new AuthorizationError(
+      `Failed to sign EIP-3009 authorization: ${error instanceof Error ? error.message : "Unknown error"}`,
+      error
+    );
+  }
+}
+
+// src/protocol.ts
+async function createPaymentPayloadV1(params) {
+  const { signer, from, to, amount, nonce, expiry, chainId, contractAddress, network, domainName, domainVersion } = params;
+  const authParams = {
+    from,
+    to,
+    value: BigInt(Math.floor(parseFloat(amount) * 1e6)),
+    validAfter: 0n,
+    validBefore: BigInt(expiry),
+    nonce: BigInt(nonce)
+  };
+  const domain = {
+    name: domainName ?? "USD Coin",
+    version: domainVersion ?? "2",
+    chainId,
+    verifyingContract: contractAddress
+  };
+  const signature = await signEIP3009(signer, authParams, domain);
+  const payload = {
+    from,
+    to,
+    amount,
+    nonce,
+    expiry,
+    v: signature.v,
+    r: signature.r,
+    s: signature.s,
+    chainId,
+    contractAddress,
+    network
+  };
+  return encodePaymentV1(payload);
+}
+async function createPaymentPayloadV2(params) {
+  const { signer, from, to, amount, nonce, expiry, chainId, assetId, extensions, domainName, domainVersion } = params;
+  const chainIdNum = parseInt(chainId.split(":")[1], 10);
+  const contractAddress = assetId.split(":")[2];
+  const authParams = {
+    from,
+    to: typeof to === "string" ? to : "0x0000000000000000000000000000000000000000",
+    value: BigInt(Math.floor(parseFloat(amount) * 1e6)),
+    validAfter: 0n,
+    validBefore: BigInt(expiry),
+    nonce: BigInt(nonce)
+  };
+  const domain = {
+    name: domainName ?? "USD Coin",
+    version: domainVersion ?? "2",
+    chainId: chainIdNum,
+    verifyingContract: contractAddress
+  };
+  const signature = await signEIP3009(signer, authParams, domain);
+  const payload = {
+    from,
+    to,
+    amount,
+    nonce,
+    expiry,
+    signature: {
+      v: signature.v,
+      r: signature.r,
+      s: signature.s
+    },
+    chainId,
+    assetId,
+    extensions
+  };
+  return encodePaymentV2(payload);
+}
+function detectProtocolVersion(requirements) {
+  if ("contractAddress" in requirements && "network" in requirements) {
+    return 1;
+  }
+  return 2;
+}
+async function createPaymentPayload(requirements, signer, from) {
+  const version = detectProtocolVersion(requirements);
+  const now = Math.floor(Date.now() / 1e3);
+  const nonce = now.toString();
+  const expiry = now + 3600;
+  if (version === 1) {
+    const req2 = requirements;
+    const networkConfig = getNetworkByChainId(
+      parseInt(req2.contractAddress.slice(0, 10), 16)
+    );
+    const payload2 = await createPaymentPayloadV1({
+      signer,
+      from,
+      to: req2.payTo,
+      amount: req2.amount,
+      nonce,
+      expiry,
+      chainId: networkConfig?.chainId || 1,
+      contractAddress: req2.contractAddress,
+      network: req2.network
+    });
+    return [payload2, V1_HEADERS.PAYMENT];
+  }
+  const req = requirements;
+  const payload = await createPaymentPayloadV2({
+    signer,
+    from,
+    to: req.to,
+    amount: req.amount,
+    nonce,
+    expiry,
+    chainId: req.chainId,
+    assetId: req.assetId
+  });
+  return [payload, V2_HEADERS.PAYMENT_SIGNATURE];
+}
+async function parsePaymentRequirements(response) {
+  const v2Header = response.headers.get(V2_HEADERS.PAYMENT_REQUIRED);
+  if (v2Header) {
+    return JSON.parse(v2Header);
+  }
+  try {
+    return await response.json();
+  } catch {
+    throw new Error("No payment requirements found in response");
+  }
+}
+
+// src/transport.ts
+import {
+  decodeSettlement
+} from "@armory-sh/base";
+var defaultConfig = {
+  baseURL: "",
+  headers: {},
+  timeout: 3e4,
+  autoPay: true,
+  maxRetries: 3,
+  retryDelay: 1e3,
+  onPaymentRequired: () => true,
+  onPaymentSuccess: () => {
+  },
+  onPaymentError: () => {
+  }
+};
+var createState = (config) => ({
+  config: { ...defaultConfig, ...config }
+});
+var fetchWithTimeout = async (url, init, timeout) => {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+  try {
+    const response = await fetch(url, { ...init, signal: controller.signal });
+    clearTimeout(timeoutId);
+    return response;
+  } catch (error) {
+    clearTimeout(timeoutId);
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new Error(`Request timeout after ${timeout}ms`);
+    }
+    throw error;
+  }
+};
+var delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var handlePaymentRequired = async (state, response) => {
+  if (!state.signer) {
+    throw new SignerRequiredError("Cannot handle payment: no signer configured.");
+  }
+  try {
+    const requirements = await parsePaymentRequirements(response);
+    const from = await state.signer.getAddress();
+    const [payload, headerName] = await createPaymentPayload(requirements, state.signer, from);
+    const paymentResponse = await fetchWithTimeout(
+      response.url,
+      {
+        method: "GET",
+        headers: { ...state.config.headers, [headerName]: payload }
+      },
+      state.config.timeout
+    );
+    return { success: true, settlement: decodeSettlement(paymentResponse.headers) };
+  } catch (error) {
+    return { success: false, error: error instanceof Error ? error : new Error(String(error)) };
+  }
+};
+var shouldRetryPayment = async (state, response) => {
+  if (!state.config.autoPay) return false;
+  const requirements = await parsePaymentRequirements(response);
+  return await state.config.onPaymentRequired(requirements);
+};
+var x402Fetch = async (state, url, init = {}) => {
+  const fullUrl = state.config.baseURL ? new URL(url, state.config.baseURL).toString() : url;
+  const headers = new Headers({ ...state.config.headers, ...init.headers });
+  for (let attempt = 1; attempt <= state.config.maxRetries; attempt++) {
+    try {
+      const response = await fetchWithTimeout(fullUrl, { ...init, headers }, state.config.timeout);
+      if (response.status === 402 && !init.skipAutoPay && await shouldRetryPayment(state, response)) {
+        const paymentResult = await handlePaymentRequired(state, response);
+        if (paymentResult.success) {
+          state.config.onPaymentSuccess(paymentResult.settlement);
+          continue;
+        }
+        state.config.onPaymentError(paymentResult.error ?? new Error("Payment failed"));
+      }
+      return response;
+    } catch (error) {
+      const lastError = error instanceof Error ? error : new Error(String(error));
+      if (attempt === state.config.maxRetries) throw lastError;
+      await delay(state.config.retryDelay * attempt);
+    }
+  }
+  throw new Error("Max retries exceeded");
+};
+var createMethod = (state, method) => async (url, bodyOrInit, init) => {
+  const bodyInit = typeof bodyOrInit === "object" && bodyOrInit !== null && "headers" in bodyOrInit ? bodyOrInit : void 0;
+  const body = typeof bodyOrInit === "object" && bodyOrInit !== null && !("headers" in bodyOrInit) ? bodyOrInit : void 0;
+  const finalInit = bodyInit ?? init;
+  return x402Fetch(state, url, {
+    ...finalInit,
+    method,
+    headers: { ...finalInit?.headers, "Content-Type": "application/json" },
+    body: body ? JSON.stringify(body) : void 0
+  });
+};
+var createX402Transport = (config) => {
+  let state = createState(config);
+  return {
+    fetch: (url, init) => x402Fetch(state, url, init),
+    get: createMethod(state, "GET"),
+    post: createMethod(state, "POST"),
+    put: createMethod(state, "PUT"),
+    del: createMethod(state, "DELETE"),
+    patch: createMethod(state, "PATCH"),
+    setSigner: (signer) => {
+      state.signer = signer;
+    },
+    getSigner: () => state.signer
+  };
+};
+export {
+  EIP712_TYPES,
+  ERC20_ABI,
+  NETWORKS,
+  V1_HEADERS2 as V1_HEADERS,
+  V2_HEADERS2 as V2_HEADERS,
+  createEIP712Domain2 as createEIP712Domain,
+  createPaymentPayload,
+  createPaymentPayloadV1,
+  createPaymentPayloadV2,
+  createTransferWithAuthorization,
+  createX402Transport,
+  decodePayment,
+  decodePaymentPayload,
+  decodePaymentV1,
+  decodePaymentV2,
+  decodeSettlement2 as decodeSettlement,
+  decodeSettlementResponse,
+  decodeSettlementV1,
+  decodeSettlementV2,
+  detectPaymentVersion,
+  detectProtocolVersion,
+  encodePaymentPayload,
+  encodePaymentV12 as encodePaymentV1,
+  encodePaymentV22 as encodePaymentV2,
+  encodeSettlementResponse,
+  encodeSettlementV1,
+  encodeSettlementV2,
+  getMainnets,
+  getNetworkByChainId2 as getNetworkByChainId,
+  getNetworkConfig,
+  getPaymentHeaderName,
+  getPaymentRequiredHeaderName,
+  getPaymentResponseHeaderName,
+  getPaymentVersionFromPayload,
+  getRequirementsVersion,
+  getSettlementVersion,
+  getTestnets,
+  getTxHash,
+  isAddress,
+  isCAIP2ChainId,
+  isCAIPAssetId,
+  isPaymentV1,
+  isPaymentV2,
+  isSettlementSuccessful,
+  isSettlementV1,
+  isSettlementV2,
+  isV1,
+  isV2,
+  parsePaymentRequirements,
+  validateTransferWithAuthorization
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@armory-sh/client-ethers",
+  "version": "0.2.0",
+  "license": "MIT",
+  "author": "Sawyer Cutler <sawyer@dirtroad.dev>",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./dist/*": "./dist/*.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thegreataxios/armory.git",
+    "directory": "packages/client-ethers"
+  },
+  "dependencies": {
+    "@armory-sh/base": "workspace:*",
+    "ethers": "6.16.0"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "bun-types": "latest"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "bun test",
+    "example": "bun run examples/"
+  }
+}