How staticbit-io/xrplcsharp works
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.csproj Xrpl NuGet library · Signer.cs Transaction signer · XrplWallet.cs Wallet API · IXrplClient.cs Client API
Components 21
Xrpl SDK
Primary NuGet library and application APIs.
- Xrpl NuGet library · Primary SDK deliverable.
Xrpl/Xrpl.csproj - Client API · Typed access to XRPL methods and subscriptions.
Xrpl/Client/IXrplClient.cs - Wallet API · Creates wallets and signs transactions.
Xrpl/Wallet/XrplWallet.cs - WebSocket session · Maintains the rippled WebSocket connection.
Xrpl/Client/WebSocketClient.cs - Request manager · Matches JSON-RPC requests, responses, and streams.
Xrpl/Client/RequestManager.cs - JSON converters · Maps wire payload variations to C# models.
Xrpl/Client/Json/XrplJsonOptions.cs - Typed XRPL models · Shared method, transaction, ledger, value, and event types.
Xrpl/Models/Transactions/Common.cs - Autofill sugar · Obtains account, fee, and ledger context.
Xrpl/Sugar/Autofill.cs - Submit-and-wait sugar · Submits transactions and can await validation.
Xrpl/Sugar/Submit.cs - Transaction signer · Serializes and signs transaction models.
Xrpl/Wallet/Signer.cs
Protocol Foundation
XRPL encoding, keys, and generated definitions.
- Address codec · XRPL address and seed encoding.
Base/Xrpl.AddressCodec/XrplAddressCodec.cs - Keypairs · Seed derivation and Ed25519/secp256k1 signing.
Base/Xrpl.Keypairs/XrplKeypairs.cs - Binary codec · Canonical serialization, hashes, fields, and ledger primitives.
Base/Xrpl.BinaryCodec/XrplBinaryCodec.cs - XRPL definitions · Committed field and enumeration definitions.
Base/Xrpl.BinaryCodec/Enums/definitions.json
x402 Extension
Optional payment protocol packages.
- x402 core · Challenges, signed payment envelopes, handlers, and facilitators.
Xrpl.X402/X402PaymentHandler.cs - x402 ASP.NET Core · ASP.NET Core integration for x402.
Xrpl.X402.AspNetCore/X402PaymentExtensions.cs
Protocol Sync & CI
Definition generation and integration environment.
- Definition generator · Synchronizes codec definitions with server protocol data.
Tools/GenerateEnums/Program.cs - Dockerized rippled CI · Runs integration workflows against rippled.
.ci-config/docker-compose.ci.yml
Other components
- Application consumer · Uses the SDK as a NuGet library.
- rippled endpoint · Remote JSON-RPC/WebSocket server.
- x402 facilitator · Used when x402 payment handling is enabled.
Connections 22
- 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