@rozoai/intent-common 0.1.2 → 0.1.4

package/src/bridge-utils.ts

@@ -1,382 +0,0 @@
-import { parseUnits } from "viem";
-import {
-  baseUSDC,
-  getChainById,
-  getKnownToken,
-  isChainSupported,
-  isTokenSupported,
-  PaymentResponse,
-  RozoPayHydratedOrderWithOrg,
-  RozoPayIntentStatus,
-  RozoPayOrderMode,
-  RozoPayOrderStatusDest,
-  RozoPayOrderStatusSource,
-  RozoPayUserMetadata,
-  rozoSolana,
-  rozoSolanaUSDC,
-  rozoStellarUSDC,
-  solana,
-  validateAddressForChain,
-} from ".";
-
-export interface PaymentBridgeConfig {
-  toChain: number;
-  toToken: string;
-  toAddress: string;
-  toUnits: string;
-  preferredChain: number;
-  preferredTokenAddress: string;
-}
-
-export interface PreferredPaymentConfig {
-  preferredChain: string;
-  preferredToken: string;
-  preferredTokenAddress: string;
-}
-
-export interface DestinationConfig {
-  destinationAddress?: string;
-  chainId: string;
-  amountUnits: string;
-  tokenSymbol: string;
-  tokenAddress: string;
-}
-
-interface PaymentBridge {
-  preferred: PreferredPaymentConfig;
-  destination: DestinationConfig;
-  isIntentPayment: boolean;
-}
-
-/**
- * Creates payment bridge configuration for cross-chain payment routing
- *
- * Determines the optimal payment routing based on the destination chain/token
- * and the preferred payment method selected by the user. This function handles
- * the complexity of multi-chain payments by:
- *
- * 1. **Preferred Payment Method**: Identifies which chain/token the user will pay from
- *    - Supports Base USDC, Polygon USDC, Ethereum USDC, Solana USDC, Stellar USDC, Worldchain USDC, and BSC USDT
- *    - Sets appropriate chain ID and token address for the source transaction
- *
- * 2. **Destination Configuration**: Determines where funds will be received
- *    - Supports Base, Solana, Stellar, and Worldchain as destination chains
- *    - Automatically handles special address formats for Solana and Stellar addresses
- *    - Configures destination token based on chain type (e.g., Stellar/Solana USDC)
- *
- * 3. **Intent Payment Detection**: Determines if this is a cross-chain intent payment
- *    - Returns `isIntentPayment: true` when preferred chain/token differs from destination
- *    - Returns `isIntentPayment: false` for same-chain, same-token payments
- *
- * @param config - Payment bridge configuration parameters
- * @param config.toChain - Destination chain ID (e.g., 8453 for Base, 900 for Solana, 10001 for Stellar)
- * @param config.toToken - Destination token address (must be a supported token on the destination chain)
- * @param config.toAddress - Destination address (format validated based on chain type: EVM 0x..., Solana Base58, Stellar G...)
- * @param config.toUnits - Amount in human-readable units (e.g., "1" for 1 USDC, "0.5" for half a USDC)
- * @param config.preferredChain - Chain ID where the user will pay from (e.g., 137 for Polygon, 8453 for Base)
- * @param config.preferredTokenAddress - Token address the user selected to pay with (must be a supported token on preferredChain)
- *
- * @returns Payment routing configuration object
- * @returns preferred - Source payment configuration (chain, token user will pay from)
- * @returns preferred.preferredChain - Chain ID as string where payment originates
- * @returns preferred.preferredToken - Token symbol (e.g., "USDC", "USDT")
- * @returns preferred.preferredTokenAddress - Token contract address
- * @returns destination - Destination payment configuration (chain, token user will receive)
- * @returns destination.destinationAddress - Address where funds will be received
- * @returns destination.chainId - Destination chain ID as string
- * @returns destination.amountUnits - Payment amount in token units
- * @returns destination.tokenSymbol - Destination token symbol
- * @returns destination.tokenAddress - Destination token contract address
- * @returns isIntentPayment - Boolean indicating if this is a cross-chain intent payment
- *
- * @throws {Error} If the destination token is not supported for the destination chain
- * @throws {Error} If the destination address format is invalid for the destination chain
- * @throws {Error} If the preferred token is not supported for the preferred chain
- * @throws {Error} If the destination chain or token is not supported
- *
- * @example
- * ```typescript
- * // User wants to pay with Polygon USDC to receive on Base
- * import { baseUSDC, polygonUSDCe } from '@rozoai/intent-common';
- * import { base, polygon } from '@rozoai/intent-common';
- *
- * const { preferred, destination, isIntentPayment } = createPaymentBridgeConfig({
- *   toChain: base.chainId, // 8453
- *   toToken: baseUSDC.token,
- *   toAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
- *   toUnits: '1000000', // 1 USDC (6 decimals)
- *   preferredChain: polygon.chainId, // 137
- *   preferredToken: polygonUSDCe.token,
- * });
- *
- * // preferred = { preferredChain: '137', preferredToken: 'USDCe', preferredTokenAddress: '0x2791...' }
- * // destination = { destinationAddress: '0x742d...', chainId: '8453', amountUnits: '1000000', tokenSymbol: 'USDC', tokenAddress: '0x8335...' }
- * // isIntentPayment = true (different chains)
- * ```
- *
- * @example
- * ```typescript
- * // User wants to pay to a Stellar address using Base USDC
- * import { baseUSDC, rozoStellarUSDC } from '@rozoai/intent-common';
- * import { base, rozoStellar } from '@rozoai/intent-common';
- *
- * const { preferred, destination, isIntentPayment } = createPaymentBridgeConfig({
- *   toChain: rozoStellar.chainId, // 10001
- *   toToken: rozoStellarUSDC.token,
- *   toAddress: 'GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN',
- *   toUnits: '10000000', // 1 USDC (7 decimals for Stellar)
- *   preferredChain: base.chainId, // 8453
- *   preferredToken: baseUSDC.token,
- * });
- *
- * // preferred = { preferredChain: '8453', preferredToken: 'USDC', preferredTokenAddress: '0x8335...' }
- * // destination = { destinationAddress: 'GA5Z...', chainId: '10001', amountUnits: '10000000', tokenSymbol: 'USDC', tokenAddress: 'USDC:GA5Z...' }
- * // isIntentPayment = true (Base to Stellar)
- * ```
- *
- * @example
- * ```typescript
- * // Same-chain payment (not an intent payment)
- * const { preferred, destination, isIntentPayment } = createPaymentBridgeConfig({
- *   toChain: base.chainId, // 8453
- *   toToken: baseUSDC.token,
- *   toAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
- *   toUnits: '1000000',
- *   preferredChain: base.chainId, // 8453
- *   preferredToken: baseUSDC.token,
- * });
- *
- * // isIntentPayment = false (same chain and token)
- * ```
- *
- * @see PreferredPaymentConfig
- * @see DestinationConfig
- * @see PaymentBridgeConfig
- */
-export function createPaymentBridgeConfig({
-  toChain,
-  toToken,
-  toAddress,
-  toUnits,
-  preferredChain,
-  preferredTokenAddress,
-}: PaymentBridgeConfig): PaymentBridge {
-  const chain = getChainById(toChain);
-  const token = getKnownToken(toChain, toToken);
-
-  if (!token) {
-    throw new Error(
-      `Unsupported token ${toToken} for chain ${chain.name} (${toChain})`
-    );
-  }
-
-  const addressValid = validateAddressForChain(toChain, toAddress);
-  if (!addressValid) {
-    throw new Error(
-      `Invalid address ${toAddress} for chain ${chain.name} (${toChain})`
-    );
-  }
-
-  const preferredChainData = getChainById(preferredChain);
-  const tokenConfig = getKnownToken(preferredChain, preferredTokenAddress);
-  if (!tokenConfig) {
-    throw new Error(
-      `Unknown token ${preferredTokenAddress} for chain ${preferredChainData.name} (${preferredChain})`
-    );
-  }
-
-  let preferred: PreferredPaymentConfig = {
-    preferredChain: String(preferredChain),
-    preferredToken: tokenConfig.symbol,
-    preferredTokenAddress: preferredTokenAddress,
-  };
-
-  let destination: DestinationConfig = {
-    destinationAddress: toAddress,
-    chainId: String(toChain),
-    amountUnits: toUnits,
-    tokenSymbol: token.symbol,
-    tokenAddress: toToken,
-  };
-
-  if (isChainSupported(toChain) && isTokenSupported(toChain, toToken)) {
-    preferred = {
-      preferredChain: String(
-        tokenConfig.chainId === solana.chainId
-          ? rozoSolana.chainId
-          : tokenConfig.chainId
-      ),
-      preferredToken: tokenConfig.symbol,
-      preferredTokenAddress: tokenConfig.token,
-    };
-
-    // Determine destination based on special address types
-    if (isChainSupported(toChain, "stellar")) {
-      destination = {
-        ...destination,
-        tokenSymbol: rozoStellarUSDC.symbol,
-        chainId: String(rozoStellarUSDC.chainId),
-        tokenAddress: rozoStellarUSDC.token,
-      };
-    } else if (isChainSupported(toChain, "solana")) {
-      destination = {
-        ...destination,
-        tokenSymbol: rozoSolanaUSDC.symbol,
-        chainId: String(rozoSolanaUSDC.chainId),
-        tokenAddress: rozoSolanaUSDC.token,
-      };
-    }
-  } else {
-    throw new Error(
-      `Unsupported chain ${chain.name} (${toChain}) or token ${token.symbol} (${toToken})`
-    );
-  }
-
-  // If the preferred chain and token are not the same as the toChain and toToken, then it is an intent payment
-  const isIntentPayment =
-    preferred.preferredChain !== String(toChain) &&
-    preferred.preferredTokenAddress !== toToken;
-
-  return { preferred, destination, isIntentPayment };
-}
-
-/**
- * Converts a RozoAI payment API response to a fully hydrated RozoPay order.
- *
- * This utility transforms the low-level {@link PaymentResponse} object returned by the RozoAI Intent Pay API
- * into a {@link RozoPayHydratedOrderWithOrg}, containing all values needed for UI display, order tracking,
- * and multi-chain cross-payment logic. Fields are normalized and token metadata is resolved in order to
- * standardize data from different chains and token types.
- *
- * Key steps performed:
- *
- * 1. **Token Metadata Lookup**: Uses {@link getKnownToken} to identify the correct token
- *    for the payment, including decimals, symbol, logo, and chain details.
- *    Special handling is applied for Stellar and Solana tokens based on how they're encoded in the backend.
- *
- * 2. **Order Hydration**: Generates a unique (random BigInt) internal order ID for frontend usage, sets the
- *    payment mode as HYDRATED, and resolves all destination call and amount fields from the payment response.
- *
- * 3. **Status Initialization**: Initializes the payment, source, and destination status fields
- *    with their correct values based on the payment's progress in the state machine. The returned object is
- *    ready for status tracking and user notification.
- *
- * 4. **Metadata Consolidation**: Merges core order metadata, user metadata (if provided by the payer),
- *    and any external references such as org info. Ensures all details needed for order display and analytics are available.
- *
- * @param order - Low-level API payment response (from RozoAI Intent Pay backend)
- * @param feeType - Optional: Fee deduction mode (ExactIn/ExactOut); determines which side's amount is shown as source. Defaults to ExactIn.
- *
- * @returns {RozoPayHydratedOrderWithOrg} A normalized, display-ready order representation containing all tracking, status,
- *          token, org, and routing information for frontend use.
- *
- * @example
- * ```typescript
- * const paymentResponse = await getPayment(paymentId);
- * const hydratedOrder = formatPaymentResponseToHydratedOrder(paymentResponse.data);
- * console.log(hydratedOrder.sourceStatus); // 'WAITING_PAYMENT'
- * console.log(hydratedOrder.destFinalCallTokenAmount.token.symbol); // 'USDC'
- * console.log(hydratedOrder.usdValue); // 10.00
- * ```
- *
- * @remarks
- * - The returned `id` (BigInt) is generated randomly and is client-side only; always use
- *   `order.orderId` or the API reference for backend/server reconciliation.
- * - The expiration timestamp and org info are carried over if present on the API response.
- * - Decimals, token symbol, and display metadata for the amount and destination chain
- *   are resolved so the result is immediately usable for UI.
- *
- * @see PaymentResponse
- * @see RozoPayHydratedOrderWithOrg
- * @see getKnownToken
- */
-export function formatPaymentResponseToHydratedOrder(
-  order: PaymentResponse
-): RozoPayHydratedOrderWithOrg {
-  // Source amount is in the same units as the destination amount without fee
-  const sourceAmountUnits =
-    order.source?.amount ?? order.destination?.amountUnits ?? "0";
-
-  // Destination Intent Address
-  const intentAddress =
-    order.metadata?.receivingAddress ?? order.source?.receiverAddress;
-
-  // Destination Intent Memo
-  const intentMemo = order.metadata?.memo ?? order.source?.receiverMemo;
-
-  // Destination address is where the payment will be received
-  const destAddress = order.source?.receiverAddress;
-
-  // Determine the chain from metadata or default to the source chain
-  const requiredChain = order.source?.chainId || baseUSDC.chainId;
-
-  const token = getKnownToken(
-    Number(requiredChain),
-    Number(requiredChain) === rozoStellarUSDC.chainId
-      ? rozoStellarUSDC.token
-      : order.source?.tokenAddress || ""
-  );
-
-  return {
-    id: BigInt(Math.floor(Math.random() * Number.MAX_SAFE_INTEGER)),
-    mode: RozoPayOrderMode.HYDRATED,
-    intentAddr: intentAddress ?? "",
-    memo: intentMemo ?? null,
-    preferredChainId: order.source?.chainId ?? null,
-    preferredTokenAddress: order.source?.tokenAddress ?? null,
-    destFinalCallTokenAmount: {
-      token: {
-        chainId: token ? token.chainId : baseUSDC.chainId,
-        token: token ? token.token : baseUSDC.token,
-        symbol: token ? token.symbol : baseUSDC.symbol,
-        usd: Number(sourceAmountUnits),
-        priceFromUsd: 1,
-        decimals: token ? token.decimals : baseUSDC.decimals,
-        displayDecimals: 2,
-        logoSourceURI: token ? token.logoSourceURI : baseUSDC.logoSourceURI,
-        logoURI: token ? token.logoURI : baseUSDC.logoURI,
-        maxAcceptUsd: 100000,
-        maxSendUsd: 0,
-      },
-      amount: parseUnits(
-        sourceAmountUnits,
-        token ? token.decimals : baseUSDC.decimals
-      ).toString() as `${bigint}`,
-      usd: Number(sourceAmountUnits),
-    },
-    usdValue: Number(sourceAmountUnits),
-    destFinalCall: {
-      to: destAddress ?? "",
-      value: BigInt("0"),
-      data: "0x",
-    },
-    refundAddr: (order.source?.senderAddress as any) || null,
-    nonce: BigInt(order.nonce ?? 0),
-    sourceFulfillerAddr: null,
-    sourceTokenAmount: null,
-    sourceInitiateTxHash: null,
-    sourceStatus: RozoPayOrderStatusSource.WAITING_PAYMENT,
-    destStatus: RozoPayOrderStatusDest.PENDING,
-    intentStatus: RozoPayIntentStatus.UNPAID,
-    destFastFinishTxHash: null,
-    destClaimTxHash: null,
-    redirectUri: null,
-    createdAt: Math.floor(new Date(order.createdAt).getTime() / 1000),
-    lastUpdatedAt: Math.floor(new Date(order.updatedAt).getTime() / 1000),
-    orgId: order.orgId ?? "",
-    metadata: {
-      ...(order?.metadata ?? {}),
-      receivingAddress: intentAddress ?? "",
-      memo: intentMemo ?? null,
-    } as any,
-    externalId: order.externalId ?? null,
-    userMetadata: order.userMetadata as RozoPayUserMetadata | null,
-    expirationTs: BigInt(
-      Math.floor(new Date(order.expiresAt).getTime() / 1000).toString()
-    ),
-    org: {
-      orgId: order.orgId ?? "",
-      name: "",
-    },
-  };
-}

package/src/chain.ts

@@ -1,257 +0,0 @@
-export type Chain = {
-  type: "evm" | "solana" | "stellar";
-  chainId: number;
-  name: string;
-  cctpDomain: number | null;
-};
-
-export const arbitrum: Chain = {
-  type: "evm",
-  chainId: 42161,
-  name: "Arbitrum",
-  cctpDomain: 3,
-};
-
-export const base: Chain = {
-  type: "evm",
-  chainId: 8453,
-  name: "Base",
-  cctpDomain: 6,
-};
-
-export const bsc: Chain = {
-  type: "evm",
-  chainId: 56,
-  name: "BNB",
-  cctpDomain: null,
-};
-
-export const celo: Chain = {
-  type: "evm",
-  chainId: 42220,
-  name: "Celo",
-  cctpDomain: null,
-};
-
-export const ethereum: Chain = {
-  type: "evm",
-  chainId: 1,
-  name: "Ethereum",
-  cctpDomain: 0,
-};
-
-export const linea: Chain = {
-  type: "evm",
-  chainId: 59144,
-  name: "Linea",
-  cctpDomain: 11,
-};
-
-export const mantle: Chain = {
-  type: "evm",
-  chainId: 5000,
-  name: "Mantle",
-  cctpDomain: null,
-};
-
-export const optimism: Chain = {
-  type: "evm",
-  chainId: 10,
-  name: "Optimism",
-  cctpDomain: 2,
-};
-
-export const polygon: Chain = {
-  type: "evm",
-  chainId: 137,
-  name: "Polygon",
-  cctpDomain: 7,
-};
-
-export const solana: Chain = {
-  type: "solana",
-  chainId: 501,
-  name: "Solana",
-  cctpDomain: 5,
-};
-
-export const stellar: Chain = {
-  type: "stellar",
-  chainId: 10001,
-  name: "Stellar",
-  cctpDomain: null,
-};
-
-export const worldchain: Chain = {
-  type: "evm",
-  chainId: 480,
-  name: "Worldchain",
-  cctpDomain: 14,
-};
-
-/**
- * Rozo Solana
- * @link https://github.com/RozoAI/rozo-payment-manager/tree/staging?tab=readme-ov-file#supported-chains-and-tokens
- */
-export const rozoSolana: Chain = {
-  type: "solana",
-  chainId: 900,
-  name: "Solana",
-  cctpDomain: 5,
-};
-
-export const rozoStellar: Chain = {
-  type: "stellar",
-  chainId: 1500,
-  name: "Stellar",
-  cctpDomain: null,
-};
-
-export const gnosis: Chain = {
-  type: "evm",
-  chainId: 100,
-  name: "Gnosis",
-  cctpDomain: null,
-};
-
-export const avalanche: Chain = {
-  type: "evm",
-  chainId: 43114,
-  name: "Avalanche",
-  cctpDomain: null,
-};
-
-/**
- * Supported chains for Near Intents cross-chain swaps
- * Based on USDC/USDT support documentation
- */
-export const supportedChains: Chain[] = [
-  // Supported for Near Intents (USDC/USDT)
-  arbitrum, // USDC & USDT
-  avalanche, // USDC & USDT
-  base, // USDC only (no USDT)
-  bsc, // USDC & USDT
-  ethereum, // USDC & USDT
-  gnosis, // USDC & USDT
-  optimism, // USDC & USDT
-  polygon, // USDC & USDT
-  worldchain,
-  solana,
-  rozoSolana, // USDC & USDT (chainId: 900)
-  rozoStellar, // USDC only (chainId: 1500, no USDT)
-
-  // Not supported for Near Intents - kept for other features
-  // celo, // Not in Near Intents docs
-  // linea, // Not in Near Intents docs
-  // mantle, // Not in Near Intents docs
-  // solana, // Use rozoSolana (900) instead of solana (501)
-  // stellar, // Use rozoStellar (1500) instead of stellar (10001)
-];
-
-// https://developers.circle.com/stablecoins/supported-domains
-const cctpV1Chains = [
-  arbitrum,
-  base,
-  ethereum,
-  optimism,
-  polygon,
-  solana,
-  rozoSolana,
-  stellar,
-  rozoStellar,
-];
-const cctpV2Chains = [arbitrum, base, ethereum, linea, worldchain];
-
-/** Given a chainId, return the chain. */
-export function getChainById(chainId: number): Chain {
-  const ret = supportedChains.find((c) => c.chainId === chainId);
-  if (ret == null) throw new Error(`Unknown chainId ${chainId}`);
-  return ret;
-}
-
-/** Returns the chain name for the given chainId. */
-export function getChainName(chainId: number): string {
-  return getChainById(chainId).name;
-}
-
-/** Returns the CCTP domain for the given chainId. */
-export function getCCTPDomain(chainId: number): number | null {
-  return getChainById(chainId).cctpDomain;
-}
-
-/** Returns true if the chain is a CCTP v1 chain. */
-export function isCCTPV1Chain(chainId: number): boolean {
-  return cctpV1Chains.some((c) => c.chainId === chainId);
-}
-
-/** Returns true if the chain is a CCTP v2 chain. */
-export function isCCTPV2Chain(chainId: number): boolean {
-  return cctpV2Chains.some((c) => c.chainId === chainId);
-}
-
-/**
- * Get block explorer URL for chain ID
- */
-export function getChainExplorerByChainId(chainId: number): string | undefined {
-  switch (chainId) {
-    case arbitrum.chainId:
-      return "https://arbiscan.io";
-    case base.chainId:
-      return "https://basescan.org";
-    case bsc.chainId:
-      return "https://bscscan.com";
-    case celo.chainId:
-      return "https://celoscan.io";
-    case ethereum.chainId:
-      return "https://etherscan.io";
-    case linea.chainId:
-      return "https://lineascan.build";
-    case mantle.chainId:
-      return "https://mantlescan.xyz";
-    case optimism.chainId:
-      return "https://optimistic.etherscan.io";
-    case polygon.chainId:
-      return "https://polygonscan.com";
-    case gnosis.chainId:
-      return "https://gnosisscan.io";
-    case avalanche.chainId:
-      return "https://snowtrace.io";
-    case solana.chainId:
-    case rozoSolana.chainId:
-      return "https://solscan.io";
-    case stellar.chainId:
-    case rozoStellar.chainId:
-      return "https://stellar.expert/explorer/public/search?term=";
-    case worldchain.chainId:
-      return "https://worldscan.org";
-    default:
-      return undefined;
-  }
-}
-
-/**
- * Get block explorer address URL for chain ID and address.
- */
-export function getChainExplorerAddressUrl(chainId: number, address: string) {
-  const explorer = getChainExplorerByChainId(chainId);
-  if (!explorer) {
-    return undefined;
-  }
-  return `${explorer}/address/${address}`;
-}
-
-/**
- * Get block explorer transaction URL for chain ID and transaction hash.
- */
-export function getChainExplorerTxUrl(chainId: number, txHash: string) {
-  const explorer = getChainExplorerByChainId(chainId);
-  if (!explorer) {
-    return undefined;
-  }
-
-  if ([stellar.chainId, rozoStellar.chainId].includes(chainId)) {
-    return `${explorer}${txHash}`;
-  }
-
-  return `${explorer}/tx/${txHash}`;
-}

package/src/debug.ts

@@ -1,14 +0,0 @@
-/** Return compact JSON, 10000 chars max. Never throws. */
-export function debugJson(obj: any) {
-  try {
-    let serialized = JSON.stringify(obj, (_, value) =>
-      typeof value === "bigint" ? value.toString() : value,
-    );
-    if (typeof serialized !== "string") {
-      serialized = "" + obj;
-    }
-    return serialized.slice(0, 10000);
-  } catch (e: any) {
-    return `<JSON error: ${e.message}>`;
-  }
-}