# reya-labs/reya-python-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/reya-labs/reya-python-sdk
- Repository: https://github.com/reya-labs/reya-python-sdk

## Overview

##### Project type and purpose
- This is an open-source Python SDK (library + examples) for interacting with the Reya blockchain ecosystem.
- It provides two orthogonal capabilities:
- A WebSocket-based market data feed client (`reya_data_feed`)
- An RPC-based on-chain action library (`reya_actions`)
- The `examples/` folder ties them together with runnable scripts showcasing common use-cases (trading, bridging, staking, etc.).

##### File structure
- Top level
- `.env.example`, `.gitignore`, `README.md` – configuration & project metadata
- `examples/` – executable scripts orchestrating the SDK
- `reya_actions/` – core on-chain command library
- `reya_data_feed/` – market data WebSocket consumer
- `reya_actions/` substructure
- `abis/` – JSON ABI definitions for on-chain Proxy contracts
- `actions/` – one module per supported on-chain operation (trade, deposit, bridge_in, etc.)
- `config.py`, `consts.py`, `types.py` – SDK configuration, constants, type definitions
- `utils/execute_core_commands.py` – low-level helper to assemble and send RPC calls
- `reya_data_feed/consumer.py` – connects to the Reya WebSocket API, subscribes to market channels

##### README for additional insights
- Lists features, prerequisites (private key, chain_id, account_id), and usage patterns
- Describes how data-feed and action modules are consumed by example scripts
- Emphasizes Poetry for dependency management and running the examples

##### Main components
a. Examples Runner
- Each `examples/*.py` script
- Orchestrates calls into `reya_data_feed` and/or `reya_actions`
b. Data-Feed Module (`reya_data_feed`)
- WebSocket client → Reya WebSocket API (external)
- Subscriptions: candles, spot prices, funding rates
c. Actions Module (`reya_actions`)
- Config & environment loader (.env)
- ABI loader → Proxy contracts on-chain
- Action handlers (trade, deposit, withdraw, stake, bridge)
- RPC client → JSON-RPC endpoint (external)
d. External Services
- Reya WebSocket Server
- Reya JSON-RPC Node
- On-chain Proxy contracts (addresses loaded from config)

##### Relationships and interactions
- Examples → import & invoke Data-Feed or Action functions
- Data-Feed → opens WebSocket connection → streams data → propagates events to examples
- Actions → assemble transactions using ABIs → send JSON-RPC calls → await on-chain confirmations
- Environment variables (private key, chain_id, account_id, RPC URL) flow into both modules via `config.py`

##### Architectural patterns and design principles
- Modular separation: data feed vs on-chain commands
- Command pattern in `actions/` (one file per action)
- Clear abstraction around ABIs and RPC/WS transport
- Extensible: drop-in new `actions/` or `abis/` for additional smart contracts

##### Essential elements to capture
- Components: examples, modules, external endpoints
- Data flow: subscription & event streaming vs transaction submission & confirmation
- Configuration boundary: where `.env` values are consumed
- Technology call-outs: Python, WebSocket API, JSON-RPC, smart-contract ABIs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Environment Variables
    Env["Environment Variables<br/>(.env)"]:::external

    %% Example Runner
    Ex["Examples Runner<br/>(examples/)"]:::examples

    %% Data-Feed Module
    subgraph "Data-Feed Module"
        DFInit["__init__.py"]:::datafeed
        Consumer["consumer.py"]:::datafeed
    end

    %% Actions Module
    subgraph "Actions Module"
        AMInit["__init__.py"]:::actions
        Config["config.py"]:::actions
        Consts["consts.py"]:::actions
        Types["types.py"]:::actions
        Abis["abis/"]:::actions
        ActHandlers["actions/"]:::actions
        Utils["utils/execute_core_commands.py"]:::actions
    end

    %% External Services
    WebSocketAPI["Reya WebSocket API"]:::external
    RPCNode["Reya JSON-RPC Node"]:::external
    ProxyContracts["On-chain Proxy Contracts"]:::external

    %% Connections
    Env -->|consumed by| Config
    Env -->|consumed by| DFInit
    Ex -->|"imports & invokes"| Consumer
    Ex -->|"imports & invokes"| ActHandlers
    Consumer -->|WS| WebSocketAPI
    ActHandlers -->|assemble+send RPC| RPCNode
    ActHandlers -->|load ABIs| Abis
    RPCNode -->|interacts with| ProxyContracts

    %% Click Events
    click Ex "https://github.com/reya-labs/reya-python-sdk/tree/main/examples/"
    click DFInit "https://github.com/reya-labs/reya-python-sdk/blob/main/reya_data_feed/__init__.py"
    click Consumer "https://github.com/reya-labs/reya-python-sdk/blob/main/reya_data_feed/consumer.py"
    click Config "https://github.com/reya-labs/reya-python-sdk/blob/main/reya_actions/config.py"
    click Consts "https://github.com/reya-labs/reya-python-sdk/blob/main/reya_actions/consts.py"
    click Types "https://github.com/reya-labs/reya-python-sdk/blob/main/reya_actions/types.py"
    click Abis "https://github.com/reya-labs/reya-python-sdk/tree/main/reya_actions/abis/"
    click ActHandlers "https://github.com/reya-labs/reya-python-sdk/tree/main/reya_actions/actions/"
    click Utils "https://github.com/reya-labs/reya-python-sdk/blob/main/reya_actions/utils/execute_core_commands.py"
    click AMInit "https://github.com/reya-labs/reya-python-sdk/blob/main/reya_actions/__init__.py"

    %% Styles
    classDef examples fill:#e0ffe0,stroke:#2d8f00,color:#004400;
    classDef datafeed fill:#e0f0ff,stroke:#0050a0,color:#002050;
    classDef actions fill:#f0f8ff,stroke:#0070c0,color:#003050;
    classDef external fill:#f0f0f0,stroke:#888888,color:#444444;
```
