@t402/tezos 2.3.0

package/src/types.ts

@@ -0,0 +1,160 @@
+/**
+ * Tezos mechanism types
+ */
+
+import type { Network } from "@t402/core/types";
+
+/**
+ * Exact-direct payment payload for Tezos
+ */
+export type ExactDirectTezosPayload = {
+  /** Operation hash (o...) */
+  opHash: string;
+  /** Sender address (tz1/tz2/tz3...) */
+  from: string;
+  /** Recipient address */
+  to: string;
+  /** Amount in smallest units */
+  amount: string;
+  /** FA2 contract address (KT1...) */
+  contractAddress: string;
+  /** Token ID within the FA2 contract */
+  tokenId: number;
+};
+
+/**
+ * Tezos signer interface for client-side operations
+ */
+export interface TezosSigner {
+  /** Get the signer's address */
+  getAddress(): Promise<string>;
+
+  /**
+   * Execute an FA2 transfer
+   * @param contractAddress FA2 contract address
+   * @param tokenId Token ID
+   * @param to Recipient address
+   * @param amount Amount to transfer
+   * @returns Operation hash
+   */
+  transfer(
+    contractAddress: string,
+    tokenId: number,
+    to: string,
+    amount: bigint,
+  ): Promise<string>;
+
+  /**
+   * Get token balance
+   * @param contractAddress FA2 contract address
+   * @param tokenId Token ID
+   * @param address Address to check (optional, defaults to signer address)
+   * @returns Balance in smallest units
+   */
+  getBalance(
+    contractAddress: string,
+    tokenId: number,
+    address?: string,
+  ): Promise<bigint>;
+}
+
+/**
+ * Tezos signer interface for facilitator operations
+ */
+export interface FacilitatorTezosSigner {
+  /** Get facilitator addresses for a network */
+  getAddresses(network: Network): string[];
+
+  /**
+   * Query an operation by hash
+   * @param opHash Operation hash
+   * @returns Operation result or null if not found
+   */
+  queryOperation(opHash: string): Promise<TezosOperationResult | null>;
+
+  /**
+   * Get token balance for an address
+   * @param contractAddress FA2 contract address
+   * @param tokenId Token ID
+   * @param address Address to check
+   * @returns Balance as string
+   */
+  getBalance(
+    contractAddress: string,
+    tokenId: number,
+    address: string,
+  ): Promise<string>;
+}
+
+/**
+ * Tezos operation result from indexer
+ */
+export interface TezosOperationResult {
+  /** Operation hash */
+  hash: string;
+  /** Block level */
+  level: number;
+  /** Timestamp */
+  timestamp: string;
+  /** Status: applied, failed, backtracked, skipped */
+  status: "applied" | "failed" | "backtracked" | "skipped";
+  /** Sender address */
+  sender: {
+    address: string;
+  };
+  /** Target contract (for contract calls) */
+  target?: {
+    address: string;
+  };
+  /** Entrypoint called */
+  entrypoint?: string;
+  /** Parameter value */
+  parameter?: unknown;
+  /** Amount transferred (in mutez for XTZ) */
+  amount?: number;
+  /** Errors if failed */
+  errors?: Array<{
+    type: string;
+    message?: string;
+  }>;
+}
+
+/**
+ * FA2 transfer parameter structure
+ */
+export interface FA2TransferParam {
+  from_: string;
+  txs: Array<{
+    to_: string;
+    token_id: number;
+    amount: string;
+  }>;
+}
+
+/**
+ * Check if a string is a valid Tezos address
+ */
+export function isValidTezosAddress(address: string): boolean {
+  if (!address) return false;
+  // tz1, tz2, tz3 for implicit accounts, KT1 for contracts
+  const prefixPattern = /^(tz1|tz2|tz3|KT1)/;
+  if (!prefixPattern.test(address)) return false;
+  // Base58 check - length should be 36 characters
+  return address.length === 36;
+}
+
+/**
+ * Check if a string is a valid Tezos operation hash
+ */
+export function isValidOperationHash(opHash: string): boolean {
+  if (!opHash) return false;
+  // Operation hashes start with 'o' and are 51 characters
+  return opHash.startsWith("o") && opHash.length === 51;
+}
+
+/**
+ * Check if a network is a Tezos network
+ */
+export function isTezosNetwork(network: string): boolean {
+  return network.startsWith("tezos:");
+}

package/src/utils.ts

@@ -0,0 +1,128 @@
+/**
+ * Tezos utility functions
+ */
+
+import {
+  NETWORK_CONFIGS,
+  TEZOS_CAIP2_NAMESPACE,
+  SUPPORTED_NETWORKS,
+} from "./constants.js";
+
+/**
+ * Get network configuration
+ */
+export function getNetworkConfig(network: string) {
+  return NETWORK_CONFIGS[network];
+}
+
+/**
+ * Check if a network is supported
+ */
+export function isSupportedNetwork(network: string): boolean {
+  return (SUPPORTED_NETWORKS as readonly string[]).includes(network);
+}
+
+/**
+ * Parse a CAIP-2 network identifier to extract the chain reference
+ */
+export function parseNetworkId(network: string): {
+  namespace: string;
+  reference: string;
+} | null {
+  const parts = network.split(":");
+  if (parts.length !== 2) return null;
+  return {
+    namespace: parts[0],
+    reference: parts[1],
+  };
+}
+
+/**
+ * Build a CAIP-2 network identifier
+ */
+export function buildNetworkId(reference: string): string {
+  return `${TEZOS_CAIP2_NAMESPACE}:${reference}`;
+}
+
+/**
+ * Get indexer URL for a network
+ */
+export function getIndexerUrl(network: string): string | undefined {
+  return NETWORK_CONFIGS[network]?.indexerUrl;
+}
+
+/**
+ * Get RPC URL for a network
+ */
+export function getRpcUrl(network: string): string | undefined {
+  return NETWORK_CONFIGS[network]?.rpcUrl;
+}
+
+/**
+ * Compare two Tezos addresses (case-insensitive for base58)
+ */
+export function compareAddresses(addr1: string, addr2: string): boolean {
+  if (!addr1 || !addr2) return false;
+  return addr1 === addr2;
+}
+
+/**
+ * Format amount with decimals
+ */
+export function formatAmount(amount: bigint, decimals: number): string {
+  const divisor = BigInt(10 ** decimals);
+  const wholePart = amount / divisor;
+  const fractionalPart = amount % divisor;
+  const fractionalStr = fractionalPart.toString().padStart(decimals, "0");
+  return `${wholePart}.${fractionalStr}`;
+}
+
+/**
+ * Parse amount string to bigint
+ */
+export function parseAmount(amount: string, decimals: number): bigint {
+  const [whole, fractional = ""] = amount.split(".");
+  const paddedFractional = fractional.padEnd(decimals, "0").slice(0, decimals);
+  return BigInt(whole + paddedFractional);
+}
+
+/**
+ * Extract FA2 transfer details from operation parameter
+ */
+export function extractFA2TransferDetails(
+  parameter: unknown,
+): {
+  from: string;
+  to: string;
+  tokenId: number;
+  amount: string;
+} | null {
+  if (!parameter || !Array.isArray(parameter)) return null;
+
+  // FA2 transfer parameter is an array of { from_: string, txs: [...] }
+  const firstTransfer = parameter[0];
+  if (!firstTransfer || typeof firstTransfer !== "object") return null;
+
+  const transfer = firstTransfer as Record<string, unknown>;
+  const from = transfer.from_ as string;
+  const txs = transfer.txs as Array<{
+    to_: string;
+    token_id: number | string;
+    amount: number | string;
+  }>;
+
+  if (!from || !Array.isArray(txs) || txs.length === 0) return null;
+
+  const firstTx = txs[0];
+  if (!firstTx) return null;
+
+  return {
+    from,
+    to: firstTx.to_,
+    tokenId:
+      typeof firstTx.token_id === "string"
+        ? parseInt(firstTx.token_id, 10)
+        : firstTx.token_id,
+    amount: String(firstTx.amount),
+  };
+}