@4mica/sdk 0.5.0 → 0.5.2

package/src/signing.ts

@@ -1,330 +0,0 @@
-import { AbiCoder, Wallet, getBytes } from 'ethers';
-import { SigningError } from './errors';
-import { PaymentGuaranteeRequestClaims, PaymentSignature, SigningScheme } from './models';
-import { ValidationError, normalizeAddress, normalizePrivateKey } from './utils';
-
-/**
- * ClientEvmSigner - Used by x402 clients to sign payment authorizations
- * This is typically a LocalAccount or wallet that holds private keys
- * and can sign EIP-712 typed data for payment authorizations
- */
-export type EvmSigner = {
-  readonly address: `0x${string}`;
-
-  signTypedData(message: {
-    domain: Record<string, unknown>;
-    types: Record<string, unknown>;
-    primaryType: string;
-    message: Record<string, unknown>;
-  }): Promise<`0x${string}`>;
-
-  signMessage(message: { message: string }): Promise<`0x${string}`>;
-};
-
-export function createLocalSigner(privateKey: string): EvmSigner {
-  privateKey = normalizePrivateKey(privateKey);
-  const wallet = new Wallet(privateKey);
-  return {
-    address: wallet.address as `0x${string}`,
-    signTypedData: async (message) => {
-      const signature = await wallet.signTypedData(
-        message.domain,
-        { [message.primaryType]: message.types[message.primaryType] } as Record<
-          string,
-          Array<{ name: string; type: string }>
-        >,
-        message.message
-      );
-      return signature as `0x${string}`;
-    },
-    signMessage: async ({ message }) => {
-      const signature = await wallet.signMessage(message);
-      return signature as `0x${string}`;
-    },
-  };
-}
-
-export class CorePublicParameters {
-  constructor(
-    public publicKey: Uint8Array,
-    public contractAddress: string,
-    public ethereumHttpRpcUrl: string,
-    public eip712Name: string,
-    public eip712Version: string,
-    public chainId: number
-  ) {}
-
-  static fromRpc(payload: Record<string, unknown>): CorePublicParameters {
-    const pkRaw = payload.public_key ?? payload.publicKey;
-    const pk =
-      typeof pkRaw === 'string'
-        ? getBytes(pkRaw)
-        : pkRaw instanceof Uint8Array
-          ? pkRaw
-          : Array.isArray(pkRaw)
-            ? Uint8Array.from(pkRaw as ArrayLike<number>)
-            : new Uint8Array();
-    return new CorePublicParameters(
-      pk,
-      String(payload.contract_address ?? payload.contractAddress ?? ''),
-      String(payload.ethereum_http_rpc_url ?? payload.ethereumHttpRpcUrl ?? ''),
-      (payload.eip712_name ?? payload.eip712Name ?? '4Mica') as string,
-      (payload.eip712_version ?? payload.eip712Version ?? '1') as string,
-      Number(payload.chain_id ?? payload.chainId)
-    );
-  }
-}
-
-export const GUARANTEE_EIP712_TYPES = {
-  EIP712Domain: [
-    { name: 'name', type: 'string' },
-    { name: 'version', type: 'string' },
-    { name: 'chainId', type: 'uint256' },
-  ],
-  SolGuaranteeRequestClaimsV1: [
-    { name: 'user', type: 'address' },
-    { name: 'recipient', type: 'address' },
-    { name: 'tabId', type: 'uint256' },
-    { name: 'reqId', type: 'uint256' },
-    { name: 'amount', type: 'uint256' },
-    { name: 'asset', type: 'address' },
-    { name: 'timestamp', type: 'uint64' },
-  ],
-} as const;
-
-export type GuaranteeTypedData = {
-  types: typeof GUARANTEE_EIP712_TYPES;
-  primaryType: 'SolGuaranteeRequestClaimsV1';
-  domain: {
-    name: string;
-    version: string;
-    chainId: number;
-  };
-  message: {
-    user: string;
-    recipient: string;
-    tabId: bigint;
-    reqId: bigint;
-    amount: bigint;
-    asset: string;
-    timestamp: bigint;
-  };
-};
-
-export type GuaranteeTypedDataValidationOptions = {
-  expectedChainId?: number;
-  expectedSigner?: string;
-  expectedRecipient?: string;
-};
-
-export type GuaranteeSigningContextOptions = {
-  signerAddress?: string;
-  signerChainId?: number;
-};
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  Boolean(value) && typeof value === 'object' && !Array.isArray(value);
-
-const fieldsMatch = (
-  actual: unknown,
-  expected: readonly { name: string; type: string }[]
-): boolean => {
-  if (!Array.isArray(actual) || actual.length !== expected.length) return false;
-  const norm = (list: readonly { name: string; type: string }[]) =>
-    list.map((item) => `${item.name}:${item.type}`).sort();
-  const actualSet = new Set(norm(actual));
-  return norm(expected).every((key) => actualSet.has(key));
-};
-
-const parseChainId = (value: unknown): number => {
-  if (typeof value === 'bigint') return Number(value);
-  if (typeof value === 'number') return value;
-  if (typeof value === 'string' && value.trim()) return Number(value);
-  return Number.NaN;
-};
-
-const ensureBigIntish = (value: unknown, label: string): void => {
-  try {
-    BigInt(value as bigint | number | string);
-  } catch {
-    throw new ValidationError(`${label} must be a numeric value`);
-  }
-};
-
-export function validateGuaranteeTypedData(
-  payload: {
-    domain: Record<string, unknown>;
-    types: Record<string, Array<{ name: string; type: string }>>;
-    message: Record<string, unknown>;
-  },
-  options: GuaranteeTypedDataValidationOptions = {}
-): void {
-  if (!isRecord(payload)) {
-    throw new ValidationError('typed data payload is required');
-  }
-  if (!isRecord(payload.domain)) {
-    throw new ValidationError('domain is required');
-  }
-  if (!isRecord(payload.types)) {
-    throw new ValidationError('types are required');
-  }
-  if (!isRecord(payload.message)) {
-    throw new ValidationError('message is required');
-  }
-
-  const types = payload.types;
-  if (
-    !fieldsMatch(
-      types.SolGuaranteeRequestClaimsV1,
-      GUARANTEE_EIP712_TYPES.SolGuaranteeRequestClaimsV1
-    )
-  ) {
-    throw new ValidationError('Unexpected struct fields for SolGuaranteeRequestClaimsV1');
-  }
-
-  const message = payload.message;
-  const requiredFields = ['user', 'recipient', 'tabId', 'reqId', 'amount', 'asset', 'timestamp'];
-  if (requiredFields.some((field) => !(field in message))) {
-    throw new ValidationError('message is missing required SolGuaranteeRequestClaimsV1 fields');
-  }
-
-  const user = normalizeAddress(message.user as string);
-  const recipient = normalizeAddress(message.recipient as string);
-  normalizeAddress(message.asset as string);
-
-  if (options.expectedSigner) {
-    if (normalizeAddress(options.expectedSigner) !== user) {
-      throw new ValidationError('message.user must match signer address');
-    }
-  }
-  if (options.expectedRecipient) {
-    if (normalizeAddress(options.expectedRecipient) !== recipient) {
-      throw new ValidationError('message.recipient must match expected recipient');
-    }
-  }
-
-  ensureBigIntish(message.tabId, 'tabId');
-  ensureBigIntish(message.reqId, 'reqId');
-  ensureBigIntish(message.amount, 'amount');
-  ensureBigIntish(message.timestamp, 'timestamp');
-
-  if (options.expectedChainId !== undefined) {
-    const domainChainId = parseChainId(payload.domain.chainId);
-    if (!Number.isFinite(domainChainId)) {
-      throw new ValidationError('domain.chainId is required for typed data signatures');
-    }
-    if (Number(domainChainId) !== Number(options.expectedChainId)) {
-      throw new ValidationError(
-        `domain.chainId mismatch; expected ${options.expectedChainId}, got ${domainChainId}`
-      );
-    }
-  }
-}
-
-export function validateGuaranteeSigningContext(
-  params: CorePublicParameters,
-  claims: PaymentGuaranteeRequestClaims,
-  options: GuaranteeSigningContextOptions = {}
-): void {
-  if (options.signerAddress) {
-    const signer = normalizeAddress(options.signerAddress);
-    const user = normalizeAddress(claims.userAddress);
-    if (signer !== user) {
-      throw new ValidationError(
-        `address mismatch: signer ${options.signerAddress} != claims.user_address ${claims.userAddress}`
-      );
-    }
-  }
-
-  if (options.signerChainId !== undefined) {
-    const signerChainId = Number(options.signerChainId);
-    if (!Number.isFinite(signerChainId)) {
-      throw new ValidationError('signer chain id is invalid');
-    }
-    if (Number(params.chainId) !== signerChainId) {
-      throw new ValidationError(
-        `chain id mismatch: expected ${params.chainId}, got ${signerChainId}`
-      );
-    }
-  }
-}
-
-export function buildGuaranteeTypedData(
-  params: CorePublicParameters,
-  claims: PaymentGuaranteeRequestClaims
-): GuaranteeTypedData {
-  return {
-    types: GUARANTEE_EIP712_TYPES,
-    primaryType: 'SolGuaranteeRequestClaimsV1',
-    domain: {
-      name: params.eip712Name,
-      version: params.eip712Version,
-      chainId: params.chainId,
-    },
-    message: {
-      user: claims.userAddress,
-      recipient: claims.recipientAddress,
-      tabId: claims.tabId,
-      reqId: claims.reqId,
-      amount: claims.amount,
-      asset: claims.assetAddress,
-      timestamp: BigInt(claims.timestamp),
-    },
-  } as const;
-}
-
-export function encodeGuaranteeEip191(claims: PaymentGuaranteeRequestClaims): string {
-  const payload = AbiCoder.defaultAbiCoder().encode(
-    ['address', 'address', 'uint256', 'uint256', 'uint256', 'address', 'uint64'],
-    [
-      claims.userAddress,
-      claims.recipientAddress,
-      claims.tabId,
-      claims.reqId,
-      claims.amount,
-      claims.assetAddress,
-      claims.timestamp,
-    ]
-  );
-  return payload;
-}
-
-export class PaymentSigner {
-  private signer: EvmSigner;
-
-  constructor(signer: EvmSigner) {
-    this.signer = signer;
-  }
-
-  async signRequest(
-    params: CorePublicParameters,
-    claims: PaymentGuaranteeRequestClaims,
-    scheme: SigningScheme = SigningScheme.EIP712
-  ): Promise<PaymentSignature> {
-    try {
-      validateGuaranteeSigningContext(params, claims, { signerAddress: this.signer.address });
-      if (scheme === SigningScheme.EIP712) {
-        const typed = buildGuaranteeTypedData(params, claims);
-        const signature = await this.signer.signTypedData({
-          domain: typed.domain,
-          types: { SolGuaranteeRequestClaimsV1: typed.types.SolGuaranteeRequestClaimsV1 },
-          primaryType: typed.primaryType,
-          message: typed.message,
-        });
-        return { signature, scheme };
-      }
-      if (scheme === SigningScheme.EIP191) {
-        const message = encodeGuaranteeEip191(claims);
-        const signature = await this.signer.signMessage({ message });
-        return { signature, scheme };
-      }
-      throw new SigningError(`unsupported signing scheme: ${scheme}`);
-    } catch (err: unknown) {
-      if (err instanceof ValidationError) {
-        throw new SigningError(err.message);
-      }
-      const message = err instanceof Error ? err.message : String(err);
-      throw new SigningError(message);
-    }
-  }
-}

package/src/utils.ts

@@ -1,75 +0,0 @@
-import { getAddress, isAddress } from 'ethers';
-
-export class ValidationError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'ValidationError';
-  }
-}
-
-export function validateUrl(raw: string): string {
-  try {
-    const url = new URL(raw);
-    if (!url.protocol || !url.host) {
-      throw new Error('missing parts');
-    }
-    return raw;
-  } catch {
-    throw new ValidationError(`invalid URL: ${raw}`);
-  }
-}
-
-export function normalizePrivateKey(raw: string): string {
-  const key = raw.startsWith('0x') ? raw.slice(2) : raw;
-  if (!/^[0-9a-fA-F]{64}$/.test(key)) {
-    throw new ValidationError('invalid private key (expected 32 byte hex)');
-  }
-  return `0x${key.toLowerCase()}`;
-}
-
-export function normalizeAddress(raw: string): string {
-  const candidate: string = String(raw);
-  if (isAddress(candidate)) {
-    return getAddress(candidate);
-  }
-  const lower: string = (candidate as string).toLowerCase();
-  if (isAddress(lower)) {
-    return getAddress(lower);
-  }
-  throw new ValidationError(`invalid address: ${raw}`);
-}
-
-function parseNumericString(raw: string): bigint {
-  const text = raw.trim();
-  const n = BigInt(text);
-  if (n < 0n) {
-    throw new ValidationError('u256 cannot be negative');
-  }
-  return n;
-}
-
-export function parseU256(value: number | bigint | string): bigint {
-  if (typeof value === 'number') {
-    if (!Number.isFinite(value)) {
-      throw new ValidationError('invalid integer');
-    }
-    if (value < 0) {
-      throw new ValidationError('u256 cannot be negative');
-    }
-    return BigInt(value);
-  }
-  if (typeof value === 'bigint') {
-    if (value < 0) {
-      throw new ValidationError('u256 cannot be negative');
-    }
-    return value;
-  }
-  if (typeof value === 'string') {
-    return parseNumericString(value);
-  }
-  throw new ValidationError(`unsupported numeric type: ${typeof value}`);
-}
-
-export function serializeU256(value: number | bigint | string): string {
-  return `0x${parseU256(value).toString(16)}`;
-}

package/src/x402/index.ts

@@ -1,192 +0,0 @@
-import { PaymentGuaranteeRequestClaims, PaymentSignature, SigningScheme } from '../models';
-import {
-  PaymentRequirementsV1,
-  TabResponse,
-  X402SignedPayment,
-  X402SettledPayment,
-  X402PaymentPayload,
-  PaymentRequirementsV2,
-  X402PaymentRequired,
-  X402PaymentEnvelopeV1,
-  X402PaymentEnvelopeV2,
-  X402ResourceInfo,
-} from './models';
-import { normalizeAddress, parseU256 } from '../utils';
-import type { FetchFn } from '../rpc';
-import { X402Error } from '../errors';
-
-export * from './models';
-
-export interface FlowSigner {
-  signPayment(
-    claims: PaymentGuaranteeRequestClaims,
-    scheme: SigningScheme
-  ): Promise<PaymentSignature>;
-}
-
-export class X402Flow {
-  private fetchFn: FetchFn;
-
-  constructor(
-    private signer: FlowSigner,
-    fetchFn: FetchFn = fetch
-  ) {
-    this.fetchFn = fetchFn;
-  }
-
-  static fromClient(client: { user: FlowSigner }): X402Flow {
-    return new X402Flow(client.user);
-  }
-
-  async signPayment(
-    paymentRequirements: PaymentRequirementsV1,
-    userAddress: string
-  ): Promise<X402SignedPayment> {
-    X402Flow.validateScheme(paymentRequirements.scheme);
-    const tab = await this.requestTab(1, paymentRequirements, userAddress);
-
-    const claims = this.buildClaims(paymentRequirements, tab, userAddress);
-    const signature = await this.signer.signPayment(claims, SigningScheme.EIP712);
-    const paymentPayload = X402Flow.buildPaymentPayload(claims, signature);
-
-    const envelope: X402PaymentEnvelopeV1 = {
-      x402Version: 1,
-      scheme: paymentRequirements.scheme,
-      network: paymentRequirements.network,
-      payload: paymentPayload,
-    };
-    const header = Buffer.from(JSON.stringify(envelope)).toString('base64');
-    return { header, payload: paymentPayload, signature };
-  }
-
-  async signPaymentV2(
-    paymentRequired: X402PaymentRequired,
-    accepted: PaymentRequirementsV2,
-    userAddress: string
-  ): Promise<X402SignedPayment> {
-    X402Flow.validateScheme(accepted.scheme);
-    const tab = await this.requestTab(2, accepted, userAddress, paymentRequired.resource);
-
-    const claims = this.buildClaims(accepted, tab, userAddress);
-    const signature = await this.signer.signPayment(claims, SigningScheme.EIP712);
-    const paymentPayload = X402Flow.buildPaymentPayload(claims, signature);
-
-    const envelope: X402PaymentEnvelopeV2 = {
-      x402Version: 2,
-      accepted: accepted,
-      payload: paymentPayload,
-      resource: paymentRequired.resource,
-    };
-    const header = Buffer.from(JSON.stringify(envelope)).toString('base64');
-    return { header, payload: paymentPayload, signature };
-  }
-
-  async settlePayment(
-    payment: X402SignedPayment,
-    paymentRequirements: PaymentRequirementsV1,
-    facilitatorUrl: string
-  ): Promise<X402SettledPayment> {
-    const url = `${facilitatorUrl.replace(/\/$/, '')}/settle`;
-    const response = await this.fetchFn(url, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({
-        x402Version: 1,
-        paymentHeader: payment.header,
-        paymentRequirements,
-      }),
-    });
-    const data = await response.text();
-    if (!response.ok) {
-      throw new X402Error(`settlement failed with status ${response.status}: ${data}`);
-    }
-    const settlement = data ? JSON.parse(data) : {};
-    return { payment, settlement };
-  }
-
-  protected async requestTab(
-    x402Version: number,
-    paymentRequirements: PaymentRequirementsV1 | PaymentRequirementsV2,
-    userAddress: string,
-    resource?: X402ResourceInfo
-  ): Promise<TabResponse> {
-    const tabEndpoint = paymentRequirements.extra?.tabEndpoint;
-    if (!tabEndpoint || typeof tabEndpoint !== 'string') {
-      throw new X402Error('missing tabEndpoint in paymentRequirements.extra');
-    }
-    const resp = await this.fetchFn(tabEndpoint, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({
-        x402Version,
-        userAddress,
-        paymentRequirements,
-        resource,
-      }),
-    });
-    if (!resp.ok) {
-      const text = await resp.text();
-      throw new X402Error(`tab resolution failed: ${resp.status} ${text}`);
-    }
-    const body = await resp.json();
-    return {
-      tabId: body.tabId ?? body.tab_id,
-      userAddress: body.userAddress ?? body.user_address,
-      nextReqId: body.nextReqId ?? body.next_req_id ?? body.reqId ?? body.req_id,
-    };
-  }
-
-  protected buildClaims(
-    requirements: PaymentRequirementsV1 | PaymentRequirementsV2,
-    tab: TabResponse,
-    userAddress: string
-  ): PaymentGuaranteeRequestClaims {
-    const tabId = parseU256(tab.tabId);
-    const reqId =
-      tab.nextReqId !== undefined && tab.nextReqId !== null ? parseU256(tab.nextReqId) : 0n;
-    const amount = parseU256(
-      'maxAmountRequired' in requirements ? requirements.maxAmountRequired : requirements.amount
-    );
-    if (tab.userAddress.toLowerCase() !== userAddress.toLowerCase()) {
-      throw new X402Error(
-        `user mismatch in paymentRequirements: found ${tab.userAddress}, expected ${userAddress}`
-      );
-    }
-    const timestamp = Math.floor(Date.now() / 1000);
-    return PaymentGuaranteeRequestClaims.new(
-      userAddress,
-      normalizeAddress(requirements.payTo),
-      tabId,
-      amount,
-      timestamp,
-      requirements.asset,
-      reqId
-    );
-  }
-
-  private static validateScheme(scheme: string): void {
-    if (!scheme.toLowerCase().includes('4mica')) {
-      throw new X402Error(`invalid scheme: ${scheme}`);
-    }
-  }
-
-  private static buildPaymentPayload(
-    claims: PaymentGuaranteeRequestClaims,
-    signature: PaymentSignature
-  ): X402PaymentPayload {
-    return {
-      claims: {
-        version: 'v1',
-        user_address: claims.userAddress,
-        recipient_address: claims.recipientAddress,
-        tab_id: `0x${claims.tabId.toString(16)}`,
-        req_id: `0x${claims.reqId.toString(16)}`,
-        amount: `0x${claims.amount.toString(16)}`,
-        asset_address: claims.assetAddress,
-        timestamp: claims.timestamp,
-      },
-      signature: signature.signature,
-      scheme: signature.scheme,
-    };
-  }
-}

package/src/x402/models.ts

@@ -1,94 +0,0 @@
-import { PaymentSignature, SigningScheme } from '../models';
-
-export interface PaymentRequirementsV1 {
-  scheme: string;
-  network: string;
-  maxAmountRequired: string;
-  payTo: string;
-  asset: string;
-  resource?: string;
-  description?: string;
-  mimeType?: string;
-  outputSchema?: unknown;
-  maxTimeoutSeconds?: number;
-  extra?: PaymentRequirementsExtra;
-}
-
-export interface PaymentRequirementsV2 {
-  scheme: string;
-  network: string;
-  asset: string;
-  amount: string;
-  payTo: string;
-  maxTimeoutSeconds?: number;
-  extra?: PaymentRequirementsExtra;
-}
-
-export type PaymentRequirements = PaymentRequirementsV2;
-
-export interface PaymentRequirementsExtra {
-  tabEndpoint?: string;
-}
-
-export interface TabResponse {
-  tabId: string;
-  userAddress: string;
-  nextReqId?: string;
-}
-
-export interface X402PaymentPayloadClaims {
-  version: string;
-  user_address: string;
-  recipient_address: string;
-  tab_id: string;
-  req_id: string;
-  amount: string;
-  timestamp: number;
-  asset_address: string;
-}
-
-export interface X402PaymentPayload {
-  claims: X402PaymentPayloadClaims;
-  /// 65-byte signature as 0x-prefixed hex
-  signature: string;
-  scheme: SigningScheme;
-}
-
-export interface X402PaymentEnvelopeV1 {
-  x402Version: number;
-  scheme: string;
-  network: string;
-  payload: X402PaymentPayload;
-}
-
-export interface X402ResourceInfo {
-  url: string;
-  description: string;
-  mimeType: string;
-}
-
-export interface X402PaymentEnvelopeV2 {
-  x402Version: number;
-  accepted: PaymentRequirementsV2;
-  payload: X402PaymentPayload;
-  resource: X402ResourceInfo;
-}
-
-export interface X402SignedPayment {
-  header: string;
-  payload: X402PaymentPayload;
-  signature: PaymentSignature;
-}
-
-export interface X402SettledPayment {
-  payment: X402SignedPayment;
-  settlement: unknown;
-}
-
-export interface X402PaymentRequired {
-  x402Version: number;
-  error?: string;
-  resource: X402ResourceInfo;
-  accepts: PaymentRequirementsV2[];
-  extensions?: Record<string, unknown>;
-}