# splashprotocol/protocol-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/splashprotocol/protocol-sdk
- Repository: https://github.com/splashprotocol/protocol-sdk

## Overview

##### Project Type and Purpose
- This is a TypeScript‐based monorepo managed by Turborepo.
- It provides a layered SDK for interacting with the Splash DeFi protocol on Cardano:
- A “core” domain model layer
- An “api” data‐fetching layer
- A “builder” transaction-construction layer (with on-chain explorers and wallet adapters)
- A top-level “sdk” that ties api + builder (and their remote counterparts) into a developer-friendly package
- Remote variants (remote-builder, remote-sdk) for server-side or headless usage
- Supporting packages include TypeScript configs and ESLint rules.

##### File‐Structure Analysis
- Top-level “packages/” folder: each package is its own npm library.
- “core”: pure TS domain models & utilities (addresses, assets, pools, transactions).
- “api”: generic Datafeed/BasicApi layer; plugs into “backends” (Splash) and exposes typed methods (getOrderBook, getRecentTrades, etc.).
- “builder”: transaction Builder with pluggable explorers (Blockfrost, Maestro, Splash) and wallet adapters (HotWallet, CIP-30 emulator); implements operations (create pool, spot orders, XY deposit/withdraw).
- “remote-builder” + “remote-sdk”: variants that marshal build requests to a remote service or emulator.
- “sdk”: high-level front door combining api + builder + remote options.
- Config packages: typescript-config, eslint-config.

##### Key Architectural Patterns
- Layered/Hexagonal:
- Core models at the center
- API layer for reads (Datafeed → Backend adapters → external Splash endpoints)
- Builder layer for writes (Operations → Explorer adapters → blockchain nodes → wallet signing)
- SDK orchestration at the top
- Plugin/Adapter pattern for Backends (Splash), Explorers (Blockfrost, Maestro, Splash), and Wallets (HotWallet, CIP-30).
- Monorepo dependency graph: lower layers have no upstream deps; higher layers depend on lower ones.

##### Main Components & Interactions
[Component Blocks]
- Core Package (“core”)
- API Package (“api”)
- Builder Package (“builder”)
- Remote-Builder (“remote-builder”)
- Remote-SDK (“remote-sdk”)
- SDK Package (“sdk”)
- External Services: Splash REST API, Blockfrost/other Explorer APIs, Cardano node RPC endpoints
- Wallet Interfaces: CIP-30 wallet, HotWallet adapter

[Relationships & Data Flow]
1. SDK calls → API to fetch on-chain data
2. API uses Backend Adapters → external Splash endpoints → returns typed models → back to SDK
3. SDK calls → Builder to construct transactions
4. Builder calls → Explorer adapters → fetch network context & UTxO → applies Operations → builds unsigned tx → passes to Wallet adapters → signs → returns SignedTransaction
5. Optionally, SDK uses Remote-SDK which sends requests to Remote-Builder service instead of local Builder
6. Signed transactions are submitted back to node or forwarded to Splash for execution

##### Technologies & Frameworks
- Node.js, TypeScript, pnpm, Turborepo
- Jest (unit tests)
- Explorer Adapters: blockfrost-js, custom Maestro/Splash
- CIP-30 wallet integration or HotWallet shim

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Domain Layer
    subgraph "Domain/Core Layer"
        core["core"]:::library
        tsConfig["typescript-config"]:::library
        eslintConfig["eslint-config"]:::library
    end

    %% Read/API Layer
    subgraph "Read/API Layer"
        api["api"]:::library
    end

    %% Write/Builder Layer
    subgraph "Write/Builder Layer"
        builder["builder"]:::library
    end

    %% SDK & Remote Variants
    subgraph "SDK Layer"
        sdk["sdk"]:::library
        remoteSDK["remote-sdk"]:::remote
        remoteBuilder["remote-builder"]:::remote
    end

    %% External Systems
    subgraph "External Services" 
        SplashAPI["Splash REST API"]:::external
        Blockfrost["Blockfrost API"]:::external
        CardanoNode["Cardano Node RPC"]:::external
        WalletAdapters["Wallet Adapters (CIP-30, HotWallet)"]:::external
    end

    %% Dependencies and Data Flows
    api -->|"depends on"| core
    builder -->|"depends on"| core
    sdk -->|"uses api"| api
    sdk -->|"uses builder"| builder
    sdk -->|"uses remote-sdk"| remoteSDK
    sdk -->|"calls remote-builder"| remoteBuilder
    remoteSDK -->|"forwards to"| remoteBuilder

    sdk -->|"fetch data"| api
    api -.->|"getOrderBook, getRecentTrades"| SplashAPI
    sdk -->|"construct tx"| builder
    builder -.->|"fetch UTxO, context"| Blockfrost
    builder -.->|"submitTransaction"| CardanoNode
    builder -->|"sign transaction"| WalletAdapters

    %% Click Events
    click core "https://github.com/splashprotocol/protocol-sdk/tree/main/packages/core"
    click api "https://github.com/splashprotocol/protocol-sdk/tree/main/packages/api"
    click builder "https://github.com/splashprotocol/protocol-sdk/tree/main/packages/builder"
    click remoteBuilder "https://github.com/splashprotocol/protocol-sdk/tree/main/packages/remote-builder"
    click remoteSDK "https://github.com/splashprotocol/protocol-sdk/tree/main/packages/remote-sdk"
    click sdk "https://github.com/splashprotocol/protocol-sdk/tree/main/packages/sdk"
    click tsConfig "https://github.com/splashprotocol/protocol-sdk/tree/main/packages/typescript-config"
    click eslintConfig "https://github.com/splashprotocol/protocol-sdk/tree/main/packages/eslint-config"

    %% Styles
    classDef library fill:#ccf,stroke:#000,color:#000
    classDef remote fill:#cfc,stroke:#000,color:#000
    classDef external fill:#eee,stroke:#000,color:#000
```
