@fystack/sdk 0.1.0

package/src/solanaSigner.ts

@@ -0,0 +1,243 @@
+import { APIService, WalletAddressType, WalletDetail } from './api'
+import { APICredentials, TransactionStatusResponse, TxStatus, TransactionError } from './types'
+import { Environment } from './config'
+import { StatusPoller, StatusPollerOptions } from './utils/statusPoller'
+import { Transaction, PublicKey, VersionedTransaction } from '@solana/web3.js'
+import bs58 from 'bs58'
+import { Buffer } from 'buffer'
+
+export class SolanaSigner {
+  private address!: string
+  private APIService: APIService
+  private APIKey: string
+  private walletDetail: WalletDetail
+  private pollerOptions?: StatusPollerOptions
+
+  constructor(
+    credentials: APICredentials,
+    environment: Environment,
+    pollerOptions?: StatusPollerOptions
+  ) {
+    this.APIKey = credentials.apiKey
+    this.APIService = new APIService(credentials, environment)
+    this.pollerOptions = pollerOptions
+  }
+
+  setWallet(walletId: string): void {
+    if (!walletId || walletId.trim() === '') {
+      throw new Error('Invalid wallet ID provided')
+    }
+    // Set walletId in walletDetail with default values for required properties
+    this.walletDetail = {
+      WalletID: walletId,
+      APIKey: '',
+      Name: '',
+      AddressType: '',
+      Address: ''
+      // Other fields will be populated when getAddress is called
+    }
+    // Reset address cache since we're changing wallets
+    this.address = ''
+  }
+
+  async getAddress(): Promise<string> {
+    if (this.address) {
+      return this.address
+    }
+
+    if (!this.APIKey && !this.walletDetail?.WalletID) {
+      throw new Error('Wallet detail not found, use setWallet(walletId) to set wallet first!')
+    }
+
+    const detail: WalletDetail = await this.APIService.getWalletDetail(
+      WalletAddressType.Sol,
+      this.walletDetail?.WalletID
+    )
+
+    this.walletDetail = detail
+    if (detail?.Address) {
+      // cache the address
+      this.address = detail.Address
+    }
+
+    if (!this.address) {
+      throw new Error('Address not found')
+    }
+
+    return this.address
+  }
+
+  private async waitForTransactionStatus(transactionId: string): Promise<string> {
+    const poller = new StatusPoller(this.pollerOptions)
+    // Poll for transaction status using signaturePoller
+    const result = await poller.poll<TransactionStatusResponse>(
+      // Polling function
+      () => {
+        console.log('Polling status')
+        return this.APIService.getTransactionStatus(this.walletDetail.WalletID, transactionId)
+      },
+      // Success condition
+      (result) =>
+        (result.status === TxStatus.Confirmed || result.status === TxStatus.Completed) &&
+        !!result.hash,
+      // Error condition
+      (result) => {
+        if (result.status === TxStatus.Failed) {
+          throw new TransactionError(
+            result.failed_reason || 'Transaction failed',
+            'TRANSACTION_FAILED',
+            result.transaction_id
+          )
+        }
+        return result.status === TxStatus.Rejected
+      }
+    )
+    console.log('result', result)
+
+    if (!result.hash) {
+      throw new TransactionError(
+        'Transaction hash not found in successful response',
+        'TRANSACTION_HASH_MISSING',
+        result.transaction_id
+      )
+    }
+
+    return result.hash
+  }
+
+  /**
+   * Signs a Solana transaction
+   * @param transaction Base64 encoded serialized transaction
+   * @returns Signature as a base58 encoded string
+   */
+  async signTransaction(transaction: string): Promise<string> {
+    if (!this.address) {
+      await this.getAddress()
+    }
+
+    const data = {
+      data: transaction,
+      from: this.address
+    }
+
+    // Call the signRaw API similar to ApexSigner
+    const response = await this.APIService.signTransaction(this.walletDetail.WalletID, {
+      ...data,
+      meta: {
+        tx_method: 'solana_signTransaction'
+      },
+      chainId: '1399811149'
+    })
+    console.log('respnpse', response)
+
+    // Wait for the signature
+    return this.waitForTransactionStatus(response.transaction_id)
+  }
+
+  /**
+   * Signs a Solana message
+   * @param message The message to sign (string or Uint8Array)
+   * @returns Signature as a base58 encoded string
+   */
+  async signMessage(message: string | Uint8Array): Promise<string> {
+    if (!this.address) {
+      await this.getAddress()
+    }
+
+    const messageStr =
+      typeof message === 'string' ? message : Buffer.from(message).toString('base64')
+
+    const response = await this.APIService.requestSign(this.walletDetail.WalletID, {
+      method: 'solana_signMessage',
+      message: messageStr,
+      chain_id: 0 // Not used for Solana but required by API
+    })
+
+    console.log('Respnse', response)
+
+    return this.waitForTransactionStatus(response.transaction_id)
+  }
+
+  /**
+   * Signs and sends a Solana transaction
+   * @param transaction Base64 encoded serialized transaction
+   * @returns Transaction signature
+   */
+  async signAndSendTransaction(transaction: string): Promise<string> {
+    if (!this.address) {
+      await this.getAddress()
+    }
+
+    const data = {
+      transaction,
+      from: this.address,
+      method: 'solana_signAndSendTransaction'
+    }
+
+    const response = await this.APIService.signTransaction(this.walletDetail.WalletID, data)
+    const txHash = await this.waitForTransactionStatus(response.transaction_id)
+    console.log('transaction succeed!')
+
+    return txHash
+  }
+
+  /**
+   * Signs multiple Solana transactions
+   * @param transactions Array of base64 encoded serialized transactions
+   * @returns Array of signatures as base58 encoded strings
+   */
+  async signAllTransactions(transactions: string[]): Promise<{ transactions: string[] }> {
+    if (!this.address) {
+      await this.getAddress()
+    }
+
+    // We need to get the signatures and then incorporate them into the transactions
+    const signaturePromises = transactions.map(async (transaction) => {
+      // Get the signature
+      const signature = await this.signTransaction(transaction)
+
+      // Here you would need to incorporate the signature into the transaction
+      // This is a placeholder - you'll need to implement actual signature incorporation
+      // based on your Solana transaction structure
+      const signedTransaction = this.incorporateSignatureIntoTransaction(transaction, signature)
+      return signedTransaction
+    })
+
+    // Wait for all transactions to be signed in parallel
+    const signedTransactions = await Promise.all(signaturePromises)
+    return { transactions: signedTransactions }
+  }
+
+  private incorporateSignatureIntoTransaction(transaction: string, signature: string): string {
+    // Decode base64 transaction to buffer
+    const transactionBuffer = Buffer.from(transaction, 'base64')
+
+    try {
+      // First try with legacy transaction format
+      const tx = Transaction.from(transactionBuffer)
+
+      // Decode the base58 signature
+      const signatureBuffer = bs58.decode(signature)
+
+      // Add the signature to the transaction
+      tx.addSignature(new PublicKey(this.address), Buffer.from(signatureBuffer))
+
+      // Serialize and encode back to base64
+      return Buffer.from(tx.serialize()).toString('base64')
+    } catch (error) {
+      if (error.message.includes('Versioned messages')) {
+        // Deserialize as a versioned transaction
+        const versionedTx = VersionedTransaction.deserialize(transactionBuffer)
+
+        // Add the signature (convert from base58)
+        const signatureBuffer = bs58.decode(signature)
+        versionedTx.signatures[0] = Buffer.from(signatureBuffer)
+
+        // Serialize and encode back to base64
+        return Buffer.from(versionedTx.serialize()).toString('base64')
+      }
+      // If it's another type of error, rethrow it
+      throw error
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,161 @@
+export class TransactionError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly transactionId?: string,
+    public readonly originalError?: Error
+  ) {
+    super(message)
+    this.name = 'TransactionError'
+  }
+}
+export enum TxStatus {
+  Pending = 'pending',
+  Completed = 'completed',
+  Confirmed = 'confirmed',
+  Failed = 'failed',
+  PendingApproval = 'pending_approval',
+  Rejected = 'rejected'
+}
+
+export enum TxApprovalStatus {
+  Pending = 'pending',
+  Approved = 'approved',
+  Rejected = 'rejected'
+}
+
+export interface APICredentials {
+  apiKey: string
+  apiSecret: string
+}
+
+export interface WebhookEvent {
+  webhook_id: string // Equivalent to "webhook_id" in Go struct
+  resource_id: string // Equivalent to "resource_id" in Go struct
+  url: string // URL where the webhook was triggered
+  payload: any // Binary or string representation of the payload
+  event: string // Name of the event
+}
+
+export interface SignRequestParams {
+  method: string
+  message: string
+  chain_id: number
+  typed_data?: string
+}
+
+export interface SignResponse {
+  transaction_id: string
+}
+
+export interface SignatureStatusResponse {
+  status: TxStatus
+  signature?: string
+  transaction_id: string
+  created_at: string
+  updated_at: string
+  approvals: Array<{
+    user_id: string
+    status: TxApprovalStatus
+  }>
+}
+
+export interface ApprovalInfo {
+  user_id: string
+  status: TxApprovalStatus
+}
+
+export interface TransactionStatusResponse {
+  transaction_id: string
+  status: TxStatus
+  method: string
+  hash?: string
+  created_at: string
+  updated_at: string
+  approvals: ApprovalInfo[]
+  failed_reason?: string
+}
+
+// Wallets
+export enum WalletType {
+  Standard = 'standard',
+  MPC = 'mpc'
+}
+
+export interface CreateWalletOptions {
+  name: string
+  walletType: WalletType
+}
+export enum WalletCreationStatus {
+  Pending = 'pending',
+  Success = 'success',
+  Error = 'error'
+}
+
+export interface CreateWalletResponse {
+  wallet_id: string
+  status: WalletCreationStatus
+}
+
+export interface WalletCreationStatusResponse {
+  wallet_id: string
+  status: WalletCreationStatus
+}
+
+export interface WalletAssetNetwork {
+  id: string
+  created_at: string
+  updated_at: string
+  name: string
+  description?: string
+  is_evm: boolean
+  chain_id: number
+  native_currency: string
+  is_testnet?: boolean
+  internal_code: string
+  explorer_tx: string
+  explorer_address: string
+  explorer_token: string
+  confirmation_blocks: number
+  block_interval_in_seconds: number
+  disabled: boolean
+  logo_url: string
+}
+
+export interface WalletAssetDetail {
+  id: string
+  created_at: string
+  updated_at: string
+  name: string
+  symbol: string
+  decimals: number
+  logo_url: string
+  is_native: boolean
+  address_type: string
+  is_whitelisted: boolean
+  address?: string
+  network_id: string
+  network?: WalletAssetNetwork
+}
+
+export interface WalletAsset {
+  id: string
+  created_at: string
+  updated_at: string
+  wallet_id: string
+  asset_id: string
+  deposit_address: string
+  hidden: boolean
+  asset: WalletAssetDetail
+}
+
+export enum AddressType {
+  Evm = 'evm',
+  Solana = 'sol'
+}
+
+export interface DepositAddressResponse {
+  asset_id?: string
+  address: string
+  qr_code: string
+}

package/src/utils/statusPoller.ts

@@ -0,0 +1,82 @@
+export interface StatusPollerOptions {
+  maxAttempts?: number
+  interval?: number
+  backoffFactor?: number
+  maxInterval?: number
+  timeoutMs?: number
+}
+
+export const DEFAULT_POLLER_OPTIONS: StatusPollerOptions = {
+  maxAttempts: 10,
+  interval: 1000, // Start with 1 second
+  backoffFactor: 1.5, // Increase interval by 50% each time
+  maxInterval: 10000, // Max 10 seconds between attempts
+  timeoutMs: 10 * 60 * 1000 // 10 minutes totla
+}
+
+export class StatusPoller {
+  private startTime: number
+  private attempts: number
+  private currentInterval: number
+  private readonly options: Required<StatusPollerOptions>
+
+  constructor(options: StatusPollerOptions = {}) {
+    this.options = { ...DEFAULT_POLLER_OPTIONS, ...options } as Required<StatusPollerOptions>
+    this.startTime = Date.now()
+    this.attempts = 0
+    this.currentInterval = this.options.interval
+  }
+
+  private async wait(): Promise<void> {
+    await new Promise((resolve) => setTimeout(resolve, this.currentInterval))
+
+    // Implement exponential backoff
+    this.currentInterval = Math.min(
+      this.currentInterval * this.options.backoffFactor,
+      this.options.maxInterval
+    )
+  }
+
+  private shouldContinue(): boolean {
+    const timeElapsed = Date.now() - this.startTime
+    if (timeElapsed >= this.options.timeoutMs) {
+      throw new Error(`Status polling timed out after ${timeElapsed}ms`)
+    }
+
+    if (this.attempts >= this.options.maxAttempts) {
+      throw new Error(`Maximum polling attempts (${this.options.maxAttempts}) exceeded`)
+    }
+
+    return true
+  }
+
+  async poll<T>(
+    pollingFn: () => Promise<T>,
+    successCondition: (result: T) => boolean,
+    errorCondition?: (result: T) => boolean | void
+  ): Promise<T> {
+    while (this.shouldContinue()) {
+      this.attempts++
+
+      const result = await pollingFn()
+
+      // Check for error condition first
+      if (errorCondition) {
+        const shouldError = errorCondition(result)
+        if (shouldError) {
+          throw new Error('Status polling failed')
+        }
+      }
+
+      // Check for success condition
+      if (successCondition(result)) {
+        return result
+      }
+
+      // If neither condition is met, wait and continue polling
+      await this.wait()
+    }
+
+    throw new Error('Polling ended without meeting success condition')
+  }
+}

package/src/utils.ts

@@ -0,0 +1,101 @@
+import CryptoJS from 'crypto-js'
+import { WebhookEvent } from './types'
+
+export async function computeHMAC(
+  apiSecret: string,
+  params: Record<string, string>
+): Promise<string> {
+  const encodedParams = Object.entries(params)
+    .map(([key, value]) => `${key}=${value}`)
+    .join('&')
+
+  const digest = CryptoJS.HmacSHA256(encodedParams, apiSecret)
+  return digest.toString(CryptoJS.enc.Hex)
+}
+
+export async function computeHMACForWebhook(
+  apiSecret: string,
+  event: WebhookEvent
+): Promise<string> {
+  const eventStr = canonicalizeJSON(event)
+  console.log('eventStr', eventStr)
+  const digest = CryptoJS.HmacSHA256(eventStr, apiSecret)
+  return digest.toString(CryptoJS.enc.Hex)
+}
+
+/**
+ * Canonicalizes a TypeScript object by sorting its keys recursively.
+ *
+ * @param inputObject - The input object to canonicalize.
+ * @returns A canonicalized JSON string with sorted keys.
+ * @throws Error if the input is not a valid object.
+ */
+export function canonicalizeJSON(inputObject: Record<string, any>): string {
+  if (typeof inputObject !== 'object' || inputObject === null) {
+    throw new Error('Input must be a non-null object.')
+  }
+
+  /**
+   * Recursively sorts the keys of an object or processes arrays.
+   *
+   * @param value - The value to sort (can be an object, array, or primitive).
+   * @returns The sorted value.
+   */
+  const sortKeys = (value: any): any => {
+    if (Array.isArray(value)) {
+      // Recursively sort each element in the array
+      return value.map(sortKeys)
+    }
+
+    if (value && typeof value === 'object' && value.constructor === Object) {
+      // Sort object keys and recursively sort their values
+      return Object.keys(value)
+        .sort()
+        .reduce((sortedObj: Record<string, any>, key: string) => {
+          sortedObj[key] = sortKeys(value[key])
+          return sortedObj
+        }, {})
+    }
+
+    // Return primitive values as-is
+    return value
+  }
+
+  // Sort the keys recursively
+  const sortedObject = sortKeys(inputObject)
+
+  // Convert the sorted object back into a JSON string
+  return JSON.stringify(sortedObject)
+}
+
+/**
+ * Validates if a string is a valid UUID v4
+ * @param uuid The string to validate
+ * @returns boolean indicating if the string is a valid UUID
+ */
+export function isValidUUID(uuid: string): boolean {
+  if (!uuid || typeof uuid !== 'string') {
+    return false
+  }
+
+  // UUID v4 pattern:
+  // 8-4-4-4-12 where third group starts with 4 and fourth group starts with 8, 9, a, or b
+  const uuidV4Regex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+  return uuidV4Regex.test(uuid)
+}
+
+/**
+ * Validates if a string is a valid UUID and throws an error if not
+ * @param uuid The string to validate
+ * @param paramName The name of the parameter being validated (for error message)
+ * @throws Error if the UUID is invalid
+ */
+export function validateUUID(uuid: string, paramName: string): void {
+  if (!uuid || typeof uuid !== 'string') {
+    throw new Error(`${paramName} is required and must be a string`)
+  }
+
+  if (!isValidUUID(uuid)) {
+    throw new Error(`Invalid ${paramName} format. Must be a valid UUID v4`)
+  }
+}

package/test.js

@@ -0,0 +1,76 @@
+import { TypedDataEncoder, verifyTypedData, Signature } from 'ethers'
+
+// 0x2f71f2595162eaca40708bf6d6327d437e760b27d26f3a933389ebdb4eedf3b167008df6f1d403503c82a6d58da5659b14c578019603d6b138b2c03729c92af701
+// 0xd77d10c530b25d1ea6a466eb2b3169138b5ca0d1320ff54bbad000d97f686d0a314c5233844d84da5adf3580afa38c82d9595c22a985acfea02ca722c55df48a00
+// Example usage
+const address = '0xFFe120Fd4D5AB5A9f25b25c30620ac8ee3E1EF21'
+const jsonData = {
+  domain: {
+    name: 'Permit2',
+    chainId: '8453',
+    verifyingContract: '0x000000000022d473030f116ddee9f6b43ac78ba3'
+  },
+  types: {
+    PermitSingle: [
+      { name: 'details', type: 'PermitDetails' },
+      { name: 'spender', type: 'address' },
+      { name: 'sigDeadline', type: 'uint256' }
+    ],
+    PermitDetails: [
+      { name: 'token', type: 'address' },
+      { name: 'amount', type: 'uint160' },
+      { name: 'expiration', type: 'uint48' },
+      { name: 'nonce', type: 'uint48' }
+    ]
+  },
+  message: {
+    details: {
+      token: '0x0b3e328455c4059eeb9e3f84b5543f74e24e7e1b',
+      amount: '1461501637330902918203684832716283019655932542975',
+      expiration: '1743496074',
+      nonce: '0'
+    },
+    spender: '0x6ff5693b99212da76ad316178a184ab56d299b43',
+    sigDeadline: '1740905874'
+  }
+}
+const signature =
+  '0x032f29648f9c2d9d2524aef755c225b96121f2c9b01beee5869a70ef95eb089548dc41f71126dac83c1632738dbea12bf5c925715068e32dda0064701bfc019e00'
+
+async function verifySignature(address, jsonData, signature) {
+  try {
+    // Step 1: Compute the EIP-712 hash
+    const computedHash = TypedDataEncoder.hash(jsonData.domain, jsonData.types, jsonData.message)
+    console.log('🔹 Computed EIP-712 Hash:', computedHash)
+
+    // Step 2: Recover the signer address
+    const recoveredAddress = verifyTypedData(
+      jsonData.domain,
+      jsonData.types,
+      jsonData.message,
+      signature
+    )
+
+    console.log('✅ Recovered Address:', recoveredAddress)
+    console.log('🔹 Expected Address:', address)
+
+    // Step 3: Compare the addresses
+    const isValid = recoveredAddress.toLowerCase() === address.toLowerCase()
+    console.log('🔹 Is Signature Valid?', isValid)
+
+    // Step 4: Debug signature parts (r, s, v)
+    const sig = Signature.from(signature)
+    console.log('🔹 Signature Parts:')
+    console.log('   r:', sig.r)
+    console.log('   s:', sig.s)
+    console.log('   v:', sig.v)
+
+    return isValid
+  } catch (error) {
+    console.error('❌ Signature Verification Failed:', error)
+    return false
+  }
+}
+
+// Run verification
+verifySignature(address, jsonData, signature)

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "declaration": true,
+    "declarationDir": "dist/types",
+    "rootDirs": ["src", "test"],
+    "outDir": "dist",
+    "module": "es2020",
+    "target": "es2020",
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node",
+    "lib": ["es2020"],
+    "strictNullChecks": true,
+    "noImplicitAny": true,
+    "skipLibCheck": true
+  },
+  "exclude": ["node_modules", "**/*.test.ts"]
+}

package/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/types/importMeta.d.ts" />

package/vitest.config.js

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config'
+import { loadEnv } from 'vite'
+
+// https://vitest.dev/config/
+export default defineConfig({
+  test: {
+    testTimeout: 20000 * 1000,
+    env: loadEnv('', process.cwd(), '')
+  }
+})