Keygate SDK

Introduction

Internet Computer Protocol needs an aggregator to find routes between networks in the most efficient way. This repository provides that SDK for developers to integrate into their dApps.

Architecture

This SDK is a fork of the LI.FI SDK. If one desires to migrate from LI.FI to Keygate, doing so is quite simple since both of these tools share the same API and design patterns.

Abstractions

graph TB
    subgraph "Client Application"
        APP["Client App"]
        CONFIG["createConfig()"]
    end
    
    subgraph "SDK Core"
        CORE_CONFIG["config"]
        API["API Services"]
        EXECUTION["Route Execution Engine"]
        STATE["Execution State Manager"]
    end
    
    subgraph "Chain Providers"
        EVM_PROV["EVM Provider"]
        ICP_PROV["ICP Provider"]
        SOL_PROV["Solana Provider"]
        SUI_PROV["Sui Provider"]
        UTXO_PROV["UTXO Provider"]
    end
    
    subgraph "Step Executors"
        EVM_EXEC["EVMStepExecutor"]
        ICP_EXEC["ICPStepExecutor"]
        SOL_EXEC["SolanaStepExecutor"]
        SUI_EXEC["SuiStepExecutor"]
        UTXO_EXEC["UTXOStepExecutor"]
        BASE_EXEC["BaseStepExecutor"]
    end
    
    subgraph "External Services"
        KEYGATE_API["Keygate API<br/>(Routes, Status, Tokens)"]
        ONESEC["OneSec Bridge<br/>(ICP to EVM)"]
        RPC["RPC Endpoints<br/>(Various Chains)"]
    end
    
    subgraph "Blockchain Networks"
        ETHEREUM["Ethereum"]
        ARBITRUM["Arbitrum"]
        BASE["Base"]
        ICP_CHAIN["Internet Computer"]
        SOLANA_CHAIN["Solana"]
        SUI_CHAIN["Sui"]
        BITCOIN["Bitcoin/UTXO"]
    end
    
    %% Client connections
    APP --> CONFIG
    CONFIG --> CORE_CONFIG
    APP --> EXECUTION
    
    %% Core connections
    CORE_CONFIG --> API
    EXECUTION --> STATE
    EXECUTION --> CORE_CONFIG
    API --> KEYGATE_API
    
    %% Provider registration
    CORE_CONFIG --> EVM_PROV
    CORE_CONFIG --> ICP_PROV
    CORE_CONFIG --> SOL_PROV
    CORE_CONFIG --> SUI_PROV
    CORE_CONFIG --> UTXO_PROV
    
    %% Step executor creation
    EVM_PROV --> EVM_EXEC
    ICP_PROV --> ICP_EXEC
    SOL_PROV --> SOL_EXEC
    SUI_PROV --> SUI_EXEC
    UTXO_PROV --> UTXO_EXEC
    
    %% Inheritance
    BASE_EXEC -.-> EVM_EXEC
    BASE_EXEC -.-> ICP_EXEC
    BASE_EXEC -.-> SOL_EXEC
    BASE_EXEC -.-> SUI_EXEC
    BASE_EXEC -.-> UTXO_EXEC
    
    %% External service connections
    ICP_EXEC --> ONESEC
    EVM_EXEC --> RPC
    SOL_EXEC --> RPC
    SUI_EXEC --> RPC
    UTXO_EXEC --> RPC
    
    %% Blockchain connections
    EVM_EXEC --> ETHEREUM
    EVM_EXEC --> ARBITRUM
    EVM_EXEC --> BASE
    ICP_EXEC --> ICP_CHAIN
    SOL_EXEC --> SOLANA_CHAIN
    SUI_EXEC --> SUI_CHAIN
    UTXO_EXEC --> BITCOIN
    
    %% Bridge connections
    ONESEC --> ETHEREUM
    ONESEC --> ARBITRUM
    ONESEC --> BASE
    
    classDef clientClass fill:#e1f5fe,color:#000
    classDef coreClass fill:#f3e5f5,color:#000
    classDef providerClass fill:#e8f5e8,color:#000
    classDef executorClass fill:#fff3e0,color:#000
    classDef externalClass fill:#fce4ec,color:#000
    classDef blockchainClass fill:#f1f8e9,color:#000
    
    class APP,CONFIG clientClass
    class CORE_CONFIG,API,EXECUTION,STATE coreClass
    class EVM_PROV,ICP_PROV,SOL_PROV,SUI_PROV,UTXO_PROV providerClass
    class EVM_EXEC,ICP_EXEC,SOL_EXEC,SUI_EXEC,UTXO_EXEC,BASE_EXEC executorClass
    class KEYGATE_API,ONESEC,RPC externalClass
    class ETHEREUM,ARBITRUM,BASE,ICP_CHAIN,SOLANA_CHAIN,SUI_CHAIN,BITCOIN blockchainClass

Sequence diagram

sequenceDiagram
    participant Client
    participant SDK as SDK Core
    participant Provider as Chain Provider
    participant Executor as Step Executor
    participant StatusMgr as Status Manager
    participant External as External Service
    participant Blockchain
    
    Note over Client, Blockchain: Route Execution Flow
    
    Client->>SDK: executeRoute(route, options)
    SDK->>SDK: Clone route & check execution state
    SDK->>Provider: Find provider by fromAddress
    Provider->>Executor: getStepExecutor(options)
    Executor->>StatusMgr: Initialize StatusManager
    
    loop For each step in route
        SDK->>Executor: executeStep(step)
        Executor->>StatusMgr: initExecutionObject(step)
        StatusMgr-->>Executor: execution object
        
        Executor->>StatusMgr: findOrCreateProcess(CROSS_CHAIN/SWAP)
        StatusMgr-->>Executor: process object
        
        Executor->>StatusMgr: updateProcess(STARTED)
        
        alt ICP Bridge Execution
            Executor->>External: Create OneSec bridge plan
            External-->>Executor: Bridge plan with steps
            
            loop Execute bridge steps
                Executor->>External: nextStep.run()
                External->>Blockchain: Submit transaction
                Blockchain-->>External: Transaction result
                External-->>Executor: Step result
                Executor->>StatusMgr: updateProcess(progress)
            end
            
            Executor->>StatusMgr: updateProcess(DONE, txHash)
            
        else EVM Execution
            Executor->>Blockchain: Submit transaction
            Blockchain-->>Executor: Transaction hash
            Executor->>StatusMgr: updateProcess(DONE, txHash)
            
        else Other Chain Execution
            Executor->>Blockchain: Submit transaction
            Blockchain-->>Executor: Transaction result
            Executor->>StatusMgr: updateProcess(DONE)
        end
        
        Executor-->>SDK: Updated step
        
        alt Step not complete
            SDK->>SDK: Stop execution (awaiting user interaction)
            SDK-->>Client: Partial route
        end
    end
    
    SDK->>SDK: Clean up execution state
    SDK-->>Client: Completed route

Feature overview

graph LR
    subgraph "Chain Type Support"
        EVM["EVM Chains<br/>• Ethereum<br/>• Arbitrum<br/>• Base<br/>• Polygon<br/>• Optimism<br/>• BSC<br/>• Avalanche"]
        ICP["Internet Computer<br/>• ICP Mainnet<br/>• Canisters<br/>• ICRC-1 Tokens"]
        SVM["Solana VM<br/>• Solana Mainnet<br/>• SPL Tokens<br/>• Program Calls"]
        MVM["Sui Move VM<br/>• Sui Mainnet<br/>• Sui Objects<br/>• Move Packages"]
        UTXO["UTXO Chains<br/>• Bitcoin<br/>• Litecoin<br/>• Bitcoin Cash"]
    end
    
    subgraph "Cross-Chain Operations"
        BRIDGE["Bridging<br/>• Asset transfers<br/>• Cross-chain swaps<br/>• Liquidity bridging"]
        SWAP["Swapping<br/>• DEX aggregation<br/>• Best price routing<br/>• Slippage protection"]
        YIELD["DeFi Operations<br/>• Yield farming<br/>• Staking<br/>• Lending"]
    end
    
    subgraph "Supported Bridges & DEXs"
        ONESEC_B["OneSec<br/>(ICP ↔ EVM)"]
        LIFI["LiFi Protocol<br/>(Multi-chain)"]
        STARGATE["Stargate<br/>(LayerZero)"]
        ACROSS["Across Protocol"]
        CCTP["Circle CCTP<br/>(USDC)"]
        UNISWAP["Uniswap V2/V3"]
        SUSHISWAP["SushiSwap"]
        PANCAKE["PancakeSwap"]
        JUPITER["Jupiter<br/>(Solana)"]
    end
    
    subgraph "Key Features"
        GASLESS["Gasless Transactions<br/>• Meta transactions<br/>• Relayer support<br/>• Sponsored gas"]
        PERMITS["Permit Support<br/>• EIP-2612<br/>• Permit2<br/>• Gas optimization"]
        BATCHING["Transaction Batching<br/>• EIP-5792<br/>• Atomic operations<br/>• Reduced gas costs"]
        RECOVERY["Error Recovery<br/>• Resume execution<br/>• Retry failed steps<br/>• State persistence"]
    end
    
    %% Cross-chain connections
    EVM -.-> BRIDGE
    ICP -.-> BRIDGE
    SVM -.-> BRIDGE
    MVM -.-> BRIDGE
    UTXO -.-> BRIDGE
    
    %% Swap connections
    EVM --> SWAP
    SVM --> SWAP
    MVM --> SWAP
    
    %% Bridge/DEX connections
    BRIDGE --> ONESEC_B
    BRIDGE --> LIFI
    BRIDGE --> STARGATE
    BRIDGE --> ACROSS
    BRIDGE --> CCTP
    
    SWAP --> UNISWAP
    SWAP --> SUSHISWAP
    SWAP --> PANCAKE
    SWAP --> JUPITER
    
    %% Feature connections
    EVM --> GASLESS
    EVM --> PERMITS
    EVM --> BATCHING
    
    BRIDGE --> RECOVERY
    SWAP --> RECOVERY
    YIELD --> RECOVERY
    
    classDef chainClass fill:#e3f2fd,color:#000
    classDef operationClass fill:#f3e5f5,color:#000
    classDef protocolClass fill:#e8f5e8,color:#000
    classDef featureClass fill:#fff8e1,color:#000
    
    class EVM,ICP,SVM,MVM,UTXO chainClass
    class BRIDGE,SWAP,YIELD operationClass
    class ONESEC_B,LIFI,STARGATE,ACROSS,CCTP,UNISWAP,SUSHISWAP,PANCAKE,JUPITER protocolClass
    class GASLESS,PERMITS,BATCHING,RECOVERY featureClass