SDK Design Guide

IBEx.Fi API SDK - Guide de conception

Ce document présente les recommandations et conseils pour la création d'un SDK permettant d'utiliser l'API IBEx.Fi.

Vue d'ensemble de l'API

L'API IBEx.Fi est une API RESTful avec support WebSocket qui permet :

Authentification passwordless via FIDO2/Passkeys (WebAuthn)
Déploiement de wallets Safe sur plusieurs blockchains (EVM, Solana, Bitcoin)
Opérations blockchain : transferts de tokens, signatures de messages, swaps
Gestion de récupération de wallet
Stockage de données utilisateur (IBEx Safe)
Lecture de données blockchain (balances, transactions, pools)
Mises à jour en temps réel via WebSocket

Versions de l'API

L'API supporte plusieurs versions :

v1 : Version de base
v1.1 : Extensions avec fallback automatique vers v1
v1.2 : Extensions spécifiques (ex: recovery)

Authentification

JWT : Token Bearer pour les endpoints authentifiés
API_KEY : Pour certains endpoints système
Passkey : Authentification WebAuthn pour signup/signin

Multi-tenant (rpId/CNAME)

L'API utilise le concept de rpId (relying party ID) extrait du hostname pour isoler les tenants. Les clients doivent configurer un CNAME pointant vers l'API.

Recommandations pour le SDK

1. Architecture générale

1.1 Structure modulaire

Le SDK devrait être organisé en modules correspondant aux domaines fonctionnels de l'API :

IBExSDK/
├── core/
│   ├── Client.ts          # Client HTTP de base
│   ├── Auth.ts            # Gestion de l'authentification
│   ├── Config.ts          # Configuration
│   └── Types.ts           # Types TypeScript
├── auth/
│   ├── PasskeyAuth.ts     # Authentification Passkey
│   └── TokenManager.ts    # Gestion des tokens JWT
├── blockchain/
│   ├── Safes.ts           # Opérations Safe
│   ├── Operations.ts      # Opérations blockchain
│   └── BCReader.ts        # Lecture blockchain
├── swap/
│   ├── CoWSwap.ts         # Intégration CoW Protocol
│   └── OneInch.ts         # Intégration 1inch
├── recovery/
│   └── Recovery.ts        # Gestion de la récupération
├── users/
│   └── Users.ts           # Gestion utilisateurs
├── websocket/
│   └── WebSocketClient.ts # Client WebSocket
└── index.ts               # Point d'entrée principal

1.2 Langages ciblés

Priorité 1 : TypeScript/JavaScript (Node.js et navigateur)

Support natif de WebAuthn dans les navigateurs
Large adoption dans l'écosystème Web3
Typage fort avec TypeScript

Priorité 2 : Python

Popularité dans l'écosystème blockchain
Support WebAuthn via bibliothèques tierces

Priorité 3 : Autres langages selon la demande (Rust, Go, etc.)

2. Configuration et initialisation

2.1 Configuration de base

interface IBExSDKConfig {
  // URL de base de l'API (optionnel, peut être déduit du rpId)
  baseUrl?: string;
  
  // rpId (relying party ID) - requis pour le multi-tenant
  rpId: string;
  
  // Blockchain par défaut (chainId)
  defaultChainId?: number;
  
  // Headers personnalisés
  headers?: Record<string, string>;
  
  // Configuration du timeout
  timeout?: number;
  
  // Mode debug
  debug?: boolean;
}

2.2 Initialisation

import { IBExSDK } from '@ibexfi/sdk';
 
const sdk = new IBExSDK({
  rpId: 'example.com',
  defaultChainId: 100, // Gnosis Chain
  debug: true
});

3. Gestion de l'authentification

3.1 Flow Passkey (WebAuthn)

Le SDK doit abstraire le flow WebAuthn en deux étapes :

// Signup
const signupOptions = await sdk.auth.passkey.getSignupOptions({
  userName: 'John Doe',
  userDisplayName: 'John'
});
 
const credential = await navigator.credentials.create(signupOptions);
const signupResult = await sdk.auth.passkey.completeSignup({
  challenge: signupOptions.challenge,
  credential: credential,
  chainIds: [100, 1, 137] // Multi-chain deployment
});
 
// Le SDK stocke automatiquement les tokens
// signupResult.access_token, signupResult.refresh_token

// Signin
const signinOptions = await sdk.auth.passkey.getSigninOptions();
const assertion = await navigator.credentials.get(signinOptions);
const signinResult = await sdk.auth.passkey.completeSignin({
  challenge: signinOptions.challenge,
  credential: assertion
});

3.2 Gestion des tokens

Le SDK doit gérer automatiquement :

Stockage sécurisé des tokens (localStorage, sessionStorage, ou storage personnalisé)
Refresh automatique des tokens expirés
Injection automatique du token Bearer dans les requêtes
Gestion de la déconnexion

// Le SDK gère automatiquement le refresh
sdk.auth.setTokens({
  accessToken: '...',
  refreshToken: '...',
  expiresIn: 3600
});
 
// Vérification de l'état d'authentification
if (await sdk.auth.isAuthenticated()) {
  // Utilisateur authentifié
}
 
// Déconnexion
await sdk.auth.signout();

4. Support multi-chaînes

4.1 Gestion des chainIds

Le SDK doit supporter :

Header X-Blockchain-Id (méthode préférée)
Query parameter blockchainId (fallback)
Configuration par défaut via defaultChainId

// Utilisation avec chainId spécifique
const balances = await sdk.blockchain.balances.get({
  address: '0x...',
  chainId: 421614 // Arbitrum Sepolia
});
 
// Utilisation avec chainId par défaut
const balances = await sdk.blockchain.balances.get({
  address: '0x...'
});

4.2 Support multi-blockchains

L'API supporte :

EVM chains : Ethereum, Gnosis, Polygon, Arbitrum, Base, etc.
Solana : Mainnet (chainId: 900), Devnet (chainId: 901)
Bitcoin : Mainnet, Testnet

Le SDK doit abstraire les différences entre ces blockchains :

// Transfert EVM
await sdk.blockchain.transfer({
  to: '0x...',
  tokenAddress: '0x...',
  amount: '1.5',
  chainId: 100
});
 
// Transfert Solana
await sdk.blockchain.transfer({
  to: 'So11111111111111111111111111111111111111112',
  tokenAddress: 'So11111111111111111111111111111111111111111',
  amount: '1.5',
  chainId: 900 // Solana Mainnet
});

5. Opérations blockchain

5.1 Opérations Safe

// Créer une opération de transfert
const operation = await sdk.blockchain.safes.createOperation({
  type: 'TRANSFER_TOKEN',
  data: {
    to: '0x...',
    tokenAddress: '0x...',
    amount: '1.5'
  },
  chainId: 100
});
 
// Signer l'opération (via Passkey)
await sdk.blockchain.safes.signOperation(operation.id);
 
// Vérifier le statut
const status = await sdk.blockchain.safes.getOperationStatus(operation.id);

5.2 Types d'opérations supportées

Le SDK doit supporter tous les types d'opérations :

TRANSFER_TOKEN : Transfert de tokens ERC20
SIGN_MESSAGE : Signature de messages
ENABLE_RECOVERY : Activation de la récupération
DISABLE_RECOVERY : Désactivation de la récupération
EXECUTE_RECOVERY : Exécution de la récupération
SWAP_TOKEN : Échange de tokens
Et autres...

6. BCReader (Lecture blockchain)

6.1 Balances

// Récupérer les balances
const balances = await sdk.blockchain.bcreader.getBalances({
  address: '0x...',
  chainId: 100,
  includePrices: true, // Inclure les prix en USD/EUR
  includeZero: false
});
 
// Balances multi-chaînes
const multiChainBalances = await sdk.blockchain.bcreader.getBalancesMultiChain({
  address: '0x...',
  chainIds: [100, 1, 137],
  includePrices: true
});

6.2 Transactions

// Récupérer les transactions
const transactions = await sdk.blockchain.bcreader.getTransactions({
  address: '0x...',
  chainId: 100,
  startDate: '2024-01-01',
  endDate: '2024-12-31',
  limit: 50,
  offset: 0
});

6.3 Pools (AAVE)

// Lister les pools disponibles
const pools = await sdk.blockchain.bcreader.getPools({
  chainId: 100
});
 
// Récupérer les positions d'un utilisateur
const positions = await sdk.blockchain.bcreader.getUserPositions({
  address: '0x...',
  chainId: 100
});

7. Swap (Échange de tokens)

7.1 CoW Protocol

// Obtenir un devis
const quote = await sdk.swap.cow.getQuote({
  sellToken: '0x...',
  buyToken: '0x...',
  amount: '100',
  chainId: 100
});
 
// Exécuter le swap
const swapResult = await sdk.swap.cow.executeSwap({
  quote: quote,
  chainId: 100
});

7.2 1inch

// Obtenir un devis
const quote = await sdk.swap.oneinch.getQuote({
  fromTokenAddress: '0x...',
  toTokenAddress: '0x...',
  amount: '100',
  chainId: 100
});
 
// Exécuter le swap
const swapResult = await sdk.swap.oneinch.executeSwap({
  quote: quote,
  chainId: 100
});

8. WebSocket (Mises à jour en temps réel)

// Connexion WebSocket
const ws = await sdk.websocket.connect({
  onBalanceUpdate: (data) => {
    console.log('Balance updated:', data);
  },
  onTransactionUpdate: (data) => {
    console.log('Transaction updated:', data);
  },
  onOperationUpdate: (data) => {
    console.log('Operation updated:', data);
  }
});
 
// S'abonner à des événements spécifiques
ws.subscribe('balance', { address: '0x...', chainId: 100 });
ws.subscribe('transaction', { address: '0x...', chainId: 100 });
 
// Déconnexion
ws.disconnect();

9. Gestion des erreurs

9.1 Types d'erreurs

Le SDK doit définir des classes d'erreur spécifiques :

class IBExSDKError extends Error {}
class AuthenticationError extends IBExSDKError {}
class NetworkError extends IBExSDKError {}
class ValidationError extends IBExSDKError {}
class RateLimitError extends IBExSDKError {}
class BlockchainError extends IBExSDKError {}

9.2 Gestion des erreurs API

L'API retourne des erreurs structurées. Le SDK doit les mapper :

try {
  await sdk.blockchain.transfer({...});
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Token expiré, tenter refresh
    await sdk.auth.refreshToken();
  } else if (error instanceof RateLimitError) {
    // Attendre avant de réessayer
    await delay(error.retryAfter);
  }
}

10. Utilitaires et helpers

10.1 Conversion de montants

// Convertir un montant en wei
const weiAmount = sdk.utils.toWei('1.5', 18); // 1.5 ETH -> wei
 
// Convertir wei en montant lisible
const readableAmount = sdk.utils.fromWei('1500000000000000000', 18); // wei -> 1.5 ETH

10.2 Validation d'adresses

// Valider une adresse EVM
sdk.utils.isValidEVMAddress('0x...');
 
// Valider une adresse Solana
sdk.utils.isValidSolanaAddress('So11111111111111111111111111111111111111112');
 
// Valider une adresse Bitcoin
sdk.utils.isValidBitcoinAddress('bc1...');

10.3 Formatage

// Formater un montant avec décimales
sdk.utils.formatAmount('1500000000000000000', 18, 2); // "1.50"
 
// Formater une adresse (raccourcie)
sdk.utils.formatAddress('0x1234567890123456789012345678901234567890'); // "0x1234...7890"

11. Gestion de la récupération

// Activer la récupération
await sdk.recovery.enable({
  safeAddress: '0x...',
  recoveryAddress: '0x...',
  delay: 86400, // 24 heures en secondes
  description: 'Recovery wallet'
});
 
// Vérifier le statut
const status = await sdk.recovery.getStatus({
  safeAddress: '0x...'
});
 
// Initier la récupération
await sdk.recovery.initiate({
  safeAddress: '0x...'
});
 
// Exécuter la récupération (après le délai)
await sdk.recovery.execute({
  safeAddress: '0x...',
  newOwners: ['0x...'],
  threshold: 1
});

12. Stockage de données utilisateur (IBEx Safe)

// Stocker des données
await sdk.users.data.set({
  key: 'userPreferences',
  value: { theme: 'dark', language: 'fr' }
});
 
// Récupérer des données
const data = await sdk.users.data.get('userPreferences');
 
// Supprimer des données
await sdk.users.data.delete('userPreferences');

13. Gestion des versions

13.1 Support des versions multiples

Le SDK doit supporter les différentes versions de l'API :

// Utiliser v1.1 explicitement
const user = await sdk.v1_1.users.get('userId');
 
// Utiliser v1.2 pour recovery
const recovery = await sdk.v1_2.recovery.getStatus('0x...');
 
// Version par défaut (v1)
const balances = await sdk.blockchain.balances.get({...});

13.2 Migration entre versions

Le SDK doit faciliter la migration :

// Détecter automatiquement la meilleure version
const user = await sdk.users.get('userId'); // Utilise v1.1 si disponible

14. Tests et validation

14.1 Tests unitaires

Le SDK doit inclure des tests pour :

Chaque module fonctionnel
Gestion des erreurs
Conversion de formats
Validation des données

14.2 Tests d'intégration

Tests avec un environnement de test de l'API :

Flow complet d'authentification
Opérations blockchain end-to-end
WebSocket en conditions réelles

14.3 Mocks et fixtures

Fournir des mocks pour faciliter les tests des applications utilisant le SDK :

import { createMockSDK } from '@ibexfi/sdk/mocks';
 
const mockSDK = createMockSDK({
  mockAuth: true,
  mockBlockchain: true
});

15. Documentation

15.1 Documentation API

JSDoc/TSDoc : Documentation inline pour toutes les méthodes
README : Guide de démarrage rapide
Guides : Tutoriels pour les cas d'usage courants
Exemples : Exemples de code pour chaque fonctionnalité

15.2 Documentation de référence

API Reference : Documentation complète de toutes les méthodes
Types : Documentation des types TypeScript
Erreurs : Liste complète des erreurs possibles

16. Performance et optimisation

16.1 Mise en cache

// Cache des balances
const balances = await sdk.blockchain.balances.get({
  address: '0x...',
  cache: true, // Utiliser le cache si disponible
  cacheTTL: 60 // TTL en secondes
});

16.2 Requêtes batch

// Récupérer plusieurs balances en une seule requête
const balances = await sdk.blockchain.balances.getBatch([
  { address: '0x...', chainId: 100 },
  { address: '0x...', chainId: 1 }
]);

16.3 Retry et backoff

Le SDK doit implémenter une stratégie de retry intelligente :

const sdk = new IBExSDK({
  retry: {
    maxRetries: 3,
    retryDelay: 1000, // ms
    backoff: 'exponential'
  }
});

17. Sécurité

17.1 Stockage sécurisé des tokens

Navigateur : Utiliser sessionStorage ou localStorage avec préfixe sécurisé
Node.js : Utiliser un système de stockage sécurisé (keychain, etc.)
Support de storage personnalisé : Permettre aux utilisateurs de fournir leur propre storage

17.2 Validation côté client

Valider les données avant l'envoi à l'API :

// Validation automatique
await sdk.blockchain.transfer({
  to: 'invalid', // Lève une ValidationError avant l'appel API
  amount: '-1'   // Lève une ValidationError
});

17.3 Protection CSRF

Le SDK doit gérer automatiquement les tokens CSRF si nécessaire.

18. Intégration avec frameworks populaires

18.1 React

import { useIBExSDK } from '@ibexfi/sdk-react';
 
function MyComponent() {
  const { sdk, isAuthenticated, user } = useIBExSDK();
  
  // Utiliser le SDK dans le composant
}

18.2 Vue.js

import { useIBExSDK } from '@ibexfi/sdk-vue';
 
export default {
  setup() {
    const { sdk, isAuthenticated } = useIBExSDK();
    // ...
  }
}

18.3 Next.js

// Support SSR
import { IBExSDKProvider } from '@ibexfi/sdk-next';
 
function App({ Component, pageProps }) {
  return (
    <IBExSDKProvider config={{ rpId: 'example.com' }}>
      <Component {...pageProps} />
    </IBExSDKProvider>
  );
}

19. Observabilité et logging

19.1 Logging

const sdk = new IBExSDK({
  logger: {
    level: 'debug', // 'error' | 'warn' | 'info' | 'debug'
    handler: (level, message, data) => {
      console.log(`[${level}] ${message}`, data);
    }
  }
});

19.2 Métriques

Le SDK peut exposer des métriques :

const metrics = sdk.getMetrics();
// {
//   requests: { total: 100, success: 95, failed: 5 },
//   averageResponseTime: 250,
//   cacheHitRate: 0.8
// }

20. Roadmap et évolutions futures

20.1 Fonctionnalités à considérer

Support offline : Cache local pour fonctionnement hors ligne
Synchronisation : Synchronisation automatique des données
Plugins : Système de plugins pour étendre le SDK
CLI : Outil en ligne de commande pour les développeurs
DevTools : Extension navigateur pour le débogage

20.2 Compatibilité

Rétrocompatibilité : Maintenir la compatibilité avec les versions précédentes
Dépréciations : Gérer les dépréciations de manière claire
Migration guides : Guides de migration entre versions majeures

Exemple d'utilisation complète

import { IBExSDK } from '@ibexfi/sdk';
 
// 1. Initialisation
const sdk = new IBExSDK({
  rpId: 'myapp.com',
  defaultChainId: 100,
  debug: true
});
 
// 2. Authentification
const signupOptions = await sdk.auth.passkey.getSignupOptions({
  userName: 'John Doe'
});
const credential = await navigator.credentials.create(signupOptions);
await sdk.auth.passkey.completeSignup({
  challenge: signupOptions.challenge,
  credential: credential,
  chainIds: [100, 1]
});
 
// 3. Récupérer les balances
const balances = await sdk.blockchain.bcreader.getBalances({
  address: '0x...',
  chainId: 100,
  includePrices: true
});
 
// 4. Effectuer un transfert
const operation = await sdk.blockchain.safes.createOperation({
  type: 'TRANSFER_TOKEN',
  data: {
    to: '0x...',
    tokenAddress: '0x...',
    amount: '1.5'
  },
  chainId: 100
});
await sdk.blockchain.safes.signOperation(operation.id);
 
// 5. Écouter les mises à jour via WebSocket
const ws = await sdk.websocket.connect({
  onOperationUpdate: (data) => {
    console.log('Operation status:', data.status);
  }
});
ws.subscribe('operation', { operationId: operation.id });

Conclusion

Ce SDK doit être :

Simple à utiliser : API intuitive et bien documentée
Type-safe : Support TypeScript complet
Robuste : Gestion d'erreurs complète et retry automatique
Performant : Mise en cache et optimisations
Sécurisé : Gestion sécurisée des tokens et validation
Extensible : Architecture modulaire permettant l'extension
Bien documenté : Documentation complète avec exemples

Le SDK doit abstraire la complexité de l'API tout en restant flexible pour les cas d'usage avancés.

SDK Design Guide

On this page