# alongside-finance/amkt-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/alongside-finance/amkt-v2
- Repository: https://github.com/alongside-finance/amkt-v2

## Overview

Based on our analysis of the file tree and the README, this project is a smart contract–based decentralized finance (DeFi) system for an on-chain crypto market index (AMKT). Its primary purpose is to enable issuance and redemption of an index token (AMKT) that represents a basket of underlying assets, with governance-led rebalances and on-chain custody via a Vault. In addition to the on-chain Solidity contracts, there is an SDK (with Rust-based bindings and a bot) to assist with off-chain tooling like preparing rebalance proposals and automating interactions.

##### Main architectural layers and components
- On-Chain Smart Contracts (in the contracts directory)
- Core Components:
- Vault – Custodies assets, tracks index composition and virtual units, and supports issuance and redemption.
- Issuance – Provides permissionless functions (issue/redeem) for converting the basket of underlying assets and the AMKT token.
- InvokeableBounty – Entry point for rebalancing the index (via fulfillBounty), along with ActiveBounty which holds the currently active bounty.
- Governance and Administration:
- Governance/TimelockController – Manages configuration changes, upgrade processes, fee handling and enforces delay for non-rebalance operations.
- Emergency Multisig – Authorized to perform emergency actions (pausing issuance and rebalances).
- Ancillary Modules:
- The ERC20 token implementation (AMKT) which is upgradeable and votable.
- Various libraries and contracts imported from OpenZeppelin (for upgradeability, governance, and security).

- Off-Chain Components (in the sdk directory)
- SDK Bindings – Provide Rust bindings to interact with the on-chain contracts.
- The Bot Component – Implements orchestration logic (API calls and market data interactions).
- Rebalance Tool – A separate Rust example program that helps in preparing rebalance proposals.

- Development and Testing

##### Relationships and data flow
- Vault at the center as it is the “source of truth” for asset custody, connected to Issuance and Bounty operations.
- InvokeableBounty (and its sub-component ActiveBounty) to Vault to represent how rebalances adjust the virtual units.
- Its management of Vault parameters (such as fee rates and emergency controls) via the TimelockController.
- Its connection to external governance platforms (e.g., Tally) and its multisig for sensitive actions.
- A separate section for off-chain interactions:

##### Architectural patterns and technologies
- Modularity and upgradeability of the token and contractual components (using patterns like upgradeable proxies from OpenZeppelin).
- Permissionless nature of Issuance functions versus the permissioned rebalances and governance actions.

##### Putting it all together
- Separately, add the off-chain layer that interacts with the smart contracts through the SDK, clearly showing the “bridge” between on- and off-chain.
- Roles and permissions (who can call what) with labels such as “permissionless functions” for Issuance and “governance-controlled changes” for the Vault and TimelockController.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "On-Chain Smart Contracts"
        Vault["Vault"]:::onchain
        Issuance["Issuance"]:::onchain
        Bounty["InvokeableBounty/ActiveBounty"]:::onchain
        Governance["Governance (TimelockController & Multisig)"]:::onchain
        AMKTToken["AMKT Token"]:::onchain
    end

    subgraph "Off-Chain Components"
        SDKBindings["SDK Bindings"]:::offchain
        Bot["Bot Component"]:::offchain
        RebalanceTool["Rebalance Tool"]:::offchain
    end

    %% On-chain relationships
    Vault -->|"issue/redeem"| Issuance
    Issuance -->|"asset_transfer"| Vault

    Vault -->|"rebalance_update"| Bounty
    Bounty -->|"virtual_unit_adjust"| Vault

    Governance -->|"config_updates"| Vault
    Governance -->|"token_control"| AMKTToken

    %% Off-chain to on-chain interactions
    SDKBindings -->|"binds_to"| Vault
    SDKBindings -->|"binds_to"| Issuance
    SDKBindings -->|"binds_to"| Bounty
    SDKBindings -->|"binds_to"| Governance
    SDKBindings -->|"binds_to"| AMKTToken

    Bot -->|"API_calls"| Vault
    Bot -->|"API_calls"| Issuance

    RebalanceTool -->|"prepare_rebalance"| Bounty

    %% Click Events for on-chain components
    click Vault "https://github.com/alongside-finance/amkt-v2/tree/main/contracts/src"
    click Vault "https://github.com/alongside-finance/amkt-v2/blob/main/sdk/bindings/src/vault.rs"
    click Issuance "https://github.com/alongside-finance/amkt-v2/tree/main/contracts/src"
    click Issuance "https://github.com/alongside-finance/amkt-v2/blob/main/sdk/bindings/src/issuance.rs"
    click Bounty "https://github.com/alongside-finance/amkt-v2/tree/main/contracts/src"
    click Bounty "https://github.com/alongside-finance/amkt-v2/blob/main/sdk/bindings/src/invokeable_bounty.rs"
    click Bounty "https://github.com/alongside-finance/amkt-v2/blob/main/sdk/bindings/src/initial_bounty.rs"
    click Governance "https://github.com/alongside-finance/amkt-v2/tree/main/contracts/src"
    click Governance "https://github.com/alongside-finance/amkt-v2/blob/main/sdk/bindings/src/timelock_controller.rs"
    click AMKTToken "https://github.com/alongside-finance/amkt-v2/tree/main/contracts/src"
    click AMKTToken "https://github.com/alongside-finance/amkt-v2/blob/main/sdk/bindings/src/erc20_upgradeable.rs"
    click AMKTToken "https://github.com/alongside-finance/amkt-v2/blob/main/sdk/bindings/src/erc20_votes.rs"

    %% Click Events for off-chain components
    click SDKBindings "https://github.com/alongside-finance/amkt-v2/tree/main/sdk/bindings/"
    click Bot "https://github.com/alongside-finance/amkt-v2/tree/main/sdk/bot/"
    click RebalanceTool "https://github.com/alongside-finance/amkt-v2/tree/main/sdk/rebalance/"

    %% Styles
    classDef onchain fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef offchain fill:#90EE90,stroke:#000,stroke-width:2px;
```
