Skip to main content

Captive Core

Captive Core invokes the stellar-core binary as a subprocess to stream ledgers from the Stellar network. It can be used to stream a ledger range from the past or to stream new ledgers whenever they are confirmed by the network.

Prerequisites​

Using captive Core requires stellar-core binary to be installed first.

Installation​

  1. Install Stellar Core:

  2. Verify installation:

    ./stellar-core version

Configuration and Usage​

Set the captive core configuration for target Stellar network in TOML format. This configuration requires at a minimum:

  • The passphrase of the Stellar network you want to connect to.
  • The path to history archives, necessary for initialization.

Step 1: Generate a CaptiveCoreToml configuration

captiveCoreToml, err := ledgerbackend.NewCaptiveCoreTomlFromData(
    ledgerbackend.PubnetDefaultConfig,
    ledgerbackend.CaptiveCoreTomlParams{
        NetworkPassphrase:  network.PublicNetworkPassphrase,
        HistoryArchiveURLs: network.PublicNetworkhistoryArchiveURLs,
    },
)

if err != nil {
    // Handle error
}

Step 2: Construct a CaptiveCoreConfig object

Next, create a CaptiveCoreConfig object. This object combines the CaptiveCoreToml configuration with the path to your stellar-core binary and other necessary parameters.

config := ledgerbackend.CaptiveCoreConfig{
    BinaryPath:         "/usr/local/bin/stellar-core", // Adjust to your stellar-core binary path
    NetworkPassphrase:  network.PublicNetworkPassphrase,
    HistoryArchiveURLs: network.PublicNetworkhistoryArchiveURLs,
    Toml:               captiveCoreToml,
}

Step 3: Instantiate CaptiveStellarCore

Finally, create a CaptiveStellarCore instance using the NewCaptive function. This function manages the complete lifecycle of the stellar-core process, including communication with your application.

captiveStellarCoreBackend, err := ledgerbackend.NewCaptive(config)
if err != nil {
    // Handle error
}

The captiveStellarCoreBackend can now be used to retrieve ledger data within a specified range. For detailed usage, refer to the code samples.