@funkit/api-base 0.0.1

package/src/errors/types.ts

@@ -0,0 +1,64 @@
+export type ErrorData = {
+  location: string
+  error?: {
+    txDetails?: ErrorTransactionDetails
+    reasonData?: {
+      title: string
+      reasons: string[]
+    }
+  }
+}
+
+export type ErrorTransactionDetails = {
+  method: string
+  params: any[]
+  contractAddress?: string
+  chainId?: number | string
+}
+
+export enum ErrorBaseType {
+  ClientError = 'ClientError',
+  ServerError = 'ServerError',
+}
+
+export enum ErrorType {
+  InvalidParameter = 'InvalidParameter',
+  InternalServerFailure = 'InternalServerFailure',
+  ResourceNotFound = 'ResourceNotFound',
+  InvalidAction = 'InvalidAction',
+  ThrottlingError = 'ThrottlingError',
+  AccessDeniedError = 'AccessDeniedError',
+  UserOpFailureError = 'UserOpFailureError',
+}
+
+export enum ErrorCode {
+  MissingParameter = 'MissingParameter',
+  InvalidParameter = 'InvalidParameter',
+  InvalidThreshold = 'InvalidThreshold',
+  InvalidChainIdentifier = 'InvalidChainIdentifier',
+  InvalidNFTIdentifier = 'InvalidNFTIdentifier',
+  InsufficientSignatures = 'InsufficientSignatures',
+  InvalidParameterCombination = 'InvalidParameterCombination',
+  CheckPointHintsNotFound = 'CheckPointHintsNotFound',
+  GroupNotFound = 'GroupNotFound',
+  TokenNotFound = 'TokenNotFound',
+  AddressNotFound = 'AddressNotFound',
+  UserAlreadyExists = 'UserAlreadyExists',
+  UserNotFound = 'UserNotFound',
+  ChainNotSupported = 'ChainNotSupported',
+  ServerMissingData = 'ServerMissingData',
+  ServerFailure = 'ServerFailure',
+  ServerTimeout = 'ServerTimeout',
+  UnknownServerError = 'UnknownServerError',
+  ServerConnectionError = 'ServerConnectionError',
+  UserOpFailureError = 'UserOpFailureError',
+  Unauthorized = 'Unauthorized',
+  RequestLimitExceeded = 'RequestLimitExceeded',
+  WalletPrefundError = 'PrefundError',
+  GasSponsorFundError = 'GasSponsorFundError',
+  FunWalletErrorCode = 'FunWalletErrorCode',
+  BridgeRouteNotFound = 'BridgeRouteNotFound',
+  BridgeAllowanceDataNotFound = 'BridgeAllowanceDataNotFound',
+  BridgeApproveTxDataNotFound = 'BridgeApproveTxDataNotFound',
+  CheckoutInitDepositAddrNotFound = 'CheckoutInitDepositAddrNotFound',
+}

package/src/services/assets/endpoints.ts

@@ -0,0 +1,131 @@
+import { API_BASE_URL } from '../../consts'
+import { sendGetRequest } from '../../utils'
+import {
+  GetAllWalletNFTsByChainIdRequest,
+  GetAllWalletNFTsByChainIdResponse,
+  GetAllWalletNFTsRequest,
+  GetAllWalletNFTsResponse,
+  GetAllWalletTokensByChainIdRequest,
+  GetAllWalletTokensByChainIdResponse,
+  GetAllWalletTokensRequest,
+  GetAllWalletTokensResponse,
+  GetAssetPriceInfoRequest,
+  GetAssetPriceInfoResponse,
+  GetWalletLidoWithdrawalsByChainId,
+  GetWalletLidoWithdrawalsByChainIdResponse,
+} from './types'
+
+/**===========================================================
+ * REFERENCE CORE FILE: /packages/core/src/apis/AssetApis.ts
+ * TODO: Remove this comment once migration is complete
+ *===========================================================*/
+
+/**
+ * Gets the estimated dollar unit price of a tokenAddress for checkout
+ * @param chainId https://chainlist.org/ e.g. "1" for ethereum
+ * @param assetTokenAddress tokenAddress of the asset on the given chain
+ * @param apiKey
+ */
+export async function getAssetPriceInfo({
+  chainId,
+  assetTokenAddress,
+  apiKey,
+}: GetAssetPriceInfoRequest): Promise<GetAssetPriceInfoResponse> {
+  const priceInfo = await sendGetRequest({
+    uri: `${API_BASE_URL}/asset/erc20/price/${chainId}/${assetTokenAddress}`,
+    apiKey,
+    retryOptions: { maxAttempts: 2 },
+  })
+  return priceInfo
+}
+
+/**
+ * Get all tokens for a given wallet address
+ * @param walletAddress
+ * @param onlyVerifiedTokens If true, only return alchemy tokens that are verified(filters spam)
+ * @param apiKey
+ */
+export async function getAllWalletTokens({
+  walletAddress,
+  onlyVerifiedTokens,
+  apiKey,
+}: GetAllWalletTokensRequest): Promise<GetAllWalletTokensResponse> {
+  return await sendGetRequest({
+    uri: `${API_BASE_URL}/assets/erc20s/${walletAddress}?onlyVerifiedTokens=${onlyVerifiedTokens}`,
+    apiKey,
+    retryOptions: { maxAttempts: 2 },
+  })
+}
+
+/**
+ * Get all tokens for a given wallet address on a specific chain
+ * @param chainId https://chainlist.org/
+ * @param walletAddress
+ * @param onlyVerifiedTokens If true, only return alchemy tokens that are verified(filters spam)
+ * @param apiKey
+ */
+export async function getAllWalletTokensByChainId({
+  chainId,
+  walletAddress,
+  onlyVerifiedTokens,
+  apiKey,
+}: GetAllWalletTokensByChainIdRequest): Promise<GetAllWalletTokensByChainIdResponse> {
+  return await sendGetRequest({
+    uri: `${API_BASE_URL}/assets/erc20s/${walletAddress}/${chainId}?onlyVerifiedTokens=${onlyVerifiedTokens}`,
+    apiKey,
+    retryOptions: { maxAttempts: 2 },
+  })
+}
+
+/**=======================
+ * POTENTIAL DEPRECATION
+ *=======================*/
+
+/**
+ * Get all the NFTs owned by a wallet
+ * @param walletAddress
+ * @param apiKey
+ */
+export async function getAllWalletNFTs({
+  walletAddress,
+  apiKey,
+}: GetAllWalletNFTsRequest): Promise<GetAllWalletNFTsResponse> {
+  return await sendGetRequest({
+    uri: `${API_BASE_URL}/assets/nfts/${walletAddress}`,
+    apiKey,
+  })
+}
+
+/**
+ * Get all the NFTs owned by a wallet on a specific chain
+ * @param chainId From https://chainlist.org/
+ * @param walletAddress Address of holder
+ * @param apiKey
+ */
+export async function getAllWalletNFTsByChainId({
+  chainId,
+  walletAddress,
+  apiKey,
+}: GetAllWalletNFTsByChainIdRequest): Promise<GetAllWalletNFTsByChainIdResponse> {
+  return await sendGetRequest({
+    uri: `${API_BASE_URL}/assets/nfts/${walletAddress}/${chainId}`,
+    apiKey,
+  })
+}
+
+/**
+ * Get all lido withdrawal request ids for a wallet address on a specific chain
+ * @param {string} chainId https://chainlist.org/ ie "1" for ethereum
+ * @param {string} holderAddr Address of holder
+ * @returns [readyToWithdrawRequestIds, notReadyToWithdrawRequestIds]
+ */
+export async function getWalletLidoWithdrawalsByChainId({
+  chainId,
+  walletAddress,
+  apiKey,
+}: GetWalletLidoWithdrawalsByChainId): Promise<GetWalletLidoWithdrawalsByChainIdResponse> {
+  return await sendGetRequest({
+    uri: `${API_BASE_URL}/assets/lido-withdrawals/${walletAddress}/${chainId}`,
+    apiKey,
+  })
+}

package/src/services/assets/index.ts

@@ -0,0 +1,2 @@
+export * from './endpoints'
+export * from './types'

package/src/services/assets/types.ts

@@ -0,0 +1,80 @@
+export interface GetAssetPriceInfoRequest {
+  chainId: string
+  assetTokenAddress: string
+  apiKey: string
+}
+
+interface AssetPriceInfo {
+  unitPrice: number
+  amount: number
+  total: number
+}
+
+export type GetAssetPriceInfoResponse = AssetPriceInfo
+
+export interface GetAllWalletTokensRequest {
+  walletAddress: string
+  onlyVerifiedTokens: boolean
+  apiKey: string
+}
+
+interface AssetBalanceInfo {
+  chainId: string
+  contractAddress: string
+  decimals: number
+  logo: string
+  name: string
+  price: number | null
+  symbol: string
+  tokenBalance: string
+  totalUsdValue: number | null
+}
+
+interface ChainAssetBalanceInfo {
+  [tokenAddress: string]: AssetBalanceInfo
+}
+
+export interface GetAllWalletTokensResponse {
+  [chainId: number]: ChainAssetBalanceInfo
+}
+
+export interface GetAllWalletTokensByChainIdRequest {
+  chainId: string
+  walletAddress: string
+  onlyVerifiedTokens: boolean
+  apiKey: string
+}
+
+export type GetAllWalletTokensByChainIdResponse = ChainAssetBalanceInfo
+
+export interface GetAllWalletNFTsRequest {
+  walletAddress: string
+  apiKey: string
+}
+
+interface ChainNFTInfo {
+  address: string
+  token_id: string
+  floor_price: string
+}
+
+export interface GetAllWalletNFTsResponse {
+  [chainId: string]: ChainNFTInfo[]
+}
+
+export interface GetAllWalletNFTsByChainIdRequest {
+  chainId: string
+  walletAddress: string
+  apiKey: string
+}
+
+export type GetAllWalletNFTsByChainIdResponse = ChainNFTInfo[]
+
+export interface GetWalletLidoWithdrawalsByChainId {
+  chainId: string
+  walletAddress: string
+  apiKey: string
+}
+
+// [readyToWithdrawRequestIds, notReadyToWithdrawRequestIds]
+export type GetWalletLidoWithdrawalsByChainIdResponse = [number[], number[]]

package/src/services/checkout/endpoints.ts

@@ -0,0 +1,233 @@
+import Big from 'big.js'
+import { Address } from 'viem'
+
+import { API_BASE_URL } from '../../consts'
+import { ErrorCode, ResourceNotFoundError } from '../../errors'
+import {
+  generateRandomCheckoutSalt,
+  roundToNearestBottomTenth,
+  sendGetRequest,
+  sendPostRequest,
+} from '../../utils'
+import {
+  CheckoutApiInitParams,
+  CheckoutApiQuoteParams,
+  CheckoutApiQuoteResponse,
+  CheckoutHistoryItem,
+  CheckoutInitParams,
+  CheckoutInitResponse,
+  CheckoutQuoteParams,
+  CheckoutQuoteResponse,
+  CheckoutTransferSponsorshipApiParams,
+  CheckoutTransferSponsorshipParams,
+  CheckoutTransferSponsorshipResponse,
+} from './types'
+
+/**
+ * Gets a checkout quote (estimation).
+ * @param fromChainId The ID of the chain where funds will be provided from.
+ * @param fromTokenAddress The asset to fund the checkout. This must be either a chain native token or an ERC-20, on the fromChainId.
+ * @param fromTokenDecimals The number of decimals for the fromTokenAddress.
+ * @param toChainId The ID of the chain where the checkout operation is to be performed.
+ * @param toTokenAddress The wanted asset for the checkout operation. This must be either a chain native token or an ERC-20, on the target chain.
+ * @param toTokenAmount The amount of wanted asset for the checkout operation in base units.
+ * @param toTokenDecimals The number of decimals for the toTokenAddress.
+ * @param expirationTimestampMs The amount of time (duration) from now before the checkout operation expires.
+ * @param apiKey A valid fun api key.
+ * @return {Promise<CheckoutCoreQuoteResponse>} The formatted quote object
+ */
+export async function getCheckoutQuote({
+  fromChainId,
+  fromTokenAddress,
+  fromTokenDecimals,
+  toChainId,
+  toTokenAddress,
+  toTokenDecimals,
+  toTokenAmount,
+  expirationTimestampMs,
+  sponsorInitialTransferGasLimit,
+  recipientAddr,
+  needsRefuel,
+  apiKey,
+}: CheckoutQuoteParams): Promise<CheckoutQuoteResponse> {
+  try {
+    const toMultipler = 10 ** toTokenDecimals
+    const toAmountBaseUnitBI = BigInt(Math.floor(toTokenAmount * toMultipler))
+    const queryParams = {
+      fromChainId,
+      fromTokenAddress,
+      toChainId,
+      toTokenAddress,
+      toAmountBaseUnit: toAmountBaseUnitBI.toString(),
+      // Only pass in recipientAddr if specified
+      ...(recipientAddr ? { recipientAddr } : {}),
+      // Rounding nearest tenth second (instead of seconds) to better support backend quote caching feature
+      // Reference: https://vintage-heaven-3cd.notion.site/API-Gateway-Caching-and-Pre-Warming-System-Draft-ee7909d9b85f43c793ce7bd2607bec02?pvs=4
+      // Note: Rounding *down* instead of a regular round to safeguard against edge case of timing passing frontend range validation but failing backend range validation
+      checkoutExpirationTimestampSeconds: roundToNearestBottomTenth(
+        Math.round((Date.now() + expirationTimestampMs) / 1000),
+      ).toString(),
+      sponsorInitialTransferGasLimit,
+      refuel: needsRefuel.toString(),
+    } as CheckoutApiQuoteParams
+
+    const searchParams = new URLSearchParams(queryParams)
+    const quoteRes = (await sendGetRequest({
+      uri: `${API_BASE_URL}/checkout/quote?${searchParams}`,
+      apiKey,
+    })) as CheckoutApiQuoteResponse
+
+    const fromMultipler = 10 ** fromTokenDecimals
+    // Format the response for frontend usage
+    return {
+      quoteId: quoteRes.quoteId,
+      fromTokenAddress: quoteRes.fromTokenAddress,
+      estFeesUsd: quoteRes.estFeesUsd,
+      estSubtotalUsd: quoteRes.estSubtotalUsd,
+      estTotalUsd: quoteRes.estTotalUsd,
+      estCheckoutTimeMs: quoteRes.estCheckoutTimeMs,
+      estTotalFromAmountBaseUnit: quoteRes.estTotalFromAmountBaseUnit,
+      estSubtotalFromAmountBaseUnit: quoteRes.estSubtotalFromAmountBaseUnit,
+      estFeesFromAmountBaseUnit: quoteRes.estFeesFromAmountBaseUnit,
+      // Added fields
+      estFeesFromAmount: new Big(quoteRes.estFeesFromAmountBaseUnit)
+        .div(fromMultipler)
+        .toString(),
+      estSubtotalFromAmount: new Big(quoteRes.estSubtotalFromAmountBaseUnit)
+        .div(fromMultipler)
+        .toString(),
+      estTotalFromAmount: new Big(quoteRes.estTotalFromAmountBaseUnit)
+        .div(fromMultipler)
+        .toString(),
+    } as CheckoutQuoteResponse
+  } catch (err: any) {
+    throw new Error(
+      `An error occured trying to generate a checkout quote: ${err.message}`,
+    )
+  }
+}
+
+/**
+ * Initializes a checkout
+ * @param userOp The checkout UserOp, signed.
+ * @param quoteId The quoteId specific to the checkout.
+ * @param apiKey A valid fun api key.
+ * @return {Address} The generated deposit address
+ */
+export async function initializeCheckout({
+  userOp,
+  quoteId,
+  sourceOfFund,
+  apiKey,
+  clientMetadata,
+}: CheckoutInitParams): Promise<Address> {
+  const body = {
+    ...(userOp ? { userOp } : {}),
+    quoteId,
+    sourceOfFund,
+    salt: generateRandomCheckoutSalt(),
+    clientMetadata,
+  } as CheckoutApiInitParams
+  const res = await sendPostRequest({
+    uri: `${API_BASE_URL}/checkout`,
+    body,
+    apiKey,
+  })
+  if (!res?.depositAddr) {
+    throw new ResourceNotFoundError(
+      ErrorCode.CheckoutInitDepositAddrNotFound,
+      'Unable to initialize checkout',
+      body,
+      '',
+      'https://docs.fun.xyz',
+    )
+  }
+  return res.depositAddr as CheckoutInitResponse
+}
+
+/**
+ * Gets a checkout given a depositAddress
+ * @param depositAddress A unique deposit address associated with a backend checkout item.
+ * @param apiKey A valid fun api key.
+ * @returns The checkout object if exists. Otherwise, null.
+ */
+export async function getCheckoutByDepositAddress({
+  depositAddress,
+  apiKey,
+}: {
+  depositAddress: Address
+  apiKey: string
+}): Promise<CheckoutHistoryItem | null> {
+  try {
+    return await sendGetRequest({
+      uri: `${API_BASE_URL}/checkout/${depositAddress}`,
+      apiKey,
+    })
+  } catch (err) {
+    if (err instanceof ResourceNotFoundError) {
+      return null
+    }
+    throw err
+  }
+}
+
+/**
+ * Gets all checkouts associated with a funWallet
+ * @param funWalletAddress A funWallet address.
+ * @param apiKey A valid fun api key.
+ * @returns A list of checkout objects if exists. Otherwise, an empty array.
+ */
+export async function getCheckoutsByFunWalletAddress({
+  funWalletAddress,
+  apiKey,
+}: {
+  funWalletAddress: Address
+  apiKey: string
+}): Promise<CheckoutHistoryItem[]> {
+  const res = await sendGetRequest({
+    uri: `${API_BASE_URL}/checkout/fun-wallet/${funWalletAddress}`,
+    apiKey,
+  })
+  return res || []
+}
+
+/**
+ * Gets all checkouts associated with a recipient address
+ * @param recipientAddress A wallet address.
+ * @param apiKey A valid fun api key.
+ * @returns A list of checkout objects if exists. Otherwise, an empty array.
+ */
+export async function getCheckoutsByRecipientAddress({
+  recipientAddress,
+  apiKey,
+}: {
+  recipientAddress: Address
+  apiKey: string
+}): Promise<CheckoutHistoryItem[]> {
+  const res = await sendGetRequest({
+    uri: `${API_BASE_URL}/checkout/recipient/${recipientAddress}`,
+    apiKey,
+  })
+  return res || []
+}
+
+export async function getPaymasterDataForCheckoutSponsoredTransfer({
+  depositAddress,
+  transferUserOp,
+  apiKey,
+}: CheckoutTransferSponsorshipParams): Promise<CheckoutTransferSponsorshipResponse> {
+  const body = {
+    depositAddress,
+    userOp: transferUserOp,
+  } as CheckoutTransferSponsorshipApiParams
+  const res = await sendPostRequest({
+    uri: `${API_BASE_URL}/checkout/sponsorship`,
+    body,
+    apiKey,
+  })
+  if (!res) {
+    // TODO: Better error handling
+    throw new Error('Unable to get sponsorship information')
+  }
+  return res as CheckoutTransferSponsorshipResponse
+}

package/src/services/checkout/index.ts

@@ -0,0 +1,2 @@
+export * from './endpoints'
+export * from './types'

package/src/services/checkout/types.ts

@@ -0,0 +1,130 @@
+/**===============*
+ * CHECKOUT QUOTE *
+ *================*/
+import { Address, Hex } from 'viem'
+
+// TODO: Define the UserOperation type
+type UserOperation = any
+
+// The params required for the actual /checkout/quote api
+export type CheckoutApiQuoteParams = {
+  fromChainId: string
+  fromTokenAddress: Address
+  toChainId: string
+  toTokenAddress: Address
+  toAmountBaseUnit: string
+  checkoutExpirationTimestampSeconds: string
+  sponsorInitialTransferGasLimit: string
+  refuel: string
+  recipientAddr?: Address
+}
+
+export type CheckoutQuoteParams = Omit<
+  CheckoutApiQuoteParams,
+  'toAmountBaseUnit' | 'checkoutExpirationTimestampSeconds' | 'refuel'
+> & {
+  fromTokenDecimals: number
+  toTokenDecimals: number
+  toTokenAmount: number
+  expirationTimestampMs: number
+  needsRefuel: boolean
+  apiKey: string
+}
+
+// The response of the actual /checkout/quote api
+export type CheckoutApiQuoteResponse = {
+  quoteId: string
+  estTotalFromAmountBaseUnit: string
+  estSubtotalFromAmountBaseUnit: string
+  estFeesFromAmountBaseUnit: string
+  fromTokenAddress: Address
+  estFeesUsd: number
+  estSubtotalUsd: number
+  estTotalUsd: number
+  estCheckoutTimeMs: number
+}
+
+// The formatted response quote interface from the core sdk
+export type CheckoutQuoteResponse = CheckoutApiQuoteResponse & {
+  estTotalFromAmount: string
+  estSubtotalFromAmount: string
+  estFeesFromAmount: string
+}
+
+/**===============*
+ * CHECKOUT INIT  *
+ *================*/
+
+export type CheckoutApiInitParams = {
+  userOp?: UserOperation
+  quoteId: string
+  sourceOfFund: string
+  salt: bigint
+  clientMetadata: object
+}
+
+export type CheckoutInitParams = Omit<CheckoutApiInitParams, 'salt'> & {
+  apiKey: string
+}
+
+export type CheckoutInitResponse = Address
+
+// Reference from api server: https://github.com/fun-xyz/fun-api-server/blob/main/src/tables/FunWalletCheckout.ts#L11C1-L21C2
+export enum CheckoutState {
+  // In-progress States
+  FROM_UNFUNDED = 'FROM_UNFUNDED',
+  FROM_FUNDED = 'FROM_FUNDED',
+  FROM_POOLED = 'FROM_POOLED',
+  TO_UNFUNDED = 'TO_UNFUNDED',
+  TO_FUNDED = 'TO_FUNDED',
+  TO_POOLED = 'TO_POOLED',
+  TO_READY = 'TO_READY',
+  PENDING_RECEIVAL = 'PENDING_RECEIVAL',
+  // Terminal States
+  COMPLETED = 'COMPLETED',
+  CHECKOUT_ERROR = 'CHECKOUT_ERROR',
+  EXPIRED = 'EXPIRED',
+}
+
+export type CheckoutHistoryItem = {
+  createdTimeMs: number
+  depositAddr: Address
+  currentDepositAddr: Address
+  recipientAddr: Address
+  expirationTimestampSeconds: number
+  fromAmountBaseUnit: string
+  fromChainId: string
+  fromTokenAddress: Address
+  funWalletAddr: Address
+  lastUpdatedTimeMs: number
+  salt: Hex
+  state: CheckoutState
+  toAmountBaseUnit: string
+  toChainId: string
+  toTokenAddress: Address
+  userOp: UserOperation
+  version: number
+  clientMetadata: object
+}
+
+/**===============================*
+ * CHECKOUT TRANSFER SPONSORSHIP  *
+ *================================*/
+
+export type CheckoutTransferSponsorshipParams = {
+  transferUserOp: UserOperation
+  depositAddress: Address
+  apiKey: string
+}
+
+export type CheckoutTransferSponsorshipApiParams = {
+  userOp: UserOperation
+  depositAddress: Address
+}
+
+export type CheckoutTransferSponsorshipResponse = {
+  signerAddress: Address
+  signature: Hex
+  deadline: number
+  paymasterAndData: Hex
+}

package/src/services/index.ts

@@ -0,0 +1,4 @@
+export * from './assets'
+export * from './checkout'
+export * from './mesh'
+export * from './moonpay'