@shogun-sdk/intents-sdk 1.0.0

package/src/index.ts

@@ -0,0 +1,10 @@
+export type { ChainID, ChainType } from './chains.js';
+export { SupportedChains } from './chains.js';
+
+export type { EVMConfig, SolanaConfig, SuiConfig } from './config.js';
+export { EVMSDK } from './core/evm/sdk.js';
+export { Order } from './core/order.js';
+export { SolanaSDK } from './core/solana/sdk.js';
+export { SuiSDK } from './core/sui/sdk.js';
+export { ValidationError } from './errors/index.js';
+export type { CreateOrderParams } from './types/intent.js';

package/src/types/intent.ts

@@ -0,0 +1,143 @@
+import type { SupportedChain } from '../chains.js';
+import type { ExtraTransfer, Order } from '../core/order.js';
+
+/**
+ * Parameters for creating a cross-chain order
+ * Used as input for the createOrder and createAndSendOrder methods
+ */
+export type CreateOrderParams = {
+  /** 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, in smallest units (e.g., Wei for ETH) */
+  sourceTokenAmount: bigint;
+
+  /** 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, in smallest units */
+  destinationTokenMinAmount: bigint;
+  /** Recipient wallet address on the destination chain */
+  destinationAddress: string;
+
+  /** Minimum amount of stablecoins in the intermediate swap, in smallest units */
+  minStablecoinAmount: bigint;
+  /** Timestamp (in seconds) after which the order expires */
+  deadline: number;
+
+  /** Extra Transfers */
+  extraTransfers?: ExtraTransfer[];
+};
+
+/**
+ * Details required to execute the order on the destination chain
+ * Contains all information needed for the cross-chain fulfillment
+ */
+export type ExecutionDetails = {
+  /** Chain ID where tokens will be received */
+  destChainId: SupportedChain;
+  /** Token address on the destination chain to receive */
+  tokenOut: string;
+  /** Minimum amount of destination tokens to receive, in smallest units */
+  amountOutMin: bigint;
+  /** Recipient wallet address on the destination chain */
+  destinationAddress: string;
+  /** Extra transfers to be made */
+  extraTransfers?: ExtraTransfer[];
+};
+
+/** Hex string with 0x prefix, used for various hashes */
+export type Hash = `0x${string}`;
+/** Hash of execution details, used to verify order integrity across chains */
+export type ExecutionDetailsHash = Hash;
+
+/**
+ * EVM-specific data required for prepared orders
+ * Contains the signature and nonce for Permit2 allowance
+ */
+export type EvmPreparedData = {
+  /** Random nonce for Permit2 signature, prevents replay attacks */
+  nonce: string;
+  /** EIP-712 signature authorizing the order */
+  signature: string | Hash;
+};
+
+/**
+ * Sui-specific data required for prepared orders
+ * Contains the transaction hash of the order creation transaction
+ */
+export type SuiPreparedData = {
+  /** Transaction hash of the successful order creation transaction */
+  transactionHash: string;
+};
+
+/**
+ * Solana-specific data required for prepared orders
+ * Contains the public key of the created order account
+ */
+export type SolanaPreparedData = {
+  /** Public key of the created order account on Solana */
+  orderPubkey: string;
+};
+
+/**
+ * Source chain data sent to the auctioneer
+ * Contains all information needed to start the cross-chain swap from the source chain
+ */
+export type SourceChainData = {
+  /** User's wallet address that initiated the order */
+  user: string;
+  /** Source chain ID where tokens will be sent from */
+  srcChainId: SupportedChain;
+  /** Token address on the source chain to be swapped */
+  tokenIn: string;
+  /** Amount of source tokens to swap, in smallest units */
+  amountIn: bigint;
+  /** Minimum amount of stablecoins in the intermediate swap, in smallest units */
+  minStablecoinsAmount: bigint;
+  /** Timestamp (in seconds) after which the order expires */
+  deadline: number;
+  /** Hash of execution details for cross-chain verification */
+  executionDetailsHash: ExecutionDetailsHash;
+};
+
+/**
+ * Complete user intent request sent to the auctioneer service
+ * Contains all the information needed to execute the cross-chain swap
+ */
+export type UserIntentRequest = {
+  /** Generic data common to all chains */
+  genericData: SourceChainData;
+  /** JSON-stringified execution details for the destination chain */
+  executionDetails: string;
+  /** Chain-specific data including signatures and transaction details */
+  chainSpecificData: {
+    /** EVM-specific data (for Ethereum, Arbitrum, Optimism, Base) */
+    EVM?: EvmPreparedData;
+    /** Solana-specific data */
+    Solana?: SolanaPreparedData;
+    /** Sui-specific data */
+    Sui?: SolanaPreparedData;
+  };
+};
+
+/**
+ * Union type of all chain-specific prepared data
+ * The actual type depends on the source chain
+ */
+export type ChainPreparedData = EvmPreparedData | SuiPreparedData | SolanaPreparedData;
+
+/**
+ * Fully prepared order ready for submission to the auctioneer
+ * Contains both the order details and chain-specific prepared data
+ */
+export type PreparedOrder = {
+  /** The original order with all cross-chain details */
+  order: Order;
+  /** Chain-specific data needed for order execution */
+  preparedData: ChainPreparedData;
+  /** Hash related to the start order execution */
+  // txHash: string // TODO: Think if we need this
+};

package/src/utils/base-validator.ts

@@ -0,0 +1,64 @@
+import type { OrderInput } from '../core/order.js';
+import { ValidationError } from '../errors/index.js';
+import type { IChainValidator } from './order-validator.js';
+
+/**
+ * BaseValidator - Abstract class implementing common validation logic
+ * This follows the Template Method pattern
+ */
+export abstract class BaseValidator implements IChainValidator {
+  abstract isValidAddress(address: string): boolean;
+  abstract isValidTokenAddress(tokenAddress: string): boolean;
+  abstract isValidAmount(amount: bigint): boolean;
+  protected abstract getChainName(): string;
+  abstract chainSpecificValidation(order: OrderInput): Promise<void>;
+
+  /**
+   * Validate source chain specific parameters of the order
+   */
+  async validateSourceChain(order: OrderInput): Promise<void> {
+    this.validateAddress(order.user);
+    this.validateTokenAddress(order.sourceTokenAddress);
+    this.validateAmount(order.sourceTokenAmount);
+    this.validateAmount(order.minStablecoinAmount);
+    await this.chainSpecificValidation(order);
+  }
+
+  /**
+   * Validate destination chain specific parameters of the order
+   */
+  validateDestinationChain(order: OrderInput): void {
+    this.validateAddress(order.destinationAddress);
+    this.validateTokenAddress(order.destinationTokenAddress);
+    this.validateAmount(order.destinationTokenMinAmount);
+
+    if (order.extraTransfers) {
+      for (const extraTransfer of order.extraTransfers) {
+        this.validateAddress(extraTransfer.receiver);
+        this.validateTokenAddress(extraTransfer.token);
+        this.validateAmount(extraTransfer.amount);
+      }
+    }
+  }
+
+  /**
+   * Helper methods that throw specific validation errors
+   */
+  protected validateAddress(address: string): void {
+    if (!this.isValidAddress(address)) {
+      throw new ValidationError(`Invalid ${this.getChainName()} address: ${address}`);
+    }
+  }
+
+  protected validateTokenAddress(tokenAddress: string): void {
+    if (!this.isValidTokenAddress(tokenAddress)) {
+      throw new ValidationError(`Invalid ${this.getChainName()} token address: ${tokenAddress}`);
+    }
+  }
+
+  protected validateAmount(amount: bigint): void {
+    if (!this.isValidAmount(amount)) {
+      throw new ValidationError(`Amount must be greater than 0. Value: ${amount}`);
+    }
+  }
+}

package/src/utils/logger.ts

@@ -0,0 +1,128 @@
+import { BaseError } from '../errors/index.js';
+
+export enum LogLevel {
+  DEBUG = 'DEBUG',
+  INFO = 'INFO',
+  WARN = 'WARN',
+  ERROR = 'ERROR',
+  NONE = 'NONE',
+}
+
+export type LoggerConfig = {
+  level: LogLevel;
+  customLogger?: CustomLogger;
+};
+
+export interface CustomLogger {
+  debug(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+}
+
+class DefaultLogger implements CustomLogger {
+  debug(message: string, ...args: unknown[]): void {
+    console.debug(`[${new Date().toISOString()} DEBUG] ${message}`, ...args);
+  }
+
+  info(message: string, ...args: unknown[]): void {
+    console.info(`[${new Date().toISOString()} INFO] ${message}`, ...args);
+  }
+
+  warn(message: string, ...args: unknown[]): void {
+    console.warn(`[${new Date().toISOString()} WARN] ${message}`, ...args);
+  }
+
+  error(message: string, ...args: unknown[]): void {
+    console.error(`[${new Date().toISOString()} ERROR] ${message}`, ...args);
+  }
+}
+
+class Logger {
+  private static instance: Logger;
+  private loggerImpl: CustomLogger = new DefaultLogger();
+  private logLevel: LogLevel = LogLevel.INFO;
+
+  private constructor() {}
+
+  public static getInstance(): Logger {
+    if (!Logger.instance) {
+      Logger.instance = new Logger();
+    }
+    return Logger.instance;
+  }
+
+  public configure(config: LoggerConfig): void {
+    this.logLevel = config.level;
+    if (config.customLogger) {
+      this.loggerImpl = config.customLogger;
+    }
+  }
+
+  public debug(message: string, ...args: unknown[]): void {
+    if (this.shouldLog(LogLevel.DEBUG)) {
+      this.loggerImpl.debug(message, ...args);
+    }
+  }
+
+  public info(message: string, ...args: unknown[]): void {
+    if (this.shouldLog(LogLevel.INFO)) {
+      this.loggerImpl.info(message, ...args);
+    }
+  }
+
+  public warn(message: string, ...args: unknown[]): void {
+    if (this.shouldLog(LogLevel.WARN)) {
+      this.loggerImpl.warn(message, ...args);
+    }
+  }
+
+  public error(message: string, error?: unknown): void {
+    if (this.shouldLog(LogLevel.ERROR)) {
+      const formattedError = this.formatError(error);
+      this.loggerImpl.error(message, formattedError);
+    }
+  }
+
+  public logError(error: unknown): void {
+    if (this.shouldLog(LogLevel.ERROR)) {
+      const formattedError = this.formatError(error);
+
+      if (error instanceof BaseError) {
+        this.loggerImpl.error(`${error.name}: ${error.message}`, formattedError);
+      } else if (error instanceof Error) {
+        this.loggerImpl.error(`${error.name}: ${error.message}`, formattedError);
+      } else {
+        this.loggerImpl.error('Unknown error', formattedError);
+      }
+    }
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    const levels = [LogLevel.DEBUG, LogLevel.INFO, LogLevel.WARN, LogLevel.ERROR];
+    const currentLevelIndex = levels.indexOf(this.logLevel);
+    const targetLevelIndex = levels.indexOf(level);
+
+    return currentLevelIndex <= targetLevelIndex && this.logLevel !== LogLevel.NONE;
+  }
+
+  private formatError(error?: unknown): unknown {
+    if (!error) return 'No error details provided';
+
+    if (error instanceof BaseError) {
+      return error.toJSON();
+    }
+
+    if (error instanceof Error) {
+      return {
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+      };
+    }
+
+    return error;
+  }
+}
+
+export const logger = Logger.getInstance();

package/src/utils/order-validator.ts

@@ -0,0 +1,103 @@
+import { ChainType, chainIdToChainTypeMap, type SupportedChain } from '../chains.js';
+import { EvmValidator } from '../core/evm/validator.js';
+import type { OrderInput } from '../core/order.js';
+import { SolanaValidator } from '../core/solana/validator.js';
+import { SuiValidator } from '../core/sui/validator.js';
+import { ValidationError } from '../errors/index.js';
+
+export interface IAddressValidator {
+  isValidAddress(address: string): boolean;
+}
+
+export interface ITokenValidator {
+  isValidTokenAddress(tokenAddress: string): boolean;
+}
+
+export interface IAmountValidator {
+  isValidAmount(amount: bigint): boolean;
+}
+
+export interface IDeadlineValidator {
+  isValidDeadline(deadline: number): boolean;
+}
+
+export interface ICrossChainValidator {
+  isValidCrossChain(sourceChainId: SupportedChain, destinationChainId: SupportedChain): boolean;
+}
+
+export interface IChainValidator extends IAddressValidator, ITokenValidator, IAmountValidator {
+  validateSourceChain(order: OrderInput): Promise<void>;
+  validateDestinationChain(order: OrderInput): void;
+}
+
+/**
+ * CommonValidator - Handles validations shared across chains
+ */
+export class CommonValidator implements IDeadlineValidator, ICrossChainValidator {
+  isValidDeadline(deadline: number): boolean {
+    return deadline > Math.floor(Date.now() / 1000);
+  }
+
+  validateDeadline(deadline: number): void {
+    if (!this.isValidDeadline(deadline)) {
+      throw new ValidationError('Deadline must be in the future');
+    }
+  }
+
+  isValidCrossChain(sourceChainId: SupportedChain, destinationChainId: SupportedChain): boolean {
+    return sourceChainId !== destinationChainId;
+  }
+
+  validateCrossChain(sourceChainId: SupportedChain, destinationChainId: SupportedChain): void {
+    if (!this.isValidCrossChain(sourceChainId, destinationChainId)) {
+      throw new ValidationError('Source and destination chains cannot be the same');
+    }
+  }
+}
+
+export class ValidatorFactory {
+  private static validators: Map<ChainType, IChainValidator> = new Map();
+
+  static getValidator(chainType: ChainType): IChainValidator {
+    if (!this.validators.has(chainType)) {
+      switch (chainType) {
+        case ChainType.EVM:
+          this.validators.set(chainType, new EvmValidator());
+          break;
+        case ChainType.Solana:
+          this.validators.set(chainType, new SolanaValidator());
+          break;
+        case ChainType.Sui:
+          this.validators.set(chainType, new SuiValidator());
+          break;
+        default:
+          throw new ValidationError(`Chain type ${chainType} validation is not implemented.`);
+      }
+    }
+
+    return this.validators.get(chainType)!;
+  }
+
+  static getValidatorForChain(chainId: SupportedChain): IChainValidator {
+    const chainType = chainIdToChainTypeMap[chainId];
+    return this.getValidator(chainType);
+  }
+}
+
+export class OrderValidator {
+  private readonly commonValidator = new CommonValidator();
+
+  async validateOrder(order: OrderInput): Promise<void> {
+    const sourceValidator = ValidatorFactory.getValidatorForChain(order.sourceChainId);
+
+    await sourceValidator.validateSourceChain(order);
+
+    this.commonValidator.validateCrossChain(order.sourceChainId, order.destinationChainId);
+
+    const destinationValidator = ValidatorFactory.getValidatorForChain(order.destinationChainId);
+
+    destinationValidator.validateDestinationChain(order);
+
+    this.commonValidator.validateDeadline(order.deadline);
+  }
+}

package/src/utils/parsers.ts

@@ -0,0 +1,8 @@
+/* eslint-disable @typescript-eslint/no-namespace */
+
+export namespace Parsers {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export function bigIntReplacer(_key: string, value: any): any {
+    return typeof value === 'bigint' ? value.toString() : value;
+  }
+}

package/src/utils/type-utils.ts

@@ -0,0 +1 @@
+export type TupleToUnion<ArrayType> = ArrayType extends readonly unknown[] ? ArrayType[number] : never;