> ## Documentation Index
> Fetch the complete documentation index at: https://blackswan-23965643.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# BlackSwan Protocol Architecture: Components and Flow

> How BlackSwan's components fit together: SDKs, REST API, smart contracts, and Soulbound Tokens working in concert to provide on-chain credit data.

BlackSwan is built as a layered decentralized credit infrastructure. Each layer has a distinct responsibility — from the client-facing SDKs and REST API down to the on-chain smart contracts and identity primitives that anchor credit data to individual wallets. Understanding how these components interact helps you choose the right integration path and reason about the trust guarantees the protocol provides.

## Components

| Component              | Role                                                                   |
| ---------------------- | ---------------------------------------------------------------------- |
| JavaScript/Python SDKs | Client libraries that read blockchain state directly                   |
| REST API               | Cached HTTP endpoints — no blockchain interaction required for callers |
| Smart Contracts        | On-chain P2P lending logic and credit state                            |
| Soulbound Token (SBT)  | Non-transferable NFT representing credit identity                      |

## Request Flow

When you make a call — whether through an SDK or a direct REST request — here's what happens under the hood:

<Steps>
  <Step title="SDK call or REST request">
    Your application initiates a request by calling an SDK method or hitting a REST endpoint with a wallet address.
  </Step>

  <Step title="RPC provider connects to blockchain">
    The SDK (or the REST API's backend) connects to the blockchain via an RPC provider to query on-chain state.
  </Step>

  <Step title="Smart contract reads/writes state">
    The relevant smart contract is queried (or written to), returning or updating credit data, loan records, and SBT metadata.
  </Step>

  <Step title="Response returned to caller">
    The result is decoded and returned to your application — either as a typed SDK response object or a structured JSON body from the REST API.
  </Step>
</Steps>

## SDK vs REST API

Both integration paths expose the same underlying credit data, but they operate differently:

**SDK** — The JavaScript and Python SDKs read directly from the blockchain via an RPC provider. This gives you the freshest possible data with no intermediary caching layer. Choose the SDK when you need real-time state, are building server-side services with direct chain access, or want strongly typed contract interactions.

**REST API** — The REST API sits in front of the blockchain and serves cached, optimized responses over standard HTTP. You don't need to manage an RPC provider, handle ABIs, or parse raw contract output. Choose the REST API when you want the simplest integration, are building frontend applications, or need to minimize latency for read-heavy workloads.

<Info>
  BlackSwan currently supports two testnets: **Polygon Amoy** and **Ethereum Sepolia**. All SDK methods and REST endpoints work identically on both networks. Mainnet support is planned for v1.1 — see the [Roadmap](/protocol/roadmap) for details.
</Info>