@shogun-sdk/intents-sdk 1.0.0

package/src/core/evm/intent-provider.ts

@@ -0,0 +1,63 @@
+import { type Address } from 'viem';
+import { type SupportedEvmChain } from '../../chains.js';
+import type { EVMConfig } from '../../config.js';
+import { SRC_CHAIN_GUARD } from '../../constants.js';
+import type { PreparedOrder } from '../../types/intent.js';
+import type { Order } from '../order.js';
+import { getEvmOrderTypedData } from './order-signature.js';
+import { type PermitTransferFrom } from './permit2.js';
+import { ChainProvider } from './viem-provider.js';
+
+export class EVMIntentProvider {
+  private provider: ChainProvider;
+
+  constructor(config: EVMConfig) {
+    this.provider = new ChainProvider(config);
+  }
+
+  async prepare(order: Order): Promise<PreparedOrder> {
+    const { orderTypedData: dataToSign, nonce } = await getEvmOrderTypedData(order);
+
+    const signature = await this.provider.walletClient.signTypedData({
+      message: dataToSign.message,
+      primaryType: dataToSign.primaryType,
+      types: dataToSign.types,
+      domain: dataToSign.domain,
+      account: this.provider.getAccount(),
+    });
+
+    return {
+      order,
+      preparedData: {
+        nonce: nonce.toString(),
+        signature: signature.slice(2),
+      },
+    };
+  }
+
+  static getPermissionMessage(order: Order, nonce: bigint): PermitTransferFrom {
+    return {
+      permitted: {
+        token: order.sourceTokenAddress as Address,
+        amount: order.sourceTokenAmount,
+      },
+      spender: SRC_CHAIN_GUARD[order.sourceChainId as SupportedEvmChain] as Address,
+      nonce,
+      deadline: BigInt(order.deadline),
+      witness: {
+        user: order.user as Address,
+        tokenIn: order.sourceTokenAddress as Address,
+        srcChainId: order.sourceChainId,
+        deadline: order.deadline,
+        amountIn: order.sourceTokenAmount,
+        minStablecoinsAmount: order.minStablecoinAmount,
+        nonce,
+        executionDetailsHash: order.getExecutionDetailsHash(),
+      },
+    };
+  }
+
+  static getRandomNonce(): bigint {
+    return BigInt(Math.floor(Math.random() * 1000000000000));
+  }
+}

package/src/core/evm/order-signature.ts

@@ -0,0 +1,33 @@
+import type { TypedDataDomain } from 'viem';
+import type { SupportedEvmChain } from '../../chains.js';
+import type { Order } from '../order.js';
+import { EVMIntentProvider } from './intent-provider.js';
+import { PERMIT2_DOMAIN, PERMIT2_TYPES, type PermitTransferFrom } from './permit2.js';
+
+export type EvmOrderTypedData = {
+  domain: TypedDataDomain;
+  types: typeof PERMIT2_TYPES;
+  primaryType: 'PermitWitnessTransferFrom';
+  message: PermitTransferFrom;
+};
+
+/**
+ * Generates typed data for EVM order signatures
+ * @param order The order to generate typed data for
+ * @returns Object containing the typed data and nonce
+ */
+export async function getEvmOrderTypedData(
+  order: Order,
+): Promise<{ orderTypedData: EvmOrderTypedData; nonce: bigint }> {
+  const randomNonce = EVMIntentProvider.getRandomNonce();
+  const permissionMessage = EVMIntentProvider.getPermissionMessage(order, randomNonce);
+
+  const orderTypedData = {
+    domain: PERMIT2_DOMAIN(order.sourceChainId as SupportedEvmChain),
+    types: PERMIT2_TYPES,
+    primaryType: 'PermitWitnessTransferFrom',
+    message: permissionMessage,
+  } as EvmOrderTypedData;
+
+  return { orderTypedData, nonce: randomNonce };
+}

package/src/core/evm/permit2.ts

@@ -0,0 +1,60 @@
+import type { Address, Hex, TypedDataDomain } from 'viem';
+import type { SupportedEvmChain } from '../../chains.js';
+import { PERMIT2_ADDRESS } from '../../constants.js';
+
+export type TokenPermissions = {
+  token: Address;
+  amount: bigint;
+};
+
+export type OrderInfo = {
+  user: Address;
+  tokenIn: Address;
+  srcChainId: number;
+  deadline: number;
+  amountIn: bigint;
+  minStablecoinsAmount: bigint;
+  executionDetailsHash: Hex;
+  nonce: bigint;
+};
+
+export type PermitTransferFrom = {
+  permitted: TokenPermissions;
+  spender: Address;
+  nonce: bigint;
+  deadline: bigint;
+  witness: OrderInfo;
+};
+
+const TOKEN_PERMISSIONS = [
+  { name: 'token', type: 'address' },
+  { name: 'amount', type: 'uint256' },
+] as const;
+
+export const PERMIT2_TYPES = {
+  TokenPermissions: TOKEN_PERMISSIONS,
+  OrderInfo: [
+    { name: 'user', type: 'address' },
+    { name: 'tokenIn', type: 'address' },
+    { name: 'srcChainId', type: 'uint32' },
+    { name: 'deadline', type: 'uint32' },
+    { name: 'amountIn', type: 'uint128' },
+    { name: 'minStablecoinsAmount', type: 'uint128' },
+    { name: 'executionDetailsHash', type: 'bytes32' },
+    { name: 'nonce', type: 'uint256' },
+  ],
+  PermitWitnessTransferFrom: [
+    { name: 'permitted', type: 'TokenPermissions' },
+    { name: 'spender', type: 'address' },
+    { name: 'nonce', type: 'uint256' },
+    { name: 'deadline', type: 'uint256' },
+    { name: 'witness', type: 'OrderInfo' },
+  ],
+} as const;
+
+export const PERMIT2_DOMAIN = (chainId: SupportedEvmChain) =>
+  ({
+    name: 'Permit2',
+    chainId,
+    verifyingContract: PERMIT2_ADDRESS[chainId],
+  }) as TypedDataDomain;

package/src/core/evm/sdk.ts

@@ -0,0 +1,74 @@
+// src/core/evm/sdk.ts
+
+import { privateKeyToAccount } from 'viem/accounts';
+import type { EVMConfig } from '../../config.js';
+import { EVMError, OrderCreationError } from '../../errors/index.js';
+import type { PreparedOrder } from '../../types/intent.js';
+import type { Order } from '../order.js';
+import { BaseSDK } from '../sdk.js';
+import { EVMIntentProvider } from './intent-provider.js';
+
+/**
+ * EVM-specific SDK implementation
+ *
+ * Handles EVM-specific aspects of cross-chain swaps for Ethereum-compatible chains:
+ * - Arbitrum
+ * - Optimism
+ * - Base
+ *
+ * Uses viem for blockchain interactions and EIP-712 signatures for order authorization.
+ */
+export class EVMSDK extends BaseSDK {
+  /** Configuration for EVM chain connections and authentication */
+  private readonly config: EVMConfig;
+  /** Provider for EVM-specific order preparation and submission */
+  private readonly evmIntentProvider: EVMIntentProvider;
+
+  /**
+   * Creates a new instance of the EVM SDK
+   *
+   * @param config EVM configuration including chainId, privateKey, and optional RPC URL
+   */
+  constructor(config: EVMConfig) {
+    super();
+    this.config = config;
+    this.evmIntentProvider = new EVMIntentProvider(config);
+  }
+
+  /**
+   * Gets the user's Ethereum address derived from their private key
+   *
+   * Uses viem's privateKeyToAccount function to derive the address securely
+   *
+   * @returns Promise resolving to the user's Ethereum address as a 0x-prefixed string
+   * @throws {EVMError} If address derivation fails
+   */
+  public async getUserAddress(): Promise<string> {
+    try {
+      return privateKeyToAccount(this.config.privateKey).address;
+    } catch (error) {
+      throw new EVMError('Failed to get user address', error);
+    }
+  }
+
+  /**
+   * Prepares an EVM order for submission
+   *
+   * This method:
+   * 1. Validates token balances and allowances
+   * 2. Creates and signs the EIP-712 typed data for Permit2
+   * 3. Prepares the order for submission to the auctioneer
+   *
+   * @param order The validated order to prepare
+   * @returns Promise resolving to a prepared order with EVM-specific signature data
+   * @throws {OrderCreationError} If order preparation fails
+   * @protected
+   */
+  protected prepareOrder(order: Order): Promise<PreparedOrder> {
+    try {
+      return this.evmIntentProvider.prepare(order);
+    } catch (error) {
+      throw new OrderCreationError('Failed to prepare EVM order', error);
+    }
+  }
+}

package/src/core/evm/validator.ts

@@ -0,0 +1,60 @@
+import { type Address, getContract, isAddress as isEvmAddress } from 'viem';
+import type { SupportedEvmChain } from '../../chains.js';
+import { MAX_UINT_128, PERMIT2_ADDRESS } from '../../constants.js';
+import { InsufficientAllowanceError, InsufficientBalanceError } from '../../errors/index.js';
+import { BaseValidator } from '../../utils/base-validator.js';
+import type { OrderInput } from '../order.js';
+import { ERC20ABI } from './abi/erc20.js';
+import { ChainProvider } from './viem-provider.js';
+
+/**
+ * Chain-specific validator implementations
+ */
+export class EvmValidator extends BaseValidator {
+  isValidAddress(address: string): boolean {
+    return isEvmAddress(address);
+  }
+
+  isValidTokenAddress(tokenAddress: string): boolean {
+    return isEvmAddress(tokenAddress);
+  }
+
+  isValidAmount(amount: bigint): boolean {
+    return amount > 0n && amount < MAX_UINT_128;
+  }
+
+  protected getChainName(): string {
+    return 'EVM';
+  }
+
+  public async chainSpecificValidation(order: OrderInput): Promise<void> {
+    const chain = order.sourceChainId as SupportedEvmChain;
+    const client = ChainProvider.getClient(chain);
+    const user = order.user as Address;
+
+    const ERC20Contract = getContract({
+      address: order.sourceTokenAddress as Address,
+      abi: ERC20ABI,
+      client: {
+        public: client,
+        chain,
+      },
+    });
+    const balance = await ERC20Contract.read.balanceOf([user]);
+
+    if (balance < order.sourceTokenAmount) {
+      throw new InsufficientBalanceError(
+        `Insufficient balance for token ${order.sourceTokenAddress}. Current balance: ${balance}. Required balance: ${order.sourceTokenAmount}`,
+      );
+    }
+
+    const permit2Address = PERMIT2_ADDRESS[chain];
+    const allowance = await ERC20Contract.read.allowance([user, permit2Address]);
+
+    if (allowance < order.sourceTokenAmount) {
+      throw new InsufficientAllowanceError(
+        `Insufficient allowance for token ${order.sourceTokenAddress} on permit2 address ${permit2Address}. Current allowance: ${allowance}. Required allowance: ${order.sourceTokenAmount}`,
+      );
+    }
+  }
+}

package/src/core/evm/viem-provider.ts

@@ -0,0 +1,79 @@
+import {
+  type Account,
+  type Address,
+  type Chain,
+  type Client,
+  createClient,
+  createWalletClient,
+  getContract,
+  type Hex,
+  http,
+  type Transport,
+  type WalletClient,
+} from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { arbitrum, base, optimism } from 'viem/chains';
+import { ChainID, type SupportedEvmChain } from '../../chains.js';
+import type { EVMConfig } from '../../config.js';
+import { ERC20ABI } from './abi/erc20.js';
+
+const chainIdToProviderChainMap = {
+  [ChainID.Arbitrum]: arbitrum,
+  [ChainID.Optimism]: optimism,
+  [ChainID.Base]: base,
+};
+
+export class ChainProvider {
+  private readonly privateKey: Hex;
+  public readonly chainId: SupportedEvmChain;
+  public readonly publicClient: Client;
+  public readonly walletClient: WalletClient<Transport, Chain, Account>;
+
+  constructor(config: EVMConfig) {
+    this.privateKey = config.privateKey as Hex;
+    this.chainId = config.chainId;
+
+    this.publicClient = this.getClient(config.rpcProviderUrl);
+    this.walletClient = this.getWalletClient(config.rpcProviderUrl);
+  }
+
+  static getClient(chainId: SupportedEvmChain, rpcProviderUrl?: string): Client {
+    const chain = chainIdToProviderChainMap[chainId];
+
+    return createClient({
+      chain,
+      transport: http(rpcProviderUrl),
+    });
+  }
+
+  getClient(rpcProviderUrl?: string): Client {
+    return ChainProvider.getClient(this.chainId, rpcProviderUrl);
+  }
+
+  getAccount(): Account {
+    return privateKeyToAccount(this.privateKey);
+  }
+
+  getWalletClient(rpcProviderUrl?: string): WalletClient<Transport, Chain, Account> {
+    const chain = chainIdToProviderChainMap[this.chainId];
+
+    return createWalletClient({
+      account: privateKeyToAccount(this.privateKey),
+      chain,
+      transport: http(rpcProviderUrl),
+    });
+  }
+
+  getERC20Contract(tokenAddress: Address) {
+    return getContract({
+      address: tokenAddress,
+      abi: ERC20ABI,
+      client: {
+        wallet: this.walletClient,
+        public: this.publicClient,
+        chain: chainIdToProviderChainMap[this.chainId],
+        account: this.walletClient.account,
+      },
+    });
+  }
+}

package/src/core/order.ts

@@ -0,0 +1,186 @@
+import { sha256, toBytes } from 'viem';
+import { type SupportedChain } from '../chains.js';
+import { ValidationError } from '../errors/index.js';
+import { type ExecutionDetails, type Hash } from '../types/intent.js';
+import { OrderValidator } from '../utils/order-validator.js';
+import { Parsers } from '../utils/parsers.js';
+
+/**
+ * Input parameters for creating a cross-chain order
+ */
+export type OrderInput = {
+  /** User's wallet address that initiates the order */
+  user: string;
+  /** Source chain ID where tokens will be sent from */
+  sourceChainId: SupportedChain;
+  /** Token address on the source chain to be swapped */
+  sourceTokenAddress: string;
+  /** Amount of source tokens to swap with decimals */
+  sourceTokenAmount: bigint;
+  /** Destination chain ID where tokens will be received */
+  destinationChainId: SupportedChain;
+  /** Token address on the destination chain to receive */
+  destinationTokenAddress: string;
+  /** Minimum amount of destination tokens to receive */
+  destinationTokenMinAmount: bigint;
+  /** Recipient wallet address on the destination chain */
+  destinationAddress: string;
+  /** Minimum amount of stablecoins in the intermediate swap */
+  minStablecoinAmount: bigint;
+  /** Timestamp (in seconds) after which the order expires */
+  deadline: number;
+  /** Extra transfers to be made */
+  extraTransfers?: ExtraTransfer[];
+};
+
+export type ExtraTransfer = {
+  /** Token address */
+  token: string;
+  /** Receiver address */
+  receiver: string;
+  /** Amount of tokens to transfer */
+  amount: bigint;
+};
+
+/**
+ * Represents a cross-chain swap order
+ * Contains all the information needed to execute the order on both source and destination chains
+ */
+export class Order {
+  /** User's wallet address that initiates the order */
+  public user: string;
+  /** Source chain ID where tokens will be sent from */
+  public sourceChainId: SupportedChain;
+  /** Token address on the source chain to be swapped */
+  public sourceTokenAddress: string;
+  /** Amount of source tokens to swap */
+  public sourceTokenAmount: bigint;
+  /** Destination chain ID where tokens will be received */
+  public destinationChainId: SupportedChain;
+  /** Token address on the destination chain to receive */
+  public destinationTokenAddress: string;
+  /** Minimum amount of destination tokens to receive */
+  public destinationTokenMinAmount: bigint;
+  /** Recipient wallet address on the destination chain */
+  public destinationAddress: string;
+  /** Minimum amount of stablecoins in the intermediate swap */
+  public minStablecoinAmount: bigint;
+  /** Timestamp (in seconds) after which the order expires */
+  public deadline: number;
+  /** Extra transfers to be made */
+  public extraTransfers?: ExtraTransfer[];
+
+  constructor(input: OrderInput) {
+    this.user = input.user;
+    this.sourceChainId = input.sourceChainId;
+    this.sourceTokenAddress = input.sourceTokenAddress;
+    this.sourceTokenAmount = input.sourceTokenAmount;
+    this.destinationChainId = input.destinationChainId;
+    this.destinationTokenAddress = input.destinationTokenAddress;
+    this.destinationTokenMinAmount = input.destinationTokenMinAmount;
+    this.destinationAddress = input.destinationAddress;
+    this.minStablecoinAmount = input.minStablecoinAmount;
+    this.deadline = input.deadline;
+    this.extraTransfers = input.extraTransfers;
+  }
+
+  /**
+   * Factory method to create and validate a new Order instance
+   * @param input Order parameters
+   * @returns Validated Order instance
+   * @throws {ValidationError} If order validation fails
+   */
+  public static async create(input: OrderInput): Promise<Order> {
+    await new OrderValidator().validateOrder(input);
+
+    const order = new Order({
+      ...input,
+    });
+
+    return order;
+  }
+
+  /**
+   * Gets the execution details for the destination chain
+   * These details are used to complete the order on the destination chain
+   * @returns Structured execution details object
+   */
+  public getExecutionDetails(): ExecutionDetails {
+    return {
+      destChainId: this.destinationChainId,
+      tokenOut: this.destinationTokenAddress,
+      destinationAddress: this.destinationAddress,
+      amountOutMin: this.destinationTokenMinAmount,
+      extraTransfers: this.extraTransfers,
+    };
+  }
+
+  public executionDetailsHashToBytes(): Uint8Array {
+    const executionDetailsHash = this.getExecutionDetailsHash().slice(2);
+
+    const executionHashByteSlice = Buffer.from(executionDetailsHash, 'hex');
+
+    return new Uint8Array(executionHashByteSlice);
+  }
+
+  /**
+   * Generates a cryptographic hash of the execution details
+   * This hash is used to verify order integrity across chains
+   * @returns SHA-256 hash of the execution details as a 0x-prefixed hex string
+   * @throws {ValidationError} If hash generation fails
+   */
+  public getExecutionDetailsHash(): Hash {
+    try {
+      const executionDetails = this.getExecutionDetails();
+      const executionDetailsString = JSON.stringify(executionDetails, Parsers.bigIntReplacer);
+
+      const bytes = toBytes(executionDetailsString);
+      return sha256(bytes);
+    } catch (error) {
+      throw new ValidationError(
+        'Failed to generate execution details hash',
+        error instanceof Error ? error : new Error(String(error)),
+      );
+    }
+  }
+
+  /**
+   * Converts the order to the format required for source chain processing
+   * Used when sending the order to the auctioneer for execution
+   * @returns Object containing source chain-specific data
+   */
+  public toSourceChainData() {
+    return {
+      user: this.user,
+      srcChainId: this.sourceChainId,
+      tokenIn: this.sourceTokenAddress,
+      amountIn: this.sourceTokenAmount,
+      minStablecoinsAmount: this.minStablecoinAmount,
+      deadline: this.deadline,
+      executionDetailsHash: this.getExecutionDetailsHash(),
+      extraTransfers: this.extraTransfers,
+    };
+  }
+
+  /**
+   * Serializes the order to a JSON-compatible object
+   * Converts bigint values to strings to ensure proper JSON serialization
+   * @returns JSON-serializable representation of the order
+   */
+  public toJSON() {
+    return {
+      user: this.user,
+      sourceChainId: this.sourceChainId as number,
+      sourceTokenAddress: this.sourceTokenAddress,
+      sourceTokenAmount: this.sourceTokenAmount.toString(),
+      destinationChainId: this.destinationChainId as number,
+      destinationTokenAddress: this.destinationTokenAddress,
+      destinationTokenMinAmount: this.destinationTokenMinAmount.toString(),
+      destinationAddress: this.destinationAddress,
+      minStablecoinAmount: this.minStablecoinAmount.toString(),
+      deadline: this.deadline,
+      executionDetailsHash: this.getExecutionDetailsHash(),
+      extraTransfers: this.extraTransfers,
+    };
+  }
+}