# 0xsquid/examples architecture

> Architecture diagram of the GitHub repository 0xsquid/examples, 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/0xsquid/examples
- Repository: https://github.com/0xsquid/examples

## Overview

##### Project Type and Purpose
- This repository is a collection of examples demonstrating integrations with the Squid API, SDK, and Widget. Its purpose is to show how to perform various cross-chain transactions (such as swaps, NFT purchases, deposits, and staking) using the Squid infrastructure.
- There are multiple “routes” that illustrate interactions with different blockchain networks (EVM chains, Cosmos, Bitcoin, Solana, etc.), with V2 being the active set of examples, while V1 is deprecated.

##### Analyzing the File Structure
- The top-level structure contains two main versions: V1 (deprecated examples) and V2 (current examples and SDK).
- Within V2, the “api” directory holds many examples that implement specific transaction routes (e.g., “bitcoinToEVM_Swap”, “evmPrehooktoEVM”, “buyNFTonEVM”, etc.), each with its own configuration, source code (typically in TypeScript), and .env.example file.
- The “sdk” directory in V2 similarly provides library components and example integrations that can be used as a foundation for application development.
- The organization by transaction route, network type, and hook (preHook/postHook) shows a clear separation by function and integration point.

##### How to Represent the Architecture
a. Main Components:
– Squid API / Squid Widget: At the center, illustrate the external Squid service that the examples integrate with.
– Example Applications: Each example (found in V2/api and V2/sdk) should be viewed as a self-contained application component demonstrating a particular transaction route, such as:
- EVM Routes (e.g., buyNFTonEVM, evmPrehooktoEVM, evmToEVMSwap)
- Cosmos Routes (e.g., cosmosContractCall, cosmosMarsRedBankDeposit, cosmosToCosmosSwap)
- BTC & Solana Routes (e.g., bitcoinToEVM_Swap and solanaToEVM_Swap)
– Configuration Layer: Represent the common use of .env configuration files (duplicated across different folders) which govern environment-specific parameters like API keys, network endpoints, and credentials.
– Blockchain Networks: Include external blockchain networks or nodes that these examples interact with – EVM chains, Cosmos chain, Bitcoin network, and Solana.
– Supporting Libraries / ABI Definitions: Show the “abi” subfolders (present in many examples) that define the smart contract interfaces, indicating that these form important building blocks for blockchain interactions.
– Node.js Runtime Environment: As all examples use Node.js (indicated by package.json and tsconfig.json files), include a representation of the underlying runtime environment.

b. Relationships and Interactions:
- The Squid API (indicating usage of the external API to initiate and track transactions)
- The targeted blockchain networks (showing outbound transactions, swaps, deposits, or staking operations)
- The configuration/environment component (indicating that each example is parametrized via its .env file)
– Connect the SDK components with the example applications where the SDK is used as the foundational library for blockchain interactions or route management.

c. Architectural Patterns and Design Principles:
– Modular Design: Each example is self-contained with its own source, configuration, and dependencies.
– Layered Architecture: Separate network communication (via Smart Contract ABI files), business logic (in “src”), and configuration handling.
– Extensibility: The differentiation between V2/api and V2/sdk suggests the project is built to allow developers to either run example endpoints directly or use the SDK components to extend functionality.

d. Technologies and Frameworks:
– Node.js and npm (or yarn) as the runtime and build system.
– TypeScript (evident from tsconfig.json) for strongly typed development.
– Contract ABI files for various blockchains (e.g., ERC20, ERC721, etc.), used to interact with decentralized smart contracts.
– External services provided by Squid (as described in the README and Squid API documentation).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Top Layer: Runtime Environment
    Runtime["Node.js Runtime Environment"]:::runtime

    %% Subgraph: V2/api Examples
    subgraph "V2/api Examples"
        %% EVM Routes
        subgraph "EVM Routes"
            buyNFTonEVMExample["buyNFTonEVM Example"]:::APIExample
            evmPrehooktoEVMExample["evmPrehooktoEVM Example"]:::APIExample
            evmToEVMSwapExample["evmToEVMSwap Example"]:::APIExample
            evmToEVMSwapSet["evmToEVMSwap_setToAmount"]:::APIExample
            evmWithdrawPrehookExample["evmWithdrawPrehooktoEVM Example"]:::APIExample
            evmWithdrawPrehookDepExample["evmWithdrawPrehooktoEVMDeposit Example"]:::APIExample
        end
        %% BTC & Solana Routes
        subgraph "BTC & Solana Routes"
            bitcoinToEVMSwapExample["bitcoinToEVMSwap Example"]:::APIExample
            solanaToEVMSwapExample["solanaToEVMSwap Example"]:::APIExample
        end
        %% Other Examples
        subgraph "Other Examples"
            swapEVMToEVMSwapAndLendPosthookExample["swapEVMToEVMSwapAndLendPosthook Example"]:::APIExample
            txLookupExample["tx_lookup Example"]:::APIExample
        end
    end

    %% Subgraph: V1 Deprecated Examples
    subgraph "V1 Deprecated Examples"
        cosmosContractCallExample["cosmosContractCall Example"]:::deprecated
    end

    %% Subgraph: V2/sdk Components
    subgraph "V2/sdk Components"
        evmPrehooktoEVMSDK["evmPrehooktoEVM SDK"]:::sdk
        evmToEVMSwapSDK["evmToEVMSwap SDK"]:::sdk
        buyNftFromAnyChainSDK["buyNftFromAnyChain (old) SDK"]:::sdk
        ethersV5SwapAvalancheUsdcToMoonbeamSDK["ethersV5SwapAvalancheUsdcToMoonbeam SDK"]:::sdk
        swapEVMtoEVMAndLendPosthookSDK["swapEVMtoEVMAndLendPosthook SDK"]:::sdk
    end

    %% Subgraph: Configuration Files
    subgraph "Configuration Files"
        buyNFTonEVMConfig["buyNFTonEVM .env"]:::configuration
        bitcoinToEVMSwapConfig["bitcoinToEVMSwap .env"]:::configuration
    end

    %% Subgraph: ABI Definitions
    subgraph "ABI Definitions"
        buyNFTonEVMABI["buyNFTonEVM ABI"]:::abi
        evmPrehooktoEVMABI["evmPrehooktoEVM ABI"]:::abi
    end

    %% External Services
    Squid["Squid API/Widget"]:::external

    %% Blockchain Networks (vertical grouping)
    subgraph "Blockchain Networks"
        evmChains["EVM Chains"]:::external
        cosmosChain["Cosmos Chain"]:::external
        bitcoinNetwork["Bitcoin Network"]:::external
        solanaNetwork["Solana Network"]:::external
    end

    %% CONNECTIONS
    %% Link Runtime to representative examples from each group
    Runtime -->|"triggers"| buyNFTonEVMExample
    Runtime -->|"triggers"| cosmosContractCallExample
    Runtime -->|"triggers"| evmPrehooktoEVMSDK

    %% Representative connections from each group to Squid API/Widget
    buyNFTonEVMExample -->|"calls"| Squid
    cosmosContractCallExample -->|"calls"| Squid
    evmPrehooktoEVMSDK -->|"calls"| Squid

    %% Squid API/Widget routes to Blockchain Networks
    Squid -->|"interacts"| evmChains
    Squid -->|"interacts"| cosmosChain
    Squid -->|"interacts"| bitcoinNetwork
    Squid -->|"interacts"| solanaNetwork

    %% Dotted links for Configuration and ABI dependencies
    buyNFTonEVMExample -.->|"uses"| buyNFTonEVMConfig
    buyNFTonEVMExample -.->|"uses"| buyNFTonEVMABI
    bitcoinToEVMSwapExample -.->|"uses"| bitcoinToEVMSwapConfig
    evmPrehooktoEVMExample -.->|"uses"| evmPrehooktoEVMSDK

    %% STYLES
    classDef runtime fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
    classDef APIExample fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef sdk fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef deprecated fill:#F5CBA7,stroke:#9C640C,stroke-width:2px;
    classDef configuration fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef abi fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef external fill:#FADBD8,stroke:#C0392B,stroke-width:2px;

    %% CLICK EVENTS
    click buyNFTonEVMExample "https://github.com/0xsquid/examples/tree/main/V2/api/buyNFTonEVM"
    click evmPrehooktoEVMExample "https://github.com/0xsquid/examples/tree/main/V2/api/evmPrehooktoEVM"
    click evmToEVMSwapExample "https://github.com/0xsquid/examples/tree/main/V2/api/evmToEVMSwap"
    click evmToEVMSwapSet "https://github.com/0xsquid/examples/tree/main/V2/api/evmToEVMSwap_setToAmount"
    click evmWithdrawPrehookExample "https://github.com/0xsquid/examples/tree/main/V2/api/evmWithdrawPrehooktoEVM"
    click evmWithdrawPrehookDepExample "https://github.com/0xsquid/examples/tree/main/V2/api/evmWithdrawPrehooktoEVMDeposit"
    click bitcoinToEVMSwapExample "https://github.com/0xsquid/examples/tree/main/V2/api/bitcoinToEVM_Swap"
    click solanaToEVMSwapExample "https://github.com/0xsquid/examples/tree/main/V2/api/solanaToEVM_Swap"
    click cosmosContractCallExample "https://github.com/0xsquid/examples/tree/main/V1/cosmos/cosmosContractCall"
    click swapEVMToEVMSwapAndLendPosthookExample "https://github.com/0xsquid/examples/tree/main/V2/api/swapEVMToEVMSwapAndLendPosthook"
    click txLookupExample "https://github.com/0xsquid/examples/tree/main/V2/api/tx_lookup"
    click evmPrehooktoEVMSDK "https://github.com/0xsquid/examples/tree/main/V2/sdk/evmPrehooktoEVM"
    click evmToEVMSwapSDK "https://github.com/0xsquid/examples/tree/main/V2/sdk/evmToEVMSwap"
    click buyNftFromAnyChainSDK "https://github.com/0xsquid/examples/tree/main/V2/sdk/oldExamples/buyNftFromAnyChain"
    click ethersV5SwapAvalancheUsdcToMoonbeamSDK "https://github.com/0xsquid/examples/tree/main/V2/sdk/oldExamples/ethersV5SwapAvalancheUsdcToMoonbeam"
    click swapEVMtoEVMAndLendPosthookSDK "https://github.com/0xsquid/examples/tree/main/V2/sdk/swapEVMtoEVMAndLendPosthook"
    click buyNFTonEVMConfig "https://github.com/0xsquid/examples/blob/main/V2/api/buyNFTonEVM/.env.example"
    click bitcoinToEVMSwapConfig "https://github.com/0xsquid/examples/blob/main/V2/api/bitcoinToEVMSwap/.env.example"
    click buyNFTonEVMABI "https://github.com/0xsquid/examples/tree/main/V2/api/buyNFTonEVM/src/abi"
    click evmPrehooktoEVMSDK "https://github.com/0xsquid/examples/tree/main/V2/api/evmPrehooktoEVM/abi"
```
