|
| 1 | +--- |
| 2 | +title: RPC Ledger Backend |
| 3 | +sidebar_position: 10 |
| 4 | +--- |
| 5 | + |
| 6 | +The [RPCLedgerBackend](https://github.com/stellar/go/blob/master/ingest/ledgerbackend/rpc_backend.go) is a [LedgerBackend](https://github.com/stellar/go/blob/master/ingest/ledgerbackend/ledger_backend.go) implementation in Stellar [Ingest SDK](https://github.com/stellar/go/tree/master/ingest) which uses an RPC Server as the backing source of ledger meta data. |
| 7 | + |
| 8 | +Applications can use this ledger backend in order to obtain ledger meta data from the Stellar network through the standard [LedgerBackend](https://github.com/stellar/go/blob/master/ingest/ledgerbackend/ledger_backend.go) 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. |
| 9 | + |
| 10 | +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. |
| 11 | + |
| 12 | +- `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. |
| 13 | +- [Data Lake Integration](/docs/data/apis/rpc/admin-guide/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. |
| 14 | + |
| 15 | +## Example SDK Usage |
| 16 | + |
| 17 | +### Prerequisites |
| 18 | + |
| 19 | +1. A URL of an RPC Server. |
| 20 | +2. Go 1.2x runtime |
| 21 | + |
| 22 | +### Code |
| 23 | + |
| 24 | +A working example demonstrating programmatic usage of [RPCLedgerBackend](https://github.com/stellar/go/blob/master/ingest/ledgerbackend/rpc_backend.go) to print a stream of latest ledgers emitted from the Stellar Testnet Network. Note the additional usage of the [RPC Go Client](https://github.com/stellar/stellar-rpc/blob/main/client/main.go) 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. |
| 25 | + |
| 26 | +Prerequisites: |
| 27 | + |
| 28 | +1. Create an empty directory `rpc-backend` and`cd` into the directory. |
| 29 | +2. Run `go mod init example/rpc-backend` |
| 30 | +3. Run `go get github.com/stellar/go github.com/stellar/stellar-rpc@rpcclient-v23.0.0` |
| 31 | +4. Copy this code snippet to `rpc_ledger_backend_demo.go` |
| 32 | + |
| 33 | +```go |
| 34 | +package main |
| 35 | + |
| 36 | +import ( |
| 37 | + "context" |
| 38 | + "fmt" |
| 39 | + "log" |
| 40 | + |
| 41 | + "github.com/stellar/go/ingest/ledgerbackend" |
| 42 | + "github.com/stellar/stellar-rpc/client" |
| 43 | +) |
| 44 | + |
| 45 | +func main() { |
| 46 | + ctx := context.Background() |
| 47 | + |
| 48 | + // Use the public SDF Testnet RPC for demo purpose |
| 49 | + endpoint := "https://soroban-testnet.stellar.org" |
| 50 | + |
| 51 | + // Create a new RPC client |
| 52 | + rpcClient := client.NewClient(endpoint, nil) |
| 53 | + |
| 54 | + // Get the latest ledger sequence from the RPC server |
| 55 | + health, err := rpcClient.GetHealth(ctx) |
| 56 | + if err != nil { |
| 57 | + log.Fatalf("Failed to get RPC health: %v", err) |
| 58 | + } |
| 59 | + startSeq := health.LatestLedger |
| 60 | + |
| 61 | + // Configure the RPC Ledger Backend |
| 62 | + backend := ledgerbackend.NewRPCLedgerBackend(ledgerbackend.RPCLedgerBackendOptions{ |
| 63 | + RPCServerURL: endpoint, |
| 64 | + }) |
| 65 | + defer backend.Close() |
| 66 | + |
| 67 | + fmt.Printf("Prepare unbounded range starting with Testnet ledger sequence %d: \n", startSeq) |
| 68 | + // Prepare an unbounded range starting from the latest ledger |
| 69 | + if err := backend.PrepareRange(ctx, ledgerbackend.UnboundedRange(startSeq)); err != nil { |
| 70 | + log.Fatalf("Failed to prepare range: %v", err) |
| 71 | + } |
| 72 | + |
| 73 | + fmt.Println("Iterating over Testnet ledgers:") |
| 74 | + seq := startSeq |
| 75 | + for { |
| 76 | + ledger, err := backend.GetLedger(ctx, seq) |
| 77 | + if err != nil { |
| 78 | + fmt.Printf("No more ledgers or error at sequence %d: %v\n", seq, err) |
| 79 | + break |
| 80 | + } |
| 81 | + fmt.Printf("Ledger %d: Hash=%x, CloseTime=%d\n", ledger.LedgerSequence(), ledger.LedgerHash(), ledger.LedgerCloseTime()) |
| 82 | + seq++ |
| 83 | + } |
| 84 | + |
| 85 | + fmt.Println("Done.") |
| 86 | +} |
| 87 | +``` |
| 88 | + |
| 89 | +5. Run `go mod tidy` |
| 90 | +6. Run `go run rpc_ledger_backend_demo.go` |
0 commit comments