@t402/near 2.3.0

package/README.md

@@ -0,0 +1,173 @@
+# @t402/near
+
+NEAR Protocol implementation of the t402 payment protocol using the **exact-direct** payment scheme with NEP-141 fungible token transfers.
+
+## Installation
+
+```bash
+npm install @t402/near
+# or
+pnpm add @t402/near
+```
+
+## Overview
+
+This package provides support for USDT/USDC payments on NEAR Protocol using the exact-direct scheme. The client executes an `ft_transfer` call directly on-chain, then provides the transaction hash as proof of payment.
+
+Three main components:
+
+- **Client** - For applications that make payments (have NEAR wallets)
+- **Facilitator** - For payment processors that verify transactions via RPC
+- **Server** - For resource servers that accept payments and build payment requirements
+
+## Supported Networks
+
+| Network      | CAIP-2 Identifier | USDT Contract            | USDC Contract                                                      | Status     |
+| ------------ | ----------------- | ------------------------ | ------------------------------------------------------------------ | ---------- |
+| NEAR Mainnet | `near:mainnet`    | `usdt.tether-token.near` | `17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1` | Production |
+| NEAR Testnet | `near:testnet`    | -                        | `usdc.fakes.testnet`                                               | Testnet    |
+
+## Package Exports
+
+### Main Package (`@t402/near`)
+
+**Constants:**
+
+- `NEAR_MAINNET_CAIP2` - CAIP-2 identifier for mainnet
+- `NEAR_TESTNET_CAIP2` - CAIP-2 identifier for testnet
+- `NEAR_NETWORKS` - Array of supported networks
+- `NETWORK_RPC_ENDPOINTS` - RPC endpoint mapping
+- `SCHEME_EXACT_DIRECT` - Scheme identifier
+- `DEFAULT_FT_TRANSFER_GAS` - Default gas for transfers (30 TGas)
+
+**Tokens:**
+
+- `TOKEN_REGISTRY` - Token configurations by network
+- `getTokenConfig(network, symbol)` - Get token by symbol
+- `getTokenByContract(network, contractId)` - Get token by contract
+- `getDefaultToken(network)` - Get default token
+- `isNetworkSupported(network)` - Check if network is supported
+
+**Utilities:**
+
+- `isValidAccountId(accountId)` - Validate NEAR account ID
+- `normalizeNetwork(network)` - Normalize to CAIP-2 format
+- `extractNetworkId(network)` - Extract network ID from CAIP-2
+- `getRpcEndpoint(network)` - Get RPC endpoint for network
+- `formatAmount(amount, decimals)` - Format for display
+- `toTokenUnits(amount, decimals)` - Convert to smallest units
+- `parseFtTransferArgs(argsBase64)` - Parse ft_transfer arguments
+- `isTransactionSuccessful(status)` - Check transaction status
+
+### Client (`@t402/near/exact-direct/client`)
+
+```typescript
+import { createExactDirectNearClient } from "@t402/near/exact-direct/client";
+
+const client = createExactDirectNearClient({
+  signer: myNearSigner,
+});
+```
+
+### Server (`@t402/near/exact-direct/server`)
+
+```typescript
+import { registerExactDirectNearServer } from "@t402/near/exact-direct/server";
+
+registerExactDirectNearServer(server);
+```
+
+### Facilitator (`@t402/near/exact-direct/facilitator`)
+
+```typescript
+import { createExactDirectNearFacilitator } from "@t402/near/exact-direct/facilitator";
+
+const facilitator = createExactDirectNearFacilitator(signer);
+```
+
+## Payment Flow
+
+1. **Client** requests protected resource
+2. **Server** responds with 402 + payment requirements (network, amount, payTo)
+3. **Client** calls `ft_transfer` on token contract with 1 yoctoNEAR deposit
+4. **Client** submits transaction hash as payment proof
+5. **Facilitator** queries NEAR RPC to verify the transaction
+6. **Facilitator** confirms payment matches requirements
+
+## Payload Structure
+
+```typescript
+interface ExactDirectNearPayload {
+  txHash: string; // Transaction hash (Base58)
+  from: string; // Sender account ID
+  to: string; // Recipient account ID
+  amount: string; // Amount in smallest units
+}
+```
+
+## Account ID Format
+
+NEAR uses human-readable account IDs:
+
+- 2-64 characters
+- Lowercase alphanumeric, underscores, hyphens
+- Can have subaccounts (e.g., `sub.account.near`)
+
+Examples:
+
+```
+alice.near
+merchant.near
+usdt.tether-token.near
+```
+
+## NEP-141 Token Standard
+
+This package uses the NEP-141 fungible token standard:
+
+- `ft_transfer(receiver_id, amount, memo?)` - Transfer tokens
+- `ft_balance_of(account_id)` - Query balance
+- Requires 1 yoctoNEAR deposit for security
+
+```typescript
+// ft_transfer arguments
+{
+  receiver_id: "merchant.near",
+  amount: "1000000",
+  memo: null
+}
+```
+
+## Gas Configuration
+
+Default gas amounts:
+
+- `ft_transfer`: 30 TGas (30,000,000,000,000 gas)
+- `storage_deposit`: 10 TGas
+
+Required deposits:
+
+- `ft_transfer`: 1 yoctoNEAR
+
+## 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 chains implementation
+- `@t402/aptos` - Aptos implementation

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

@@ -0,0 +1,105 @@
+import { SchemeNetworkClient, PaymentRequirements, PaymentPayload, Network } from '@t402/core/types';
+import { C as ClientNearSigner } from '../../types-Ca7ztL_f.js';
+import { t402Client, PaymentPolicy } from '@t402/core/client';
+
+/**
+ * NEAR Client Scheme Implementation - Exact Direct
+ *
+ * Creates payment payloads for NEAR NEP-141 transfers using the exact-direct scheme.
+ * In this scheme, the client executes the ft_transfer directly and provides
+ * the transaction hash as proof of payment.
+ */
+
+/**
+ * Configuration for ExactDirectNearClient
+ */
+interface ExactDirectNearClientConfig {
+    /** Override the gas amount for ft_transfer */
+    gasAmount?: string;
+    /** Optional memo to include in the transfer */
+    memo?: string;
+}
+/**
+ * NEAR client implementation for the Exact-Direct payment scheme.
+ *
+ * Executes NEP-141 ft_transfer and returns the transaction hash as proof.
+ */
+declare class ExactDirectNearClient implements SchemeNetworkClient {
+    private readonly signer;
+    private readonly config;
+    readonly scheme = "exact-direct";
+    /**
+     * Creates a new ExactDirectNearScheme instance.
+     *
+     * @param signer - The NEAR signer for client operations
+     * @param config - Optional configuration overrides
+     */
+    constructor(signer: ClientNearSigner, config?: ExactDirectNearClientConfig);
+    /**
+     * Creates a payment payload by executing the transfer.
+     *
+     * Unlike other schemes where the client creates a signed message for
+     * the facilitator to execute, the exact-direct scheme has the client
+     * execute the transfer directly. The transaction hash is then used
+     * as proof of payment.
+     *
+     * @param t402Version - The t402 protocol version
+     * @param paymentRequirements - The payment requirements
+     * @returns Promise resolving to a payment payload with transaction hash
+     */
+    createPaymentPayload(t402Version: number, paymentRequirements: PaymentRequirements): Promise<Pick<PaymentPayload, "t402Version" | "payload">>;
+}
+
+/**
+ * Registration function for NEAR Exact-Direct client
+ */
+
+/**
+ * Configuration options for registering NEAR schemes to a t402Client
+ */
+interface NearClientConfig {
+    /**
+     * The NEAR signer to use for creating payment payloads
+     */
+    signer: ClientNearSigner;
+    /**
+     * Optional policies to apply to the client
+     */
+    policies?: PaymentPolicy[];
+    /**
+     * Optional specific networks to register
+     * If not provided, registers wildcard support (near:*)
+     */
+    networks?: Network[];
+    /**
+     * Optional scheme configuration (gas amounts, memo)
+     */
+    schemeConfig?: ExactDirectNearClientConfig;
+}
+/**
+ * Registers NEAR exact-direct payment schemes to a t402Client instance.
+ *
+ * @param client - The t402Client instance to register schemes to
+ * @param config - Configuration for NEAR client registration
+ * @returns The client instance for chaining
+ *
+ * @example
+ * ```typescript
+ * import { registerExactDirectNearClient } from "@t402/near/exact-direct/client";
+ * import { t402Client } from "@t402/core/client";
+ *
+ * const client = new t402Client();
+ * registerExactDirectNearClient(client, {
+ *   signer: {
+ *     accountId: "alice.near",
+ *     signAndSendTransaction: async (receiverId, methodName, args, gas, deposit) => {
+ *       // Sign and send using wallet
+ *       return txHash;
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare function registerExactDirectNearClient(client: t402Client, config: NearClientConfig): t402Client;
+
+export { ExactDirectNearClient, type ExactDirectNearClientConfig, type NearClientConfig, registerExactDirectNearClient };

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

@@ -0,0 +1,156 @@
+"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, {
+  ExactDirectNearClient: () => ExactDirectNearClient,
+  registerExactDirectNearClient: () => registerExactDirectNearClient
+});
+module.exports = __toCommonJS(client_exports);
+
+// src/constants.ts
+var NEAR_MAINNET_CAIP2 = "near:mainnet";
+var NEAR_TESTNET_CAIP2 = "near:testnet";
+var NEAR_NETWORK_IDS = {
+  [NEAR_MAINNET_CAIP2]: "mainnet",
+  [NEAR_TESTNET_CAIP2]: "testnet"
+};
+var NEAR_MAINNET_RPC = "https://rpc.mainnet.near.org";
+var NEAR_TESTNET_RPC = "https://rpc.testnet.near.org";
+var NETWORK_RPC_ENDPOINTS = {
+  [NEAR_MAINNET_CAIP2]: NEAR_MAINNET_RPC,
+  [NEAR_TESTNET_CAIP2]: NEAR_TESTNET_RPC
+};
+var DEFAULT_FT_TRANSFER_GAS = "30000000000000";
+var FT_TRANSFER_DEPOSIT = "1";
+var SCHEME_EXACT_DIRECT = "exact-direct";
+var MAX_TRANSACTION_AGE = 5 * 60 * 1e3;
+var NEAR_CAIP2_NAMESPACE = "near";
+
+// src/utils.ts
+function normalizeNetwork(network) {
+  if (network.startsWith(`${NEAR_CAIP2_NAMESPACE}:`)) {
+    return network;
+  }
+  return `${NEAR_CAIP2_NAMESPACE}:${network}`;
+}
+function isValidAccountId(accountId) {
+  if (!accountId || accountId.length < 2 || accountId.length > 64) {
+    return false;
+  }
+  const regex = /^[a-z0-9]([a-z0-9_-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9_-]*[a-z0-9])?)*$/;
+  return regex.test(accountId);
+}
+
+// src/exact-direct/client/scheme.ts
+var ExactDirectNearClient = class {
+  /**
+   * Creates a new ExactDirectNearScheme instance.
+   *
+   * @param signer - The NEAR signer for client operations
+   * @param config - Optional configuration overrides
+   */
+  constructor(signer, config = {}) {
+    this.signer = signer;
+    this.config = config;
+    this.scheme = SCHEME_EXACT_DIRECT;
+  }
+  /**
+   * Creates a payment payload by executing the transfer.
+   *
+   * Unlike other schemes where the client creates a signed message for
+   * the facilitator to execute, the exact-direct scheme has the client
+   * execute the transfer directly. The transaction hash is then used
+   * as proof of payment.
+   *
+   * @param t402Version - The t402 protocol version
+   * @param paymentRequirements - The payment requirements
+   * @returns Promise resolving to a payment payload with transaction hash
+   */
+  async createPaymentPayload(t402Version, paymentRequirements) {
+    normalizeNetwork(paymentRequirements.network);
+    if (!paymentRequirements.asset) {
+      throw new Error("Asset (token contract address) is required");
+    }
+    if (!paymentRequirements.payTo) {
+      throw new Error("PayTo address is required");
+    }
+    if (!paymentRequirements.amount) {
+      throw new Error("Amount is required");
+    }
+    if (!isValidAccountId(paymentRequirements.payTo)) {
+      throw new Error(`Invalid recipient account ID: ${paymentRequirements.payTo}`);
+    }
+    if (!isValidAccountId(this.signer.accountId)) {
+      throw new Error(`Invalid sender account ID: ${this.signer.accountId}`);
+    }
+    const tokenContract = paymentRequirements.asset;
+    const recipient = paymentRequirements.payTo;
+    const amount = paymentRequirements.amount;
+    const ftTransferArgs = {
+      receiver_id: recipient,
+      amount
+    };
+    if (this.config.memo) {
+      ftTransferArgs.memo = this.config.memo;
+    }
+    const txHash = await this.signer.signAndSendTransaction(
+      tokenContract,
+      "ft_transfer",
+      ftTransferArgs,
+      this.config.gasAmount || DEFAULT_FT_TRANSFER_GAS,
+      FT_TRANSFER_DEPOSIT
+    );
+    const payload = {
+      txHash,
+      from: this.signer.accountId,
+      to: recipient,
+      amount
+    };
+    return {
+      t402Version,
+      payload
+    };
+  }
+};
+
+// src/exact-direct/client/register.ts
+function registerExactDirectNearClient(client, config) {
+  const scheme = new ExactDirectNearClient(config.signer, config.schemeConfig);
+  if (config.networks && config.networks.length > 0) {
+    config.networks.forEach((network) => {
+      client.register(network, scheme);
+    });
+  } else {
+    client.register("near:*", scheme);
+  }
+  if (config.policies) {
+    config.policies.forEach((policy) => {
+      client.registerPolicy(policy);
+    });
+  }
+  return client;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ExactDirectNearClient,
+  registerExactDirectNearClient
+});
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/exact-direct/client/index.ts","../../../../src/constants.ts","../../../../src/utils.ts","../../../../src/exact-direct/client/scheme.ts","../../../../src/exact-direct/client/register.ts"],"sourcesContent":["/**\n * NEAR Exact-Direct Client Exports\n */\n\nexport { ExactDirectNearClient, type ExactDirectNearClientConfig } from \"./scheme.js\";\nexport { registerExactDirectNearClient, type NearClientConfig } from \"./register.js\";\n","/**\n * NEAR Network Constants\n *\n * This module provides constants for NEAR blockchain integration including:\n * - CAIP-2 network identifiers\n * - RPC endpoints\n * - NEP-141 function names\n * - Default gas amounts\n */\n\n/**\n * CAIP-2 Network Identifiers for NEAR\n */\nexport const NEAR_MAINNET_CAIP2 = \"near:mainnet\";\nexport const NEAR_TESTNET_CAIP2 = \"near:testnet\";\n\n/**\n * Supported NEAR networks\n */\nexport const NEAR_NETWORKS = [NEAR_MAINNET_CAIP2, NEAR_TESTNET_CAIP2] as const;\n\nexport type NearNetwork = (typeof NEAR_NETWORKS)[number];\n\n/**\n * NEAR network IDs (for wallet connection)\n */\nexport const NEAR_NETWORK_IDS: Record<string, string> = {\n  [NEAR_MAINNET_CAIP2]: \"mainnet\",\n  [NEAR_TESTNET_CAIP2]: \"testnet\",\n};\n\n/**\n * Default RPC endpoints\n */\nexport const NEAR_MAINNET_RPC = \"https://rpc.mainnet.near.org\";\nexport const NEAR_TESTNET_RPC = \"https://rpc.testnet.near.org\";\n\n/**\n * Network RPC endpoint mapping\n */\nexport const NETWORK_RPC_ENDPOINTS: Record<string, string> = {\n  [NEAR_MAINNET_CAIP2]: NEAR_MAINNET_RPC,\n  [NEAR_TESTNET_CAIP2]: NEAR_TESTNET_RPC,\n};\n\n/**\n * NEP-141 Fungible Token Standard function names\n * @see https://nomicon.io/Standards/Tokens/FungibleToken/Core\n */\nexport const NEP141_FT_TRANSFER = \"ft_transfer\";\nexport const NEP141_FT_BALANCE_OF = \"ft_balance_of\";\nexport const NEP141_STORAGE_DEPOSIT = \"storage_deposit\";\nexport const NEP141_STORAGE_BALANCE_OF = \"storage_balance_of\";\n\n/**\n * Default gas amounts for NEP-141 transfers\n * NEAR gas is measured in TGas (1 TGas = 10^12 gas)\n */\nexport const DEFAULT_FT_TRANSFER_GAS = \"30000000000000\"; // 30 TGas\nexport const DEFAULT_STORAGE_DEPOSIT_GAS = \"10000000000000\"; // 10 TGas\n\n/**\n * Required deposits for NEP-141 operations\n * ft_transfer requires 1 yoctoNEAR attached deposit\n */\nexport const FT_TRANSFER_DEPOSIT = \"1\"; // 1 yoctoNEAR\nexport const DEFAULT_STORAGE_DEPOSIT = \"1250000000000000000000\"; // 0.00125 NEAR\n\n/**\n * Scheme identifier for exact-direct payments\n */\nexport const SCHEME_EXACT_DIRECT = \"exact-direct\";\n\n/**\n * Default timeout for payment validity (in seconds)\n */\nexport const DEFAULT_VALIDITY_DURATION = 3600; // 1 hour\n\n/**\n * Maximum transaction age to accept (in milliseconds)\n */\nexport const MAX_TRANSACTION_AGE = 5 * 60 * 1000; // 5 minutes\n\n/**\n * CAIP-2 namespace for NEAR\n */\nexport const NEAR_CAIP2_NAMESPACE = \"near\";\n","/**\n * NEAR Utility Functions\n *\n * Helper functions for NEAR address validation, network normalization,\n * and RPC interactions.\n */\n\nimport { NEAR_CAIP2_NAMESPACE, NETWORK_RPC_ENDPOINTS, type NearNetwork } from \"./constants.js\";\nimport type {\n  NearRpcRequest,\n  NearRpcResponse,\n  TransactionResult,\n  FtTransferArgs,\n} from \"./types.js\";\n\n/**\n * Normalize a network identifier to CAIP-2 format\n * @param network - Network identifier (e.g., \"mainnet\", \"near:mainnet\")\n * @returns CAIP-2 formatted network identifier\n */\nexport function normalizeNetwork(network: string): NearNetwork {\n  // Already in CAIP-2 format\n  if (network.startsWith(`${NEAR_CAIP2_NAMESPACE}:`)) {\n    return network as NearNetwork;\n  }\n  // Convert shorthand to CAIP-2\n  return `${NEAR_CAIP2_NAMESPACE}:${network}` as NearNetwork;\n}\n\n/**\n * Extract network ID from CAIP-2 identifier\n * @param network - CAIP-2 network identifier\n * @returns Network ID (e.g., \"mainnet\")\n */\nexport function extractNetworkId(network: string): string {\n  if (network.includes(\":\")) {\n    return network.split(\":\")[1];\n  }\n  return network;\n}\n\n/**\n * Validate a NEAR account ID\n * NEAR account IDs must:\n * - Be 2-64 characters\n * - Contain only lowercase alphanumeric, underscores, hyphens\n * - Not start with a hyphen or underscore\n * @param accountId - Account ID to validate\n * @returns Whether the account ID is valid\n */\nexport function isValidAccountId(accountId: string): boolean {\n  if (!accountId || accountId.length < 2 || accountId.length > 64) {\n    return false;\n  }\n  // NEAR account ID regex\n  const regex = /^[a-z0-9]([a-z0-9_-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9_-]*[a-z0-9])?)*$/;\n  return regex.test(accountId);\n}\n\n/**\n * Get RPC endpoint for a network\n * @param network - CAIP-2 network identifier\n * @returns RPC endpoint URL\n */\nexport function getRpcEndpoint(network: string): string {\n  const normalizedNetwork = normalizeNetwork(network);\n  return NETWORK_RPC_ENDPOINTS[normalizedNetwork] || NETWORK_RPC_ENDPOINTS[\"near:mainnet\"];\n}\n\n/**\n * Make a JSON-RPC call to NEAR\n * @param network - CAIP-2 network identifier\n * @param method - RPC method name\n * @param params - Method parameters\n * @returns RPC response result\n */\nexport async function rpcCall<T>(\n  network: string,\n  method: string,\n  params: NearRpcRequest[\"params\"],\n): Promise<T> {\n  const endpoint = getRpcEndpoint(network);\n\n  const request: NearRpcRequest = {\n    jsonrpc: \"2.0\",\n    id: `t402-${Date.now()}`,\n    method,\n    params,\n  };\n\n  const response = await fetch(endpoint, {\n    method: \"POST\",\n    headers: { \"Content-Type\": \"application/json\" },\n    body: JSON.stringify(request),\n  });\n\n  const data = (await response.json()) as NearRpcResponse<T>;\n\n  if (data.error) {\n    throw new Error(`NEAR RPC error: ${data.error.message}`);\n  }\n\n  return data.result as T;\n}\n\n/**\n * Query a transaction by hash\n * @param network - CAIP-2 network identifier\n * @param txHash - Transaction hash\n * @param senderAccountId - Sender account ID\n * @returns Transaction result\n */\nexport async function queryTransaction(\n  network: string,\n  txHash: string,\n  senderAccountId: string,\n): Promise<TransactionResult> {\n  return rpcCall<TransactionResult>(network, \"tx\", [txHash, senderAccountId]);\n}\n\n/**\n * Query token balance\n * @param network - CAIP-2 network identifier\n * @param accountId - Account to query\n * @param tokenContract - Token contract address\n * @returns Balance as bigint\n */\nexport async function queryTokenBalance(\n  network: string,\n  accountId: string,\n  tokenContract: string,\n): Promise<bigint> {\n  try {\n    const result = await rpcCall<{ result: number[] }>(network, \"query\", {\n      request_type: \"call_function\",\n      finality: \"final\",\n      account_id: tokenContract,\n      method_name: \"ft_balance_of\",\n      args_base64: btoa(JSON.stringify({ account_id: accountId })),\n    });\n\n    // Result is a byte array representing the JSON response\n    const bytes = new Uint8Array(result.result);\n    const text = new TextDecoder().decode(bytes);\n    // Remove quotes from JSON string response\n    const balance = text.replace(/\"/g, \"\");\n    return BigInt(balance);\n  } catch (error) {\n    console.error(\"Error fetching token balance:\", error);\n    return 0n;\n  }\n}\n\n/**\n * Parse ft_transfer args from base64 encoded string\n * @param argsBase64 - Base64 encoded JSON arguments\n * @returns Parsed ft_transfer arguments\n */\nexport function parseFtTransferArgs(argsBase64: string): FtTransferArgs | null {\n  try {\n    const argsJson = atob(argsBase64);\n    return JSON.parse(argsJson) as FtTransferArgs;\n  } catch {\n    // Try parsing as raw JSON (some nodes return it differently)\n    try {\n      return JSON.parse(argsBase64) as FtTransferArgs;\n    } catch {\n      return null;\n    }\n  }\n}\n\n/**\n * Check if a transaction succeeded\n * @param status - Transaction status\n * @returns Whether the transaction succeeded\n */\nexport function isTransactionSuccessful(status: {\n  SuccessValue?: string;\n  Failure?: unknown;\n}): boolean {\n  return status.SuccessValue !== undefined && status.Failure === undefined;\n}\n\n/**\n * Format amount for display (with decimals)\n * @param amount - Amount in smallest units\n * @param decimals - Number of decimal places\n * @returns Formatted amount string\n */\nexport function formatAmount(amount: bigint, decimals: number): string {\n  const divisor = BigInt(10 ** decimals);\n  const whole = amount / divisor;\n  const remainder = amount % divisor;\n  const decimal = remainder.toString().padStart(decimals, \"0\").slice(0, 2);\n  return `${whole}.${decimal}`;\n}\n\n/**\n * Convert decimal amount to token units\n * @param decimalAmount - Amount with decimals (e.g., \"1.50\")\n * @param decimals - Token decimals\n * @returns Amount in smallest units\n */\nexport function toTokenUnits(decimalAmount: string | number, decimals: number): bigint {\n  const amount = typeof decimalAmount === \"string\" ? parseFloat(decimalAmount) : decimalAmount;\n  if (isNaN(amount)) {\n    throw new Error(`Invalid amount: ${decimalAmount}`);\n  }\n  const multiplier = 10 ** decimals;\n  return BigInt(Math.floor(amount * multiplier));\n}\n","/**\n * NEAR Client Scheme Implementation - Exact Direct\n *\n * Creates payment payloads for NEAR NEP-141 transfers using the exact-direct scheme.\n * In this scheme, the client executes the ft_transfer directly and provides\n * the transaction hash as proof of payment.\n */\n\nimport type { PaymentPayload, PaymentRequirements, SchemeNetworkClient } from \"@t402/core/types\";\nimport type { ClientNearSigner, ExactDirectNearPayload } from \"../../types.js\";\nimport {\n  SCHEME_EXACT_DIRECT,\n  DEFAULT_FT_TRANSFER_GAS,\n  FT_TRANSFER_DEPOSIT,\n} from \"../../constants.js\";\nimport { normalizeNetwork, isValidAccountId } from \"../../utils.js\";\n\n/**\n * Configuration for ExactDirectNearClient\n */\nexport interface ExactDirectNearClientConfig {\n  /** Override the gas amount for ft_transfer */\n  gasAmount?: string;\n  /** Optional memo to include in the transfer */\n  memo?: string;\n}\n\n/**\n * NEAR client implementation for the Exact-Direct payment scheme.\n *\n * Executes NEP-141 ft_transfer and returns the transaction hash as proof.\n */\nexport class ExactDirectNearClient implements SchemeNetworkClient {\n  readonly scheme = SCHEME_EXACT_DIRECT;\n\n  /**\n   * Creates a new ExactDirectNearScheme instance.\n   *\n   * @param signer - The NEAR signer for client operations\n   * @param config - Optional configuration overrides\n   */\n  constructor(\n    private readonly signer: ClientNearSigner,\n    private readonly config: ExactDirectNearClientConfig = {},\n  ) {}\n\n  /**\n   * Creates a payment payload by executing the transfer.\n   *\n   * Unlike other schemes where the client creates a signed message for\n   * the facilitator to execute, the exact-direct scheme has the client\n   * execute the transfer directly. The transaction hash is then used\n   * as proof of payment.\n   *\n   * @param t402Version - The t402 protocol version\n   * @param paymentRequirements - The payment requirements\n   * @returns Promise resolving to a payment payload with transaction hash\n   */\n  async createPaymentPayload(\n    t402Version: number,\n    paymentRequirements: PaymentRequirements,\n  ): Promise<Pick<PaymentPayload, \"t402Version\" | \"payload\">> {\n    // Normalize and validate network\n    normalizeNetwork(paymentRequirements.network);\n\n    // Validate required fields\n    if (!paymentRequirements.asset) {\n      throw new Error(\"Asset (token contract address) is required\");\n    }\n    if (!paymentRequirements.payTo) {\n      throw new Error(\"PayTo address is required\");\n    }\n    if (!paymentRequirements.amount) {\n      throw new Error(\"Amount is required\");\n    }\n\n    // Validate addresses\n    if (!isValidAccountId(paymentRequirements.payTo)) {\n      throw new Error(`Invalid recipient account ID: ${paymentRequirements.payTo}`);\n    }\n    if (!isValidAccountId(this.signer.accountId)) {\n      throw new Error(`Invalid sender account ID: ${this.signer.accountId}`);\n    }\n\n    const tokenContract = paymentRequirements.asset;\n    const recipient = paymentRequirements.payTo;\n    const amount = paymentRequirements.amount;\n\n    // Build ft_transfer arguments\n    const ftTransferArgs: Record<string, unknown> = {\n      receiver_id: recipient,\n      amount: amount,\n    };\n\n    if (this.config.memo) {\n      ftTransferArgs.memo = this.config.memo;\n    }\n\n    // Execute the transfer\n    const txHash = await this.signer.signAndSendTransaction(\n      tokenContract,\n      \"ft_transfer\",\n      ftTransferArgs,\n      this.config.gasAmount || DEFAULT_FT_TRANSFER_GAS,\n      FT_TRANSFER_DEPOSIT,\n    );\n\n    // Build the payload\n    const payload: ExactDirectNearPayload = {\n      txHash,\n      from: this.signer.accountId,\n      to: recipient,\n      amount: amount,\n    };\n\n    return {\n      t402Version,\n      payload,\n    };\n  }\n}\n","/**\n * Registration function for NEAR Exact-Direct client\n */\n\nimport { t402Client, PaymentPolicy } from \"@t402/core/client\";\nimport { Network } from \"@t402/core/types\";\nimport type { ClientNearSigner } from \"../../types.js\";\nimport { ExactDirectNearClient, type ExactDirectNearClientConfig } from \"./scheme.js\";\n\n/**\n * Configuration options for registering NEAR schemes to a t402Client\n */\nexport interface NearClientConfig {\n  /**\n   * The NEAR signer to use for creating payment payloads\n   */\n  signer: ClientNearSigner;\n\n  /**\n   * Optional policies to apply to the client\n   */\n  policies?: PaymentPolicy[];\n\n  /**\n   * Optional specific networks to register\n   * If not provided, registers wildcard support (near:*)\n   */\n  networks?: Network[];\n\n  /**\n   * Optional scheme configuration (gas amounts, memo)\n   */\n  schemeConfig?: ExactDirectNearClientConfig;\n}\n\n/**\n * Registers NEAR exact-direct payment schemes to a t402Client instance.\n *\n * @param client - The t402Client instance to register schemes to\n * @param config - Configuration for NEAR client registration\n * @returns The client instance for chaining\n *\n * @example\n * ```typescript\n * import { registerExactDirectNearClient } from \"@t402/near/exact-direct/client\";\n * import { t402Client } from \"@t402/core/client\";\n *\n * const client = new t402Client();\n * registerExactDirectNearClient(client, {\n *   signer: {\n *     accountId: \"alice.near\",\n *     signAndSendTransaction: async (receiverId, methodName, args, gas, deposit) => {\n *       // Sign and send using wallet\n *       return txHash;\n *     }\n *   }\n * });\n * ```\n */\nexport function registerExactDirectNearClient(\n  client: t402Client,\n  config: NearClientConfig,\n): t402Client {\n  const scheme = new ExactDirectNearClient(config.signer, config.schemeConfig);\n\n  // Register scheme\n  if (config.networks && config.networks.length > 0) {\n    // Register specific networks\n    config.networks.forEach((network) => {\n      client.register(network, scheme);\n    });\n  } else {\n    // Register wildcard for all NEAR networks\n    client.register(\"near:*\", scheme);\n  }\n\n  // Apply policies if provided\n  if (config.policies) {\n    config.policies.forEach((policy) => {\n      client.registerPolicy(policy);\n    });\n  }\n\n  return client;\n}\n"],"mappings":"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","names":[]}

package/dist/cjs/exact-direct/facilitator/index.d.ts

@@ -0,0 +1,114 @@
+import { SchemeNetworkFacilitator, Network, PaymentPayload, PaymentRequirements, VerifyResponse, SettleResponse } from '@t402/core/types';
+import { f as FacilitatorNearSigner } from '../../types-Ca7ztL_f.js';
+import { t402Facilitator } from '@t402/core/facilitator';
+
+/**
+ * NEAR Facilitator Scheme Implementation - Exact Direct
+ *
+ * Verifies and settles NEAR NEP-141 payments using the exact-direct scheme.
+ * The facilitator verifies that the client's transaction was successful
+ * and matches the payment requirements.
+ */
+
+/**
+ * Configuration for ExactDirectNearFacilitator
+ */
+interface ExactDirectNearFacilitatorConfig {
+    /** Maximum age of a transaction to accept (in milliseconds) */
+    maxTransactionAge?: number;
+    /** Duration to cache used transaction hashes (in milliseconds) */
+    usedTxCacheDuration?: number;
+}
+/**
+ * NEAR facilitator implementation for the Exact-Direct payment scheme.
+ * Verifies transaction proofs and confirms payments.
+ */
+declare class ExactDirectNearFacilitator implements SchemeNetworkFacilitator {
+    private readonly signer;
+    readonly scheme = "exact-direct";
+    readonly caipFamily = "near:*";
+    private readonly config;
+    private usedTxs;
+    constructor(signer: FacilitatorNearSigner, config?: ExactDirectNearFacilitatorConfig);
+    /**
+     * Get extra data for a supported kind
+     */
+    getExtra(network: Network): Record<string, unknown> | undefined;
+    /**
+     * Get signer addresses for a network
+     */
+    getSigners(network: Network): string[];
+    /**
+     * Verify a payment payload
+     */
+    verify(payload: PaymentPayload, requirements: PaymentRequirements): Promise<VerifyResponse>;
+    /**
+     * Settle a payment - for exact-direct, the transfer is already complete
+     */
+    settle(payload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleResponse>;
+    /**
+     * Check if a transaction has been used
+     */
+    private isTxUsed;
+    /**
+     * Mark a transaction as used
+     */
+    private markTxUsed;
+    /**
+     * Start the cleanup interval for used transactions
+     */
+    private startCleanupInterval;
+}
+
+/**
+ * Registration function for NEAR Exact-Direct facilitator
+ */
+
+/**
+ * Configuration options for registering NEAR schemes to a t402Facilitator
+ */
+interface NearFacilitatorConfig {
+    /**
+     * The NEAR signer for facilitator operations (verify and settle)
+     */
+    signer: FacilitatorNearSigner;
+    /**
+     * Networks to register (single network or array of networks)
+     * Examples: "near:mainnet", ["near:mainnet", "near:testnet"]
+     */
+    networks: Network | Network[];
+    /**
+     * Optional scheme configuration
+     */
+    schemeConfig?: ExactDirectNearFacilitatorConfig;
+}
+/**
+ * Registers NEAR exact-direct payment schemes to a t402Facilitator instance.
+ *
+ * @param facilitator - The t402Facilitator instance to register schemes to
+ * @param config - Configuration for NEAR facilitator registration
+ * @returns The facilitator instance for chaining
+ *
+ * @example
+ * ```typescript
+ * import { registerExactDirectNearFacilitator } from "@t402/near/exact-direct/facilitator";
+ * import { t402Facilitator } from "@t402/core/facilitator";
+ *
+ * const facilitator = new t402Facilitator();
+ *
+ * // Single network
+ * registerExactDirectNearFacilitator(facilitator, {
+ *   signer: myNearSigner,
+ *   networks: "near:mainnet"
+ * });
+ *
+ * // Multiple networks
+ * registerExactDirectNearFacilitator(facilitator, {
+ *   signer: myNearSigner,
+ *   networks: ["near:mainnet", "near:testnet"]
+ * });
+ * ```
+ */
+declare function registerExactDirectNearFacilitator(facilitator: t402Facilitator, config: NearFacilitatorConfig): t402Facilitator;
+
+export { ExactDirectNearFacilitator, type ExactDirectNearFacilitatorConfig, type NearFacilitatorConfig, registerExactDirectNearFacilitator };