# staticbit-io/xrplcsharp architecture

> Architecture diagram of the GitHub repository staticbit-io/xrplcsharp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/staticbit-io/xrplcsharp
- Repository: https://github.com/staticbit-io/xrplcsharp

## Overview

#### Purpose and consumption
XrplCSharp is a .NET 8/9/10 SDK for XRP Ledger (XRPL) applications. Its primary deliverable is the `Xrpl` NuGet library, exposing typed ledger/API models, WebSocket access to `rippled`, transaction construction/signing, and binary codecs. Consumers instantiate the client and wallet APIs rather than run a repository-hosted service.
- `Xrpl/Xrpl.csproj`
- `Xrpl/Client/IXrplClient.cs`
- `Xrpl/Wallet/XrplWallet.cs`

#### Network client boundary
`XrplClient` is the application-facing entry point for JSON-RPC/WebSocket interaction with a remote `rippled` node. Connection/session management and request correlation isolate transport concerns; typed method requests/responses and subscription streams form the public protocol boundary. JSON converters bridge wire payload variations to C# models.
- `Xrpl/Client/WebSocketClient.cs`
- `Xrpl/Client/RequestManager.cs`
- `Xrpl/Client/Json/XrplJsonOptions.cs`

#### Ledger domain model layer
The SDK represents server methods, transaction formats, ledger objects, common XRPL values, and subscription events as strongly typed models. Client calls serialize method models; incoming responses deserialize into these types. Transaction models are the shared boundary between application code, signing, serialization, and submission.
- `Xrpl/Models/Methods/BaseRequest.cs`
- `Xrpl/Models/Transactions/Common.cs`
- `Xrpl/Models/Ledger/BaseLedgerEntry.cs`

#### Transaction lifecycle and convenience APIs
The normal control flow is: construct a transaction model, obtain account/fee/ledger context through the client, autofill fields, serialize and sign with a wallet, then submit and optionally wait for validation. Sugar APIs package common multi-call sequences such as autofill, balance lookup, and submit-and-wait.
- `Xrpl/Sugar/Autofill.cs`
- `Xrpl/Sugar/Submit.cs`
- `Xrpl/Wallet/Signer.cs`

#### Cryptography and canonical encoding
Low-level projects implement XRPL’s address codec, seed/key derivation, Ed25519 and secp256k1 signing, canonical binary serialization, hashes, field definitions, and SHAMap/ledger primitives. These are protocol-critical dependencies beneath wallet and client layers; application models must remain compatible with their field/type definitions.
- `Base/Xrpl.AddressCodec/XrplAddressCodec.cs`
- `Base/Xrpl.Keypairs/XrplKeypairs.cs`
- `Base/Xrpl.BinaryCodec/XrplBinaryCodec.cs`

#### x402 payment extension
A separate core package and ASP.NET Core integration implement x402 payment challenges, signed payment envelopes, client-side payment handling, and facilitator abstractions. The ASP.NET layer is optional middleware/integration infrastructure, not the repository’s primary runtime.
- `Xrpl.X402/X402PaymentHandler.cs`
- `Xrpl.X402/Wire/PaymentRequiredChallenge.cs`
- `Xrpl.X402.AspNetCore/X402PaymentExtensions.cs`

#### Protocol synchronization and operational infrastructure
XRPL field/enumeration definitions are generated from server definitions and committed into the binary codec; this is a compatibility boundary when `rippled` protocol changes. CI supports unit/integration execution against Dockerized `rippled`, while documentation is built with DocFX. External services are XRPL `rippled` WebSocket endpoints, testnet faucet usage via wallet funding, and x402 facilitators where enabled.
- `Tools/GenerateEnums/Program.cs`
- `Base/Xrpl.BinaryCodec/Enums/definitions.json`
- `.ci-config/docker-compose.ci.yml`

Main entry points: [`Xrpl/Xrpl.csproj`](https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Xrpl.csproj) (Xrpl NuGet library), [`Xrpl/Wallet/Signer.cs`](https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Wallet/Signer.cs) (Transaction signer), [`Xrpl/Wallet/XrplWallet.cs`](https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Wallet/XrplWallet.cs) (Wallet API), [`Xrpl/Client/IXrplClient.cs`](https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Client/IXrplClient.cs) (Client API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sdk["Xrpl SDK"]
  node_xrpl_library["Xrpl NuGet library<br/>.NET library<br/>[Xrpl.csproj]"]
  node_client_api["Client API<br/>public interface<br/>[IXrplClient.cs]"]
  node_wallet_api["Wallet API<br/>wallet facade<br/>[XrplWallet.cs]"]
  node_websocket_client["WebSocket session<br/>transport client<br/>[WebSocketClient.cs]"]
  node_request_manager["Request manager<br/>request correlation<br/>[RequestManager.cs]"]
  node_json_options["JSON converters<br/>serialization boundary<br/>[XrplJsonOptions.cs]"]
  node_models["Typed XRPL models<br/>domain models<br/>[Common.cs]"]
  node_autofill["Autofill sugar<br/>transaction workflow<br/>[Autofill.cs]"]
  node_submit["Submit-and-wait sugar<br/>transaction workflow<br/>[Submit.cs]"]
  node_signer["Transaction signer<br/>signing service<br/>[Signer.cs]"]
end

subgraph group_protocol["Protocol Foundation"]
  node_address_codec["Address codec<br/>protocol codec"]
  node_keypairs["Keypairs<br/>cryptography<br/>[XrplKeypairs.cs]"]
  node_binary_codec["Binary codec<br/>canonical codec<br/>[XrplBinaryCodec.cs]"]
  node_definitions["XRPL definitions<br/>generated protocol data<br/>[definitions.json]"]
end

subgraph group_x402["x402 Extension"]
  node_x402_core["x402 core<br/>payment extension"]
  node_x402_aspnet["x402 ASP.NET Core<br/>optional middleware"]
end

subgraph group_operations["Protocol Sync &amp; CI"]
  node_enum_generator["Definition generator<br/>code generator<br/>[Program.cs]"]
  node_ci_rippled["Dockerized rippled CI<br/>integration environment"]
end

node_consumer(("Application consumer<br/>external application"))
node_rippled{{"rippled endpoint<br/>external XRPL node"}}
node_facilitator{{"x402 facilitator<br/>external payment service"}}

node_consumer -->|"references"| node_xrpl_library
node_xrpl_library -->|"exposes"| node_client_api
node_xrpl_library -->|"exposes"| node_wallet_api
node_xrpl_library -->|"exposes"| node_models
node_client_api -->|"sends typed calls"| node_request_manager
node_request_manager -->|"uses session"| node_websocket_client
node_websocket_client -->|"WebSocket JSON-RPC"| node_rippled
node_request_manager -->|"serializes/deserializes"| node_json_options
node_json_options -->|"maps wire payloads"| node_models
node_autofill -->|"reads account context"| node_client_api
node_submit -->|"submits and monitors"| node_client_api
node_wallet_api -->|"signs through"| node_signer
node_signer -->|"signs transactions"| node_models
node_signer -->|"uses keys"| node_keypairs
node_signer -->|"serializes"| node_binary_codec
node_wallet_api -->|"encodes addresses"| node_address_codec
node_binary_codec -->|"uses field definitions"| node_definitions
node_enum_generator -->|"generates"| node_definitions
node_x402_aspnet -->|"integrates"| node_x402_core
node_x402_core -->|"creates signed payments"| node_wallet_api
node_x402_core -->|"delegates facilitation"| node_facilitator
node_ci_rippled -.->|"provisions for integration"| node_rippled

click node_xrpl_library "https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Xrpl.csproj"
click node_client_api "https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Client/IXrplClient.cs"
click node_wallet_api "https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Wallet/XrplWallet.cs"
click node_websocket_client "https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Client/WebSocketClient.cs"
click node_request_manager "https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Client/RequestManager.cs"
click node_json_options "https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Client/Json/XrplJsonOptions.cs"
click node_models "https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Models/Transactions/Common.cs"
click node_autofill "https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Sugar/Autofill.cs"
click node_submit "https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Sugar/Submit.cs"
click node_signer "https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Wallet/Signer.cs"
click node_address_codec "https://github.com/staticbit-io/xrplcsharp/blob/dev/Base/Xrpl.AddressCodec/XrplAddressCodec.cs"
click node_keypairs "https://github.com/staticbit-io/xrplcsharp/blob/dev/Base/Xrpl.Keypairs/XrplKeypairs.cs"
click node_binary_codec "https://github.com/staticbit-io/xrplcsharp/blob/dev/Base/Xrpl.BinaryCodec/XrplBinaryCodec.cs"
click node_definitions "https://github.com/staticbit-io/xrplcsharp/blob/dev/Base/Xrpl.BinaryCodec/Enums/definitions.json"
click node_enum_generator "https://github.com/staticbit-io/xrplcsharp/blob/dev/Tools/GenerateEnums/Program.cs"
click node_x402_core "https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl.X402/X402PaymentHandler.cs"
click node_x402_aspnet "https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl.X402.AspNetCore/X402PaymentExtensions.cs"
click node_ci_rippled "https://github.com/staticbit-io/xrplcsharp/blob/dev/.ci-config/docker-compose.ci.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_xrpl_library,node_client_api,node_wallet_api,node_websocket_client,node_request_manager,node_json_options,node_models,node_autofill,node_submit,node_signer toneBlue
class node_address_codec,node_keypairs,node_binary_codec,node_definitions toneAmber
class node_x402_core,node_x402_aspnet toneMint
class node_enum_generator,node_ci_rippled toneRose
class node_consumer,node_rippled,node_facilitator toneNeutral
```

## Components

### Xrpl SDK

Primary NuGet library and application APIs.

- [Xrpl NuGet library](https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Xrpl.csproj): .NET library · Primary SDK deliverable. · `Xrpl/Xrpl.csproj`
- [Client API](https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Client/IXrplClient.cs): public interface · Typed access to XRPL methods and subscriptions. · `Xrpl/Client/IXrplClient.cs`
- [Wallet API](https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Wallet/XrplWallet.cs): wallet facade · Creates wallets and signs transactions. · `Xrpl/Wallet/XrplWallet.cs`
- [WebSocket session](https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Client/WebSocketClient.cs): transport client · Maintains the rippled WebSocket connection. · `Xrpl/Client/WebSocketClient.cs`
- [Request manager](https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Client/RequestManager.cs): request correlation · Matches JSON-RPC requests, responses, and streams. · `Xrpl/Client/RequestManager.cs`
- [JSON converters](https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Client/Json/XrplJsonOptions.cs): serialization boundary · Maps wire payload variations to C# models. · `Xrpl/Client/Json/XrplJsonOptions.cs`
- [Typed XRPL models](https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Models/Transactions/Common.cs): domain models · Shared method, transaction, ledger, value, and event types. · `Xrpl/Models/Transactions/Common.cs`
- [Autofill sugar](https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Sugar/Autofill.cs): transaction workflow · Obtains account, fee, and ledger context. · `Xrpl/Sugar/Autofill.cs`
- [Submit-and-wait sugar](https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Sugar/Submit.cs): transaction workflow · Submits transactions and can await validation. · `Xrpl/Sugar/Submit.cs`
- [Transaction signer](https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl/Wallet/Signer.cs): signing service · Serializes and signs transaction models. · `Xrpl/Wallet/Signer.cs`

### Protocol Foundation

XRPL encoding, keys, and generated definitions.

- [Address codec](https://github.com/staticbit-io/xrplcsharp/blob/dev/Base/Xrpl.AddressCodec/XrplAddressCodec.cs): protocol codec · XRPL address and seed encoding. · `Base/Xrpl.AddressCodec/XrplAddressCodec.cs`
- [Keypairs](https://github.com/staticbit-io/xrplcsharp/blob/dev/Base/Xrpl.Keypairs/XrplKeypairs.cs): cryptography · Seed derivation and Ed25519/secp256k1 signing. · `Base/Xrpl.Keypairs/XrplKeypairs.cs`
- [Binary codec](https://github.com/staticbit-io/xrplcsharp/blob/dev/Base/Xrpl.BinaryCodec/XrplBinaryCodec.cs): canonical codec · Canonical serialization, hashes, fields, and ledger primitives. · `Base/Xrpl.BinaryCodec/XrplBinaryCodec.cs`
- [XRPL definitions](https://github.com/staticbit-io/xrplcsharp/blob/dev/Base/Xrpl.BinaryCodec/Enums/definitions.json): generated protocol data · Committed field and enumeration definitions. · `Base/Xrpl.BinaryCodec/Enums/definitions.json`

### x402 Extension

Optional payment protocol packages.

- [x402 core](https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl.X402/X402PaymentHandler.cs): payment extension · Challenges, signed payment envelopes, handlers, and facilitators. · `Xrpl.X402/X402PaymentHandler.cs`
- [x402 ASP.NET Core](https://github.com/staticbit-io/xrplcsharp/blob/dev/Xrpl.X402.AspNetCore/X402PaymentExtensions.cs): optional middleware · ASP.NET Core integration for x402. · `Xrpl.X402.AspNetCore/X402PaymentExtensions.cs`

### Protocol Sync & CI

Definition generation and integration environment.

- [Definition generator](https://github.com/staticbit-io/xrplcsharp/blob/dev/Tools/GenerateEnums/Program.cs): code generator · Synchronizes codec definitions with server protocol data. · `Tools/GenerateEnums/Program.cs`
- [Dockerized rippled CI](https://github.com/staticbit-io/xrplcsharp/blob/dev/.ci-config/docker-compose.ci.yml): integration environment · Runs integration workflows against rippled. · `.ci-config/docker-compose.ci.yml`

### Other components

- **Application consumer**: external application · Uses the SDK as a NuGet library.
- **rippled endpoint**: external XRPL node · Remote JSON-RPC/WebSocket server.
- **x402 facilitator**: external payment service · Used when x402 payment handling is enabled.

## Connections

- Application consumer → Xrpl NuGet library: references
- Xrpl NuGet library → Client API: exposes
- Xrpl NuGet library → Wallet API: exposes
- Xrpl NuGet library → Typed XRPL models: exposes
- Client API → Request manager: sends typed calls
- Request manager → WebSocket session: uses session
- WebSocket session → rippled endpoint: WebSocket JSON-RPC
- Request manager → JSON converters: serializes/deserializes
- JSON converters → Typed XRPL models: maps wire payloads
- Autofill sugar → Client API: reads account context
- Submit-and-wait sugar → Client API: submits and monitors
- Wallet API → Transaction signer: signs through
- Transaction signer → Typed XRPL models: signs transactions
- Transaction signer → Keypairs: uses keys
- Transaction signer → Binary codec: serializes
- Wallet API → Address codec: encodes addresses
- Binary codec → XRPL definitions: uses field definitions
- Definition generator → XRPL definitions: generates
- x402 ASP.NET Core → x402 core: integrates
- x402 core → Wallet API: creates signed payments
- x402 core → x402 facilitator: delegates facilitation
- Dockerized rippled CI → rippled endpoint: provisions for integration