# dfinity/oisy-wallet architecture

> Architecture diagram of the GitHub repository dfinity/oisy-wallet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dfinity/oisy-wallet
- Repository: https://github.com/dfinity/oisy-wallet

## Overview

##### Project Type and Purpose
- OISY is a full-stack decentralized wallet application.
- Its goal is to provide a network-custodial wallet with multi-chain support (ICP, ICRC-1, ETH, ERC20, BTC – with more coming) utilizing features unique to the Internet Computer such as chain-key signatures and Internet Identity.
- The README emphasizes trust minimization and on-chain web serving, underpinning the secure, decentralized nature of the wallet.

##### Main Components
- Backend Canister: Written in Rust (under src/backend) and deployed as a canister on the Internet Computer. It handles critical operations such as tECDSA-based signatures, state management, migration routines, and token transactions.
- Frontend: Written entirely in Svelte (found under src/frontend), it consists of a rich set of UI components – from token management and exchange to wallet connectivity (including WalletConnect support). It calls upon on-chain canister APIs using JavaScript.
- Declarations and Shared Libraries: The “src/declarations” directory contains interface definitions (DID files, TypeScript definitions) that standardize communication between the frontend and backend as well as other canisters.
- Integration Modules: There are specialized folders (src/icp, src/eth, src/sol, src/cycles_ledger) that suggest dedicated modules for interacting with different blockchain networks, each containing API integrations, service layers, providers, and utilities.
- Testing and Scripts: The numerous test suites (e2e, frontend tests, backend tests) and deployment/build scripts show that the project follows a rigorous CI/CD and testing process.
- Infrastructure: Dockerfiles, dfx.json, and environment configuration files indicate containerization, local deployment, and integration with the Internet Computer Development Ecosystem.

##### Relationships and Interactions
- Frontend → Backend Communication: The browser-based frontend communicates with the backend canister through well-defined APIs (DID interfaces) for wallet operations, token transactions, and key management.
- Blockchain Services: The backend leverages ICP’s chain-key signature system and threshold ECDSA for distributed key custody. It calls Internet Identity for user authentication.
- External Services: The frontend also makes calls to centralized endpoints (such as Infura or Alchemy for Ethereum) – though future architecture may shift these calls to HTTP outcalls from the backend.
- Shared Modules: Libraries and shared utilities (in the “src/shared” folder) are used by both the frontend and backend canisters to standardize token formats, configuration, and cryptographic operations.
- Continuous Integration: The numerous GitHub workflows and scripts illustrate automated building, deployment, and testing processes.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clear division between frontend (UI/UX) and backend (business logic and cryptographic operations).
- Modular Design: Each supported blockchain (ICP, ETH, SOL, BTC, etc.) has its own dedicated modules and integration components.
- On-Chain Design: The architecture leverages ICP’s ability to serve both backend and frontend from canisters, emphasizing decentralization.
- Standardized Interfaces: Use of DID files and TypeScript declarations to ensure consistency between canister and browser communication.
- CI/CD and Testing: The inclusion of comprehensive tests and deployment scripts indicates a robust deployment pipeline.

##### Elements
– Frontend Canister (Svelte UI)
– Backend Canister (Rust, tECDSA, chain-key, migration)
– Blockchain Integration Modules (ICP, ETH, SOL, BTC, cycles ledger)
– Shared Libraries/Declarations (API interfaces, type schemas)
– External Services (Internet Identity, WalletConnect endpoints, centralized Ethereum providers)
– Testing & Deployment (CI/CD pipelines, Docker, dfx commands)

##### Final Suggestions
- Communication channels (HTTP calls, canister calls) to clearly show how the user’s actions in the browser translate to cryptographic operations and blockchain interactions.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["Frontend (Svelte UI)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        BE["Backend Canister (Rust, tECDSA, chain-key, migration)"]:::backend
    end

    %% Blockchain Integration Modules
    subgraph "Blockchain Integration Modules"
        ICPMod["ICP Integration Module"]:::module
        ETHMod["Ethereum Integration Module"]:::module
        SOLMod["Solana Integration Module"]:::module
        CYCMod["Cycles Ledger Module"]:::module
    end

    %% Shared Components
    subgraph "Shared Components"
        DEC["Declarations and Shared APIs"]:::shared
        SHRD["Shared Libraries/Utilities"]:::shared
    end

    %% Infrastructure & CI/CD
    subgraph "Infrastructure & CI/CD"
        CICD["Testing and CI/CD"]:::infra
        SCRIPTS["Deployment and Build Scripts"]:::infra
    end

    %% External Services
    subgraph "External Services"
        EXT["External Services (InternetIdentity, WalletConnect, Eth Providers)"]:::external
    end

    %% Connections between Frontend and Backend
    FE -->|"APICalls"| BE

    %% Backend interactions with Blockchain Integration Modules
    BE -->|"chain-key/tECDSA"| ICPMod
    BE -->|"token-ops"| ETHMod
    BE -->|"SolanaOps"| SOLMod
    BE -->|"ledgerOps"| CYCMod

    %% Shared components used by Frontend and Backend
    FE -->|"uses"| DEC
    FE -->|"uses"| SHRD
    BE -->|"uses"| DEC
    BE -->|"uses"| SHRD

    %% External services interactions
    FE -->|"auth/APICalls"| EXT
    BE -->|"HTTPOutcalls"| EXT

    %% CI/CD and Deployment into Frontend and Backend
    CICD -->|"build&test"| FE
    CICD -->|"build&test"| BE
    SCRIPTS -->|"deploy"| FE
    SCRIPTS -->|"deploy"| BE

    %% Styling Classes
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef backend fill:#F08080,stroke:#333,stroke-width:2px;
    classDef module fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef shared fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef infra fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef external fill:#FFA07A,stroke:#333,stroke-width:2px;

    %% Click Events
    click FE "https://github.com/dfinity/oisy-wallet/tree/main/src/frontend"
    click BE "https://github.com/dfinity/oisy-wallet/tree/main/src/backend"
    click DEC "https://github.com/dfinity/oisy-wallet/tree/main/src/declarations"
    click ICPMod "https://github.com/dfinity/oisy-wallet/tree/main/src/icp"
    click ETHMod "https://github.com/dfinity/oisy-wallet/tree/main/src/eth"
    click SOLMod "https://github.com/dfinity/oisy-wallet/tree/main/src/sol"
    click CYCMod "https://github.com/dfinity/oisy-wallet/tree/main/src/cycles_ledger"
    click SHRD "https://github.com/dfinity/oisy-wallet/tree/main/src/shared"
    click CICD "https://github.com/dfinity/oisy-wallet/blob/main/.github"
    click SCRIPTS "https://github.com/dfinity/oisy-wallet/tree/main/scripts"
```
