# osmosis-labs/fee-abstraction architecture

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

- Interactive diagram: https://gitdiagram.com/osmosis-labs/fee-abstraction
- Repository: https://github.com/osmosis-labs/fee-abstraction

## Overview

##### Main Components to Highlight
- Application Layer (app, cmd): The “app” directory contains the core logic (e.g., AnteHandler modification, exchange rate updates, and processing of IBC packet data) and tests. The “cmd” folder defines the entry point (feeappd) to run the application.
- Fee Abstraction Module (“x/feeabs”): This directory holds the module-specific logic for fee abstraction. It includes subdirectories for Ante handlers, keeper logic, IBC integrations, proposals, and gRPC queries.
- Protocol Buffers (“proto”): Contains all the proto definitions for various types including fee proposals, queries, transactions, and other IBC messages. It also has its own Dockerfile and build configuration (buf files) for managing proto generation.
- IBC & External Interactions: The README outlines two major workflows:
- Pulling TWAP data via an Interchain Query: the module periodically makes IBC queries (handled via async-icq) to obtain TWAP data from Osmosis.
- Swapping IbC tokens using Osmosis Crosschain Swap (XCS): Once tokens are collected as fees, they are transferred, swapped, and returned.
- Scripts & Testing: Provided scripts for deploying contracts, starting nodes, configuring relayers, and integration tests validate interchain interactions.

##### Relationships and Interactions
- The Fee Abstraction Module (in “x/feeabs”) interacts with:
- The Cosmos SDK’s Mempool and AnteHandler (modified to check and convert IBC tokens to the native token equivalent).
- The IBC protocol components for sending and receiving query packets (e.g., sending an InterchainQueryPacketData and handling MsgAcknowledgement).
- External Osmosis services (the async-icq module for TWAP queries and the swap router for performing crosschain swaps).
- The “app” layer sets-up the BeginBlocker events to trigger the periodic exchange rate update by sending IBC packets.
- The “proto” folder defines the data models used by these modules across different services.
- Command-line utilities in “cmd/feeappd” provide the interface for running and administering the blockchain node, while scripts help in testing and deployment.

##### Architectural Patterns and Principles
- Modular Design: The architecture cleanly separates core application logic from the fee abstraction module (in “x/feeabs”), and isolates protocol definitions in the “proto” directory.
- Inter-module Communication: Using IBC, the fee abstraction leverages asynchronous queries and responses along with controlled relayer interactions.
- Testing & CI/CD: Multiple test directories and GitHub Actions workflows are present to support integration, interchain tests, linting, and container builds.
- Extensibility: The project structure (with versioned branches for different Cosmos SDK and IBC-go versions) emphasizes extensibility and support for multiple chain implementations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Blockchain Node
    subgraph "Core Blockchain Node"
        cli["Node CLI (feeappd)"]:::cli
        app["Core Application (app)"]:::app
    end
    cli -->|"initiates"| app

    %% Fee Abstraction Module
    subgraph "Fee Abstraction Module"
        fee["Fee Abstraction Module (x/feeabs)"]:::module
    end
    app -->|"BeginBlocker/Event"| fee

    %% External Interfaces
    subgraph "External Interfaces"
        ibc["IBC Gateway & async-icq"]:::external
        osmosis["Osmosis Swap Router Interface (XCS)"]:::external
    end
    fee -->|"IBC_Packet_Send"| ibc
    ibc -->|"TWAP_Response"| fee
    fee -->|"Token_Swap_Request"| osmosis
    osmosis -->|"Swapped_Tokens"| fee

    %% Protocol Definitions
    subgraph "Protocol Definitions"
        proto["Protocol Definitions (proto)"]:::proto
    end
    fee ---|"Uses"| proto
    app ---|"Uses"| proto

    %% Deployment & Automation
    subgraph "Deployment & Automation"
        deploy["Deployment & Testing Scripts"]:::deploy
    end
    deploy -->|"Deploy_Configure"| cli
    deploy -->|"Deploy_Tests"| fee

    %% Click Events for Application Layer (app)
    click app "https://github.com/osmosis-labs/fee-abstraction/blob/main/app/app.go"
    click app "https://github.com/osmosis-labs/fee-abstraction/blob/main/app/ante.go"
    click app "https://github.com/osmosis-labs/fee-abstraction/blob/main/app/app_test.go"

    %% Click Events for CLI (cmd/feeappd)
    click cli "https://github.com/osmosis-labs/fee-abstraction/blob/main/cmd/feeappd/main.go"
    click cli "https://github.com/osmosis-labs/fee-abstraction/blob/main/cmd/feeappd/commands.go"

    %% Click Events for Fee Abstraction Module (x/feeabs)
    click fee "https://github.com/osmosis-labs/fee-abstraction/blob/main/x/feeabs/module.go"
    click fee "https://github.com/osmosis-labs/fee-abstraction/tree/main/x/feeabs/ante"
    click fee "https://github.com/osmosis-labs/fee-abstraction/tree/main/x/feeabs/keeper"
    click fee "https://github.com/osmosis-labs/fee-abstraction/blob/main/x/feeabs/proposal_handler.go"

    %% Click Events for IBC & External Interactions
    click ibc "https://github.com/osmosis-labs/fee-abstraction/blob/main/x/feeabs/ibc_module.go"
    click ibc "https://github.com/osmosis-labs/fee-abstraction/blob/main/x/feeabs/keeper/ibc.go"

    %% Click Events for Protocol Buffers (proto)
    click proto "https://github.com/osmosis-labs/fee-abstraction/tree/main/proto/feeabstraction/feeabs/v1beta1/"
    click proto "https://github.com/osmosis-labs/fee-abstraction/tree/main/proto/Dockerfile"
    click proto "https://github.com/osmosis-labs/fee-abstraction/blob/main/proto/buf*.yaml"

    %% Click Events for Deployment & Automation Scripts & Testing
    click deploy "https://github.com/osmosis-labs/fee-abstraction/blob/main/scripts/ibc_swap/deploy_osmosis_contract.sh"
    click deploy "https://github.com/osmosis-labs/fee-abstraction/blob/main/scripts/ibc_swap/setup.sh"
    click deploy "https://github.com/osmosis-labs/fee-abstraction/tree/main/scripts/node_start"
    click deploy "https://github.com/osmosis-labs/fee-abstraction/tree/main/scripts/relayer_hermes"
    click deploy "https://github.com/osmosis-labs/fee-abstraction/tree/main/tests/integration"
    click deploy "https://github.com/osmosis-labs/fee-abstraction/tree/main/tests/interchaintest"

    %% Styles
    classDef cli fill:#FEF3C7,stroke:#D97706,stroke-width:2px;
    classDef app fill:#BFDBFE,stroke:#2563EB,stroke-width:2px;
    classDef module fill:#BBF7D0,stroke:#16A34A,stroke-width:2px;
    classDef external fill:#FDE68A,stroke:#F59E0B,stroke-width:2px;
    classDef proto fill:#FCD34D,stroke:#FBBF24,stroke-width:2px;
    classDef deploy fill:#E0E7FF,stroke:#6366F1,stroke-width:2px;
```
