xrpl

README

xrpl

This is the core package of the SDK. It contains everything needed to construct, sign, and submit transactions to the XRP Ledger, query ledger state, and manage accounts — built on top of the lower-level address-codec, keypairs, and binary-codec packages.

Package Structure

xrpl/
├── transaction/        # All transaction types and shared transaction logic
├── wallet/             # Wallet creation, derivation, and offline signing
├── rpc/                # Synchronous JSON-RPC client
├── websocket/          # Asynchronous WebSocket client
├── queries/            # Request/response types for all rippled API methods
├── ledger-entry-types/ # Structs for ledger objects (Offer, AccountRoot, etc.)
├── currency/           # Currency amount utilities
├── hash/               # Transaction hash utilities
├── common/             # Shared constants and helpers
├── flag/               # Transaction flag definitions
├── time/               # XRPL epoch time utilities
├── multisign.go        # Multi-signature aggregation utility
└── interfaces/         # Shared interfaces (CryptoImplementation, etc.)

---

transaction/

All XRPL transaction types live here, one file per type. Every transaction embeds BaseTx and implements the Tx interface:

type Tx interface {
    TxType() TxType
}

BaseTx contains the fields common to every transaction:

Field	Description
Account	Sender's classic address
TransactionType	e.g. Payment, OfferCreate, TrustSet
Fee	Cost in drops (must be set before signing)
Sequence	Account sequence number (0 if using a Ticket)
LastLedgerSequence	Expiry ledger — always set to avoid stuck transactions
SigningPubKey	Public key of the signer, included in the signed blob produced by wallet.Sign
TxnSignature	Signature, included in the signed blob produced by wallet.Sign
Signers	Multi-signature entries
Memos	Arbitrary attached data
Flags	Bitmask of transaction-specific flags

Each transaction type has a Flatten() FlatTransaction method that converts the struct to a map[string]any for JSON-RPC submission.

Available transaction types include: Payment, AccountSet, AccountDelete, TrustSet, OfferCreate, OfferCancel, EscrowCreate/Finish/Cancel, PaymentChannelCreate/Fund/Claim, NFTokenMint/Burn/CreateOffer/CancelOffer/AcceptOffer, AMMCreate/Deposit/Withdraw/Vote/Bid/Delete, CheckCreate/Cash/Cancel, TicketCreate, SignerListSet, SetRegularKey, DepositPreauth, DIDSet/Delete, OracleSet/Delete, XChain*, Batch, and more.

---

wallet/

Provides the Wallet struct for key management and offline signing.

type Wallet struct {
    PublicKey      string
    PrivateKey     string
    ClassicAddress types.Address
    Seed           string
}

Creation

// Random wallet (ED25519 or SECP256K1)
w, err := wallet.New(crypto.ED25519())

// From an existing seed
w, err := wallet.FromSeed(seed, "")
w, err := wallet.FromSecret(seed) // alias

// From a BIP-39 mnemonic (derives via m/44'/144'/0'/0/0)
w, err := wallet.FromMnemonic("word1 word2 ...")

Signing

// Single signature — returns the signed blob and its hash; flatTx is not mutated
txBlob, txHash, err := w.Sign(flatTx)

// Multi-signature — returns the signed blob and its hash; flatTx is not mutated
txBlob, txHash, err := w.Multisign(flatTx)

Sign internally calls binarycodec.EncodeForSigning to get the signing payload, signs it with keypairs.Sign, then calls binarycodec.Encode to produce the final blob.

---

rpc/

A synchronous HTTP JSON-RPC client. Best for one-off queries and simple transaction submission.

cfg := rpc.NewConfig("https://s.altnet.rippletest.net:51234")
client := rpc.NewClient(cfg)

// Submit a pre-signed blob
resp, err := client.SubmitTxBlob(txBlob, false)

// Submit and wait for ledger confirmation
txResp, err := client.SubmitTxBlobAndWait(txBlob, false)

The client automatically retries on HTTP 503 (up to 3 times with exponential backoff) and validates that submitted blobs contain a signature before sending.

---

websocket/

An asynchronous WebSocket client. Best for subscriptions, real-time monitoring, and applications that need to react to ledger events.

cfg := websocket.NewConfig("wss://s.altnet.rippletest.net:51233")
client, err := websocket.NewClient(cfg)

// Subscribe to ledger close events
err = client.SubscribeLedger()

// Read events from channels
ledger := <-client.GetLedgerClosedChannel()
tx     := <-client.GetTransactionChannel()

The WebSocket client manages connection lifecycle, request/response correlation by ID, and exposes typed channels for each stream type (ledger, transaction, validation, etc.).

---

queries/

Typed request and response structs for every rippled API method, organized by category:

Subdirectory	Methods
account/	account_info, account_lines, account_offers, account_tx, etc.
ledger/	ledger, ledger_closed, ledger_current, ledger_data, ledger_entry
transactions/	submit, submit_multisigned, tx, transaction_entry
server/	server_info, server_state, fee
subscription/	Stream types for ledger, transaction, and validation subscriptions

---

multisign.go

Top-level utility for combining multiple individual multi-signature blobs into a single transaction ready for submission:

// Each blob must be produced by wallet.Multisign
finalBlob, err := xrpl.Multisign(blob1, blob2, blob3)

Signers are sorted by account ID bytes (ascending) as required by the XRPL protocol before the final blob is encoded.

Documentation

Overview

Package xrpl provides utilities for working with the XRP Ledger.

Index

• Variables
• func Multisign(blobs ...string) (string, error)
• func SortByAccountID[T any](items []T, account func(T) (string, error)) error
• func SortSigners(signers []any) error

Variables

var (
	// ErrNoTxToMultisign is returned when no transaction blobs are provided to Multisign.
	ErrNoTxToMultisign = errors.New("no transaction to multisign")
	// ErrMultisignNonEmptySigningPubKey is returned when SigningPubKey is not empty
	// on one or more transactions passed to Multisign, it must be an empty string for all.
	ErrMultisignNonEmptySigningPubKey = errors.New("SigningPubKey must be an empty string for all transactions when multisigning")
	// ErrMultisignTxNotEqual is returned when transaction blobs passed to Multisign
	// do not represent the same transaction (ignoring the Signers field).
	ErrMultisignTxNotEqual = errors.New("all transactions to multisign must be equal except for the Signers field")
	// ErrMultisignInvalidSignature is returned when a signer signature is invalid
	// for one or more transactions passed to Multisign.
	ErrMultisignInvalidSignature = errors.New("invalid multisign signer signature")
	// ErrInvalidSigner is returned when a signer entry is malformed.
	ErrInvalidSigner = errors.New("invalid signer")
)

Functions

func Multisign

func Multisign(blobs ...string) (string, error)

Multisign is a utility for signing a transaction offline. It takes a list of transaction blobs and returns the multisigned transaction blob. These transaction blobs must be signed with the wallet.Multisign method. They cannot contain SigningPubKey, otherwise the transaction will fail to submit. All blobs must represent the same transaction (excluding Signers); otherwise ErrMultisignTxNotEqual is returned. Every signer signature must be valid; otherwise ErrMultisignInvalidSignature is returned. If an error occurs, it will return an error.

func SortByAccountID

func SortByAccountID[T any](items []T, account func(T) (string, error)) error

SortByAccountID sorts items in place by the decoded bytes of each item's classic XRPL account address. Use it for canonical signer ordering when different signer representations store the account in different fields. The account function extracts the classic address from an item and may return an error when the item does not contain one. SortByAccountID validates and decodes every account before sorting, so items stay in their original order if extraction or decoding fails.

func SortSigners

func SortSigners(signers []any) error

SortSigners sorts signers ascending by their decoded account ID bytes.