@t402/aptos 2.3.0

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

@@ -0,0 +1,148 @@
+/**
+ * Aptos Exact-Direct Client Scheme
+ *
+ * The client executes the FA transfer directly and provides
+ * the transaction hash as proof of payment.
+ */
+
+import type {
+  SchemeNetworkClient,
+  PaymentPayload,
+  PaymentRequirements,
+} from "@t402/core/types";
+import { SCHEME_EXACT_DIRECT, APTOS_CAIP2_NAMESPACE } from "../../constants.js";
+import type { ClientAptosSigner, ExactDirectAptosPayload } from "../../types.js";
+import { getTokenConfig } from "../../tokens.js";
+import {
+  isValidAptosAddress,
+  parseAssetIdentifier,
+  compareAddresses,
+} from "../../utils.js";
+
+/**
+ * Configuration for ExactDirectAptosClient
+ */
+export interface ExactDirectAptosClientConfig {
+  /**
+   * Whether to verify the transfer was successful before returning
+   * @default true
+   */
+  verifyTransfer?: boolean;
+}
+
+/**
+ * Aptos Exact-Direct Client
+ *
+ * Implements the client-side payment flow where the client:
+ * 1. Receives payment requirements
+ * 2. Executes the FA transfer transaction
+ * 3. Returns transaction hash as proof
+ */
+export class ExactDirectAptosClient implements SchemeNetworkClient {
+  readonly scheme = SCHEME_EXACT_DIRECT;
+
+  constructor(
+    private readonly signer: ClientAptosSigner,
+    config: ExactDirectAptosClientConfig = {},
+  ) {
+    // Config reserved for future use (e.g., verifyTransfer option)
+    void config;
+  }
+
+  /**
+   * Create a payment payload by executing the transfer
+   */
+  async createPaymentPayload(
+    t402Version: number,
+    paymentRequirements: PaymentRequirements,
+  ): Promise<Pick<PaymentPayload, "t402Version" | "payload">> {
+    // Validate requirements
+    this.validateRequirements(paymentRequirements);
+
+    // Get sender address
+    const from = await this.signer.getAddress();
+
+    // Parse asset to get metadata address
+    const assetInfo = parseAssetIdentifier(paymentRequirements.asset);
+    if (!assetInfo) {
+      throw new Error(`Invalid asset identifier: ${paymentRequirements.asset}`);
+    }
+
+    // Get amount
+    const amount = BigInt(paymentRequirements.amount);
+
+    // Check balance
+    const balance = await this.signer.getBalance(assetInfo.metadataAddress);
+    if (balance < amount) {
+      throw new Error(
+        `Insufficient balance: have ${balance}, need ${amount}`,
+      );
+    }
+
+    // Execute transfer
+    const txHash = await this.signer.transfer(
+      paymentRequirements.payTo,
+      assetInfo.metadataAddress,
+      amount,
+    );
+
+    // Create payload
+    const payload: ExactDirectAptosPayload = {
+      txHash,
+      from,
+      to: paymentRequirements.payTo,
+      amount: paymentRequirements.amount,
+      metadataAddress: assetInfo.metadataAddress,
+    };
+
+    return {
+      t402Version,
+      payload,
+    };
+  }
+
+  /**
+   * 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(`${APTOS_CAIP2_NAMESPACE}:`)) {
+      throw new Error(`Invalid network: ${requirements.network}`);
+    }
+
+    // Check payTo address
+    if (!isValidAptosAddress(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}`);
+    }
+
+    // Check asset
+    const assetInfo = parseAssetIdentifier(requirements.asset);
+    if (!assetInfo) {
+      throw new Error(`Invalid asset: ${requirements.asset}`);
+    }
+
+    // Verify token is supported
+    const tokenConfig = getTokenConfig(requirements.network, "USDT");
+    if (tokenConfig && !compareAddresses(tokenConfig.metadataAddress, assetInfo.metadataAddress)) {
+      // Allow any valid FA, but log warning for unknown tokens
+      console.warn(
+        `Using non-standard token: ${assetInfo.metadataAddress}`,
+      );
+    }
+  }
+}
+
+export default ExactDirectAptosClient;

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

@@ -0,0 +1,12 @@
+/**
+ * Aptos Exact-Direct Facilitator Exports
+ */
+
+export {
+  ExactDirectAptosFacilitator,
+  type ExactDirectAptosFacilitatorConfig,
+} from "./scheme.js";
+export {
+  registerExactDirectAptosFacilitator,
+  type AptosFacilitatorConfig,
+} from "./register.js";

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

@@ -0,0 +1,74 @@
+/**
+ * Registration function for Aptos Exact-Direct facilitator
+ */
+
+import { t402Facilitator } from "@t402/core/facilitator";
+import type { Network } from "@t402/core/types";
+import type { FacilitatorAptosSigner } from "../../types.js";
+import {
+  ExactDirectAptosFacilitator,
+  type ExactDirectAptosFacilitatorConfig,
+} from "./scheme.js";
+
+/**
+ * Configuration options for registering Aptos schemes to a t402Facilitator
+ */
+export interface AptosFacilitatorConfig {
+  /**
+   * The Aptos signer for facilitator operations (verify and settle)
+   */
+  signer: FacilitatorAptosSigner;
+
+  /**
+   * Optional specific networks to register
+   * If not provided, registers wildcard support (aptos:*)
+   */
+  networks?: Network[];
+
+  /**
+   * Optional scheme configuration
+   */
+  schemeConfig?: ExactDirectAptosFacilitatorConfig;
+}
+
+/**
+ * Registers Aptos exact-direct payment schemes to a t402Facilitator instance.
+ *
+ * @param facilitator - The t402Facilitator instance to register schemes to
+ * @param config - Configuration for Aptos facilitator registration
+ * @returns The facilitator instance for chaining
+ *
+ * @example
+ * ```typescript
+ * import { registerExactDirectAptosFacilitator } from "@t402/aptos/exact-direct/facilitator";
+ * import { t402Facilitator } from "@t402/core/facilitator";
+ *
+ * const facilitator = new t402Facilitator();
+ * registerExactDirectAptosFacilitator(facilitator, {
+ *   signer: myAptosSigner,
+ *   networks: ["aptos:1"]
+ * });
+ * ```
+ */
+export function registerExactDirectAptosFacilitator(
+  facilitator: t402Facilitator,
+  config: AptosFacilitatorConfig,
+): t402Facilitator {
+  const scheme = new ExactDirectAptosFacilitator(
+    config.signer,
+    config.schemeConfig,
+  );
+
+  // Register scheme
+  if (config.networks && config.networks.length > 0) {
+    // Register specific networks
+    config.networks.forEach((network) => {
+      facilitator.register(network, scheme);
+    });
+  } else {
+    // Register wildcard for all Aptos networks
+    facilitator.register("aptos:*", scheme);
+  }
+
+  return facilitator;
+}

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

@@ -0,0 +1,300 @@
+/**
+ * Aptos Exact-Direct Facilitator Scheme
+ *
+ * Verifies FA transfer transactions and manages replay protection.
+ */
+
+import type {
+  SchemeNetworkFacilitator,
+  PaymentPayload,
+  PaymentRequirements,
+  VerifyResponse,
+  SettleResponse,
+  Network,
+} from "@t402/core/types";
+import { SCHEME_EXACT_DIRECT, APTOS_CAIP2_NAMESPACE } from "../../constants.js";
+import type {
+  FacilitatorAptosSigner,
+  ExactDirectAptosPayload,
+} from "../../types.js";
+import {
+  isValidTxHash,
+  compareAddresses,
+  parseAssetIdentifier,
+  extractTransferDetails,
+  isAptosNetwork,
+} from "../../utils.js";
+import { getDefaultToken } from "../../tokens.js";
+
+/**
+ * Configuration for ExactDirectAptosFacilitator
+ */
+export interface ExactDirectAptosFacilitatorConfig {
+  /**
+   * Maximum age of transaction in seconds (default: 3600 = 1 hour)
+   */
+  maxTransactionAge?: number;
+
+  /**
+   * Duration to cache used transaction hashes (in milliseconds)
+   */
+  usedTxCacheDuration?: number;
+}
+
+/**
+ * Aptos Exact-Direct Facilitator
+ *
+ * Implements the facilitator-side verification and settlement.
+ * For exact-direct, settlement is a no-op since client already executed.
+ */
+export class ExactDirectAptosFacilitator implements SchemeNetworkFacilitator {
+  readonly scheme = SCHEME_EXACT_DIRECT;
+  readonly caipFamily = `${APTOS_CAIP2_NAMESPACE}:*`;
+
+  private readonly config: Required<ExactDirectAptosFacilitatorConfig>;
+  private usedTxs: Map<string, number> = new Map();
+
+  constructor(
+    private readonly signer: FacilitatorAptosSigner,
+    config?: ExactDirectAptosFacilitatorConfig,
+  ) {
+    this.config = {
+      maxTransactionAge: config?.maxTransactionAge ?? 3600,
+      usedTxCacheDuration: config?.usedTxCacheDuration ?? 24 * 60 * 60 * 1000, // 24 hours
+    };
+
+    // Start cleanup interval
+    this.startCleanupInterval();
+  }
+
+  /**
+   * Get extra data for a supported kind
+   */
+  getExtra(network: Network): Record<string, unknown> | undefined {
+    const token = getDefaultToken(network);
+    if (!token) {
+      return undefined;
+    }
+    return {
+      assetSymbol: token.symbol,
+      assetDecimals: token.decimals,
+    };
+  }
+
+  /**
+   * 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> {
+    // Validate scheme
+    if (payload.accepted.scheme !== SCHEME_EXACT_DIRECT) {
+      return {
+        isValid: false,
+        invalidReason: "invalid_scheme",
+      };
+    }
+
+    // Validate network
+    if (!isAptosNetwork(payload.accepted.network)) {
+      return {
+        isValid: false,
+        invalidReason: "invalid_network",
+      };
+    }
+
+    // Extract Aptos-specific payload
+    const aptosPayload = payload.payload as ExactDirectAptosPayload;
+
+    // Validate transaction hash format
+    if (!isValidTxHash(aptosPayload.txHash)) {
+      return {
+        isValid: false,
+        invalidReason: "invalid_tx_hash_format",
+      };
+    }
+
+    // Check for replay attack
+    if (this.isTxUsed(aptosPayload.txHash)) {
+      return {
+        isValid: false,
+        invalidReason: "transaction_already_used",
+        payer: aptosPayload.from,
+      };
+    }
+
+    try {
+      // Query transaction
+      const tx = await this.signer.queryTransaction(aptosPayload.txHash);
+      if (!tx) {
+        return {
+          isValid: false,
+          invalidReason: "transaction_not_found",
+          payer: aptosPayload.from,
+        };
+      }
+
+      // Verify transaction was successful
+      if (!tx.success) {
+        return {
+          isValid: false,
+          invalidReason: `transaction_failed: ${tx.vmStatus}`,
+          payer: aptosPayload.from,
+        };
+      }
+
+      // Check transaction age
+      if (this.config.maxTransactionAge > 0) {
+        const txTimestamp = parseInt(tx.timestamp, 10) / 1000000; // Convert from microseconds
+        const now = Date.now() / 1000;
+        const age = now - txTimestamp;
+        if (age > this.config.maxTransactionAge) {
+          return {
+            isValid: false,
+            invalidReason: `transaction_too_old: ${Math.round(age)} seconds`,
+            payer: aptosPayload.from,
+          };
+        }
+      }
+
+      // Extract transfer details from transaction
+      const transferDetails = extractTransferDetails(tx);
+      if (!transferDetails) {
+        return {
+          isValid: false,
+          invalidReason: "could_not_extract_transfer_details",
+          payer: aptosPayload.from,
+        };
+      }
+
+      // Parse expected asset
+      const expectedAsset = parseAssetIdentifier(requirements.asset);
+      if (!expectedAsset) {
+        return {
+          isValid: false,
+          invalidReason: `invalid_asset_in_requirements: ${requirements.asset}`,
+          payer: aptosPayload.from,
+        };
+      }
+
+      // Verify recipient
+      if (!compareAddresses(transferDetails.to, requirements.payTo)) {
+        return {
+          isValid: false,
+          invalidReason: `recipient_mismatch: expected ${requirements.payTo}, got ${transferDetails.to}`,
+          payer: aptosPayload.from,
+        };
+      }
+
+      // Verify metadata address (token)
+      if (
+        !compareAddresses(
+          transferDetails.metadataAddress,
+          expectedAsset.metadataAddress,
+        )
+      ) {
+        return {
+          isValid: false,
+          invalidReason: `token_mismatch: expected ${expectedAsset.metadataAddress}, got ${transferDetails.metadataAddress}`,
+          payer: aptosPayload.from,
+        };
+      }
+
+      // Verify amount
+      const expectedAmount = BigInt(requirements.amount);
+      if (transferDetails.amount < expectedAmount) {
+        return {
+          isValid: false,
+          invalidReason: `insufficient_amount: expected ${expectedAmount}, got ${transferDetails.amount}`,
+          payer: aptosPayload.from,
+        };
+      }
+
+      // Mark transaction as used
+      this.markTxUsed(aptosPayload.txHash);
+
+      return {
+        isValid: true,
+        payer: transferDetails.from,
+      };
+    } catch (error) {
+      return {
+        isValid: false,
+        invalidReason: `verification_error: ${error instanceof Error ? error.message : String(error)}`,
+        payer: aptosPayload.from,
+      };
+    }
+  }
+
+  /**
+   * Settle a payment (no-op for exact-direct since client already executed)
+   */
+  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 aptosPayload = payload.payload as ExactDirectAptosPayload;
+
+    // For exact-direct, settlement is already complete
+    return {
+      success: true,
+      transaction: aptosPayload.txHash,
+      network: requirements.network,
+      payer: aptosPayload.from,
+    };
+  }
+
+  /**
+   * Check if a transaction has been used
+   */
+  private isTxUsed(txHash: string): boolean {
+    return this.usedTxs.has(txHash.toLowerCase());
+  }
+
+  /**
+   * Mark a transaction as used
+   */
+  private markTxUsed(txHash: string): void {
+    this.usedTxs.set(txHash.toLowerCase(), Date.now());
+  }
+
+  /**
+   * Start the cleanup interval for used transactions
+   */
+  private startCleanupInterval(): void {
+    setInterval(
+      () => {
+        const cutoff = Date.now() - this.config.usedTxCacheDuration;
+        for (const [txHash, usedAt] of this.usedTxs.entries()) {
+          if (usedAt < cutoff) {
+            this.usedTxs.delete(txHash);
+          }
+        }
+      },
+      60 * 60 * 1000,
+    ); // Cleanup every hour
+  }
+}
+
+export default ExactDirectAptosFacilitator;

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

@@ -0,0 +1,12 @@
+/**
+ * Aptos Exact-Direct Server Exports
+ */
+
+export {
+  ExactDirectAptosServer,
+  type ExactDirectAptosServerConfig,
+} from "./scheme.js";
+export {
+  registerExactDirectAptosServer,
+  type AptosServerConfig,
+} from "./register.js";

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

@@ -0,0 +1,65 @@
+/**
+ * Registration function for Aptos Exact-Direct server
+ */
+
+import { t402ResourceServer } from "@t402/core/server";
+import type { Network } from "@t402/core/types";
+import {
+  ExactDirectAptosServer,
+  type ExactDirectAptosServerConfig,
+} from "./scheme.js";
+
+/**
+ * Configuration options for registering Aptos schemes to a t402ResourceServer
+ */
+export interface AptosServerConfig {
+  /**
+   * Optional specific networks to register
+   * If not provided, registers wildcard support (aptos:*)
+   */
+  networks?: Network[];
+
+  /**
+   * Optional scheme configuration
+   */
+  schemeConfig?: ExactDirectAptosServerConfig;
+}
+
+/**
+ * Registers Aptos exact-direct payment schemes to a t402ResourceServer instance.
+ *
+ * @param server - The t402ResourceServer instance to register schemes to
+ * @param config - Configuration for Aptos server registration
+ * @returns The server instance for chaining
+ *
+ * @example
+ * ```typescript
+ * import { registerExactDirectAptosServer } from "@t402/aptos/exact-direct/server";
+ * import { t402ResourceServer } from "@t402/core/server";
+ *
+ * const server = new t402ResourceServer();
+ * registerExactDirectAptosServer(server, {
+ *   networks: ["aptos:1"],
+ *   schemeConfig: { preferredToken: "USDT" }
+ * });
+ * ```
+ */
+export function registerExactDirectAptosServer(
+  server: t402ResourceServer,
+  config: AptosServerConfig = {},
+): t402ResourceServer {
+  const scheme = new ExactDirectAptosServer(config.schemeConfig);
+
+  // 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 Aptos networks
+    server.register("aptos:*", scheme);
+  }
+
+  return server;
+}