# agoric-labs/dapp-evm architecture

> Architecture diagram of the GitHub repository agoric-labs/dapp-evm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agoric-labs/dapp-evm
- Repository: https://github.com/agoric-labs/dapp-evm

## Overview

##### Project Type and Purpose
- This is a full‑stack, cross‑chain dApp that lets users create Agoric chain accounts, register IBC tokens (AUSDC, WAVAX), deploy an Axelar General Message Passing (GMP) EVM contract, and then use a browser UI to send tokens across chains.
- Key features:
- Agoric smart‑contract wrappers (contract/*.js)
- Solidity EVM contracts for GMP (solidity/contracts)
- Node scripts for deployment and chain initialization (deploy/, integration/, getDenom.js)
- React/Vite UI for wallets and contract invocation (ui/)

##### File Structure
Top‑level layers:
- contract/ – Agoric “wrapper” contracts and flows (JavaScript)
- solidity/ – Hardhat + ignition scripts for EVM contracts, tests
- deploy/ – Node.js scripts to build & deploy the Agoric contract
- integration/ – End‑to‑end scripts for environment setup, cross‑chain flows
- ui/ – Frontend React/Vite app
- .github/workflows – CI for tests and merges
- getDenom.js – Utility to lookup IBC denoms on local chain

Architectural patterns:
- Multi‑chain microservices: separate modules for contract logic, EVM logic, deployment, integration, UI
- Event‑driven cross‑chain flow via Hermes relayer and Axelar relayer

##### Insights from README
- Uses Docker to run an Agoric local chain and Hermes relayer for IBC to Osmosis testnet.
- Instructions to register tokens via Agoric SDK builder.
- Deploy GMP contract on Agoric chain, then use UI.
- Can also hook into a local Axelar development environment.

##### Final Recommendations
- Build/deploy pipelines (GitHub Actions → deploy scripts → chain).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Machine
    subgraph "Developer Machine"
        DevCLI["Node.js CLI & Scripts"]:::scripts
        Denom["IBC Denom Lookup\ngetDenom.js"]:::scripts
        CI["CI Workflows\n.github/workflows/"]:::scripts
    end

    %% Backend Services
    subgraph "Backend Services"
        subgraph "Deployment Service"
            DeployJS["deploy.js"]:::scripts
            DeploySRC["deploy/src/"]:::scripts
            DeployTests["deploy/test/"]:::scripts
        end
        Integration["Integration Scripts\nintegration/scripts/"]:::scripts
    end

    %% Smart Contracts
    subgraph "Smart Contracts"
        subgraph "Agoric Contracts"
            Wrapper["Axelar GMP Wrapper\n(contract/axelar-gmp.contract.js)"]:::contract
            Flows["LCA EVM Flows\n(contract/lca-evm.flows.js)"]:::contract
            AccountKit["EVM Account Kit\ncontract/evm-account-kit.js"]:::contract
            Utils["GMP Utilities\ncontract/utils/gmp.js"]:::contract
        end
        subgraph "Solidity Contracts"
            SolContracts["GMP Contracts\nsolidity/contracts/"]:::solidity
            IgnitionMods["Ignition Modules\nsolidity/ignition/modules/"]:::solidity
            SolDeploy["Deploy Script\nsolidity/scripts/deploy.sh"]:::solidity
        end
    end

    %% On-Chain Networks
    subgraph "On-Chain Networks"
        Agoric["Agoric Local Chain\n(Cosmos SDK)"]:::chain
        Osmosis["Osmosis Testnet\n(Cosmos SDK)"]:::chain
        Axelar["Axelar Network\n(EVM)"]:::chain
    end

    Hermes["Hermes Relayer"]:::relayer
    AxelarRelayer["Axelar Relayer"]:::relayer

    UI["Frontend UI\nui/"]:::ui

    %% Connections
    DevCLI --> Denom
    DevCLI --> DeployJS
    CI --> DeployJS

    DeployJS --> Agoric
    DeploySRC --> Agoric
    Integration --> Agoric
    Integration --> Osmosis
    Integration --> Axelar

    Wrapper --> Agoric
    Flows --> Agoric
    AccountKit --> Agoric
    Utils --> Agoric

    SolContracts --> Axelar
    IgnitionMods --> Axelar
    SolDeploy --> Axelar

    Agoric <--> Hermes
    Hermes <--> Osmosis

    Agoric <--> AxelarRelayer
    AxelarRelayer <--> Axelar

    UI -->|"Agoric RPC"| Agoric
    UI -->|"EVM RPC"| Axelar

    %% Click Events
    click Wrapper "https://github.com/agoric-labs/dapp-evm/blob/main/contract/axelar-gmp.contract.js"
    click Flows "https://github.com/agoric-labs/dapp-evm/blob/main/contract/lca-evm.flows.js"
    click AccountKit "https://github.com/agoric-labs/dapp-evm/blob/main/contract/evm-account-kit.js"
    click Utils "https://github.com/agoric-labs/dapp-evm/blob/main/contract/utils/gmp.js"
    click SolContracts "https://github.com/agoric-labs/dapp-evm/tree/main/solidity/contracts/"
    click IgnitionMods "https://github.com/agoric-labs/dapp-evm/tree/main/solidity/ignition/modules/"
    click SolDeploy "https://github.com/agoric-labs/dapp-evm/blob/main/solidity/scripts/deploy.sh"
    click DeployJS "https://github.com/agoric-labs/dapp-evm/blob/main/deploy/deploy.js"
    click DeploySRC "https://github.com/agoric-labs/dapp-evm/tree/main/deploy/src/"
    click DeployTests "https://github.com/agoric-labs/dapp-evm/tree/main/deploy/test/"
    click Integration "https://github.com/agoric-labs/dapp-evm/tree/main/integration/scripts/"
    click Denom "https://github.com/agoric-labs/dapp-evm/blob/main/getDenom.js"
    click UI "https://github.com/agoric-labs/dapp-evm/tree/main/ui/"
    click CI "https://github.com/agoric-labs/dapp-evm/tree/main/.github/workflows/"

    %% Styles
    classDef chain fill:#BBDEFB,stroke:#000,stroke-width:1px
    classDef relayer fill:#C8E6C9,stroke:#000,stroke-width:1px
    classDef scripts fill:#FFF9C4,stroke:#000,stroke-width:1px
    classDef contract fill:#F8BBD0,stroke:#000,stroke-width:1px
    classDef solidity fill:#DCEDC8,stroke:#000,stroke-width:1px
    classDef ui fill:#BBDEFB,stroke:#000,stroke-width:1px
```
