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 IsoTimeToRippleTime(isoTime string) (int64, error)
• func RippleTimeToISOTime(rippleTime int64) string
• func RippleTimeToUnixTime(rippleTime int64) int64
• func StreamResponseType(streamType string) string
• func UnixTimeToRippleTime(unixTime int64) int64
• 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 RIPPLE_EPOCH_DIFF int64 = 946684800

Seconds since UNIX Epoch to Ripple Epoch (2000-01-01T00:00 UTC) https://xrpl.org/docs/references/protocol/data-types/basic-data-types#specifying-time

const XAHAU_NATIVE_ASSET = "XAH"

const XRPL_NATIVE_ASSET = "XRP"

Functions

func IsoTimeToRippleTime

func IsoTimeToRippleTime(isoTime string) (int64, error)

Convert an ISO8601 timestamp to a Ripple timestamp.

func RippleTimeToISOTime

func RippleTimeToISOTime(rippleTime int64) string

Convert a Ripple timestamp to an ISO8601 time.

func RippleTimeToUnixTime

func RippleTimeToUnixTime(rippleTime int64) int64

Convert a Ripple timestamp to a unix timestamp.

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.

func UnixTimeToRippleTime

func UnixTimeToRippleTime(unixTime int64) int64

Convert a unix timestamp to a Ripple timestamp.

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 // Default is 60 seconds
	WriteTimeout       time.Duration // Default is 60 seconds
	HeartbeatInterval  time.Duration // Default is 5 seconds
	QueueCapacity      int           // Default is 128
}

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