@t402/stacks 2.4.0

package/src/constants.ts

@@ -0,0 +1,66 @@
+/**
+ * Stacks T402 Constants
+ *
+ * Stacks is a Bitcoin Layer 2 that brings smart contracts and DeFi
+ * to Bitcoin. SIP-010 is the fungible token standard on Stacks.
+ */
+
+// CAIP-2 namespace for Stacks
+export const STACKS_CAIP2_NAMESPACE = "stacks";
+
+// CAIP-2 network identifiers
+// Stacks Mainnet (chain ID: 1)
+export const STACKS_MAINNET_CAIP2 = "stacks:1";
+
+// Stacks Testnet (chain ID: 2147483648)
+export const STACKS_TESTNET_CAIP2 = "stacks:2147483648";
+
+// Scheme identifier
+export const SCHEME_EXACT_DIRECT = "exact-direct";
+
+// Default API endpoints (Hiro API)
+export const DEFAULT_MAINNET_API = "https://api.mainnet.hiro.so";
+export const DEFAULT_TESTNET_API = "https://api.testnet.hiro.so";
+
+// Network configurations
+export interface StacksNetworkConfig {
+  readonly name: string;
+  readonly caip2: string;
+  readonly apiUrl: string;
+  readonly chainId: number;
+  readonly addressPrefix: string;
+  readonly isTestnet: boolean;
+}
+
+export const STACKS_NETWORKS: Record<string, StacksNetworkConfig> = {
+  [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,
+  },
+};
+
+/**
+ * Get network configuration by CAIP-2 identifier
+ */
+export function getNetworkConfig(network: string): StacksNetworkConfig | undefined {
+  return STACKS_NETWORKS[network];
+}
+
+/**
+ * Check if a network identifier is a Stacks network
+ */
+export function isStacksNetwork(network: string): boolean {
+  return network.startsWith(`${STACKS_CAIP2_NAMESPACE}:`);
+}

package/src/exact-direct/client/index.ts

@@ -0,0 +1,5 @@
+export {
+  ExactDirectStacksClient,
+  createExactDirectStacksClient,
+  type ExactDirectStacksClientConfig,
+} from "./scheme.js";

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

@@ -0,0 +1,115 @@
+/**
+ * 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.
+ */
+
+import type {
+  PaymentPayload,
+  PaymentRequirements,
+  SchemeNetworkClient,
+} from "@t402/core/types";
+import type { ClientStacksSigner, ExactDirectStacksPayload } from "../../types.js";
+import { SCHEME_EXACT_DIRECT, STACKS_CAIP2_NAMESPACE } from "../../constants.js";
+import { getContractAddress } from "../../tokens.js";
+import { isValidPrincipal } from "../../utils.js";
+
+/**
+ * Configuration for the exact-direct client
+ */
+export interface ExactDirectStacksClientConfig {
+  /** Signer for executing transactions */
+  signer: ClientStacksSigner;
+}
+
+/**
+ * Exact-direct client scheme for Stacks
+ */
+export class ExactDirectStacksClient implements SchemeNetworkClient {
+  readonly scheme = SCHEME_EXACT_DIRECT;
+  private readonly signer: ClientStacksSigner;
+
+  constructor(config: ExactDirectStacksClientConfig) {
+    this.signer = config.signer;
+  }
+
+  /**
+   * Create a payment payload by executing the transfer
+   */
+  async createPaymentPayload(
+    t402Version: number,
+    requirements: PaymentRequirements,
+  ): Promise<Pick<PaymentPayload, "t402Version" | "payload">> {
+    // Validate requirements
+    this.validateRequirements(requirements);
+
+    const { network, amount, payTo, extra } = requirements;
+
+    // Get contract address from extra or use default sUSDC
+    const symbol = (extra?.assetSymbol as string) || "sUSDC";
+    const contractAddress =
+      (extra?.contractAddress as string) ?? getContractAddress(network, symbol);
+
+    if (!contractAddress) {
+      throw new Error(`Unknown asset ${symbol} on network ${network}`);
+    }
+
+    // Get sender address
+    const from = await this.signer.getAddress();
+
+    // Execute the transfer
+    const { txId } = await this.signer.transferToken(contractAddress, payTo, amount);
+
+    // Build the payload
+    const stacksPayload: ExactDirectStacksPayload = {
+      txId,
+      from,
+      to: payTo,
+      amount,
+      contractAddress,
+    };
+
+    return {
+      t402Version,
+      payload: stacksPayload,
+    };
+  }
+
+  /**
+   * Validate payment requirements
+   */
+  private validateRequirements(requirements: PaymentRequirements): void {
+    // Check scheme
+    if (requirements.scheme !== SCHEME_EXACT_DIRECT) {
+      throw new Error(
+        `Invalid scheme: expected ${SCHEME_EXACT_DIRECT}, got ${requirements.scheme}`,
+      );
+    }
+
+    // Check network
+    if (!requirements.network.startsWith(`${STACKS_CAIP2_NAMESPACE}:`)) {
+      throw new Error(`Invalid network: ${requirements.network}`);
+    }
+
+    // Check payTo address
+    if (!isValidPrincipal(requirements.payTo)) {
+      throw new Error(`Invalid payTo address: ${requirements.payTo}`);
+    }
+
+    // Check amount
+    const amount = BigInt(requirements.amount);
+    if (amount <= 0n) {
+      throw new Error(`Invalid amount: ${requirements.amount}`);
+    }
+  }
+}
+
+/**
+ * Create an exact-direct client for Stacks
+ */
+export function createExactDirectStacksClient(
+  config: ExactDirectStacksClientConfig,
+): ExactDirectStacksClient {
+  return new ExactDirectStacksClient(config);
+}

package/src/exact-direct/facilitator/index.ts

@@ -0,0 +1,4 @@
+export {
+  ExactDirectStacksFacilitator,
+  createExactDirectStacksFacilitator,
+} from "./scheme.js";

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

@@ -0,0 +1,308 @@
+/**
+ * Stacks Exact-Direct Facilitator Scheme
+ *
+ * Verifies that a Stacks SIP-010 token transfer was executed correctly
+ * by querying the Hiro API.
+ */
+
+import type {
+  Network,
+  PaymentPayload,
+  PaymentRequirements,
+  SchemeNetworkFacilitator,
+  SettleResponse,
+  VerifyResponse,
+} from "@t402/core/types";
+import { STACKS_CAIP2_NAMESPACE, SCHEME_EXACT_DIRECT, getNetworkConfig } from "../../constants.js";
+import { getDefaultToken } from "../../tokens.js";
+import type {
+  ExactDirectStacksPayload,
+  FacilitatorStacksSigner,
+  StacksFacilitatorConfig,
+} from "../../types.js";
+import {
+  comparePrincipals,
+  extractTokenTransfer,
+  extractTokenTransferFromPostConditions,
+  isValidTxId,
+  isValidPrincipal,
+} from "../../utils.js";
+
+// Default configuration
+const DEFAULT_MAX_TRANSACTION_AGE = 3600; // 1 hour
+const DEFAULT_CACHE_DURATION = 24 * 60 * 60 * 1000; // 24 hours in ms
+
+/**
+ * Exact-direct facilitator scheme for Stacks
+ */
+export class ExactDirectStacksFacilitator implements SchemeNetworkFacilitator {
+  readonly scheme = SCHEME_EXACT_DIRECT;
+  readonly caipFamily = `${STACKS_CAIP2_NAMESPACE}:*`;
+
+  private readonly signer: FacilitatorStacksSigner;
+  private readonly config: Required<StacksFacilitatorConfig>;
+  private readonly usedTransactions = new Map<string, number>();
+
+  constructor(
+    signer: FacilitatorStacksSigner,
+    config: StacksFacilitatorConfig = {},
+  ) {
+    this.signer = signer;
+    this.config = {
+      maxTransactionAge: config.maxTransactionAge ?? DEFAULT_MAX_TRANSACTION_AGE,
+      usedTxCacheDuration:
+        config.usedTxCacheDuration ?? DEFAULT_CACHE_DURATION,
+    };
+
+    // Start cleanup interval
+    this.startCleanupInterval();
+  }
+
+  /**
+   * Get extra data for payment requirements
+   */
+  getExtra(network: Network): Record<string, unknown> | undefined {
+    const config = getNetworkConfig(network);
+    if (!config) return undefined;
+
+    const token = getDefaultToken(network);
+    return {
+      contractAddress: token?.contractAddress,
+      assetSymbol: token?.symbol,
+      assetDecimals: token?.decimals,
+      networkName: config.name,
+    };
+  }
+
+  /**
+   * Get facilitator signer addresses for a network
+   */
+  getSigners(network: Network): string[] {
+    return this.signer.getAddresses(network);
+  }
+
+  /**
+   * Verify a payment payload
+   */
+  async verify(
+    payload: PaymentPayload,
+    requirements: PaymentRequirements,
+  ): Promise<VerifyResponse> {
+    const network = requirements.network;
+
+    // Validate scheme
+    if (payload.accepted.scheme !== SCHEME_EXACT_DIRECT) {
+      return {
+        isValid: false,
+        invalidReason: `invalid_scheme: expected ${SCHEME_EXACT_DIRECT}, got ${payload.accepted.scheme}`,
+      };
+    }
+
+    // Validate network
+    if (payload.accepted.network !== network) {
+      return {
+        isValid: false,
+        invalidReason: `network_mismatch: expected ${network}, got ${payload.accepted.network}`,
+      };
+    }
+
+    // Parse payload
+    const stacksPayload = payload.payload as unknown as ExactDirectStacksPayload;
+
+    // Validate required fields
+    if (!stacksPayload.txId) {
+      return {
+        isValid: false,
+        invalidReason: "missing_tx_id",
+      };
+    }
+
+    // Validate tx ID format
+    if (!isValidTxId(stacksPayload.txId)) {
+      return {
+        isValid: false,
+        invalidReason: "invalid_tx_id_format",
+      };
+    }
+
+    // Validate from address
+    if (!stacksPayload.from) {
+      return {
+        isValid: false,
+        invalidReason: "missing_from_address",
+      };
+    }
+
+    if (!isValidPrincipal(stacksPayload.from)) {
+      return {
+        isValid: false,
+        invalidReason: "invalid_from_address",
+        payer: stacksPayload.from,
+      };
+    }
+
+    // Check for replay attack
+    if (this.isTransactionUsed(stacksPayload.txId)) {
+      return {
+        isValid: false,
+        invalidReason: "transaction_already_used",
+        payer: stacksPayload.from,
+      };
+    }
+
+    // Query transaction
+    const txResult = await this.signer.queryTransaction(stacksPayload.txId);
+
+    if (!txResult) {
+      return {
+        isValid: false,
+        invalidReason: "transaction_not_found",
+        payer: stacksPayload.from,
+      };
+    }
+
+    // Verify transaction was successful
+    if (txResult.txStatus !== "success") {
+      return {
+        isValid: false,
+        invalidReason: `transaction_failed: status=${txResult.txStatus}`,
+        payer: stacksPayload.from,
+      };
+    }
+
+    // Check transaction age
+    if (this.config.maxTransactionAge > 0) {
+      const txTime = txResult.burnBlockTime * 1000; // Convert to milliseconds
+      const age = (Date.now() - txTime) / 1000;
+      if (age > this.config.maxTransactionAge) {
+        return {
+          isValid: false,
+          invalidReason: `transaction_too_old: ${Math.round(age)} seconds`,
+          payer: stacksPayload.from,
+        };
+      }
+    }
+
+    // Extract transfer details
+    const expectedContract = (requirements.extra?.contractAddress as string) ??
+      stacksPayload.contractAddress;
+
+    const transfer =
+      extractTokenTransfer(txResult, expectedContract) ||
+      extractTokenTransferFromPostConditions(txResult, expectedContract);
+
+    if (!transfer) {
+      return {
+        isValid: false,
+        invalidReason: "not_token_transfer",
+        payer: stacksPayload.from,
+      };
+    }
+
+    // Verify contract address
+    if (expectedContract && !comparePrincipals(transfer.contractAddress, expectedContract)) {
+      return {
+        isValid: false,
+        invalidReason: `contract_mismatch: expected ${expectedContract}, got ${transfer.contractAddress}`,
+        payer: stacksPayload.from,
+      };
+    }
+
+    // Verify recipient
+    if (!comparePrincipals(transfer.to, requirements.payTo)) {
+      return {
+        isValid: false,
+        invalidReason: `recipient_mismatch: expected ${requirements.payTo}, got ${transfer.to}`,
+        payer: stacksPayload.from,
+      };
+    }
+
+    // Verify amount
+    const txAmount = BigInt(transfer.amount);
+    const requiredAmount = BigInt(requirements.amount);
+    if (txAmount < requiredAmount) {
+      return {
+        isValid: false,
+        invalidReason: `insufficient_amount: expected ${requirements.amount}, got ${transfer.amount}`,
+        payer: stacksPayload.from,
+      };
+    }
+
+    // Mark transaction as used
+    this.markTransactionUsed(stacksPayload.txId);
+
+    return {
+      isValid: true,
+      payer: stacksPayload.from,
+    };
+  }
+
+  /**
+   * Settle a payment (for exact-direct, the transfer is already complete)
+   */
+  async settle(
+    payload: PaymentPayload,
+    requirements: PaymentRequirements,
+  ): Promise<SettleResponse> {
+    // Verify first
+    const verifyResult = await this.verify(payload, requirements);
+
+    if (!verifyResult.isValid) {
+      return {
+        success: false,
+        errorReason: verifyResult.invalidReason || "verification_failed",
+        payer: verifyResult.payer,
+        transaction: "",
+        network: requirements.network,
+      };
+    }
+
+    const stacksPayload = payload.payload as unknown as ExactDirectStacksPayload;
+
+    // For exact-direct, settlement is already complete
+    return {
+      success: true,
+      transaction: stacksPayload.txId,
+      network: requirements.network,
+      payer: verifyResult.payer,
+    };
+  }
+
+  /**
+   * Check if a transaction has been used
+   */
+  private isTransactionUsed(txId: string): boolean {
+    return this.usedTransactions.has(txId);
+  }
+
+  /**
+   * Mark a transaction as used
+   */
+  private markTransactionUsed(txId: string): void {
+    this.usedTransactions.set(txId, Date.now());
+  }
+
+  /**
+   * Start the cleanup interval for used transactions cache
+   */
+  private startCleanupInterval(): void {
+    setInterval(() => {
+      const cutoff = Date.now() - this.config.usedTxCacheDuration;
+      for (const [txId, timestamp] of this.usedTransactions) {
+        if (timestamp < cutoff) {
+          this.usedTransactions.delete(txId);
+        }
+      }
+    }, 60 * 60 * 1000); // Run every hour
+  }
+}
+
+/**
+ * Create an exact-direct facilitator for Stacks
+ */
+export function createExactDirectStacksFacilitator(
+  signer: FacilitatorStacksSigner,
+  config: StacksFacilitatorConfig = {},
+): ExactDirectStacksFacilitator {
+  return new ExactDirectStacksFacilitator(signer, config);
+}

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

@@ -0,0 +1,9 @@
+export {
+  ExactDirectStacksServer,
+  createExactDirectStacksServer,
+} from "./scheme.js";
+
+export {
+  registerExactDirectStacksServer,
+  type StacksServerRegistrationConfig,
+} from "./register.js";

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

@@ -0,0 +1,57 @@
+/**
+ * Registration function for Stacks exact-direct server
+ */
+
+import { t402ResourceServer } from "@t402/core/server";
+import type { Network } from "@t402/core/types";
+import { STACKS_CAIP2_NAMESPACE } from "../../constants.js";
+import { ExactDirectStacksServer, type ExactDirectStacksServerConfig } from "./scheme.js";
+
+/**
+ * Configuration for registering Stacks server schemes
+ */
+export interface StacksServerRegistrationConfig extends ExactDirectStacksServerConfig {
+  /**
+   * Optional specific networks to register
+   * If not provided, registers wildcard support (stacks:*)
+   */
+  networks?: Network[];
+}
+
+/**
+ * Registers Stacks exact-direct payment scheme to a t402ResourceServer instance.
+ *
+ * @param server - The t402ResourceServer instance to register schemes to
+ * @param config - Configuration for Stacks server registration
+ * @returns The server instance for chaining
+ *
+ * @example
+ * ```typescript
+ * import { registerExactDirectStacksServer } from "@t402/stacks/exact-direct/server";
+ * import { t402ResourceServer } from "@t402/core/server";
+ *
+ * const server = new t402ResourceServer();
+ * registerExactDirectStacksServer(server, {
+ *   networks: ["stacks:1"]
+ * });
+ * ```
+ */
+export function registerExactDirectStacksServer(
+  server: t402ResourceServer,
+  config: StacksServerRegistrationConfig = {},
+): t402ResourceServer {
+  const scheme = new ExactDirectStacksServer(config);
+
+  // Register scheme
+  if (config.networks && config.networks.length > 0) {
+    // Register specific networks
+    config.networks.forEach((network) => {
+      server.register(network, scheme);
+    });
+  } else {
+    // Register wildcard for all Stacks networks
+    server.register(`${STACKS_CAIP2_NAMESPACE}:*`, scheme);
+  }
+
+  return server;
+}