xrpl

README

xrpl-go: A Go client for the XRP Ledger

Motivation

We use Go and XRPL websocket APIs a lot a XRPScan. Unfortunately, the state of the Go client libraries for XRPL at the time of publishing this package is not ideal. This is where xrpl-go comes in. It provides a low level API for interacting with XRPL websocket interface. This library aims to mirror concepts of the official JavaScript/TypeScript library xrpl.js.

Reference documentation

See the full reference documentation for all packages, functions and constants.

Features

1. Sending requests to observe ledger state using public websocket API methods
2. Subscribing to changes in the ledger (ledger, transactions, validations streams)
3. Parsing ledger data into mode convenient formats [WIP]

rippled versions

xrpl-go is currently tested with rippled versions > 1.9.4. While it should also be compatible with later versions, newer features available on XRPL mainnet may not be available on day 0.

Installation

go get -u github.com/xrpscan/xrpl-go

Getting started

Here are some examples showing typical use:

Establish a new websocket connection

config := xrpl.ClientConfig{
  URL: "wss://s.altnet.rippletest.net:51233",
}
client, _ := xrpl.NewClient(config)
err := client.Ping([]byte("PING"))
if err != nil {
  panic(err)
}

Send account_info request

request := xrpl.BaseRequest{
  "command": "account_info",
  "account": "rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe",
  "ledger_index": "validated",
}
response, err := client.Request(request)
if err != nil {
  fmt.Println(err)
}
fmt.Println(response)

Subscribe to a single stream

client.Subscribe([]string{
  xrpl.StreamTypeLedger,
})
for {
  ledger := <-client.StreamLedger
  fmt.Println(string(ledger))
}

Subscribe to multiple streams

client.Subscribe([]string{
  xrpl.StreamTypeLedger,
  xrpl.StreamTypeTransaction,
  xrpl.StreamTypeValidations,
})
for {
  select {
  case ledger := <-client.StreamLedger:
    fmt.Println(string(ledger))
  case transaction := <-client.StreamTransaction:
    fmt.Println(string(transaction))
  case validation := <-client.StreamValidation:
    fmt.Println(string(validation))
  }
}

Bugs

xrpl-go is a work in progress. If you discover a bug or come across erratic behavior, please create an issue and we'll do our best to address it.

References

• XRPL HTTP/WebSocket API methods
• XRPL WebSocket streams
• JavaScript/TypeScript library for interacting with the XRP Ledger

Documentation

Index

• Constants
• func StreamResponseType(streamType string) string
• type BaseRequest
• type BaseResponse
• type Client
  • func NewClient(config ClientConfig) *Client
  • func (c *Client) Close() error
  • func (c *Client) NewConnection() (*websocket.Conn, error)
  • func (c *Client) NextID() string
  • func (c *Client) Ping(message []byte) error
  • func (c *Client) Reconnect() error
  • func (c *Client) Request(req BaseRequest) (BaseResponse, error)
  • func (c *Client) Subscribe(streams []string) (BaseResponse, error)
  • func (c *Client) Subscriptions() []string
  • func (c *Client) Unsubscribe(streams []string) (BaseResponse, error)
• type ClientConfig
  • func (config *ClientConfig) Validate() error
• type Network
  • func GetNetwork(networkId int) Network
  • func (n Network) Asset() string
  • func (n Network) Name() string

Constants

const (
	StreamTypeLedger               = "ledger"
	StreamTypeTransaction          = "transactions"
	StreamTypeTransactionsProposed = "transactions_proposed"
	StreamTypeValidations          = "validations"
	StreamTypeManifests            = "manifests"
	StreamTypePeerStatus           = "peer_status"
	StreamTypeConsensus            = "consensus"
	StreamTypePathFind             = "path_find"
	StreamTypeServer               = "server"
	StreamTypeResponse             = "response"
)

XRPL stream types as defined in rippled:

1. https://github.com/XRPLF/xrpl.js/blob/main/packages/xrpl/src/models/common/index.ts#L36
2. https://github.com/XRPLF/rippled/blob/master/src/ripple/rpc/handlers/Subscribe.cpp#L127

const XAHAU_NATIVE_ASSET = "XAH"

const XRPL_NATIVE_ASSET = "XRP"

Functions

func StreamResponseType

func StreamResponseType(streamType string) string

StreamResponseType returns a string denoting 'type' property present in the requested StreamType's response. It returns the empty string if there's no match for the requested StreamType.

Types

type BaseRequest

type BaseRequest map[string]interface{}

BaseRequest is a map of keys and values. Values are usually strings, but may be complex interface{} type

type BaseResponse

type BaseResponse map[string]interface{}

BaseResponse is a map of keys and values. Values may be complex interface{} type

type Client

type Client struct {
	StreamLedger        chan []byte
	StreamTransaction   chan []byte
	StreamValidation    chan []byte
	StreamManifest      chan []byte
	StreamPeerStatus    chan []byte
	StreamConsensus     chan []byte
	StreamPathFind      chan []byte
	StreamServer        chan []byte
	StreamDefault       chan []byte
	StreamSubscriptions map[string]bool
	// contains filtered or unexported fields
}

func NewClient

func NewClient(config ClientConfig) *Client

func (*Client) Close

func (c *Client) Close() error

func (*Client) NewConnection

func (c *Client) NewConnection() (*websocket.Conn, error)

func (*Client) NextID

func (c *Client) NextID() string

Returns incremental ID that may be used as request ID for websocket requests

func (*Client) Ping

func (c *Client) Ping(message []byte) error

func (*Client) Reconnect

func (c *Client) Reconnect() error

func (*Client) Request

func (c *Client) Request(req BaseRequest) (BaseResponse, error)

Send a websocket request. This method takes a BaseRequest object and automatically adds incremental request ID to it.

Example usage:

req := BaseRequest{
	"command": "account_info",
	"account": "rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn",
	"ledger_index": "current",
}

err := client.Request(req, func(){})

func (*Client) Subscribe

func (c *Client) Subscribe(streams []string) (BaseResponse, error)

func (*Client) Subscriptions

func (c *Client) Subscriptions() []string

func (*Client) Unsubscribe

func (c *Client) Unsubscribe(streams []string) (BaseResponse, error)

type ClientConfig

type ClientConfig struct {
	URL                string
	Authorization      string
	Certificate        string
	FeeCushion         uint32
	Key                string
	MaxFeeXRP          uint64
	Passphrase         byte
	Proxy              byte
	ProxyAuthorization byte
	ReadTimeout        time.Duration
	WriteTimeout       time.Duration
	HeartbeatInterval  time.Duration
	QueueCapacity      int
}

func (*ClientConfig) Validate

func (config *ClientConfig) Validate() error

type Network

type Network int32

const (
	NetworkXrplMainnet   Network = 0
	NetworkXrplTestnet   Network = 1
	NetworkXrplDevnet    Network = 2
	NetworkXrplAmmDevnet Network = 25
	NetworkXahauMainnet  Network = 21337
	NetworkXahauTestnet  Network = 21338
)

func GetNetwork

func GetNetwork(networkId int) Network

func (Network) Asset

func (n Network) Asset() string

func (Network) Name

func (n Network) Name() string