Skip to main content

RPC Ledger Backend

The RPCLedgerBackend is a LedgerBackend implementation in Stellar Ingest SDK which uses an RPC Server as the backing source of ledger meta data.

Applications can use this ledger backend in order to obtain ledger meta data from the Stellar network through the standard LedgerBackend interface methods. This ledger backend is considered the most lightweight of the available ledger backends as it only requires an HTTP client to access a remote RPC server.

Usage of the RPCLedgerBackend implies having awareness of the retention window and data lake settings on the remote RPC server as these aspects determine the range of ledgers which are accessible through the RPCLedgerBackend.

  • HISTORY_RETENTION_WINDOW - This is a setting on the RPC server which determines the range of ledgers retained by the RPC in a sliding window from latest on Stellar network. The default is to retain the latest 7 days worth of ledger data from the Stellar network.
  • Data Lake Integration - If the RPC has the Data Lake integration enabled then the range of ledgers available will be a minimum of RPC's Retention Window and extends further back in history out to the larger range provided by the data lake.

Example SDK Usage​

Prerequisites​

  1. A URL of an RPC Server.
  2. Go 1.2x runtime

Code​

A working example demonstrating programmatic usage of RPCLedgerBackend to print a stream of latest ledgers emitted from the Stellar Testnet Network. Note the additional usage of the RPC Go Client which uses the same RPC url to get the latest ledger from the RPC server. This is used to prime our live streaming example to use the latest known ledger on RPC as the starting ledger when requesting the unbounded range.

Prerequisites:

  1. Create an empty directory rpc-backend andcd into the directory.
  2. Run go mod init example/rpc-backend
  3. Run go get github.com/stellar/go github.com/stellar/[email protected]
  4. Copy this code snippet to rpc_ledger_backend_demo.go
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/stellar/go/ingest/ledgerbackend"
    "github.com/stellar/stellar-rpc/client"
)

func main() {
    ctx := context.Background()

    // Use the public SDF Testnet RPC for demo purpose
    endpoint := "https://soroban-testnet.stellar.org"

    // Create a new RPC client
    rpcClient := client.NewClient(endpoint, nil)

    // Get the latest ledger sequence from the RPC server
    health, err := rpcClient.GetHealth(ctx)
    if err != nil {
            log.Fatalf("Failed to get RPC health: %v", err)
    }
    startSeq := health.LatestLedger

    // Configure the RPC Ledger Backend
    backend := ledgerbackend.NewRPCLedgerBackend(ledgerbackend.RPCLedgerBackendOptions{
            RPCServerURL: endpoint,
    })
    defer backend.Close()

    fmt.Printf("Prepare unbounded range starting with Testnet ledger sequence %d: \n", startSeq)
    // Prepare an unbounded range starting from the latest ledger
    if err := backend.PrepareRange(ctx, ledgerbackend.UnboundedRange(startSeq)); err != nil {
            log.Fatalf("Failed to prepare range: %v", err)
    }

    fmt.Println("Iterating over Testnet ledgers:")
    seq := startSeq
    for {
            ledger, err := backend.GetLedger(ctx, seq)
            if err != nil {
                    fmt.Printf("No more ledgers or error at sequence %d: %v\n", seq, err)
                    break
            }
            fmt.Printf("Ledger %d: Hash=%x, CloseTime=%d\n", ledger.LedgerSequence(), ledger.LedgerHash(), ledger.LedgerCloseTime())
            seq++
    }

    fmt.Println("Done.")
}
  1. Run go mod tidy
  2. Run go run rpc_ledger_backend_demo.go