@t402/stacks 2.4.0

package/src/exact-direct/server/scheme.ts

@@ -0,0 +1,216 @@
+/**
+ * Stacks Exact-Direct Server Scheme
+ *
+ * Handles price parsing and payment requirement enhancement for
+ * Stacks payments using the exact-direct scheme.
+ */
+
+import type {
+  SchemeNetworkServer,
+  PaymentRequirements,
+  Price,
+  AssetAmount,
+  Network,
+  MoneyParser,
+} from "@t402/core/types";
+import { SCHEME_EXACT_DIRECT, isStacksNetwork } from "../../constants.js";
+import { getDefaultToken, getTokenConfig, TOKEN_REGISTRY } from "../../tokens.js";
+import { parseAmount } from "../../utils.js";
+
+/**
+ * Configuration for ExactDirectStacksServer
+ */
+export interface ExactDirectStacksServerConfig {
+  /** Preferred token symbol (e.g., "sUSDC"). Defaults to network's default token. */
+  preferredToken?: string;
+}
+
+/**
+ * Stacks Exact-Direct Server
+ *
+ * Implements the server-side price parsing and payment requirements enhancement.
+ */
+export class ExactDirectStacksServer implements SchemeNetworkServer {
+  readonly scheme = SCHEME_EXACT_DIRECT;
+  private moneyParsers: MoneyParser[] = [];
+  private config: ExactDirectStacksServerConfig;
+
+  constructor(config: ExactDirectStacksServerConfig = {}) {
+    this.config = config;
+  }
+
+  /**
+   * Register a custom money parser in the parser chain.
+   */
+  registerMoneyParser(parser: MoneyParser): ExactDirectStacksServer {
+    this.moneyParsers.push(parser);
+    return this;
+  }
+
+  /**
+   * Parse price into Stacks-specific amount
+   */
+  async parsePrice(price: Price, network: Network): Promise<AssetAmount> {
+    // Validate network
+    if (!isStacksNetwork(network)) {
+      throw new Error(`Invalid Stacks network: ${network}`);
+    }
+
+    // If already an AssetAmount, return it directly
+    if (typeof price === "object" && price !== null && "amount" in price) {
+      if (!price.asset) {
+        throw new Error(`Asset must be specified for AssetAmount on network ${network}`);
+      }
+      return {
+        amount: price.amount,
+        asset: price.asset,
+        extra: price.extra || {},
+      };
+    }
+
+    // Parse Money to decimal number
+    const amount = this.parseMoneyToDecimal(price);
+
+    // Try each custom money parser in order
+    for (const parser of this.moneyParsers) {
+      const result = await parser(amount, network);
+      if (result !== null) {
+        return result;
+      }
+    }
+
+    // All custom parsers returned null, use default conversion
+    return this.defaultMoneyConversion(amount, network);
+  }
+
+  /**
+   * Enhance payment requirements with Stacks-specific details
+   */
+  async enhancePaymentRequirements(
+    paymentRequirements: PaymentRequirements,
+    supportedKind: {
+      t402Version: number;
+      scheme: string;
+      network: Network;
+      extra?: Record<string, unknown>;
+    },
+    facilitatorExtensions: string[],
+  ): Promise<PaymentRequirements> {
+    // Mark unused parameters
+    void facilitatorExtensions;
+
+    // Start with existing extra fields
+    const extra = { ...paymentRequirements.extra };
+
+    // Add any facilitator-provided extra fields
+    if (supportedKind.extra?.contractAddress) {
+      extra.contractAddress = supportedKind.extra.contractAddress;
+    }
+    if (supportedKind.extra?.assetSymbol) {
+      extra.assetSymbol = supportedKind.extra.assetSymbol;
+    }
+    if (supportedKind.extra?.assetDecimals) {
+      extra.assetDecimals = supportedKind.extra.assetDecimals;
+    }
+    if (supportedKind.extra?.networkName) {
+      extra.networkName = supportedKind.extra.networkName;
+    }
+
+    return {
+      ...paymentRequirements,
+      extra,
+    };
+  }
+
+  /**
+   * Parse Money (string | number) to a decimal number.
+   */
+  private parseMoneyToDecimal(money: string | number): number {
+    if (typeof money === "number") {
+      return money;
+    }
+
+    // Remove $ sign and whitespace, then parse
+    const cleanMoney = money.replace(/^\$/, "").trim();
+    const amount = parseFloat(cleanMoney);
+
+    if (isNaN(amount)) {
+      throw new Error(`Invalid money format: ${money}`);
+    }
+
+    return amount;
+  }
+
+  /**
+   * Default money conversion implementation.
+   */
+  private defaultMoneyConversion(amount: number, network: Network): AssetAmount {
+    const token = this.getDefaultAsset(network);
+
+    // Convert decimal amount to token amount
+    const tokenAmount = parseAmount(amount.toString(), token.decimals);
+
+    return {
+      amount: tokenAmount.toString(),
+      asset: this.createAssetIdentifier(network, token.contractAddress),
+      extra: {
+        symbol: token.symbol,
+        name: token.name,
+        decimals: token.decimals,
+        contractAddress: token.contractAddress,
+      },
+    };
+  }
+
+  /**
+   * Create a CAIP-19 asset identifier for Stacks tokens
+   */
+  private createAssetIdentifier(
+    network: Network,
+    contractAddress: string,
+  ): string {
+    return `${network}/sip010:${contractAddress}`;
+  }
+
+  /**
+   * Get the default asset info for a network.
+   */
+  private getDefaultAsset(
+    network: Network,
+  ): { contractAddress: string; symbol: string; name: string; decimals: number } {
+    // If a preferred token is configured, try to use it
+    if (this.config.preferredToken) {
+      const preferred = getTokenConfig(network, this.config.preferredToken);
+      if (preferred) return preferred;
+    }
+
+    // Use the network's default token
+    const defaultToken = getDefaultToken(network);
+    if (defaultToken) return defaultToken;
+
+    throw new Error(`No tokens configured for network ${network}`);
+  }
+
+  /**
+   * Get all supported networks
+   */
+  static getSupportedNetworks(): string[] {
+    return Object.keys(TOKEN_REGISTRY);
+  }
+
+  /**
+   * Check if a network is supported
+   */
+  static isNetworkSupported(network: string): boolean {
+    return network in TOKEN_REGISTRY;
+  }
+}
+
+/**
+ * Create an exact-direct server for Stacks
+ */
+export function createExactDirectStacksServer(
+  config: ExactDirectStacksServerConfig = {},
+): ExactDirectStacksServer {
+  return new ExactDirectStacksServer(config);
+}

package/src/index.ts

@@ -0,0 +1,78 @@
+/**
+ * @t402/stacks - Stacks mechanism for T402
+ *
+ * This package provides support for SIP-010 token payments on Stacks (Bitcoin L2)
+ * using the exact-direct scheme.
+ *
+ * @example
+ * ```typescript
+ * // Client usage
+ * import { createExactDirectStacksClient } from '@t402/stacks/exact-direct/client';
+ *
+ * const client = createExactDirectStacksClient({
+ *   signer: myStacksSigner,
+ * });
+ *
+ * // Server usage
+ * import { registerExactDirectStacksServer } from '@t402/stacks/exact-direct/server';
+ *
+ * registerExactDirectStacksServer(server);
+ *
+ * // Facilitator usage
+ * import { createExactDirectStacksFacilitator } from '@t402/stacks/exact-direct/facilitator';
+ *
+ * const facilitator = createExactDirectStacksFacilitator(signer);
+ * ```
+ */
+
+// Re-export constants
+export {
+  STACKS_CAIP2_NAMESPACE,
+  STACKS_MAINNET_CAIP2,
+  STACKS_TESTNET_CAIP2,
+  SCHEME_EXACT_DIRECT,
+  DEFAULT_MAINNET_API,
+  DEFAULT_TESTNET_API,
+  STACKS_NETWORKS,
+  getNetworkConfig,
+  isStacksNetwork,
+  type StacksNetworkConfig,
+} from "./constants.js";
+
+// Re-export token registry
+export {
+  SUSDC_MAINNET,
+  SUSDC_TESTNET,
+  TOKEN_REGISTRY,
+  DEFAULT_TOKENS,
+  getTokenConfig,
+  getDefaultToken,
+  getContractAddress,
+  type TokenConfig,
+} from "./tokens.js";
+
+// Re-export types
+export type {
+  ExactDirectStacksPayload,
+  StacksTransactionResult,
+  StacksContractCall,
+  StacksFunctionArg,
+  StacksPostCondition,
+  StacksEvent,
+  ParsedTokenTransfer,
+  FacilitatorStacksSigner,
+  ClientStacksSigner,
+  StacksServerConfig,
+  StacksFacilitatorConfig,
+} from "./types.js";
+
+// Re-export utilities
+export {
+  isValidPrincipal,
+  isValidTxId,
+  comparePrincipals,
+  formatAmount,
+  parseAmount,
+  extractTokenTransfer,
+  extractTokenTransferFromPostConditions,
+} from "./utils.js";

package/src/tokens.ts

@@ -0,0 +1,96 @@
+/**
+ * Stacks Token Registry
+ *
+ * On Stacks, tokens are SIP-010 fungible tokens identified by
+ * their contract address (principal.contract-name).
+ */
+
+import {
+  STACKS_MAINNET_CAIP2,
+  STACKS_TESTNET_CAIP2,
+} from "./constants.js";
+
+/**
+ * Token configuration for Stacks SIP-010 tokens
+ */
+export interface TokenConfig {
+  /** Contract address (principal.contract-name) */
+  readonly contractAddress: string;
+  /** Token symbol */
+  readonly symbol: string;
+  /** Token name */
+  readonly name: string;
+  /** Decimal places */
+  readonly decimals: number;
+  /** Token issuer */
+  readonly issuer?: string;
+}
+
+/**
+ * sUSDC on Stacks Mainnet
+ * Contract: SP3Y2ZSH8P7D50B0VBTSX11S7XSG24M1VB9YFQA4K.token-susdc
+ * Decimals: 6
+ */
+export const SUSDC_MAINNET: TokenConfig = {
+  contractAddress: "SP3Y2ZSH8P7D50B0VBTSX11S7XSG24M1VB9YFQA4K.token-susdc",
+  symbol: "sUSDC",
+  name: "Stacks USDC",
+  decimals: 6,
+  issuer: "Stacks",
+};
+
+/**
+ * sUSDC on Stacks Testnet
+ * Contract: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.token-susdc
+ * Decimals: 6
+ */
+export const SUSDC_TESTNET: TokenConfig = {
+  contractAddress: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.token-susdc",
+  symbol: "sUSDC",
+  name: "Test Stacks USDC",
+  decimals: 6,
+};
+
+/**
+ * Network-specific token registries
+ */
+export const TOKEN_REGISTRY: Record<string, Record<string, TokenConfig>> = {
+  [STACKS_MAINNET_CAIP2]: {
+    sUSDC: SUSDC_MAINNET,
+  },
+  [STACKS_TESTNET_CAIP2]: {
+    sUSDC: SUSDC_TESTNET,
+  },
+};
+
+/**
+ * Default tokens per network
+ */
+export const DEFAULT_TOKENS: Record<string, TokenConfig> = {
+  [STACKS_MAINNET_CAIP2]: SUSDC_MAINNET,
+  [STACKS_TESTNET_CAIP2]: SUSDC_TESTNET,
+};
+
+/**
+ * Get token configuration by network and symbol
+ */
+export function getTokenConfig(
+  network: string,
+  symbol: string = "sUSDC",
+): TokenConfig | undefined {
+  return TOKEN_REGISTRY[network]?.[symbol];
+}
+
+/**
+ * Get the default token for a network
+ */
+export function getDefaultToken(network: string): TokenConfig | undefined {
+  return DEFAULT_TOKENS[network];
+}
+
+/**
+ * Get contract address for a token on a network
+ */
+export function getContractAddress(network: string, symbol: string = "sUSDC"): string | undefined {
+  return getTokenConfig(network, symbol)?.contractAddress;
+}

package/src/types.ts

@@ -0,0 +1,184 @@
+/**
+ * Stacks T402 Types
+ */
+
+import type { Network } from "@t402/core/types";
+
+/**
+ * Payment payload for exact-direct scheme on Stacks
+ */
+export type ExactDirectStacksPayload = {
+  /** Transaction ID (0x-prefixed hex, 64 chars) */
+  txId: string;
+  /** Sender address (Stacks principal) */
+  from: string;
+  /** Recipient address (Stacks principal) */
+  to: string;
+  /** Amount in smallest unit (atomic) */
+  amount: string;
+  /** SIP-010 contract address (principal.contract-name) */
+  contractAddress: string;
+};
+
+/**
+ * Result of a Stacks transaction query from Hiro API
+ */
+export interface StacksTransactionResult {
+  /** Transaction ID */
+  txId: string;
+  /** Transaction type */
+  txType: string;
+  /** Transaction status */
+  txStatus: "success" | "abort_by_response" | "abort_by_post_condition" | "pending";
+  /** Block hash */
+  blockHash: string;
+  /** Block height */
+  blockHeight: number;
+  /** Burn block time (unix timestamp) */
+  burnBlockTime: number;
+  /** Sender address */
+  senderAddress: string;
+  /** Contract call details (for contract-call transactions) */
+  contractCall?: StacksContractCall;
+  /** Post-condition mode */
+  postConditionMode: string;
+  /** Post conditions */
+  postConditions: StacksPostCondition[];
+  /** Events */
+  events: StacksEvent[];
+}
+
+/**
+ * Stacks contract call details
+ */
+export interface StacksContractCall {
+  /** Contract ID (principal.contract-name) */
+  contractId: string;
+  /** Function name */
+  functionName: string;
+  /** Function arguments */
+  functionArgs: StacksFunctionArg[];
+}
+
+/**
+ * Stacks function argument
+ */
+export interface StacksFunctionArg {
+  /** Hex-encoded value */
+  hex: string;
+  /** Human-readable representation */
+  repr: string;
+  /** Argument type */
+  type: string;
+}
+
+/**
+ * Stacks post condition
+ */
+export interface StacksPostCondition {
+  /** Principal (sender) */
+  principal: {
+    type_id: string;
+    address: string;
+    contract_name?: string;
+  };
+  /** Condition code */
+  conditionCode: string;
+  /** Amount */
+  amount: string;
+  /** Asset info */
+  asset?: {
+    contractAddress: string;
+    contractName: string;
+    assetName: string;
+  };
+}
+
+/**
+ * Stacks transaction event
+ */
+export interface StacksEvent {
+  /** Event type */
+  eventType: string;
+  /** Event index */
+  eventIndex: number;
+  /** Fungible token transfer asset event (for ft_transfer events) */
+  asset?: {
+    assetEventType: string;
+    assetId: string;
+    sender: string;
+    recipient: string;
+    amount: string;
+  };
+}
+
+/**
+ * Parsed token transfer from transaction events
+ */
+export interface ParsedTokenTransfer {
+  /** Contract address (principal.contract-name) */
+  contractAddress: string;
+  /** Sender address */
+  from: string;
+  /** Recipient address */
+  to: string;
+  /** Amount transferred (atomic units) */
+  amount: string;
+  /** Whether the transfer was successful */
+  success: boolean;
+}
+
+/**
+ * Signer interface for Stacks facilitator
+ */
+export interface FacilitatorStacksSigner {
+  /**
+   * Get the facilitator's addresses for a network
+   */
+  getAddresses(network: Network): string[];
+
+  /**
+   * Query a transaction by ID from Hiro API
+   */
+  queryTransaction(txId: string): Promise<StacksTransactionResult | null>;
+}
+
+/**
+ * Client signer interface for signing transactions
+ */
+export interface ClientStacksSigner {
+  /**
+   * Get the signer's address
+   */
+  getAddress(): Promise<string>;
+
+  /**
+   * Sign and submit a SIP-010 token transfer
+   * Returns the transaction ID
+   */
+  transferToken(
+    contractAddress: string,
+    to: string,
+    amount: string,
+  ): Promise<{ txId: string }>;
+}
+
+/**
+ * Configuration for Stacks server
+ */
+export interface StacksServerConfig {
+  /** Custom API URL */
+  apiUrl?: string;
+  /** Facilitator addresses per network */
+  facilitatorAddresses?: Record<string, string>;
+}
+
+/**
+ * Configuration for Stacks facilitator
+ */
+export interface StacksFacilitatorConfig {
+  /** Maximum age of transaction to accept (in seconds) */
+  maxTransactionAge?: number;
+  /** Duration to cache used transaction IDs */
+  usedTxCacheDuration?: number;
+}