@t402/aptos 2.3.0

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

@@ -0,0 +1,196 @@
+/**
+ * Aptos Exact-Direct Server Scheme
+ *
+ * Handles price parsing and payment requirement enhancement for
+ * Aptos FA payments using the exact-direct scheme.
+ */
+
+import type {
+  SchemeNetworkServer,
+  PaymentRequirements,
+  Price,
+  AssetAmount,
+  Network,
+  MoneyParser,
+} from "@t402/core/types";
+import { SCHEME_EXACT_DIRECT } from "../../constants.js";
+import { getTokenConfig, getDefaultToken, TOKEN_REGISTRY } from "../../tokens.js";
+import {
+  isAptosNetwork,
+  createAssetIdentifier,
+  parseAmount,
+} from "../../utils.js";
+
+/**
+ * Configuration for ExactDirectAptosServer
+ */
+export interface ExactDirectAptosServerConfig {
+  /** Preferred token symbol (e.g., "USDT"). Defaults to network's default token. */
+  preferredToken?: string;
+}
+
+/**
+ * Aptos Exact-Direct Server
+ *
+ * Implements the server-side price parsing and payment requirements enhancement.
+ */
+export class ExactDirectAptosServer implements SchemeNetworkServer {
+  readonly scheme = SCHEME_EXACT_DIRECT;
+  private moneyParsers: MoneyParser[] = [];
+  private config: ExactDirectAptosServerConfig;
+
+  constructor(config: ExactDirectAptosServerConfig = {}) {
+    this.config = config;
+  }
+
+  /**
+   * Register a custom money parser in the parser chain.
+   */
+  registerMoneyParser(parser: MoneyParser): ExactDirectAptosServer {
+    this.moneyParsers.push(parser);
+    return this;
+  }
+
+  /**
+   * Parse price into Aptos-specific amount
+   */
+  async parsePrice(price: Price, network: Network): Promise<AssetAmount> {
+    // Validate network
+    if (!isAptosNetwork(network)) {
+      throw new Error(`Invalid Aptos 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 address 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 Aptos-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?.assetSymbol) {
+      extra.assetSymbol = supportedKind.extra.assetSymbol;
+    }
+    if (supportedKind.extra?.assetDecimals) {
+      extra.assetDecimals = supportedKind.extra.assetDecimals;
+    }
+
+    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: createAssetIdentifier(network, token.metadataAddress),
+      extra: {
+        symbol: token.symbol,
+        name: token.name,
+        decimals: token.decimals,
+      },
+    };
+  }
+
+  /**
+   * Get the default asset info for a network.
+   */
+  private getDefaultAsset(
+    network: Network,
+  ): { metadataAddress: 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;
+  }
+}
+
+export default ExactDirectAptosServer;

package/src/index.ts

@@ -0,0 +1,58 @@
+/**
+ * @t402/aptos - Aptos (Move) mechanism for T402 payment protocol
+ *
+ * This package provides support for Aptos blockchain payments using
+ * the Fungible Asset (FA) standard.
+ *
+ * @example
+ * ```typescript
+ * // Client usage
+ * import { registerExactDirectAptosClient } from "@t402/aptos/exact-direct/client";
+ * import { t402Client } from "@t402/core/client";
+ *
+ * const client = new t402Client();
+ * registerExactDirectAptosClient(client, {
+ *   signer: myAptosSigner,
+ *   networks: "aptos:1"
+ * });
+ *
+ * // Server usage
+ * import { registerExactDirectAptosServer } from "@t402/aptos/exact-direct/server";
+ * import { t402ResourceServer } from "@t402/core/server";
+ *
+ * const server = new t402ResourceServer();
+ * registerExactDirectAptosServer(server, {
+ *   networks: "aptos:1",
+ *   schemeConfig: { defaultPayTo: "0x..." }
+ * });
+ *
+ * // Facilitator usage
+ * 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"
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// Constants
+export * from "./constants.js";
+
+// Types
+export * from "./types.js";
+
+// Token registry
+export * from "./tokens.js";
+
+// Utility functions
+export * from "./utils.js";
+
+// Re-export scheme modules for convenience
+export * from "./exact-direct/client/index.js";
+export * from "./exact-direct/server/index.js";
+export * from "./exact-direct/facilitator/index.js";

package/src/tokens.ts

@@ -0,0 +1,114 @@
+/**
+ * Aptos Token Registry
+ *
+ * Token addresses for supported stablecoins on Aptos networks.
+ * All tokens use the Fungible Asset (FA) standard.
+ */
+
+import {
+  APTOS_MAINNET_CAIP2,
+  APTOS_TESTNET_CAIP2,
+  APTOS_DEVNET_CAIP2,
+} from "./constants.js";
+
+/**
+ * Token configuration for Aptos fungible assets
+ */
+export interface TokenConfig {
+  /** Fungible Asset metadata address */
+  metadataAddress: string;
+  /** Token symbol (e.g., "USDT", "USDC") */
+  symbol: string;
+  /** Token name */
+  name: string;
+  /** Decimal places */
+  decimals: number;
+}
+
+/**
+ * Token registry mapping network -> tokens
+ */
+export const TOKEN_REGISTRY: Record<string, TokenConfig[]> = {
+  [APTOS_MAINNET_CAIP2]: [
+    {
+      metadataAddress:
+        "0xf73e887a8754f540ee6e1a93bdc6dde2af69fc7ca5de32013e89dd44244473cb",
+      symbol: "USDT",
+      name: "Tether USD",
+      decimals: 6,
+    },
+    {
+      metadataAddress:
+        "0xbae207659db88bea0cbead6da0ed00aac12edcdda169e591cd41c94180b46f3b",
+      symbol: "USDC",
+      name: "USD Coin",
+      decimals: 6,
+    },
+  ],
+  [APTOS_TESTNET_CAIP2]: [
+    {
+      // Testnet USDT (may differ from mainnet)
+      metadataAddress:
+        "0xf73e887a8754f540ee6e1a93bdc6dde2af69fc7ca5de32013e89dd44244473cb",
+      symbol: "USDT",
+      name: "Tether USD",
+      decimals: 6,
+    },
+  ],
+  [APTOS_DEVNET_CAIP2]: [],
+};
+
+/**
+ * Get token configuration for a specific network and symbol
+ */
+export function getTokenConfig(
+  network: string,
+  symbol: string,
+): TokenConfig | undefined {
+  const tokens = TOKEN_REGISTRY[network];
+  if (!tokens) return undefined;
+  return tokens.find(
+    (t) => t.symbol.toUpperCase() === symbol.toUpperCase(),
+  );
+}
+
+/**
+ * Get all supported tokens for a network
+ */
+export function getSupportedTokens(network: string): TokenConfig[] {
+  return TOKEN_REGISTRY[network] || [];
+}
+
+/**
+ * Check if a token is supported on a network
+ */
+export function isTokenSupported(network: string, symbol: string): boolean {
+  return getTokenConfig(network, symbol) !== undefined;
+}
+
+/**
+ * Get token by metadata address
+ */
+export function getTokenByAddress(
+  network: string,
+  metadataAddress: string,
+): TokenConfig | undefined {
+  const tokens = TOKEN_REGISTRY[network];
+  if (!tokens) return undefined;
+  const normalizedAddress = metadataAddress.toLowerCase();
+  return tokens.find(
+    (t) => t.metadataAddress.toLowerCase() === normalizedAddress,
+  );
+}
+
+/**
+ * Default token symbol for payments (USDT)
+ */
+export const DEFAULT_TOKEN_SYMBOL = "USDT";
+
+/**
+ * Get the default token for a network
+ */
+export function getDefaultToken(network: string): TokenConfig | undefined {
+  return getTokenConfig(network, DEFAULT_TOKEN_SYMBOL);
+}

package/src/types.ts

@@ -0,0 +1,174 @@
+/**
+ * Aptos Types for T402 Payment Protocol
+ */
+
+import type { Network } from "@t402/core/types";
+
+/**
+ * Exact-direct payment payload for Aptos
+ * Client executes the transfer and provides transaction hash as proof
+ */
+export type ExactDirectAptosPayload = {
+  /** Transaction hash (hex string with 0x prefix) */
+  txHash: string;
+  /** Sender's Aptos address */
+  from: string;
+  /** Recipient's Aptos address */
+  to: string;
+  /** Amount transferred (in smallest unit) */
+  amount: string;
+  /** Fungible Asset metadata address */
+  metadataAddress: string;
+  /** Transaction version (for verification) */
+  version?: string;
+};
+
+/**
+ * Aptos signer interface for client operations
+ */
+export interface ClientAptosSigner {
+  /**
+   * Get the signer's Aptos address
+   */
+  getAddress(): Promise<string>;
+
+  /**
+   * Sign and submit a fungible asset transfer transaction
+   * @param to Recipient address
+   * @param metadataAddress FA metadata address
+   * @param amount Amount to transfer
+   * @returns Transaction hash
+   */
+  transfer(
+    to: string,
+    metadataAddress: string,
+    amount: bigint,
+  ): Promise<string>;
+
+  /**
+   * Get token balance for an address
+   * @param metadataAddress FA metadata address
+   * @returns Balance in smallest unit
+   */
+  getBalance(metadataAddress: string): Promise<bigint>;
+}
+
+/**
+ * Aptos signer interface for facilitator operations
+ */
+export interface FacilitatorAptosSigner {
+  /**
+   * Get facilitator addresses for a network
+   * @param network CAIP-2 network identifier
+   */
+  getAddresses(network: Network): string[];
+
+  /**
+   * Query transaction by hash
+   * @param txHash Transaction hash
+   * @returns Transaction details or null if not found
+   */
+  queryTransaction(txHash: string): Promise<AptosTransactionResult | null>;
+
+  /**
+   * Get token balance for an address
+   * @param address Account address
+   * @param metadataAddress FA metadata address
+   * @returns Balance in smallest unit
+   */
+  getBalance(address: string, metadataAddress: string): Promise<bigint>;
+}
+
+/**
+ * Aptos transaction result from RPC
+ */
+export interface AptosTransactionResult {
+  /** Transaction hash */
+  hash: string;
+  /** Transaction version */
+  version: string;
+  /** Whether the transaction was successful */
+  success: boolean;
+  /** VM status */
+  vmStatus: string;
+  /** Sender address */
+  sender: string;
+  /** Sequence number */
+  sequenceNumber: string;
+  /** Gas used */
+  gasUsed: string;
+  /** Timestamp (microseconds) */
+  timestamp: string;
+  /** Transaction payload */
+  payload?: AptosTransactionPayload;
+  /** Events emitted by the transaction */
+  events?: AptosTransactionEvent[];
+  /** State changes */
+  changes?: AptosStateChange[];
+}
+
+/**
+ * Aptos transaction payload
+ */
+export interface AptosTransactionPayload {
+  type: string;
+  function?: string;
+  typeArguments?: string[];
+  arguments?: unknown[];
+}
+
+/**
+ * Aptos transaction event
+ */
+export interface AptosTransactionEvent {
+  guid: {
+    creationNumber: string;
+    accountAddress: string;
+  };
+  sequenceNumber: string;
+  type: string;
+  data: Record<string, unknown>;
+}
+
+/**
+ * Aptos state change
+ */
+export interface AptosStateChange {
+  type: string;
+  address: string;
+  stateKeyHash: string;
+  data?: {
+    type: string;
+    data: Record<string, unknown>;
+  };
+}
+
+/**
+ * Parsed fungible asset transfer from events
+ */
+export interface ParsedFATransfer {
+  /** Sender address */
+  from: string;
+  /** Recipient address */
+  to: string;
+  /** Amount transferred */
+  amount: bigint;
+  /** FA metadata address */
+  metadataAddress: string;
+}
+
+/**
+ * Extract Aptos chain ID from CAIP-2 network identifier
+ */
+export function extractChainId(network: Network): number {
+  const parts = network.split(":");
+  if (parts.length !== 2 || parts[0] !== "aptos") {
+    throw new Error(`Invalid Aptos network identifier: ${network}`);
+  }
+  const chainId = parseInt(parts[1], 10);
+  if (isNaN(chainId)) {
+    throw new Error(`Invalid chain ID in network identifier: ${network}`);
+  }
+  return chainId;
+}
+