@shogun-sdk/intents-sdk 1.0.0

package/src/core/solana/generated/types/orderFulfilled.ts

@@ -0,0 +1,35 @@
+/**
+ * This code was AUTOGENERATED using the codama library.
+ * Please DO NOT EDIT THIS FILE, instead use visitors
+ * to add features, then rerun codama to update it.
+ *
+ * @see https://github.com/codama-idl/codama
+ */
+
+import {
+  type Address,
+  type Codec,
+  combineCodec,
+  type Decoder,
+  type Encoder,
+  getAddressDecoder,
+  getAddressEncoder,
+  getStructDecoder,
+  getStructEncoder,
+} from '@solana/kit';
+
+export type OrderFulfilled = { orderId: Address };
+
+export type OrderFulfilledArgs = OrderFulfilled;
+
+export function getOrderFulfilledEncoder(): Encoder<OrderFulfilledArgs> {
+  return getStructEncoder([['orderId', getAddressEncoder()]]);
+}
+
+export function getOrderFulfilledDecoder(): Decoder<OrderFulfilled> {
+  return getStructDecoder([['orderId', getAddressDecoder()]]);
+}
+
+export function getOrderFulfilledCodec(): Codec<OrderFulfilledArgs, OrderFulfilled> {
+  return combineCodec(getOrderFulfilledEncoder(), getOrderFulfilledDecoder());
+}

package/src/core/solana/generated/types/tokenInSwapped.ts

@@ -0,0 +1,53 @@
+/**
+ * This code was AUTOGENERATED using the codama library.
+ * Please DO NOT EDIT THIS FILE, instead use visitors
+ * to add features, then rerun codama to update it.
+ *
+ * @see https://github.com/codama-idl/codama
+ */
+
+import {
+  type Address,
+  type Codec,
+  combineCodec,
+  type Decoder,
+  type Encoder,
+  getAddressDecoder,
+  getAddressEncoder,
+  getStructDecoder,
+  getStructEncoder,
+  getU64Decoder,
+  getU64Encoder,
+} from '@solana/kit';
+
+export type TokenInSwapped = {
+  orderId: Address;
+  solver: Address;
+  stablecoinsAmount: bigint;
+};
+
+export type TokenInSwappedArgs = {
+  orderId: Address;
+  solver: Address;
+  stablecoinsAmount: number | bigint;
+};
+
+export function getTokenInSwappedEncoder(): Encoder<TokenInSwappedArgs> {
+  return getStructEncoder([
+    ['orderId', getAddressEncoder()],
+    ['solver', getAddressEncoder()],
+    ['stablecoinsAmount', getU64Encoder()],
+  ]);
+}
+
+export function getTokenInSwappedDecoder(): Decoder<TokenInSwapped> {
+  return getStructDecoder([
+    ['orderId', getAddressDecoder()],
+    ['solver', getAddressDecoder()],
+    ['stablecoinsAmount', getU64Decoder()],
+  ]);
+}
+
+export function getTokenInSwappedCodec(): Codec<TokenInSwappedArgs, TokenInSwapped> {
+  return combineCodec(getTokenInSwappedEncoder(), getTokenInSwappedDecoder());
+}

package/src/core/solana/order-instructions.ts

@@ -0,0 +1,131 @@
+import {
+  type Address,
+  address,
+  createNoopSigner,
+  fetchEncodedAccount,
+  generateKeyPairSigner,
+  getAddressEncoder,
+  getProgramDerivedAddress,
+  type IInstruction,
+  type KeyPairSigner,
+} from '@solana/kit';
+import { getTransferSolInstruction, SYSTEM_PROGRAM_ADDRESS } from '@solana-program/system';
+import {
+  ASSOCIATED_TOKEN_PROGRAM_ADDRESS,
+  fetchMint,
+  getCreateAssociatedTokenInstructionAsync,
+  getSyncNativeInstruction,
+} from '@solana-program/token';
+import { ChainID } from '../../chains.js';
+import { NATIVE_SOLANA_TOKEN_ADDRESS, SRC_CHAIN_GUARD, WRAPPED_SOL_MINT_ADDRESS } from '../../constants.js';
+import type { Order } from '../order.js';
+import { getDefaultSolanaRPC } from './client.js';
+import { getCreateOrderInstruction } from './generated/index.js';
+
+/**
+ * Generates Solana order instructions for creating an order
+ * @param order The order to generate instructions
+ * @returns Object containing the order public key and instructions
+ */
+export async function getSolanaOrderInstructions(order: Order): Promise<{
+  orderKeyPair: KeyPairSigner<string>;
+  instructions: IInstruction[];
+}> {
+  const rpc = getDefaultSolanaRPC();
+  const orderSigner = await generateKeyPairSigner();
+  const signer = createNoopSigner(order.user as Address);
+
+  let tokenInMint = address(order.sourceTokenAddress);
+
+  const orderUserAddress = address(order.user);
+  const spendingNative = tokenInMint === NATIVE_SOLANA_TOKEN_ADDRESS;
+
+  if (spendingNative) {
+    tokenInMint = WRAPPED_SOL_MINT_ADDRESS;
+  }
+
+  const tokenMintProgram = await fetchMint(rpc, tokenInMint);
+
+  const guardAddress = address(SRC_CHAIN_GUARD[ChainID.Solana]);
+
+  const addressEncoder = getAddressEncoder();
+
+  const [tokenInProgramAccount] = await getProgramDerivedAddress({
+    programAddress: ASSOCIATED_TOKEN_PROGRAM_ADDRESS,
+    seeds: [
+      addressEncoder.encode(orderUserAddress),
+      addressEncoder.encode(tokenMintProgram.programAddress),
+      addressEncoder.encode(tokenInMint),
+    ],
+  });
+
+  const [guardProgramAccount] = await getProgramDerivedAddress({
+    programAddress: ASSOCIATED_TOKEN_PROGRAM_ADDRESS,
+    seeds: [
+      // Owner
+      addressEncoder.encode(guardAddress),
+      // Token program
+      addressEncoder.encode(tokenMintProgram.programAddress),
+      // mint address
+      addressEncoder.encode(tokenInMint),
+    ],
+  });
+
+  const instructions: Array<IInstruction> = [];
+
+  // Handle native SOL
+  if (spendingNative) {
+    order.sourceTokenAddress = WRAPPED_SOL_MINT_ADDRESS;
+
+    const userTokenInAccount = await fetchEncodedAccount(rpc, tokenInProgramAccount);
+
+    if (!userTokenInAccount.exists) {
+      const createAccountIx = await getCreateAssociatedTokenInstructionAsync({
+        payer: signer,
+        ata: tokenInProgramAccount,
+        owner: orderUserAddress,
+        mint: tokenMintProgram.address,
+        tokenProgram: tokenMintProgram.programAddress,
+      });
+
+      instructions.push(createAccountIx);
+    }
+
+    const transferIx = getTransferSolInstruction({
+      source: signer,
+      destination: userTokenInAccount.address,
+      amount: order.sourceTokenAmount,
+    });
+
+    const syncNativeIx = getSyncNativeInstruction({
+      account: userTokenInAccount.address,
+    });
+
+    instructions.push(transferIx, syncNativeIx);
+  }
+
+  const executionHashUint8Array = order.executionDetailsHashToBytes();
+
+  const createOrderIx = getCreateOrderInstruction({
+    user: signer,
+    order: orderSigner,
+    guard: address(SRC_CHAIN_GUARD[ChainID.Solana]),
+    systemProgram: SYSTEM_PROGRAM_ADDRESS,
+    associatedTokenProgram: ASSOCIATED_TOKEN_PROGRAM_ADDRESS,
+    tokenInMint: tokenInMint,
+    userTokenInAccount: tokenInProgramAccount,
+    guardTokenInAccount: guardProgramAccount,
+    tokenInProgram: tokenMintProgram.programAddress,
+    amountIn: order.sourceTokenAmount,
+    deadline: order.deadline,
+    executionDetailsHash: executionHashUint8Array,
+    minStablecoinsAmount: order.minStablecoinAmount,
+  });
+
+  instructions.push(createOrderIx);
+
+  return {
+    instructions,
+    orderKeyPair: orderSigner,
+  };
+}

package/src/core/solana/sdk.ts

@@ -0,0 +1,135 @@
+import {
+  appendTransactionMessageInstructions,
+  compileTransaction,
+  createKeyPairFromBytes,
+  createNoopSigner,
+  createSignerFromKeyPair,
+  createTransactionMessage,
+  getBase58Encoder,
+  type KeyPairSigner,
+  pipe,
+  setTransactionMessageFeePayerSigner,
+  setTransactionMessageLifetimeUsingBlockhash,
+  signTransaction,
+} from '@solana/kit';
+import type { SolanaConfig } from '../../config.js';
+import type { PreparedOrder } from '../../types/intent.js';
+import { Order } from '../order.js';
+import { BaseSDK } from '../sdk.js';
+import { createSolanaClient, type SolanaClient } from './client.js';
+import { getSolanaOrderInstructions } from './order-instructions.js';
+
+/**
+ * Solana-specific SDK implementation
+ *
+ * Handles Solana-specific aspects of cross-chain swaps using Solana blockchain.
+ * Uses @solana/kit for transaction creation, signing, and submission.
+ * Supports cross-chain swaps from Solana to other supported chains.
+ */
+export class SolanaSDK extends BaseSDK {
+  /** Configuration for Solana connection and authentication */
+  private readonly config: SolanaConfig;
+  /** Client for Solana RPC interactions and transaction handling */
+  private client: SolanaClient;
+
+  /**
+   * Creates a new instance of the Solana SDK
+   *
+   * @param config Solana configuration including privateKey, commitment level, and optional RPC URL
+   */
+  constructor(config: SolanaConfig) {
+    super();
+    this.config = config;
+    this.client = createSolanaClient(config);
+  }
+
+  /**
+   * Gets the user's Solana wallet address derived from their private key
+   *
+   * Uses @solana/kit to securely derive the wallet address from the private key
+   *
+   * @returns Promise resolving to the user's Solana address as a Base58-encoded string
+   * @throws {SolanaError} If address derivation fails
+   */
+  public async getUserAddress(): Promise<string> {
+    const signer = await this.getUserSigner();
+
+    return signer.address;
+  }
+
+  /**
+   * Creates a CryptoKeyPair from the user's private key
+   *
+   * Converts the Base58-encoded private key to the format required by WebCrypto API
+   *
+   * @returns Promise resolving to a CryptoKeyPair for transaction signing
+   * @private
+   */
+  private async getUserCryptoKeypair(): Promise<CryptoKeyPair> {
+    const encoder = getBase58Encoder();
+    const bytesWithPrefix = encoder.encode(this.config.privateKey);
+    return createKeyPairFromBytes(bytesWithPrefix);
+  }
+
+  /**
+   * Creates a KeyPairSigner from the user's crypto keypair
+   *
+   * The KeyPairSigner is used for transaction signing and verification
+   *
+   * @returns Promise resolving to a KeyPairSigner for transaction operations
+   * @private
+   */
+  private async getUserSigner(): Promise<KeyPairSigner<string>> {
+    const signer = await this.getUserCryptoKeypair();
+    return createSignerFromKeyPair(signer);
+  }
+
+  /**
+   * Prepares a Solana order for submission
+   *
+   * This method:
+   * 1. Gets the user's signer from their private key
+   * 2. Generates Solana-specific instructions for the order
+   * 3. Creates, signs, and submits the transaction to the Solana blockchain
+   * 4. Returns the prepared order with the orderPubkey for tracking
+   *
+   * @param order The validated order to prepare
+   * @returns Promise resolving to a prepared order with Solana-specific data
+   * @protected
+   */
+  protected async prepareOrder(order: Order): Promise<PreparedOrder> {
+    const signer = await this.getUserSigner();
+    const signerKeyPair = await this.getUserCryptoKeypair();
+
+    const { orderKeyPair, instructions } = await getSolanaOrderInstructions(order);
+
+    const noopSigner = createNoopSigner(signer.address);
+
+    const { value: latestBlockhash } = await this.client.rpc
+      .getLatestBlockhash({ commitment: this.config.commitment })
+      .send();
+
+    // TODO: Think if we should include transaction message on getSolanaOrderInstructions
+    const transactionMessage = pipe(
+      createTransactionMessage({ version: 0 }),
+      (tx) => setTransactionMessageFeePayerSigner(noopSigner, tx),
+      (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx),
+      (tx) => appendTransactionMessageInstructions(instructions, tx),
+    );
+
+    const myTx = compileTransaction(transactionMessage);
+
+    const signature = await signTransaction([signerKeyPair, orderKeyPair.keyPair], myTx);
+
+    await this.client.sendAndConfirmTransaction(signature, {
+      commitment: this.config.commitment,
+    });
+
+    return {
+      order,
+      preparedData: {
+        orderPubkey: orderKeyPair.address,
+      },
+    };
+  }
+}

package/src/core/solana/validator.ts

@@ -0,0 +1,26 @@
+import { isAddress as isSolanaAddress } from '@solana/kit';
+import { MAX_UINT_64 } from '../../constants.js';
+import { BaseValidator } from '../../utils/base-validator.js';
+
+export class SolanaValidator extends BaseValidator {
+  isValidAddress(address: string): boolean {
+    return isSolanaAddress(address);
+  }
+
+  isValidTokenAddress(tokenAddress: string): boolean {
+    return isSolanaAddress(tokenAddress);
+  }
+
+  isValidAmount(amount: bigint): boolean {
+    return amount > 0n && amount < MAX_UINT_64;
+  }
+
+  protected getChainName(): string {
+    return 'Solana';
+  }
+
+  public async chainSpecificValidation(): Promise<void> {
+    // No chain-specific validation implemented for now for Solana
+    return;
+  }
+}

package/src/core/sui/client.ts

@@ -0,0 +1,3 @@
+import { getFullnodeUrl, SuiClient } from '@mysten/sui/client';
+
+export const createSuiClient = () => new SuiClient({ url: getFullnodeUrl('mainnet') });

package/src/core/sui/order-transaction.ts

@@ -0,0 +1,78 @@
+import { Transaction } from '@mysten/sui/transactions';
+import { normalizeSuiObjectId, SUI_TYPE_ARG } from '@mysten/sui/utils';
+
+import { ChainID } from '../../chains.js';
+import {
+  SRC_CHAIN_GUARD,
+  SUI_GUARD_COLLATERAL_TYPE,
+  SUI_GUARD_STABLECOIN_TYPE,
+  SUI_PACKAGE_ID,
+} from '../../constants.js';
+import { ValidationError } from '../../errors/index.js';
+import type { Order } from '../order.js';
+import { createSuiClient } from './client.js';
+
+/**
+ * Generates Sui order transaction for creating an order
+ * @param order The order to generate transaction for
+ * @returns Object containing the transaction
+ */
+export async function getSuiOrderTransaction(order: Order): Promise<Transaction> {
+  const userAddress = order.user;
+  const client = createSuiClient();
+  const coins = await client.getCoins({
+    owner: userAddress,
+    coinType: order.sourceTokenAddress,
+  });
+
+  const guardAddress = SRC_CHAIN_GUARD[ChainID.Sui];
+
+  const sourceTokenInCoins = coins.data.sort((a, b) => Number(b.balance) - Number(a.balance));
+
+  if (sourceTokenInCoins.length === 0) {
+    throw new ValidationError(`No token (${order.sourceTokenAddress}) to create order`);
+  }
+
+  const coinsInSum = sourceTokenInCoins.reduce((acc, coin) => acc + BigInt(coin.balance), 0n);
+
+  if (coinsInSum < order.sourceTokenAmount) {
+    throw new ValidationError(
+      `Insufficient balance to create order. Total coins is ${coinsInSum}, but order requires ${order.sourceTokenAmount}`,
+    );
+  }
+
+  const spendingGasCoin = normalizeSuiObjectId(order.sourceTokenAddress) === normalizeSuiObjectId(SUI_TYPE_ARG);
+
+  const tx = new Transaction();
+  const coinInArg = spendingGasCoin ? tx.gas : sourceTokenInCoins[0]!.coinObjectId;
+
+  if (sourceTokenInCoins.length > 1) {
+    // Merging coins IN into a single object just in case
+    tx.mergeCoins(
+      // merge into 1st coin object
+      coinInArg,
+      // merge the rest of coins
+      sourceTokenInCoins.slice(1).map((coin) => coin.coinObjectId),
+    );
+  }
+
+  const [coinIn] = tx.splitCoins(coinInArg, [order.sourceTokenAmount]);
+
+  tx.moveCall({
+    package: SUI_PACKAGE_ID,
+    module: 'source_chain_guard',
+    function: 'create_order',
+    arguments: [
+      tx.object(guardAddress),
+      coinIn,
+      tx.pure.u64(order.minStablecoinAmount),
+      tx.pure.u64(order.deadline * 1000), // Convert to milliseconds
+      tx.pure.vector('u8', order.executionDetailsHashToBytes()),
+    ],
+    typeArguments: [SUI_GUARD_COLLATERAL_TYPE, order.sourceTokenAddress, SUI_GUARD_STABLECOIN_TYPE],
+  });
+
+  tx.setSender(userAddress);
+
+  return tx;
+}

package/src/core/sui/sdk.ts

@@ -0,0 +1,95 @@
+import type { SuiClient } from '@mysten/sui/client';
+import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
+
+import type { SuiConfig } from '../../config.js';
+import { OrderCreationError } from '../../errors/index.js';
+import type { PreparedOrder } from '../../types/intent.js';
+import { Order } from '../order.js';
+import { BaseSDK } from '../sdk.js';
+import { createSuiClient } from './client.js';
+import { getSuiOrderTransaction } from './order-transaction.js';
+
+/**
+ * Sui-specific SDK implementation
+ *
+ * Handles Sui-specific aspects of cross-chain swaps using the Sui blockchain.
+ * Uses @mysten/sui libraries for transaction creation, signing, and submission.
+ * Supports cross-chain swaps from Sui to other supported chains.
+ */
+export class SuiSDK extends BaseSDK {
+  /** Configuration for Sui connection and authentication */
+  private readonly config: SuiConfig;
+  /** Client for Sui RPC interactions and transaction handling */
+  private client: SuiClient;
+
+  /**
+   * Creates a new instance of the Sui SDK
+   *
+   * @param config Sui configuration including privateKey and optional RPC URL
+   */
+  constructor(config: SuiConfig) {
+    super();
+    this.config = config;
+    this.client = createSuiClient();
+  }
+
+  /**
+   * Gets the user's Sui wallet address derived from their private key
+   *
+   * Uses Ed25519Keypair to securely derive the wallet address from the private key
+   *
+   * @returns Promise resolving to the user's Sui address as a hex string
+   */
+  public async getUserAddress(): Promise<string> {
+    return this.getKeyPair().toSuiAddress();
+  }
+
+  /**
+   * Creates an Ed25519Keypair from the user's private key
+   *
+   * The keypair is used for transaction signing and address derivation
+   *
+   * @returns Ed25519Keypair for cryptographic operations
+   * @private
+   */
+  private getKeyPair(): Ed25519Keypair {
+    return Ed25519Keypair.fromSecretKey(this.config.privateKey);
+  }
+
+  /**
+   * Prepares a Sui order for submission
+   *
+   * This method:
+   * 1. Gets the user's keypair from their private key
+   * 2. Generates Sui-specific transaction for the order
+   * 3. Signs and executes the transaction on the Sui blockchain
+   * 4. Returns the prepared order with the transaction hash for tracking
+   *
+   * @param order The validated order to prepare
+   * @returns Promise resolving to a prepared order with Sui-specific data
+   * @protected
+   */
+  protected async prepareOrder(order: Order): Promise<PreparedOrder> {
+    try {
+      const signer = this.getKeyPair();
+
+      const transaction = await getSuiOrderTransaction(order);
+
+      const tx = await this.client.signAndExecuteTransaction({
+        signer,
+        transaction,
+      });
+
+      await this.client.waitForTransaction({ digest: tx.digest });
+
+      return {
+        order,
+        preparedData: {
+          transactionHash: tx.digest,
+        },
+      };
+    } catch (error) {
+      throw new OrderCreationError('Failed to prepare Sui order', error);
+    }
+  }
+}

package/src/core/sui/validator.ts

@@ -0,0 +1,32 @@
+import { isValidSuiAddress, normalizeSuiAddress } from '@mysten/sui/utils';
+import { MAX_UINT_64 } from '../../constants.js';
+import { BaseValidator } from '../../utils/base-validator.js';
+
+const SUI_TOKEN_ADDRESS_REGEX = /^0x[a-fA-F0-9]{64}::\w+::\w+$/;
+
+export class SuiValidator extends BaseValidator {
+  isValidAddress(address: string): boolean {
+    return isValidSuiAddress(normalizeSuiAddress(address));
+  }
+
+  isValidTokenAddress(tokenAddress: string): boolean {
+    const [address] = tokenAddress.split('::');
+
+    const isValidAddress = address !== undefined ? this.isValidAddress(address) : false;
+
+    return isValidAddress && SUI_TOKEN_ADDRESS_REGEX.test(tokenAddress);
+  }
+
+  isValidAmount(amount: bigint): boolean {
+    return amount > 0n && amount < MAX_UINT_64;
+  }
+
+  protected getChainName(): string {
+    return 'Sui';
+  }
+
+  public async chainSpecificValidation(): Promise<void> {
+    // No chain-specific validation implemented for now for Sui
+    return;
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1,106 @@
+export class BaseError extends Error {
+  constructor(
+    message: string,
+    public override readonly cause?: unknown,
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+    Object.setPrototypeOf(this, BaseError.prototype);
+  }
+
+  // Format the error for logging/debugging
+  public toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      message: this.message,
+      cause: this.formatCause(),
+    };
+  }
+
+  private formatCause(): unknown {
+    if (this.cause instanceof Error) {
+      if ('toJSON' in this.cause && typeof this.cause.toJSON === 'function') {
+        return this.cause.toJSON();
+      }
+      return {
+        name: this.cause.name,
+        message: this.cause.message,
+        ...(this.cause.stack && { stack: this.cause.stack }),
+      };
+    }
+    return this.cause;
+  }
+}
+
+// Chain-specific error classes
+export class EVMError extends BaseError {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause);
+    Object.setPrototypeOf(this, EVMError.prototype);
+  }
+}
+
+export class SolanaError extends BaseError {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause);
+    Object.setPrototypeOf(this, SolanaError.prototype);
+  }
+}
+
+export class SuiError extends BaseError {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause);
+    Object.setPrototypeOf(this, SuiError.prototype);
+  }
+}
+
+// Specific error types
+export class ValidationError extends BaseError {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause);
+    Object.setPrototypeOf(this, ValidationError.prototype);
+  }
+}
+
+export class OrderCreationError extends BaseError {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause);
+    Object.setPrototypeOf(this, OrderCreationError.prototype);
+  }
+}
+
+export class NetworkError extends BaseError {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause);
+    Object.setPrototypeOf(this, NetworkError.prototype);
+  }
+}
+
+export class InsufficientBalanceError extends BaseError {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause);
+    Object.setPrototypeOf(this, InsufficientBalanceError.prototype);
+  }
+}
+
+export class InsufficientAllowanceError extends BaseError {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause);
+    Object.setPrototypeOf(this, InsufficientAllowanceError.prototype);
+  }
+}
+export function handleError(error: unknown): BaseError {
+  if (error instanceof BaseError) {
+    return error;
+  }
+
+  if (error instanceof Error) {
+    return new BaseError(error.message, error);
+  }
+
+  return new BaseError(
+    typeof error === 'string' ? error : 'Unknown error occurred',
+
+    error,
+  );
+}