@vetro-protocol/gateway 1.0.0-beta

package/src/actions/wallet/redeem.ts

@@ -0,0 +1,321 @@
+import { EventEmitter } from "events";
+import { toPromiseEvent } from "to-promise-event";
+import {
+  type Address,
+  type TransactionReceipt,
+  type WalletClient,
+  encodeFunctionData,
+  isAddress,
+  isAddressEqual,
+  zeroAddress,
+} from "viem";
+import { waitForTransactionReceipt, writeContract } from "viem/actions";
+import { allowance, approve } from "viem-erc20/actions";
+
+import { gatewayAbi } from "../../abi/gatewayAbi.js";
+import type { RedeemEvents } from "../../types.js";
+import { getMaxWithdraw } from "../public/getMaxWithdraw.js";
+import { getPeggedToken } from "../public/getPeggedToken.js";
+import { getWithdrawalDelayEnabled } from "../public/getWithdrawalDelayEnabled.js";
+import { isInstantRedeemWhitelisted } from "../public/isInstantRedeemWhitelisted.js";
+
+export type RedeemParams = {
+  approveAmount?: bigint;
+  gatewayAddress: Address;
+  minAmountOut: bigint;
+  peggedTokenIn: bigint;
+  receiver: Address;
+  tokenOut: Address;
+};
+
+const canRedeem = async function ({
+  approveAmount,
+  client,
+  gatewayAddress,
+  minAmountOut,
+  peggedTokenIn,
+  receiver,
+  tokenOut,
+}: {
+  approveAmount: bigint;
+  client: WalletClient;
+  gatewayAddress: Address;
+  minAmountOut: bigint;
+  peggedTokenIn: bigint;
+  receiver: Address;
+  tokenOut: Address;
+}): Promise<{
+  canRedeem: boolean;
+  reason?: string;
+}> {
+  // Validate client
+  if (!client) {
+    return {
+      canRedeem: false,
+      reason: "Client is not defined",
+    };
+  }
+  if (!client.chain) {
+    return {
+      canRedeem: false,
+      reason: "Chain is not defined on wallet client",
+    };
+  }
+  // Validate client has required properties
+  if (!client.account) {
+    return {
+      canRedeem: false,
+      reason: "Client must have an account",
+    };
+  }
+  // Validate gateway address
+  if (!gatewayAddress || !isAddress(gatewayAddress)) {
+    return {
+      canRedeem: false,
+      reason: "Invalid gateway address",
+    };
+  }
+  if (isAddressEqual(gatewayAddress, zeroAddress)) {
+    return {
+      canRedeem: false,
+      reason: "Gateway address cannot be zero address",
+    };
+  }
+  // Validate tokenOut address
+  if (!tokenOut || !isAddress(tokenOut)) {
+    return {
+      canRedeem: false,
+      reason: "Invalid token address",
+    };
+  }
+  if (isAddressEqual(tokenOut, zeroAddress)) {
+    return {
+      canRedeem: false,
+      reason: "Token address cannot be zero address",
+    };
+  }
+
+  // Validate receiver address
+  if (!receiver || !isAddress(receiver)) {
+    return {
+      canRedeem: false,
+      reason: "Invalid receiver address",
+    };
+  }
+  if (isAddressEqual(receiver, zeroAddress)) {
+    return {
+      canRedeem: false,
+      reason: "Receiver address cannot be zero address",
+    };
+  }
+
+  // Validate peggedTokenIn
+  if (typeof peggedTokenIn !== "bigint") {
+    return {
+      canRedeem: false,
+      reason: "Amount must be a bigint",
+    };
+  }
+  if (peggedTokenIn <= 0n) {
+    return {
+      canRedeem: false,
+      reason: "Amount must be greater than 0",
+    };
+  }
+
+  // Validate minAmountOut
+  if (typeof minAmountOut !== "bigint") {
+    return {
+      canRedeem: false,
+      reason: "Minimum output must be a bigint",
+    };
+  }
+  if (minAmountOut < 0n) {
+    return {
+      canRedeem: false,
+      reason: "Minimum output cannot be negative",
+    };
+  }
+  // Validate approveAmount
+  if (approveAmount < peggedTokenIn) {
+    return {
+      canRedeem: false,
+      reason: "Approve amount must be greater than or equal to amount",
+    };
+  }
+
+  // Check treasury has enough balance for the requested token
+  const maxWithdrawable = await getMaxWithdraw(client, {
+    address: gatewayAddress,
+    tokenOut,
+  });
+
+  if (minAmountOut > maxWithdrawable) {
+    return {
+      canRedeem: false,
+      reason: "Not enough balance in treasury",
+    };
+  }
+
+  return { canRedeem: true };
+};
+
+const runRedeem = (
+  walletClient: WalletClient,
+  {
+    approveAmount,
+    gatewayAddress,
+    minAmountOut,
+    peggedTokenIn,
+    receiver,
+    tokenOut,
+  }: RedeemParams,
+) =>
+  async function (emitter: EventEmitter<RedeemEvents>) {
+    const resolvedApproveAmount = approveAmount ?? peggedTokenIn;
+    try {
+      const { canRedeem: canRedeemFlag, reason } = await canRedeem({
+        approveAmount: resolvedApproveAmount,
+        client: walletClient,
+        gatewayAddress,
+        minAmountOut,
+        peggedTokenIn,
+        receiver,
+        tokenOut,
+      });
+
+      if (!canRedeemFlag) {
+        emitter.emit("redeem-failed-validation", reason!);
+        return;
+      }
+
+      // Check if user is whitelisted for instant redeem
+      const [isWhitelisted, delayEnabled] = await Promise.all([
+        isInstantRedeemWhitelisted(walletClient, {
+          account: walletClient.account!.address,
+          address: gatewayAddress,
+        }),
+        getWithdrawalDelayEnabled(walletClient, {
+          address: gatewayAddress,
+        }),
+      ]);
+
+      // Approval is needed when the user is whitelisted (instant redeem burns pegged tokens)
+      // or when delay is disabled (redeem completes immediately)
+      if (isWhitelisted || !delayEnabled) {
+        // Get the pegged token address
+        const peggedTokenAddress = await getPeggedToken(walletClient, {
+          address: gatewayAddress,
+        });
+
+        // Check current allowance for pegged token
+        const currentAllowance = await allowance(walletClient, {
+          address: peggedTokenAddress,
+          owner: walletClient.account!.address,
+          spender: gatewayAddress,
+        });
+
+        // If allowance is insufficient, approve first
+        if (currentAllowance < peggedTokenIn) {
+          emitter.emit("pre-approve");
+
+          const approvalHash = await approve(walletClient, {
+            address: peggedTokenAddress,
+            amount: resolvedApproveAmount,
+            spender: gatewayAddress,
+          }).catch(function (error: Error) {
+            emitter.emit("user-signing-approval-error", error);
+          });
+
+          if (!approvalHash) {
+            return;
+          }
+
+          emitter.emit("user-signed-approval", approvalHash);
+
+          const approvalReceipt = await waitForTransactionReceipt(
+            walletClient,
+            {
+              hash: approvalHash,
+            },
+          ).catch(function (error: Error) {
+            emitter.emit("redeem-failed", error);
+          });
+
+          if (!approvalReceipt) {
+            return;
+          }
+
+          if (approvalReceipt.status === "reverted") {
+            emitter.emit("approve-transaction-reverted", approvalReceipt);
+            return;
+          }
+
+          emitter.emit("approve-transaction-succeeded", approvalReceipt);
+        }
+      }
+
+      emitter.emit("pre-redeem");
+
+      const redeemHash = await writeContract(walletClient, {
+        abi: gatewayAbi,
+        account: walletClient.account!,
+        address: gatewayAddress,
+        args: [tokenOut, peggedTokenIn, minAmountOut, receiver],
+        chain: walletClient.chain,
+        functionName: "redeem",
+      }).catch(function (error: Error) {
+        emitter.emit("user-signing-redeem-error", error);
+      });
+
+      if (!redeemHash) {
+        return;
+      }
+
+      emitter.emit("user-signed-redeem", redeemHash);
+
+      const redeemReceipt = await waitForTransactionReceipt(walletClient, {
+        hash: redeemHash,
+      }).catch(function (error: Error) {
+        emitter.emit("redeem-failed", error);
+      });
+
+      if (!redeemReceipt) {
+        return;
+      }
+
+      const redeemEventMap: Record<
+        TransactionReceipt["status"],
+        keyof RedeemEvents
+      > = {
+        reverted: "redeem-transaction-reverted",
+        success: "redeem-transaction-succeeded",
+      };
+
+      emitter.emit(redeemEventMap[redeemReceipt.status], redeemReceipt);
+    } catch (error) {
+      emitter.emit("unexpected-error", error as Error);
+    } finally {
+      emitter.emit("redeem-settled");
+    }
+  };
+
+export const redeem = (...args: Parameters<typeof runRedeem>) =>
+  toPromiseEvent<RedeemEvents>(runRedeem(...args));
+
+export const encodeRedeem = ({
+  minAmountOut,
+  peggedTokenIn,
+  receiver,
+  tokenOut,
+}: {
+  minAmountOut: bigint;
+  peggedTokenIn: bigint;
+  receiver: Address;
+  tokenOut: Address;
+}) =>
+  encodeFunctionData({
+    abi: gatewayAbi,
+    args: [tokenOut, peggedTokenIn, minAmountOut, receiver],
+    functionName: "redeem",
+  });

package/src/actions/wallet/requestRedeem.ts

@@ -0,0 +1,226 @@
+import { EventEmitter } from "events";
+import { toPromiseEvent } from "to-promise-event";
+import {
+  type Address,
+  type TransactionReceipt,
+  type WalletClient,
+  encodeFunctionData,
+  isAddress,
+  isAddressEqual,
+  zeroAddress,
+} from "viem";
+import { waitForTransactionReceipt, writeContract } from "viem/actions";
+import { allowance, approve } from "viem-erc20/actions";
+
+import { gatewayAbi } from "../../abi/gatewayAbi.js";
+import type { RequestRedeemEvents } from "../../types.js";
+import { getPeggedToken } from "../public/getPeggedToken.js";
+
+export type RequestRedeemParams = {
+  approveAmount?: bigint;
+  gatewayAddress: Address;
+  peggedTokenAmount: bigint;
+};
+
+const canRequestRedeem = function ({
+  approveAmount,
+  client,
+  gatewayAddress,
+  peggedTokenAmount,
+}: {
+  approveAmount: bigint;
+  client: WalletClient;
+  gatewayAddress: Address;
+  peggedTokenAmount: bigint;
+}): {
+  canRequestRedeem: boolean;
+  reason?: string;
+} {
+  if (!client) {
+    return {
+      canRequestRedeem: false,
+      reason: "Client is not defined",
+    };
+  }
+  if (!client.chain) {
+    return {
+      canRequestRedeem: false,
+      reason: "Chain is not defined on wallet client",
+    };
+  }
+  if (!client.account) {
+    return {
+      canRequestRedeem: false,
+      reason: "Client must have an account",
+    };
+  }
+  // Validate gateway address
+  if (!gatewayAddress || !isAddress(gatewayAddress)) {
+    return {
+      canRequestRedeem: false,
+      reason: "Invalid gateway address",
+    };
+  }
+  if (isAddressEqual(gatewayAddress, zeroAddress)) {
+    return {
+      canRequestRedeem: false,
+      reason: "Gateway address cannot be zero address",
+    };
+  }
+
+  if (typeof peggedTokenAmount !== "bigint") {
+    return {
+      canRequestRedeem: false,
+      reason: "Amount must be a bigint",
+    };
+  }
+  if (peggedTokenAmount <= 0n) {
+    return {
+      canRequestRedeem: false,
+      reason: "Amount must be greater than 0",
+    };
+  }
+
+  // Validate approveAmount
+  if (approveAmount < peggedTokenAmount) {
+    return {
+      canRequestRedeem: false,
+      reason: "Approve amount must be greater than or equal to amount",
+    };
+  }
+
+  return { canRequestRedeem: true };
+};
+
+const runRequestRedeem = (
+  walletClient: WalletClient,
+  { approveAmount, gatewayAddress, peggedTokenAmount }: RequestRedeemParams,
+) =>
+  async function (emitter: EventEmitter<RequestRedeemEvents>) {
+    const resolvedApproveAmount = approveAmount ?? peggedTokenAmount;
+    try {
+      const { canRequestRedeem: canRequestRedeemFlag, reason } =
+        canRequestRedeem({
+          approveAmount: resolvedApproveAmount,
+          client: walletClient,
+          gatewayAddress,
+          peggedTokenAmount,
+        });
+
+      if (!canRequestRedeemFlag) {
+        emitter.emit("request-redeem-failed-validation", reason!);
+        return;
+      }
+
+      // Get the pegged token address
+      const peggedTokenAddress = await getPeggedToken(walletClient, {
+        address: gatewayAddress,
+      });
+
+      // Check current allowance for pegged token
+      const currentAllowance = await allowance(walletClient, {
+        address: peggedTokenAddress,
+        owner: walletClient.account!.address,
+        spender: gatewayAddress,
+      });
+
+      // If allowance is insufficient, approve first
+      if (currentAllowance < peggedTokenAmount) {
+        emitter.emit("pre-approve");
+
+        const approvalHash = await approve(walletClient, {
+          address: peggedTokenAddress,
+          amount: resolvedApproveAmount,
+          spender: gatewayAddress,
+        }).catch(function (error: Error) {
+          emitter.emit("user-signing-approval-error", error);
+        });
+
+        if (!approvalHash) {
+          return;
+        }
+
+        emitter.emit("user-signed-approval", approvalHash);
+
+        const approvalReceipt = await waitForTransactionReceipt(walletClient, {
+          hash: approvalHash,
+        }).catch(function (error: Error) {
+          emitter.emit("request-redeem-failed", error);
+        });
+
+        if (!approvalReceipt) {
+          return;
+        }
+
+        if (approvalReceipt.status === "reverted") {
+          emitter.emit("approve-transaction-reverted", approvalReceipt);
+          return;
+        }
+
+        emitter.emit("approve-transaction-succeeded", approvalReceipt);
+      }
+
+      emitter.emit("pre-request-redeem");
+
+      const requestRedeemHash = await writeContract(walletClient, {
+        abi: gatewayAbi,
+        account: walletClient.account!,
+        address: gatewayAddress,
+        args: [peggedTokenAmount],
+        chain: walletClient.chain,
+        functionName: "requestRedeem",
+      }).catch(function (error: Error) {
+        emitter.emit("user-signing-request-redeem-error", error);
+      });
+
+      if (!requestRedeemHash) {
+        return;
+      }
+
+      emitter.emit("user-signed-request-redeem", requestRedeemHash);
+
+      const requestRedeemReceipt = await waitForTransactionReceipt(
+        walletClient,
+        {
+          hash: requestRedeemHash,
+        },
+      ).catch(function (error: Error) {
+        emitter.emit("request-redeem-failed", error);
+      });
+
+      if (!requestRedeemReceipt) {
+        return;
+      }
+
+      const requestRedeemEventMap: Record<
+        TransactionReceipt["status"],
+        keyof RequestRedeemEvents
+      > = {
+        reverted: "request-redeem-transaction-reverted",
+        success: "request-redeem-transaction-succeeded",
+      };
+
+      emitter.emit(
+        requestRedeemEventMap[requestRedeemReceipt.status],
+        requestRedeemReceipt,
+      );
+    } catch (error) {
+      emitter.emit("unexpected-error", error as Error);
+    } finally {
+      emitter.emit("request-redeem-settled");
+    }
+  };
+
+export const requestRedeem = (...args: Parameters<typeof runRequestRedeem>) =>
+  toPromiseEvent<RequestRedeemEvents>(runRequestRedeem(...args));
+
+export const encodeRequestRedeem = ({
+  peggedTokenAmount,
+}: {
+  peggedTokenAmount: bigint;
+}) =>
+  encodeFunctionData({
+    abi: gatewayAbi,
+    args: [peggedTokenAmount],
+    functionName: "requestRedeem",
+  });

package/src/gatewayAddresses.ts

@@ -0,0 +1,27 @@
+import type { Address } from "viem";
+
+export type Gateway = {
+  address: Address;
+  // Portal-API symbol used to convert this gateway's peg unit into USD.
+  // "USD" is treated as identity (no conversion needed).
+  pegBaseSymbol: string;
+};
+
+// Whitelisted-token oracles within a gateway are denominated in the gateway's
+// peg unit (e.g. WBTC/BTC for the vetBTC gateway, USDT/USD for the VUSD gateway),
+// so the USD price for any whitelisted token is `oracle × portal[pegBaseSymbol]`.
+// See `web/src/fetchers/fetchPrices.ts` for the merge.
+export const gateways: Gateway[] = [
+  // VUSD
+  {
+    address: "0xDaD503f8B9d42bb7af3AfC588358D30163e4416F",
+    pegBaseSymbol: "USD",
+  },
+  // vetBTC
+  {
+    address: "0xCBA2Ffa0AC52d7871a4221a871793Eb788013faB",
+    pegBaseSymbol: "BTC",
+  },
+];
+
+export const gatewayAddresses: Address[] = gateways.map((g) => g.address);

package/src/index.ts

@@ -0,0 +1,79 @@
+import type { Client, WalletClient } from "viem";
+
+import {
+  getMaxWithdraw,
+  getMintFee,
+  getPeggedToken,
+  getRedeemFee,
+  getRedeemRequest,
+  getTreasury,
+  getWithdrawalDelay,
+  getWithdrawalDelayEnabled,
+  isInstantRedeemWhitelisted,
+  previewDeposit,
+  previewRedeem,
+} from "./actions/public/index.js";
+import {
+  type CancelRedeemRequestParams,
+  cancelRedeemRequest,
+} from "./actions/wallet/cancelRedeemRequest.js";
+import { type DepositParams, deposit } from "./actions/wallet/deposit.js";
+import { type RedeemParams, redeem } from "./actions/wallet/redeem.js";
+import {
+  type RequestRedeemParams,
+  requestRedeem,
+} from "./actions/wallet/requestRedeem.js";
+
+// Export ABI
+export { gatewayAbi } from "./abi/gatewayAbi.js";
+// Export gateway addresses and per-gateway peg-base metadata
+export {
+  type Gateway,
+  gatewayAddresses,
+  gateways,
+} from "./gatewayAddresses.js";
+
+export type { CancelRedeemRequestParams };
+
+export {
+  type CancelRedeemRequestEvents,
+  type DepositEvents,
+  type RedeemEvents,
+  type RequestRedeemEvents,
+} from "./types.js";
+
+// Export factory functions for .extend() pattern
+export const gatewayPublicActions = () => (client: Client) => ({
+  getMaxWithdraw: (params: Parameters<typeof getMaxWithdraw>[1]) =>
+    getMaxWithdraw(client, params),
+  getMintFee: (params: Parameters<typeof getMintFee>[1]) =>
+    getMintFee(client, params),
+  getPeggedToken: (params: Parameters<typeof getPeggedToken>[1]) =>
+    getPeggedToken(client, params),
+  getRedeemFee: (params: Parameters<typeof getRedeemFee>[1]) =>
+    getRedeemFee(client, params),
+  getRedeemRequest: (params: Parameters<typeof getRedeemRequest>[1]) =>
+    getRedeemRequest(client, params),
+  getTreasury: (params: Parameters<typeof getTreasury>[1]) =>
+    getTreasury(client, params),
+  getWithdrawalDelay: (params: Parameters<typeof getWithdrawalDelay>[1]) =>
+    getWithdrawalDelay(client, params),
+  getWithdrawalDelayEnabled: (
+    params: Parameters<typeof getWithdrawalDelayEnabled>[1],
+  ) => getWithdrawalDelayEnabled(client, params),
+  isInstantRedeemWhitelisted: (
+    params: Parameters<typeof isInstantRedeemWhitelisted>[1],
+  ) => isInstantRedeemWhitelisted(client, params),
+  previewDeposit: (params: Parameters<typeof previewDeposit>[1]) =>
+    previewDeposit(client, params),
+  previewRedeem: (params: Parameters<typeof previewRedeem>[1]) =>
+    previewRedeem(client, params),
+});
+
+export const gatewayWalletActions = () => (client: WalletClient) => ({
+  cancelRedeemRequest: (params: CancelRedeemRequestParams) =>
+    cancelRedeemRequest(client, params),
+  deposit: (params: DepositParams) => deposit(client, params),
+  redeem: (params: RedeemParams) => redeem(client, params),
+  requestRedeem: (params: RequestRedeemParams) => requestRedeem(client, params),
+});

package/src/types.ts

@@ -0,0 +1,60 @@
+import type { Hash, TransactionReceipt } from "viem";
+
+type CommonEvents = {
+  "unexpected-error": [Error];
+};
+
+type ApprovalEvents = {
+  "approve-transaction-reverted": [TransactionReceipt];
+  "approve-transaction-succeeded": [TransactionReceipt];
+  "pre-approve": [];
+  "user-signed-approval": [Hash];
+  "user-signing-approval-error": [Error];
+};
+
+export type DepositEvents = ApprovalEvents &
+  CommonEvents & {
+    "deposit-failed": [Error];
+    "deposit-failed-validation": [string];
+    "deposit-settled": [];
+    "deposit-transaction-reverted": [TransactionReceipt];
+    "deposit-transaction-succeeded": [TransactionReceipt];
+    "pre-deposit": [];
+    "user-signed-deposit": [Hash];
+    "user-signing-deposit-error": [Error];
+  };
+
+export type CancelRedeemRequestEvents = CommonEvents & {
+  "cancel-redeem-request-failed": [Error];
+  "cancel-redeem-request-failed-validation": [string];
+  "cancel-redeem-request-settled": [];
+  "cancel-redeem-request-transaction-reverted": [TransactionReceipt];
+  "cancel-redeem-request-transaction-succeeded": [TransactionReceipt];
+  "pre-cancel-redeem-request": [];
+  "user-signed-cancel-redeem-request": [Hash];
+  "user-signing-cancel-redeem-request-error": [Error];
+};
+
+export type RedeemEvents = ApprovalEvents &
+  CommonEvents & {
+    "pre-redeem": [];
+    "redeem-failed": [Error];
+    "redeem-failed-validation": [string];
+    "redeem-settled": [];
+    "redeem-transaction-reverted": [TransactionReceipt];
+    "redeem-transaction-succeeded": [TransactionReceipt];
+    "user-signed-redeem": [Hash];
+    "user-signing-redeem-error": [Error];
+  };
+
+export type RequestRedeemEvents = ApprovalEvents &
+  CommonEvents & {
+    "pre-request-redeem": [];
+    "request-redeem-failed": [Error];
+    "request-redeem-failed-validation": [string];
+    "request-redeem-settled": [];
+    "request-redeem-transaction-reverted": [TransactionReceipt];
+    "request-redeem-transaction-succeeded": [TransactionReceipt];
+    "user-signed-request-redeem": [Hash];
+    "user-signing-request-redeem-error": [Error];
+  };