@t402/stacks 2.4.0

package/README.md

@@ -0,0 +1,178 @@
+# @t402/stacks
+
+Stacks (Bitcoin L2) implementation of the t402 payment protocol using the **exact-direct** payment scheme with SIP-010 fungible token transfers.
+
+## Installation
+
+```bash
+npm install @t402/stacks
+# or
+pnpm add @t402/stacks
+```
+
+## Overview
+
+This package provides support for sUSDC payments on Stacks using the exact-direct scheme. The client executes a `transfer` call on a SIP-010 token contract directly on-chain, then provides the transaction ID as proof of payment.
+
+Three main components:
+
+- **Client** - For applications that make payments (have Stacks wallets)
+- **Facilitator** - For payment processors that verify transactions via the Hiro API
+- **Server** - For resource servers that accept payments and build payment requirements
+
+## Supported Networks
+
+| Network | CAIP-2 Identifier | sUSDC Contract | Status |
+|---------|-------------------|----------------|--------|
+| Stacks Mainnet | `stacks:1` | `SP3Y2ZSH8P7D50B0VBTSX11S7XSG24M1VB9YFQA4K.token-susdc` | Production |
+| Stacks Testnet | `stacks:2147483648` | `ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.token-susdc` | Testnet |
+
+## Package Exports
+
+### Main Package (`@t402/stacks`)
+
+**Constants:**
+
+- `STACKS_CAIP2_NAMESPACE` - CAIP-2 namespace (`stacks`)
+- `STACKS_MAINNET_CAIP2` - Mainnet identifier (`stacks:1`)
+- `STACKS_TESTNET_CAIP2` - Testnet identifier (`stacks:2147483648`)
+- `STACKS_NETWORKS` - Array of supported networks
+- `SCHEME_EXACT_DIRECT` - Scheme identifier
+- `DEFAULT_MAINNET_API` - Mainnet Hiro API endpoint
+- `DEFAULT_TESTNET_API` - Testnet Hiro API endpoint
+
+**Tokens:**
+
+- `TOKEN_REGISTRY` - Token configurations by network
+- `getTokenConfig(network, symbol)` - Get token by symbol
+- `getDefaultToken(network)` - Get default token
+- `getContractAddress(network, symbol)` - Get contract address
+
+**Utilities:**
+
+- `isValidPrincipal(principal)` - Validate Stacks principal format
+- `isValidTxId(txId)` - Validate transaction ID format
+- `isStacksNetwork(network)` - Check if network is supported
+- `getNetworkConfig(network)` - Get network configuration
+- `formatAmount(amount, decimals)` - Format for display
+- `parseAmount(amount, decimals)` - Convert to atomic units
+- `extractTokenTransfer(events)` - Extract transfer from transaction events
+- `comparePrincipals(a, b)` - Compare two Stacks principals
+
+### Client (`@t402/stacks/exact-direct/client`)
+
+```typescript
+import { createExactDirectStacksClient } from "@t402/stacks/exact-direct/client";
+
+const client = createExactDirectStacksClient({
+  signer: myStacksSigner,
+});
+```
+
+### Server (`@t402/stacks/exact-direct/server`)
+
+```typescript
+import { registerExactDirectStacksServer } from "@t402/stacks/exact-direct/server";
+
+registerExactDirectStacksServer(server);
+```
+
+### Facilitator (`@t402/stacks/exact-direct/facilitator`)
+
+```typescript
+import { createExactDirectStacksFacilitator } from "@t402/stacks/exact-direct/facilitator";
+
+const facilitator = createExactDirectStacksFacilitator(signer);
+```
+
+## Payment Flow
+
+1. **Client** requests protected resource
+2. **Server** responds with 402 + payment requirements (network, amount, payTo)
+3. **Client** calls SIP-010 `transfer` on the sUSDC contract
+4. **Client** submits transaction ID as payment proof
+5. **Facilitator** queries Hiro API to verify the transaction
+6. **Facilitator** confirms payment matches requirements
+
+## Payload Structure
+
+```typescript
+interface ExactDirectStacksPayload {
+  txId: string;             // Transaction ID (0x-prefixed hex)
+  from: string;             // Sender principal
+  to: string;               // Recipient principal
+  amount: string;           // Amount in atomic units (6 decimals)
+  contractAddress: string;  // SIP-010 contract address
+}
+```
+
+## Principal Format
+
+Stacks uses principal-based addressing:
+
+- **Standard principals**: `SP` (mainnet) or `ST` (testnet) prefix + 33-41 alphanumeric characters
+- **Contract principals**: `{standard-principal}.{contract-name}`
+
+Examples:
+
+```
+SP3Y2ZSH8P7D50B0VBTSX11S7XSG24M1VB9YFQA4K
+SP3Y2ZSH8P7D50B0VBTSX11S7XSG24M1VB9YFQA4K.token-susdc
+```
+
+## SIP-010 Token Standard
+
+This package uses the SIP-010 fungible token standard on Stacks:
+
+- `transfer(amount, sender, recipient, memo?)` - Transfer tokens
+- `get-balance(owner)` - Query balance
+- Tokens have 6 decimal places (sUSDC)
+
+## CAIP-19 Asset Identifiers
+
+Assets use CAIP-19 format:
+
+```
+stacks:1/sip010:SP3Y2ZSH8P7D50B0VBTSX11S7XSG24M1VB9YFQA4K.token-susdc
+```
+
+## Transaction Verification
+
+The facilitator verifies payments by:
+
+- Querying the Hiro API for transaction details
+- Checking transaction status is `"success"`
+- Extracting token transfer from events or post conditions
+- Verifying: contract address, recipient, and amount (>= required)
+- Replay prevention via transaction ID caching (24-hour default)
+- Configurable max transaction age (1 hour default)
+
+## Development
+
+```bash
+# Build
+pnpm build
+
+# Test
+pnpm test
+
+# Test with coverage
+pnpm test:coverage
+
+# Lint
+pnpm lint
+```
+
+## Related Packages
+
+- `@t402/core` - Core protocol types and client
+- `@t402/fetch` - HTTP wrapper with automatic payment handling
+- `@t402/evm` - EVM implementation
+- `@t402/svm` - Solana implementation
+- `@t402/ton` - TON implementation
+- `@t402/tron` - TRON implementation
+- `@t402/near` - NEAR Protocol implementation
+- `@t402/aptos` - Aptos implementation
+- `@t402/tezos` - Tezos implementation
+- `@t402/polkadot` - Polkadot Asset Hub implementation
+- `@t402/cosmos` - Cosmos (Noble) implementation

package/dist/exact-direct/client/index.cjs

@@ -0,0 +1,167 @@
+"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/exact-direct/client/index.ts
+var client_exports = {};
+__export(client_exports, {
+  ExactDirectStacksClient: () => ExactDirectStacksClient,
+  createExactDirectStacksClient: () => createExactDirectStacksClient
+});
+module.exports = __toCommonJS(client_exports);
+
+// src/constants.ts
+var STACKS_CAIP2_NAMESPACE = "stacks";
+var STACKS_MAINNET_CAIP2 = "stacks:1";
+var STACKS_TESTNET_CAIP2 = "stacks:2147483648";
+var SCHEME_EXACT_DIRECT = "exact-direct";
+var DEFAULT_MAINNET_API = "https://api.mainnet.hiro.so";
+var DEFAULT_TESTNET_API = "https://api.testnet.hiro.so";
+var STACKS_NETWORKS = {
+  [STACKS_MAINNET_CAIP2]: {
+    name: "Stacks Mainnet",
+    caip2: STACKS_MAINNET_CAIP2,
+    apiUrl: DEFAULT_MAINNET_API,
+    chainId: 1,
+    addressPrefix: "SP",
+    isTestnet: false
+  },
+  [STACKS_TESTNET_CAIP2]: {
+    name: "Stacks Testnet",
+    caip2: STACKS_TESTNET_CAIP2,
+    apiUrl: DEFAULT_TESTNET_API,
+    chainId: 2147483648,
+    addressPrefix: "ST",
+    isTestnet: true
+  }
+};
+
+// src/tokens.ts
+var SUSDC_MAINNET = {
+  contractAddress: "SP3Y2ZSH8P7D50B0VBTSX11S7XSG24M1VB9YFQA4K.token-susdc",
+  symbol: "sUSDC",
+  name: "Stacks USDC",
+  decimals: 6,
+  issuer: "Stacks"
+};
+var SUSDC_TESTNET = {
+  contractAddress: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.token-susdc",
+  symbol: "sUSDC",
+  name: "Test Stacks USDC",
+  decimals: 6
+};
+var TOKEN_REGISTRY = {
+  [STACKS_MAINNET_CAIP2]: {
+    sUSDC: SUSDC_MAINNET
+  },
+  [STACKS_TESTNET_CAIP2]: {
+    sUSDC: SUSDC_TESTNET
+  }
+};
+var DEFAULT_TOKENS = {
+  [STACKS_MAINNET_CAIP2]: SUSDC_MAINNET,
+  [STACKS_TESTNET_CAIP2]: SUSDC_TESTNET
+};
+function getTokenConfig(network, symbol = "sUSDC") {
+  return TOKEN_REGISTRY[network]?.[symbol];
+}
+function getContractAddress(network, symbol = "sUSDC") {
+  return getTokenConfig(network, symbol)?.contractAddress;
+}
+
+// src/utils.ts
+function isValidPrincipal(address) {
+  if (!address || typeof address !== "string") {
+    return false;
+  }
+  const parts = address.split(".");
+  const principal = parts[0];
+  const principalRegex = /^(SP|ST)[0-9A-HJ-NP-Za-km-z]{33,41}$/;
+  if (!principalRegex.test(principal)) {
+    return false;
+  }
+  if (parts.length === 2) {
+    const contractName = parts[1];
+    const contractNameRegex = /^[a-zA-Z][a-zA-Z0-9\-_]{0,127}$/;
+    return contractNameRegex.test(contractName);
+  }
+  return parts.length === 1;
+}
+
+// src/exact-direct/client/scheme.ts
+var ExactDirectStacksClient = class {
+  scheme = SCHEME_EXACT_DIRECT;
+  signer;
+  constructor(config) {
+    this.signer = config.signer;
+  }
+  /**
+   * Create a payment payload by executing the transfer
+   */
+  async createPaymentPayload(t402Version, requirements) {
+    this.validateRequirements(requirements);
+    const { network, amount, payTo, extra } = requirements;
+    const symbol = extra?.assetSymbol || "sUSDC";
+    const contractAddress = extra?.contractAddress ?? getContractAddress(network, symbol);
+    if (!contractAddress) {
+      throw new Error(`Unknown asset ${symbol} on network ${network}`);
+    }
+    const from = await this.signer.getAddress();
+    const { txId } = await this.signer.transferToken(contractAddress, payTo, amount);
+    const stacksPayload = {
+      txId,
+      from,
+      to: payTo,
+      amount,
+      contractAddress
+    };
+    return {
+      t402Version,
+      payload: stacksPayload
+    };
+  }
+  /**
+   * Validate payment requirements
+   */
+  validateRequirements(requirements) {
+    if (requirements.scheme !== SCHEME_EXACT_DIRECT) {
+      throw new Error(
+        `Invalid scheme: expected ${SCHEME_EXACT_DIRECT}, got ${requirements.scheme}`
+      );
+    }
+    if (!requirements.network.startsWith(`${STACKS_CAIP2_NAMESPACE}:`)) {
+      throw new Error(`Invalid network: ${requirements.network}`);
+    }
+    if (!isValidPrincipal(requirements.payTo)) {
+      throw new Error(`Invalid payTo address: ${requirements.payTo}`);
+    }
+    const amount = BigInt(requirements.amount);
+    if (amount <= 0n) {
+      throw new Error(`Invalid amount: ${requirements.amount}`);
+    }
+  }
+};
+function createExactDirectStacksClient(config) {
+  return new ExactDirectStacksClient(config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ExactDirectStacksClient,
+  createExactDirectStacksClient
+});
+//# sourceMappingURL=index.cjs.map

package/dist/exact-direct/client/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/exact-direct/client/index.ts","../../../src/constants.ts","../../../src/tokens.ts","../../../src/utils.ts","../../../src/exact-direct/client/scheme.ts"],"sourcesContent":["export {\n  ExactDirectStacksClient,\n  createExactDirectStacksClient,\n  type ExactDirectStacksClientConfig,\n} from \"./scheme.js\";\n","/**\n * Stacks T402 Constants\n *\n * Stacks is a Bitcoin Layer 2 that brings smart contracts and DeFi\n * to Bitcoin. SIP-010 is the fungible token standard on Stacks.\n */\n\n// CAIP-2 namespace for Stacks\nexport const STACKS_CAIP2_NAMESPACE = \"stacks\";\n\n// CAIP-2 network identifiers\n// Stacks Mainnet (chain ID: 1)\nexport const STACKS_MAINNET_CAIP2 = \"stacks:1\";\n\n// Stacks Testnet (chain ID: 2147483648)\nexport const STACKS_TESTNET_CAIP2 = \"stacks:2147483648\";\n\n// Scheme identifier\nexport const SCHEME_EXACT_DIRECT = \"exact-direct\";\n\n// Default API endpoints (Hiro API)\nexport const DEFAULT_MAINNET_API = \"https://api.mainnet.hiro.so\";\nexport const DEFAULT_TESTNET_API = \"https://api.testnet.hiro.so\";\n\n// Network configurations\nexport interface StacksNetworkConfig {\n  readonly name: string;\n  readonly caip2: string;\n  readonly apiUrl: string;\n  readonly chainId: number;\n  readonly addressPrefix: string;\n  readonly isTestnet: boolean;\n}\n\nexport const STACKS_NETWORKS: Record<string, StacksNetworkConfig> = {\n  [STACKS_MAINNET_CAIP2]: {\n    name: \"Stacks Mainnet\",\n    caip2: STACKS_MAINNET_CAIP2,\n    apiUrl: DEFAULT_MAINNET_API,\n    chainId: 1,\n    addressPrefix: \"SP\",\n    isTestnet: false,\n  },\n  [STACKS_TESTNET_CAIP2]: {\n    name: \"Stacks Testnet\",\n    caip2: STACKS_TESTNET_CAIP2,\n    apiUrl: DEFAULT_TESTNET_API,\n    chainId: 2147483648,\n    addressPrefix: \"ST\",\n    isTestnet: true,\n  },\n};\n\n/**\n * Get network configuration by CAIP-2 identifier\n */\nexport function getNetworkConfig(network: string): StacksNetworkConfig | undefined {\n  return STACKS_NETWORKS[network];\n}\n\n/**\n * Check if a network identifier is a Stacks network\n */\nexport function isStacksNetwork(network: string): boolean {\n  return network.startsWith(`${STACKS_CAIP2_NAMESPACE}:`);\n}\n","/**\n * Stacks Token Registry\n *\n * On Stacks, tokens are SIP-010 fungible tokens identified by\n * their contract address (principal.contract-name).\n */\n\nimport {\n  STACKS_MAINNET_CAIP2,\n  STACKS_TESTNET_CAIP2,\n} from \"./constants.js\";\n\n/**\n * Token configuration for Stacks SIP-010 tokens\n */\nexport interface TokenConfig {\n  /** Contract address (principal.contract-name) */\n  readonly contractAddress: string;\n  /** Token symbol */\n  readonly symbol: string;\n  /** Token name */\n  readonly name: string;\n  /** Decimal places */\n  readonly decimals: number;\n  /** Token issuer */\n  readonly issuer?: string;\n}\n\n/**\n * sUSDC on Stacks Mainnet\n * Contract: SP3Y2ZSH8P7D50B0VBTSX11S7XSG24M1VB9YFQA4K.token-susdc\n * Decimals: 6\n */\nexport const SUSDC_MAINNET: TokenConfig = {\n  contractAddress: \"SP3Y2ZSH8P7D50B0VBTSX11S7XSG24M1VB9YFQA4K.token-susdc\",\n  symbol: \"sUSDC\",\n  name: \"Stacks USDC\",\n  decimals: 6,\n  issuer: \"Stacks\",\n};\n\n/**\n * sUSDC on Stacks Testnet\n * Contract: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.token-susdc\n * Decimals: 6\n */\nexport const SUSDC_TESTNET: TokenConfig = {\n  contractAddress: \"ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.token-susdc\",\n  symbol: \"sUSDC\",\n  name: \"Test Stacks USDC\",\n  decimals: 6,\n};\n\n/**\n * Network-specific token registries\n */\nexport const TOKEN_REGISTRY: Record<string, Record<string, TokenConfig>> = {\n  [STACKS_MAINNET_CAIP2]: {\n    sUSDC: SUSDC_MAINNET,\n  },\n  [STACKS_TESTNET_CAIP2]: {\n    sUSDC: SUSDC_TESTNET,\n  },\n};\n\n/**\n * Default tokens per network\n */\nexport const DEFAULT_TOKENS: Record<string, TokenConfig> = {\n  [STACKS_MAINNET_CAIP2]: SUSDC_MAINNET,\n  [STACKS_TESTNET_CAIP2]: SUSDC_TESTNET,\n};\n\n/**\n * Get token configuration by network and symbol\n */\nexport function getTokenConfig(\n  network: string,\n  symbol: string = \"sUSDC\",\n): TokenConfig | undefined {\n  return TOKEN_REGISTRY[network]?.[symbol];\n}\n\n/**\n * Get the default token for a network\n */\nexport function getDefaultToken(network: string): TokenConfig | undefined {\n  return DEFAULT_TOKENS[network];\n}\n\n/**\n * Get contract address for a token on a network\n */\nexport function getContractAddress(network: string, symbol: string = \"sUSDC\"): string | undefined {\n  return getTokenConfig(network, symbol)?.contractAddress;\n}\n","/**\n * Stacks Utility Functions\n */\n\nimport type { StacksTransactionResult, ParsedTokenTransfer } from \"./types.js\";\n\n/**\n * Validate a Stacks principal address format\n * Stacks addresses start with SP (mainnet) or ST (testnet)\n * followed by alphanumeric characters (base58-like encoding)\n */\nexport function isValidPrincipal(address: string): boolean {\n  if (!address || typeof address !== \"string\") {\n    return false;\n  }\n\n  // Standard principal: SP/ST prefix + base58 characters (33-41 chars total)\n  // Contract principal: standard-principal.contract-name\n  const parts = address.split(\".\");\n  const principal = parts[0];\n\n  // Check principal format: SP or ST prefix + alphanumeric (base58 chars)\n  const principalRegex = /^(SP|ST)[0-9A-HJ-NP-Za-km-z]{33,41}$/;\n  if (!principalRegex.test(principal)) {\n    return false;\n  }\n\n  // If it's a contract principal, validate contract name\n  if (parts.length === 2) {\n    const contractName = parts[1];\n    // Contract names: 1-128 chars, alphanumeric + hyphen + underscore\n    const contractNameRegex = /^[a-zA-Z][a-zA-Z0-9\\-_]{0,127}$/;\n    return contractNameRegex.test(contractName);\n  }\n\n  // Standard principal (no contract part) or exactly one dot for contract\n  return parts.length === 1;\n}\n\n/**\n * Validate a Stacks transaction ID format\n * Transaction IDs are 0x-prefixed 64-character hex strings\n */\nexport function isValidTxId(hash: string): boolean {\n  if (!hash || typeof hash !== \"string\") {\n    return false;\n  }\n  return /^0x[a-fA-F0-9]{64}$/.test(hash);\n}\n\n/**\n * Compare two Stacks principals (case-sensitive)\n */\nexport function comparePrincipals(a: string, b: string): boolean {\n  return a === b;\n}\n\n/**\n * Format an amount with decimals for display\n */\nexport function formatAmount(amount: string, decimals: number): string {\n  const amountBigInt = BigInt(amount);\n  const divisor = BigInt(10 ** decimals);\n  const wholePart = amountBigInt / divisor;\n  const fractionalPart = amountBigInt % divisor;\n\n  if (fractionalPart === 0n) {\n    return wholePart.toString();\n  }\n\n  const fractionalStr = fractionalPart.toString().padStart(decimals, \"0\");\n  const trimmedFractional = fractionalStr.replace(/0+$/, \"\");\n  return `${wholePart}.${trimmedFractional}`;\n}\n\n/**\n * Parse an amount string to the smallest unit (with decimals applied)\n */\nexport function parseAmount(amount: string, decimals: number): string {\n  const parts = amount.split(\".\");\n  const wholePart = parts[0] || \"0\";\n  const fractionalPart = (parts[1] || \"\").padEnd(decimals, \"0\").slice(0, decimals);\n  return BigInt(wholePart + fractionalPart).toString();\n}\n\n/**\n * Extract token transfer details from a Stacks transaction result\n * Looks for ft_transfer events matching the expected contract\n */\nexport function extractTokenTransfer(\n  result: StacksTransactionResult,\n  contractAddress?: string,\n): ParsedTokenTransfer | null {\n  if (result.txStatus !== \"success\") {\n    return null;\n  }\n\n  // Check if this is a contract-call transaction\n  if (result.txType !== \"contract_call\") {\n    return null;\n  }\n\n  // Check contract call is a transfer function\n  if (result.contractCall) {\n    const { contractId, functionName } = result.contractCall;\n\n    if (functionName !== \"transfer\") {\n      return null;\n    }\n\n    // If contractAddress specified, verify it matches\n    if (contractAddress && contractId !== contractAddress) {\n      return null;\n    }\n\n    // Look for ft_transfer event\n    const transferEvent = result.events.find(\n      (e) => e.eventType === \"fungible_token_asset\" && e.asset?.assetEventType === \"transfer\",\n    );\n\n    if (transferEvent?.asset) {\n      return {\n        contractAddress: contractId,\n        from: transferEvent.asset.sender,\n        to: transferEvent.asset.recipient,\n        amount: transferEvent.asset.amount,\n        success: true,\n      };\n    }\n\n    // Fallback: extract from function args if events not available\n    if (result.contractCall.functionArgs.length >= 3) {\n      const amountArg = result.contractCall.functionArgs[0];\n      const senderArg = result.contractCall.functionArgs[1];\n      const recipientArg = result.contractCall.functionArgs[2];\n\n      // Parse principal from repr (format: 'SP...')\n      const senderMatch = senderArg?.repr?.match(/^'?(S[PT][0-9A-HJ-NP-Za-km-z]+)/);\n      const recipientMatch = recipientArg?.repr?.match(/^'?(S[PT][0-9A-HJ-NP-Za-km-z]+)/);\n      const amountMatch = amountArg?.repr?.match(/^u(\\d+)$/);\n\n      if (senderMatch && recipientMatch && amountMatch) {\n        return {\n          contractAddress: contractId,\n          from: senderMatch[1],\n          to: recipientMatch[1],\n          amount: amountMatch[1],\n          success: true,\n        };\n      }\n    }\n  }\n\n  return null;\n}\n\n/**\n * Extract token transfer from post conditions (alternative method)\n */\nexport function extractTokenTransferFromPostConditions(\n  result: StacksTransactionResult,\n  contractAddress?: string,\n): ParsedTokenTransfer | null {\n  if (result.txStatus !== \"success\") {\n    return null;\n  }\n\n  // Look for fungible token post conditions\n  for (const pc of result.postConditions) {\n    if (pc.asset) {\n      const assetContractAddress = `${pc.asset.contractAddress}.${pc.asset.contractName}`;\n\n      if (contractAddress && assetContractAddress !== contractAddress) {\n        continue;\n      }\n\n      // Find corresponding ft_transfer event for recipient\n      const transferEvent = result.events.find(\n        (e) =>\n          e.eventType === \"fungible_token_asset\" &&\n          e.asset?.assetEventType === \"transfer\" &&\n          e.asset?.sender === pc.principal.address,\n      );\n\n      if (transferEvent?.asset) {\n        return {\n          contractAddress: assetContractAddress,\n          from: transferEvent.asset.sender,\n          to: transferEvent.asset.recipient,\n          amount: transferEvent.asset.amount,\n          success: true,\n        };\n      }\n    }\n  }\n\n  return null;\n}\n","/**\n * Stacks Exact-Direct Client Scheme\n *\n * In the exact-direct scheme, the client executes the SIP-010 token transfer\n * directly and provides the transaction ID as proof of payment.\n */\n\nimport type {\n  PaymentPayload,\n  PaymentRequirements,\n  SchemeNetworkClient,\n} from \"@t402/core/types\";\nimport type { ClientStacksSigner, ExactDirectStacksPayload } from \"../../types.js\";\nimport { SCHEME_EXACT_DIRECT, STACKS_CAIP2_NAMESPACE } from \"../../constants.js\";\nimport { getContractAddress } from \"../../tokens.js\";\nimport { isValidPrincipal } from \"../../utils.js\";\n\n/**\n * Configuration for the exact-direct client\n */\nexport interface ExactDirectStacksClientConfig {\n  /** Signer for executing transactions */\n  signer: ClientStacksSigner;\n}\n\n/**\n * Exact-direct client scheme for Stacks\n */\nexport class ExactDirectStacksClient implements SchemeNetworkClient {\n  readonly scheme = SCHEME_EXACT_DIRECT;\n  private readonly signer: ClientStacksSigner;\n\n  constructor(config: ExactDirectStacksClientConfig) {\n    this.signer = config.signer;\n  }\n\n  /**\n   * Create a payment payload by executing the transfer\n   */\n  async createPaymentPayload(\n    t402Version: number,\n    requirements: PaymentRequirements,\n  ): Promise<Pick<PaymentPayload, \"t402Version\" | \"payload\">> {\n    // Validate requirements\n    this.validateRequirements(requirements);\n\n    const { network, amount, payTo, extra } = requirements;\n\n    // Get contract address from extra or use default sUSDC\n    const symbol = (extra?.assetSymbol as string) || \"sUSDC\";\n    const contractAddress =\n      (extra?.contractAddress as string) ?? getContractAddress(network, symbol);\n\n    if (!contractAddress) {\n      throw new Error(`Unknown asset ${symbol} on network ${network}`);\n    }\n\n    // Get sender address\n    const from = await this.signer.getAddress();\n\n    // Execute the transfer\n    const { txId } = await this.signer.transferToken(contractAddress, payTo, amount);\n\n    // Build the payload\n    const stacksPayload: ExactDirectStacksPayload = {\n      txId,\n      from,\n      to: payTo,\n      amount,\n      contractAddress,\n    };\n\n    return {\n      t402Version,\n      payload: stacksPayload,\n    };\n  }\n\n  /**\n   * Validate payment requirements\n   */\n  private validateRequirements(requirements: PaymentRequirements): void {\n    // Check scheme\n    if (requirements.scheme !== SCHEME_EXACT_DIRECT) {\n      throw new Error(\n        `Invalid scheme: expected ${SCHEME_EXACT_DIRECT}, got ${requirements.scheme}`,\n      );\n    }\n\n    // Check network\n    if (!requirements.network.startsWith(`${STACKS_CAIP2_NAMESPACE}:`)) {\n      throw new Error(`Invalid network: ${requirements.network}`);\n    }\n\n    // Check payTo address\n    if (!isValidPrincipal(requirements.payTo)) {\n      throw new Error(`Invalid payTo address: ${requirements.payTo}`);\n    }\n\n    // Check amount\n    const amount = BigInt(requirements.amount);\n    if (amount <= 0n) {\n      throw new Error(`Invalid amount: ${requirements.amount}`);\n    }\n  }\n}\n\n/**\n * Create an exact-direct client for Stacks\n */\nexport function createExactDirectStacksClient(\n  config: ExactDirectStacksClientConfig,\n): ExactDirectStacksClient {\n  return new ExactDirectStacksClient(config);\n}\n"],"mappings":"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","names":[]}

package/dist/exact-direct/client/index.d.cts

@@ -0,0 +1,39 @@
+import { SchemeNetworkClient, PaymentRequirements, PaymentPayload } from '@t402/core/types';
+import { C as ClientStacksSigner } from '../../types-Bxzo3eQ1.cjs';
+
+/**
+ * Stacks Exact-Direct Client Scheme
+ *
+ * In the exact-direct scheme, the client executes the SIP-010 token transfer
+ * directly and provides the transaction ID as proof of payment.
+ */
+
+/**
+ * Configuration for the exact-direct client
+ */
+interface ExactDirectStacksClientConfig {
+    /** Signer for executing transactions */
+    signer: ClientStacksSigner;
+}
+/**
+ * Exact-direct client scheme for Stacks
+ */
+declare class ExactDirectStacksClient implements SchemeNetworkClient {
+    readonly scheme = "exact-direct";
+    private readonly signer;
+    constructor(config: ExactDirectStacksClientConfig);
+    /**
+     * Create a payment payload by executing the transfer
+     */
+    createPaymentPayload(t402Version: number, requirements: PaymentRequirements): Promise<Pick<PaymentPayload, "t402Version" | "payload">>;
+    /**
+     * Validate payment requirements
+     */
+    private validateRequirements;
+}
+/**
+ * Create an exact-direct client for Stacks
+ */
+declare function createExactDirectStacksClient(config: ExactDirectStacksClientConfig): ExactDirectStacksClient;
+
+export { ExactDirectStacksClient, type ExactDirectStacksClientConfig, createExactDirectStacksClient };

package/dist/exact-direct/client/index.d.ts

@@ -0,0 +1,39 @@
+import { SchemeNetworkClient, PaymentRequirements, PaymentPayload } from '@t402/core/types';
+import { C as ClientStacksSigner } from '../../types-Bxzo3eQ1.js';
+
+/**
+ * Stacks Exact-Direct Client Scheme
+ *
+ * In the exact-direct scheme, the client executes the SIP-010 token transfer
+ * directly and provides the transaction ID as proof of payment.
+ */
+
+/**
+ * Configuration for the exact-direct client
+ */
+interface ExactDirectStacksClientConfig {
+    /** Signer for executing transactions */
+    signer: ClientStacksSigner;
+}
+/**
+ * Exact-direct client scheme for Stacks
+ */
+declare class ExactDirectStacksClient implements SchemeNetworkClient {
+    readonly scheme = "exact-direct";
+    private readonly signer;
+    constructor(config: ExactDirectStacksClientConfig);
+    /**
+     * Create a payment payload by executing the transfer
+     */
+    createPaymentPayload(t402Version: number, requirements: PaymentRequirements): Promise<Pick<PaymentPayload, "t402Version" | "payload">>;
+    /**
+     * Validate payment requirements
+     */
+    private validateRequirements;
+}
+/**
+ * Create an exact-direct client for Stacks
+ */
+declare function createExactDirectStacksClient(config: ExactDirectStacksClientConfig): ExactDirectStacksClient;
+
+export { ExactDirectStacksClient, type ExactDirectStacksClientConfig, createExactDirectStacksClient };

package/dist/exact-direct/client/index.mjs

@@ -0,0 +1,139 @@
+// src/constants.ts
+var STACKS_CAIP2_NAMESPACE = "stacks";
+var STACKS_MAINNET_CAIP2 = "stacks:1";
+var STACKS_TESTNET_CAIP2 = "stacks:2147483648";
+var SCHEME_EXACT_DIRECT = "exact-direct";
+var DEFAULT_MAINNET_API = "https://api.mainnet.hiro.so";
+var DEFAULT_TESTNET_API = "https://api.testnet.hiro.so";
+var STACKS_NETWORKS = {
+  [STACKS_MAINNET_CAIP2]: {
+    name: "Stacks Mainnet",
+    caip2: STACKS_MAINNET_CAIP2,
+    apiUrl: DEFAULT_MAINNET_API,
+    chainId: 1,
+    addressPrefix: "SP",
+    isTestnet: false
+  },
+  [STACKS_TESTNET_CAIP2]: {
+    name: "Stacks Testnet",
+    caip2: STACKS_TESTNET_CAIP2,
+    apiUrl: DEFAULT_TESTNET_API,
+    chainId: 2147483648,
+    addressPrefix: "ST",
+    isTestnet: true
+  }
+};
+
+// src/tokens.ts
+var SUSDC_MAINNET = {
+  contractAddress: "SP3Y2ZSH8P7D50B0VBTSX11S7XSG24M1VB9YFQA4K.token-susdc",
+  symbol: "sUSDC",
+  name: "Stacks USDC",
+  decimals: 6,
+  issuer: "Stacks"
+};
+var SUSDC_TESTNET = {
+  contractAddress: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.token-susdc",
+  symbol: "sUSDC",
+  name: "Test Stacks USDC",
+  decimals: 6
+};
+var TOKEN_REGISTRY = {
+  [STACKS_MAINNET_CAIP2]: {
+    sUSDC: SUSDC_MAINNET
+  },
+  [STACKS_TESTNET_CAIP2]: {
+    sUSDC: SUSDC_TESTNET
+  }
+};
+var DEFAULT_TOKENS = {
+  [STACKS_MAINNET_CAIP2]: SUSDC_MAINNET,
+  [STACKS_TESTNET_CAIP2]: SUSDC_TESTNET
+};
+function getTokenConfig(network, symbol = "sUSDC") {
+  return TOKEN_REGISTRY[network]?.[symbol];
+}
+function getContractAddress(network, symbol = "sUSDC") {
+  return getTokenConfig(network, symbol)?.contractAddress;
+}
+
+// src/utils.ts
+function isValidPrincipal(address) {
+  if (!address || typeof address !== "string") {
+    return false;
+  }
+  const parts = address.split(".");
+  const principal = parts[0];
+  const principalRegex = /^(SP|ST)[0-9A-HJ-NP-Za-km-z]{33,41}$/;
+  if (!principalRegex.test(principal)) {
+    return false;
+  }
+  if (parts.length === 2) {
+    const contractName = parts[1];
+    const contractNameRegex = /^[a-zA-Z][a-zA-Z0-9\-_]{0,127}$/;
+    return contractNameRegex.test(contractName);
+  }
+  return parts.length === 1;
+}
+
+// src/exact-direct/client/scheme.ts
+var ExactDirectStacksClient = class {
+  scheme = SCHEME_EXACT_DIRECT;
+  signer;
+  constructor(config) {
+    this.signer = config.signer;
+  }
+  /**
+   * Create a payment payload by executing the transfer
+   */
+  async createPaymentPayload(t402Version, requirements) {
+    this.validateRequirements(requirements);
+    const { network, amount, payTo, extra } = requirements;
+    const symbol = extra?.assetSymbol || "sUSDC";
+    const contractAddress = extra?.contractAddress ?? getContractAddress(network, symbol);
+    if (!contractAddress) {
+      throw new Error(`Unknown asset ${symbol} on network ${network}`);
+    }
+    const from = await this.signer.getAddress();
+    const { txId } = await this.signer.transferToken(contractAddress, payTo, amount);
+    const stacksPayload = {
+      txId,
+      from,
+      to: payTo,
+      amount,
+      contractAddress
+    };
+    return {
+      t402Version,
+      payload: stacksPayload
+    };
+  }
+  /**
+   * Validate payment requirements
+   */
+  validateRequirements(requirements) {
+    if (requirements.scheme !== SCHEME_EXACT_DIRECT) {
+      throw new Error(
+        `Invalid scheme: expected ${SCHEME_EXACT_DIRECT}, got ${requirements.scheme}`
+      );
+    }
+    if (!requirements.network.startsWith(`${STACKS_CAIP2_NAMESPACE}:`)) {
+      throw new Error(`Invalid network: ${requirements.network}`);
+    }
+    if (!isValidPrincipal(requirements.payTo)) {
+      throw new Error(`Invalid payTo address: ${requirements.payTo}`);
+    }
+    const amount = BigInt(requirements.amount);
+    if (amount <= 0n) {
+      throw new Error(`Invalid amount: ${requirements.amount}`);
+    }
+  }
+};
+function createExactDirectStacksClient(config) {
+  return new ExactDirectStacksClient(config);
+}
+export {
+  ExactDirectStacksClient,
+  createExactDirectStacksClient
+};
+//# sourceMappingURL=index.mjs.map

package/dist/exact-direct/client/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/constants.ts","../../../src/tokens.ts","../../../src/utils.ts","../../../src/exact-direct/client/scheme.ts"],"sourcesContent":["/**\n * Stacks T402 Constants\n *\n * Stacks is a Bitcoin Layer 2 that brings smart contracts and DeFi\n * to Bitcoin. SIP-010 is the fungible token standard on Stacks.\n */\n\n// CAIP-2 namespace for Stacks\nexport const STACKS_CAIP2_NAMESPACE = \"stacks\";\n\n// CAIP-2 network identifiers\n// Stacks Mainnet (chain ID: 1)\nexport const STACKS_MAINNET_CAIP2 = \"stacks:1\";\n\n// Stacks Testnet (chain ID: 2147483648)\nexport const STACKS_TESTNET_CAIP2 = \"stacks:2147483648\";\n\n// Scheme identifier\nexport const SCHEME_EXACT_DIRECT = \"exact-direct\";\n\n// Default API endpoints (Hiro API)\nexport const DEFAULT_MAINNET_API = \"https://api.mainnet.hiro.so\";\nexport const DEFAULT_TESTNET_API = \"https://api.testnet.hiro.so\";\n\n// Network configurations\nexport interface StacksNetworkConfig {\n  readonly name: string;\n  readonly caip2: string;\n  readonly apiUrl: string;\n  readonly chainId: number;\n  readonly addressPrefix: string;\n  readonly isTestnet: boolean;\n}\n\nexport const STACKS_NETWORKS: Record<string, StacksNetworkConfig> = {\n  [STACKS_MAINNET_CAIP2]: {\n    name: \"Stacks Mainnet\",\n    caip2: STACKS_MAINNET_CAIP2,\n    apiUrl: DEFAULT_MAINNET_API,\n    chainId: 1,\n    addressPrefix: \"SP\",\n    isTestnet: false,\n  },\n  [STACKS_TESTNET_CAIP2]: {\n    name: \"Stacks Testnet\",\n    caip2: STACKS_TESTNET_CAIP2,\n    apiUrl: DEFAULT_TESTNET_API,\n    chainId: 2147483648,\n    addressPrefix: \"ST\",\n    isTestnet: true,\n  },\n};\n\n/**\n * Get network configuration by CAIP-2 identifier\n */\nexport function getNetworkConfig(network: string): StacksNetworkConfig | undefined {\n  return STACKS_NETWORKS[network];\n}\n\n/**\n * Check if a network identifier is a Stacks network\n */\nexport function isStacksNetwork(network: string): boolean {\n  return network.startsWith(`${STACKS_CAIP2_NAMESPACE}:`);\n}\n","/**\n * Stacks Token Registry\n *\n * On Stacks, tokens are SIP-010 fungible tokens identified by\n * their contract address (principal.contract-name).\n */\n\nimport {\n  STACKS_MAINNET_CAIP2,\n  STACKS_TESTNET_CAIP2,\n} from \"./constants.js\";\n\n/**\n * Token configuration for Stacks SIP-010 tokens\n */\nexport interface TokenConfig {\n  /** Contract address (principal.contract-name) */\n  readonly contractAddress: string;\n  /** Token symbol */\n  readonly symbol: string;\n  /** Token name */\n  readonly name: string;\n  /** Decimal places */\n  readonly decimals: number;\n  /** Token issuer */\n  readonly issuer?: string;\n}\n\n/**\n * sUSDC on Stacks Mainnet\n * Contract: SP3Y2ZSH8P7D50B0VBTSX11S7XSG24M1VB9YFQA4K.token-susdc\n * Decimals: 6\n */\nexport const SUSDC_MAINNET: TokenConfig = {\n  contractAddress: \"SP3Y2ZSH8P7D50B0VBTSX11S7XSG24M1VB9YFQA4K.token-susdc\",\n  symbol: \"sUSDC\",\n  name: \"Stacks USDC\",\n  decimals: 6,\n  issuer: \"Stacks\",\n};\n\n/**\n * sUSDC on Stacks Testnet\n * Contract: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.token-susdc\n * Decimals: 6\n */\nexport const SUSDC_TESTNET: TokenConfig = {\n  contractAddress: \"ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.token-susdc\",\n  symbol: \"sUSDC\",\n  name: \"Test Stacks USDC\",\n  decimals: 6,\n};\n\n/**\n * Network-specific token registries\n */\nexport const TOKEN_REGISTRY: Record<string, Record<string, TokenConfig>> = {\n  [STACKS_MAINNET_CAIP2]: {\n    sUSDC: SUSDC_MAINNET,\n  },\n  [STACKS_TESTNET_CAIP2]: {\n    sUSDC: SUSDC_TESTNET,\n  },\n};\n\n/**\n * Default tokens per network\n */\nexport const DEFAULT_TOKENS: Record<string, TokenConfig> = {\n  [STACKS_MAINNET_CAIP2]: SUSDC_MAINNET,\n  [STACKS_TESTNET_CAIP2]: SUSDC_TESTNET,\n};\n\n/**\n * Get token configuration by network and symbol\n */\nexport function getTokenConfig(\n  network: string,\n  symbol: string = \"sUSDC\",\n): TokenConfig | undefined {\n  return TOKEN_REGISTRY[network]?.[symbol];\n}\n\n/**\n * Get the default token for a network\n */\nexport function getDefaultToken(network: string): TokenConfig | undefined {\n  return DEFAULT_TOKENS[network];\n}\n\n/**\n * Get contract address for a token on a network\n */\nexport function getContractAddress(network: string, symbol: string = \"sUSDC\"): string | undefined {\n  return getTokenConfig(network, symbol)?.contractAddress;\n}\n","/**\n * Stacks Utility Functions\n */\n\nimport type { StacksTransactionResult, ParsedTokenTransfer } from \"./types.js\";\n\n/**\n * Validate a Stacks principal address format\n * Stacks addresses start with SP (mainnet) or ST (testnet)\n * followed by alphanumeric characters (base58-like encoding)\n */\nexport function isValidPrincipal(address: string): boolean {\n  if (!address || typeof address !== \"string\") {\n    return false;\n  }\n\n  // Standard principal: SP/ST prefix + base58 characters (33-41 chars total)\n  // Contract principal: standard-principal.contract-name\n  const parts = address.split(\".\");\n  const principal = parts[0];\n\n  // Check principal format: SP or ST prefix + alphanumeric (base58 chars)\n  const principalRegex = /^(SP|ST)[0-9A-HJ-NP-Za-km-z]{33,41}$/;\n  if (!principalRegex.test(principal)) {\n    return false;\n  }\n\n  // If it's a contract principal, validate contract name\n  if (parts.length === 2) {\n    const contractName = parts[1];\n    // Contract names: 1-128 chars, alphanumeric + hyphen + underscore\n    const contractNameRegex = /^[a-zA-Z][a-zA-Z0-9\\-_]{0,127}$/;\n    return contractNameRegex.test(contractName);\n  }\n\n  // Standard principal (no contract part) or exactly one dot for contract\n  return parts.length === 1;\n}\n\n/**\n * Validate a Stacks transaction ID format\n * Transaction IDs are 0x-prefixed 64-character hex strings\n */\nexport function isValidTxId(hash: string): boolean {\n  if (!hash || typeof hash !== \"string\") {\n    return false;\n  }\n  return /^0x[a-fA-F0-9]{64}$/.test(hash);\n}\n\n/**\n * Compare two Stacks principals (case-sensitive)\n */\nexport function comparePrincipals(a: string, b: string): boolean {\n  return a === b;\n}\n\n/**\n * Format an amount with decimals for display\n */\nexport function formatAmount(amount: string, decimals: number): string {\n  const amountBigInt = BigInt(amount);\n  const divisor = BigInt(10 ** decimals);\n  const wholePart = amountBigInt / divisor;\n  const fractionalPart = amountBigInt % divisor;\n\n  if (fractionalPart === 0n) {\n    return wholePart.toString();\n  }\n\n  const fractionalStr = fractionalPart.toString().padStart(decimals, \"0\");\n  const trimmedFractional = fractionalStr.replace(/0+$/, \"\");\n  return `${wholePart}.${trimmedFractional}`;\n}\n\n/**\n * Parse an amount string to the smallest unit (with decimals applied)\n */\nexport function parseAmount(amount: string, decimals: number): string {\n  const parts = amount.split(\".\");\n  const wholePart = parts[0] || \"0\";\n  const fractionalPart = (parts[1] || \"\").padEnd(decimals, \"0\").slice(0, decimals);\n  return BigInt(wholePart + fractionalPart).toString();\n}\n\n/**\n * Extract token transfer details from a Stacks transaction result\n * Looks for ft_transfer events matching the expected contract\n */\nexport function extractTokenTransfer(\n  result: StacksTransactionResult,\n  contractAddress?: string,\n): ParsedTokenTransfer | null {\n  if (result.txStatus !== \"success\") {\n    return null;\n  }\n\n  // Check if this is a contract-call transaction\n  if (result.txType !== \"contract_call\") {\n    return null;\n  }\n\n  // Check contract call is a transfer function\n  if (result.contractCall) {\n    const { contractId, functionName } = result.contractCall;\n\n    if (functionName !== \"transfer\") {\n      return null;\n    }\n\n    // If contractAddress specified, verify it matches\n    if (contractAddress && contractId !== contractAddress) {\n      return null;\n    }\n\n    // Look for ft_transfer event\n    const transferEvent = result.events.find(\n      (e) => e.eventType === \"fungible_token_asset\" && e.asset?.assetEventType === \"transfer\",\n    );\n\n    if (transferEvent?.asset) {\n      return {\n        contractAddress: contractId,\n        from: transferEvent.asset.sender,\n        to: transferEvent.asset.recipient,\n        amount: transferEvent.asset.amount,\n        success: true,\n      };\n    }\n\n    // Fallback: extract from function args if events not available\n    if (result.contractCall.functionArgs.length >= 3) {\n      const amountArg = result.contractCall.functionArgs[0];\n      const senderArg = result.contractCall.functionArgs[1];\n      const recipientArg = result.contractCall.functionArgs[2];\n\n      // Parse principal from repr (format: 'SP...')\n      const senderMatch = senderArg?.repr?.match(/^'?(S[PT][0-9A-HJ-NP-Za-km-z]+)/);\n      const recipientMatch = recipientArg?.repr?.match(/^'?(S[PT][0-9A-HJ-NP-Za-km-z]+)/);\n      const amountMatch = amountArg?.repr?.match(/^u(\\d+)$/);\n\n      if (senderMatch && recipientMatch && amountMatch) {\n        return {\n          contractAddress: contractId,\n          from: senderMatch[1],\n          to: recipientMatch[1],\n          amount: amountMatch[1],\n          success: true,\n        };\n      }\n    }\n  }\n\n  return null;\n}\n\n/**\n * Extract token transfer from post conditions (alternative method)\n */\nexport function extractTokenTransferFromPostConditions(\n  result: StacksTransactionResult,\n  contractAddress?: string,\n): ParsedTokenTransfer | null {\n  if (result.txStatus !== \"success\") {\n    return null;\n  }\n\n  // Look for fungible token post conditions\n  for (const pc of result.postConditions) {\n    if (pc.asset) {\n      const assetContractAddress = `${pc.asset.contractAddress}.${pc.asset.contractName}`;\n\n      if (contractAddress && assetContractAddress !== contractAddress) {\n        continue;\n      }\n\n      // Find corresponding ft_transfer event for recipient\n      const transferEvent = result.events.find(\n        (e) =>\n          e.eventType === \"fungible_token_asset\" &&\n          e.asset?.assetEventType === \"transfer\" &&\n          e.asset?.sender === pc.principal.address,\n      );\n\n      if (transferEvent?.asset) {\n        return {\n          contractAddress: assetContractAddress,\n          from: transferEvent.asset.sender,\n          to: transferEvent.asset.recipient,\n          amount: transferEvent.asset.amount,\n          success: true,\n        };\n      }\n    }\n  }\n\n  return null;\n}\n","/**\n * Stacks Exact-Direct Client Scheme\n *\n * In the exact-direct scheme, the client executes the SIP-010 token transfer\n * directly and provides the transaction ID as proof of payment.\n */\n\nimport type {\n  PaymentPayload,\n  PaymentRequirements,\n  SchemeNetworkClient,\n} from \"@t402/core/types\";\nimport type { ClientStacksSigner, ExactDirectStacksPayload } from \"../../types.js\";\nimport { SCHEME_EXACT_DIRECT, STACKS_CAIP2_NAMESPACE } from \"../../constants.js\";\nimport { getContractAddress } from \"../../tokens.js\";\nimport { isValidPrincipal } from \"../../utils.js\";\n\n/**\n * Configuration for the exact-direct client\n */\nexport interface ExactDirectStacksClientConfig {\n  /** Signer for executing transactions */\n  signer: ClientStacksSigner;\n}\n\n/**\n * Exact-direct client scheme for Stacks\n */\nexport class ExactDirectStacksClient implements SchemeNetworkClient {\n  readonly scheme = SCHEME_EXACT_DIRECT;\n  private readonly signer: ClientStacksSigner;\n\n  constructor(config: ExactDirectStacksClientConfig) {\n    this.signer = config.signer;\n  }\n\n  /**\n   * Create a payment payload by executing the transfer\n   */\n  async createPaymentPayload(\n    t402Version: number,\n    requirements: PaymentRequirements,\n  ): Promise<Pick<PaymentPayload, \"t402Version\" | \"payload\">> {\n    // Validate requirements\n    this.validateRequirements(requirements);\n\n    const { network, amount, payTo, extra } = requirements;\n\n    // Get contract address from extra or use default sUSDC\n    const symbol = (extra?.assetSymbol as string) || \"sUSDC\";\n    const contractAddress =\n      (extra?.contractAddress as string) ?? getContractAddress(network, symbol);\n\n    if (!contractAddress) {\n      throw new Error(`Unknown asset ${symbol} on network ${network}`);\n    }\n\n    // Get sender address\n    const from = await this.signer.getAddress();\n\n    // Execute the transfer\n    const { txId } = await this.signer.transferToken(contractAddress, payTo, amount);\n\n    // Build the payload\n    const stacksPayload: ExactDirectStacksPayload = {\n      txId,\n      from,\n      to: payTo,\n      amount,\n      contractAddress,\n    };\n\n    return {\n      t402Version,\n      payload: stacksPayload,\n    };\n  }\n\n  /**\n   * Validate payment requirements\n   */\n  private validateRequirements(requirements: PaymentRequirements): void {\n    // Check scheme\n    if (requirements.scheme !== SCHEME_EXACT_DIRECT) {\n      throw new Error(\n        `Invalid scheme: expected ${SCHEME_EXACT_DIRECT}, got ${requirements.scheme}`,\n      );\n    }\n\n    // Check network\n    if (!requirements.network.startsWith(`${STACKS_CAIP2_NAMESPACE}:`)) {\n      throw new Error(`Invalid network: ${requirements.network}`);\n    }\n\n    // Check payTo address\n    if (!isValidPrincipal(requirements.payTo)) {\n      throw new Error(`Invalid payTo address: ${requirements.payTo}`);\n    }\n\n    // Check amount\n    const amount = BigInt(requirements.amount);\n    if (amount <= 0n) {\n      throw new Error(`Invalid amount: ${requirements.amount}`);\n    }\n  }\n}\n\n/**\n * Create an exact-direct client for Stacks\n */\nexport function createExactDirectStacksClient(\n  config: ExactDirectStacksClientConfig,\n): ExactDirectStacksClient {\n  return new ExactDirectStacksClient(config);\n}\n"],"mappings":"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","names":[]}