Stellar RPC

https://github.com/stellar/stellar-rpc
Admin
Stellar RPC is a server that provides network information, transaction submission, and status...
Tokens:15,025
Snippets:70
Trust Score:9.4
License:Apache-2.0
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install Stellar CLI and XDR Tools

Source: https://github.com/stellar/stellar-rpc/blob/main/cmd/stellar-rpc/internal/integrationtest/infrastructure/docker/README.md

Installs the `stellar-cli` and `stellar-xdr` tools, which are necessary for encoding configuration files to XDR format. Ensure you have Rust and Cargo installed.

```bash
cargo install --locked stellar-cli@v23.0.0;
cargo install --locked stellar-xdr@v23.0.0;
```

--------------------------------

### Build stellar-rpc Binary

Source: https://github.com/stellar/stellar-rpc/blob/main/cmd/stellar-rpc/README.md

Builds the stellar-rpc binary using the make command. This process installs necessary dependencies and generates the executable file in the current directory.

```bash
make build-stellar-rpc
```

--------------------------------

### Stellar RPC Server Configuration (TOML)

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Example TOML configuration file for the Stellar RPC server. It outlines key settings for network, endpoints, data paths, retention policies, request limits, performance tuning, and logging.

```toml
# stellar-rpc.toml - Example configuration file

# Network configuration
NETWORK_PASSPHRASE = "Test SDF Network ; September 2015"
HISTORY_ARCHIVE_URLS = ["https://history.stellar.org/prd/core-testnet/core_testnet_001"]

# Server endpoints
ENDPOINT = "0.0.0.0:8000"
ADMIN_ENDPOINT = "127.0.0.1:8001"

# Stellar Core paths
STELLAR_CORE_BINARY_PATH = "/usr/local/bin/stellar-core"
CAPTIVE_CORE_CONFIG_PATH = "/etc/stellar/captive-core.cfg"
CAPTIVE_CORE_STORAGE_PATH = "/var/lib/stellar/captive-core"

# Database
DB_PATH = "/var/lib/stellar/soroban_rpc.sqlite"

# Data retention (in ledgers, ~5 seconds per ledger)
HISTORY_RETENTION_WINDOW = 17280  # ~1 day

# Request limits
MAX_EVENTS_LIMIT = 10000
DEFAULT_EVENTS_LIMIT = 100
MAX_TRANSACTIONS_LIMIT = 200
MAX_LEDGERS_LIMIT = 200

# Performance tuning
PREFLIGHT_WORKER_COUNT = 8
PREFLIGHT_WORKER_QUEUE_SIZE = 8
REQUEST_BACKLOG_GLOBAL_QUEUE_LIMIT = 5000
MAX_REQUEST_EXECUTION_DURATION = "25s"
MAX_HEALTHY_LEDGER_LATENCY = "30s"

# Logging
LOG_LEVEL = "info"
LOG_FORMAT = "json"
```

--------------------------------

### POST /getNetwork - Get Network Information

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Returns the network configuration including the network passphrase, friendbot URL (for testnets), and current protocol version. Essential for initializing SDK clients and ensuring transactions are signed for the correct network.

```APIDOC
## POST /getNetwork

### Description
Returns the network configuration including the network passphrase, friendbot URL (for testnets), and current protocol version. Essential for initializing SDK clients and ensuring transactions are signed for the correct network.

### Method
POST

### Endpoint
/getNetwork

### Parameters
#### Query Parameters
None

#### Request Body
- **jsonrpc** (string) - Required - JSON-RPC protocol version, must be "2.0".
- **id** (integer) - Required - A unique identifier for the request.
- **method** (string) - Required - The name of the method to call, must be "getNetwork".

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getNetwork"
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - JSON-RPC protocol version.
- **id** (integer) - The identifier of the request.
- **result** (object) - The network configuration.
  - **friendbotUrl** (string) - The URL for the friendbot service (if applicable).
  - **passphrase** (string) - The network passphrase.
  - **protocolVersion** (integer) - The current Stellar protocol version.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "friendbotUrl": "https://friendbot.stellar.org",
    "passphrase": "Test SDF Network ; September 2015",
    "protocolVersion": 21
  }
}
```
```

--------------------------------

### Get Stellar Network Information

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Fetches the Stellar network configuration, including the network passphrase, friendbot URL (for testnets), and the current protocol version. This information is vital for initializing SDK clients and ensuring correct transaction signing.

```bash
curl -X POST "https://soroban-testnet.stellar.org" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getNetwork"
  }'
```

--------------------------------

### getVersionInfo - Get Server Version Information

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Retrieves version information about the RPC server. This includes the software version, commit hash, build timestamp, captive core version, and the current protocol version supported by the server.

```APIDOC
## POST /getVersionInfo

### Description
Returns version information about the RPC server including the software version, commit hash, build timestamp, captive core version, and current protocol version.

### Method
POST

### Endpoint
https://soroban-testnet.stellar.org

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - Specifies the JSON-RPC protocol version.
- **id** (integer) - Required - A unique identifier for the request.
- **method** (string) - Required - The name of the method to be invoked, which is "getVersionInfo" for this endpoint.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getVersionInfo"
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - The JSON-RPC protocol version.
- **id** (integer) - The identifier of the request.
- **result** (object) - Contains the version information.
  - **version** (string) - The software version of the RPC server.
  - **commitHash** (string) - The Git commit hash of the software build.
  - **buildTimestamp** (string) - The timestamp when the software was built (ISO 8601 format).
  - **captiveCoreVersion** (string) - The version of the captive Stellar Core being used.
  - **protocolVersion** (integer) - The current Stellar protocol version supported.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "version": "21.0.0",
    "commitHash": "abc123def456",
    "buildTimestamp": "2024-01-15T10:00:00Z",
    "captiveCoreVersion": "v21.0.0",
    "protocolVersion": 21
  }
}
```
```

--------------------------------

### Get Server Version Information (RPC)

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Fetches version details of the Stellar RPC server. This includes the software version, commit hash, build timestamp, captive core version, and the currently supported protocol version. This information is useful for compatibility checks and debugging.

```bash
curl -X POST "https://soroban-testnet.stellar.org" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getVersionInfo"
  }'
```

--------------------------------

### Get Latest Stellar Ledger Information

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Retrieves details about the most recently closed ledger, such as its sequence number, hash, close time, and protocol version. The response also includes the complete ledger header in base64-encoded XDR format.

```bash
curl -X POST "https://soroban-testnet.stellar.org" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getLatestLedger"
  }'
```

--------------------------------

### Get Transaction Fee Statistics (RPC)

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Retrieves fee statistics for both classic Stellar and Soroban transactions. It provides percentile distributions based on recent ledger data, helping users determine appropriate transaction fees. The endpoint used is typically a Soroban testnet or mainnet RPC URL.

```bash
curl -X POST "https://soroban-testnet.stellar.org" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getFeeStats"
  }'
```

--------------------------------

### POST /getLatestLedger - Get Latest Ledger Information

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Returns details about the most recently closed ledger, including its sequence number, hash, close time, and protocol version. The response includes the full ledger header in base64-encoded XDR format.

```APIDOC
## POST /getLatestLedger

### Description
Returns details about the most recently closed ledger, including its sequence number, hash, close time, and protocol version. The response includes the full ledger header in base64-encoded XDR format.

### Method
POST

### Endpoint
/getLatestLedger

### Parameters
#### Query Parameters
None

#### Request Body
- **jsonrpc** (string) - Required - JSON-RPC protocol version, must be "2.0".
- **id** (integer) - Required - A unique identifier for the request.
- **method** (string) - Required - The name of the method to call, must be "getLatestLedger".

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getLatestLedger"
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - JSON-RPC protocol version.
- **id** (integer) - The identifier of the request.
- **result** (object) - The latest ledger information.
  - **hash** (string) - The hash of the latest ledger.
  - **protocolVersion** (integer) - The protocol version of the latest ledger.
  - **sequence** (integer) - The sequence number of the latest ledger.
  - **ledgerCloseTime** (integer) - The Unix timestamp of when the ledger was closed.
  - **ledgerHeader** (string) - The base64-encoded XDR of the ledger header.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "hash": "abc123...",
    "protocolVersion": 21,
    "sequence": 1234567,
    "ledgerCloseTime": 1699900000,
    "ledgerHeader": "AAAA..."
  }
}
```
```

--------------------------------

### getFeeStats - Get Transaction Fee Statistics

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Retrieves transaction fee statistics based on recent ledgers for both classic Stellar transactions and Soroban smart contract transactions. This endpoint helps in determining appropriate fees by providing percentile distributions.

```APIDOC
## POST /getFeeStats

### Description
Returns fee statistics based on recent ledgers for both classic Stellar transactions and Soroban smart contract transactions. Provides percentile distributions to help choose appropriate fees.

### Method
POST

### Endpoint
https://soroban-testnet.stellar.org

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - Specifies the JSON-RPC protocol version.
- **id** (integer) - Required - A unique identifier for the request.
- **method** (string) - Required - The name of the method to be invoked, which is "getFeeStats" for this endpoint.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getFeeStats"
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - The JSON-RPC protocol version.
- **id** (integer) - The identifier of the request.
- **result** (object) - Contains the fee statistics.
  - **sorobanInclusionFee** (object) - Fee statistics for Soroban transactions.
    - **max** (string) - Maximum fee.
    - **min** (string) - Minimum fee.
    - **mode** (string) - Most frequent fee.
    - **p10** (string) - 10th percentile fee.
    - **p20** (string) - 20th percentile fee.
    - **p30** (string) - 30th percentile fee.
    - **p40** (string) - 40th percentile fee.
    - **p50** (string) - 50th percentile fee.
    - **p60** (string) - 60th percentile fee.
    - **p70** (string) - 70th percentile fee.
    - **p80** (string) - 80th percentile fee.
    - **p90** (string) - 90th percentile fee.
    - **p95** (string) - 95th percentile fee.
    - **p99** (string) - 99th percentile fee.
    - **transactionCount** (integer) - Number of transactions considered.
    - **ledgerCount** (integer) - Number of ledgers considered.
  - **inclusionFee** (object) - Fee statistics for classic Stellar transactions.
    - **max** (string) - Maximum fee.
    - **min** (string) - Minimum fee.
    - **mode** (string) - Most frequent fee.
    - **p10** (string) - 10th percentile fee.
    - **p20** (string) - 20th percentile fee.
    - **p30** (string) - 30th percentile fee.
    - **p40** (string) - 40th percentile fee.
    - **p50** (string) - 50th percentile fee.
    - **p60** (string) - 60th percentile fee.
    - **p70** (string) - 70th percentile fee.
    - **p80** (string) - 80th percentile fee.
    - **p90** (string) - 90th percentile fee.
    - **p95** (string) - 95th percentile fee.
    - **p99** (string) - 99th percentile fee.
    - **transactionCount** (integer) - Number of transactions considered.
    - **ledgerCount** (integer) - Number of ledgers considered.
  - **latestLedger** (integer) - The sequence number of the latest ledger.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "sorobanInclusionFee": {
      "max": "210000",
      "min": "100",
      "mode": "100",
      "p10": "100",
      "p20": "100",
      "p30": "100",
      "p40": "100",
      "p50": "100",
      "p60": "100",
      "p70": "100",
      "p80": "100",
      "p90": "100",
      "p95": "150",
      "p99": "200000",
      "transactionCount": 50,
      "ledgerCount": 50
    },
    "inclusionFee": {
      "max": "100",
      "min": "100",
      "mode": "100",
      "p10": "100",
      "p20": "100",
      "p30": "100",
      "p40": "100",
      "p50": "100",
      "p60": "100",
      "p70": "100",
      "p80": "100",
      "p90": "100",
      "p95": "100",
      "p99": "100",
      "transactionCount": 100,
      "ledgerCount": 10
    },
    "latestLedger": 1234567
  }
}
```
```

--------------------------------

### Stellar RPC Server Configuration (Command-line & Environment)

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Demonstrates how to run the Stellar RPC server using command-line flags or environment variables. This allows for flexible configuration without modifying the TOML file directly, useful for containerized deployments or quick testing.

```bash
# Running with command-line flags
stellar-rpc \
  --network testnet \
  --endpoint 0.0.0.0:8000 \
  --db-path /var/lib/stellar/soroban_rpc.sqlite \
  --history-retention-window 17280 \
  --log-level info
```

```bash
# Running with environment variables
export SOROBAN_RPC_CONFIG_PATH=/etc/stellar/rpc.toml
export SOROBAN_RPC_CONFIG_STRICT=true
stellar-rpc
```

--------------------------------

### Run Integration Tests (Go)

Source: https://github.com/stellar/stellar-rpc/blob/main/README.md

Executes integration tests for the Stellar RPC project. This requires setting several environment variables to configure the test environment, including enabling tests, specifying the maximum supported protocol version, and the path to the captive stellar-core binary.

```bash
STELLAR_RPC_INTEGRATION_TESTS_ENABLED=true \
STELLAR_RPC_INTEGRATION_TESTS_CORE_MAX_SUPPORTED_PROTOCOL=23 \
STELLAR_RPC_INTEGRATION_TESTS_CAPTIVE_CORE_BIN=$(which stellar-core) \
    go test -v -failfast ./cmd/stellar-rpc/internal/integrationtest/...
```

--------------------------------

### Clone stellar-rpc Repository

Source: https://github.com/stellar/stellar-rpc/blob/main/cmd/stellar-rpc/README.md

Clones the stellar-rpc repository and navigates into the directory. This is the first step in building the Stellar-RPC service.

```bash
git clone https://github.com/stellar/stellar-rpc.git
cd stellar-rpc
```

--------------------------------

### Run Stellar-RPC Server

Source: https://github.com/stellar/stellar-rpc/blob/main/cmd/stellar-rpc/README.md

Runs the Stellar-RPC server using a generated configuration file. The `--config-path` flag specifies the location of the TOML configuration file.

```bash
./stellar-rpc --config-path <PATH_TO_THE_RPC_CONFIG_FILE>
```

--------------------------------

### Run Unit Tests (Go)

Source: https://github.com/stellar/stellar-rpc/blob/main/README.md

Executes unit tests for the Stellar RPC project using the Go testing framework. This command runs all tests verbosely and stops on the first failure.

```bash
go test -v -failfast ./...
```

--------------------------------

### Server Configuration

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Details on how to configure the Stellar RPC server, including options for network selection, data retention, request limits, and performance tuning using command-line flags, environment variables, or a TOML configuration file.

```APIDOC
## Server Configuration

### Description
The RPC server is configured via command-line flags, environment variables, or a TOML configuration file. Key configuration options control network selection, data retention, request limits, and performance tuning.

### Configuration Methods

1.  **TOML Configuration File**: 
    A TOML file can be used to specify various configuration settings. The path to this file can be provided using the `SOROBAN_RPC_CONFIG_PATH` environment variable.

    **Example `stellar-rpc.toml`:**
    ```toml
    # Network configuration
    NETWORK_PASSPHRASE = "Test SDF Network ; September 2015"
    HISTORY_ARCHIVE_URLS = ["https://history.stellar.org/prd/core-testnet/core_testnet_001"]

    # Server endpoints
    ENDPOINT = "0.0.0.0:8000"
    ADMIN_ENDPOINT = "127.0.0.1:8001"

    # Stellar Core paths
    STELLAR_CORE_BINARY_PATH = "/usr/local/bin/stellar-core"
    CAPTIVE_CORE_CONFIG_PATH = "/etc/stellar/captive-core.cfg"
    CAPTIVE_CORE_STORAGE_PATH = "/var/lib/stellar/captive-core"

    # Database
    DB_PATH = "/var/lib/stellar/soroban_rpc.sqlite"

    # Data retention (in ledgers, ~5 seconds per ledger)
    HISTORY_RETENTION_WINDOW = 17280  # ~1 day

    # Request limits
    MAX_EVENTS_LIMIT = 10000
    DEFAULT_EVENTS_LIMIT = 100
    MAX_TRANSACTIONS_LIMIT = 200
    MAX_LEDGERS_LIMIT = 200

    # Performance tuning
    PREFLIGHT_WORKER_COUNT = 8
    PREFLIGHT_WORKER_QUEUE_SIZE = 8
    REQUEST_BACKLOG_GLOBAL_QUEUE_LIMIT = 5000
    MAX_REQUEST_EXECUTION_DURATION = "25s"
    MAX_HEALTHY_LEDGER_LATENCY = "30s"

    # Logging
    LOG_LEVEL = "info"
    LOG_FORMAT = "json"
    ```

2.  **Command-Line Flags**:
    The server can be started with various command-line flags to override or set configuration options.

    **Example:**
    ```bash
    stellar-rpc \
      --network testnet \
      --endpoint 0.0.0.0:8000 \
      --db-path /var/lib/stellar/soroban_rpc.sqlite \
      --history-retention-window 17280 \
      --log-level info
    ```

3.  **Environment Variables**:
    Configuration options can also be set using environment variables. The `SOROBAN_RPC_CONFIG_PATH` variable is used to specify the TOML configuration file.

    **Example:**
    ```bash
    export SOROBAN_RPC_CONFIG_PATH=/etc/stellar/rpc.toml
    export SOROBAN_RPC_CONFIG_STRICT=true
    stellar-rpc
    ```

### Key Configuration Options

-   **Network Configuration**:
    -   `NETWORK_PASSPHRASE`: The passphrase for the Stellar network.
    -   `HISTORY_ARCHIVE_URLS`: URLs for history archives.

-   **Server Endpoints**:
    -   `ENDPOINT`: The address and port for the main RPC endpoint.
    -   `ADMIN_ENDPOINT`: The address and port for the admin endpoint.

-   **Stellar Core Paths**:
    -   `STELLAR_CORE_BINARY_PATH`: Path to the stellar-core executable.
    -   `CAPTIVE_CORE_CONFIG_PATH`: Path to the captive stellar-core configuration file.
    -   `CAPTIVE_CORE_STORAGE_PATH`: Path for captive stellar-core storage.

-   **Database**:
    -   `DB_PATH`: Path to the SQLite database file.

-   **Data Retention**:
    -   `HISTORY_RETENTION_WINDOW`: The number of ledgers to retain history for.

-   **Request Limits**:
    -   `MAX_EVENTS_LIMIT`: Maximum number of events that can be returned in a single request.
    -   `DEFAULT_EVENTS_LIMIT`: Default number of events per page.
    -   `MAX_TRANSACTIONS_LIMIT`: Maximum number of transactions.
    -   `MAX_LEDGERS_LIMIT`: Maximum number of ledgers.

-   **Performance Tuning**:
    -   `PREFLIGHT_WORKER_COUNT`: Number of worker threads for preflight checks.
    -   `PREFLIGHT_WORKER_QUEUE_SIZE`: Size of the queue for preflight workers.
    -   `REQUEST_BACKLOG_GLOBAL_QUEUE_LIMIT`: Global limit for the request backlog queue.
    -   `MAX_REQUEST_EXECUTION_DURATION`: Maximum duration for request execution.
    -   `MAX_HEALTHY_LEDGER_LATENCY`: Maximum allowed latency for a healthy ledger.

-   **Logging**:
    -   `LOG_LEVEL`: The minimum severity level for log messages (e.g., `debug`, `info`, `warn`, `error`).
    -   `LOG_FORMAT`: The format for log messages (e.g., `text`, `json`).
```

--------------------------------

### Clone stellar-core Repository

Source: https://github.com/stellar/stellar-rpc/blob/main/cmd/stellar-rpc/README.md

Clones the stellar-core repository and navigates into the directory. This is a prerequisite for building the stellar-core binary, which is required by Stellar-RPC.

```bash
git clone https://github.com/stellar/stellar-core.git
cd stellar-core
```

--------------------------------

### Checkout stellar-core Testnet Release

Source: https://github.com/stellar/stellar-rpc/blob/main/cmd/stellar-rpc/README.md

Fetches all tags from the stellar-core repository and checks out a specific testnet release tag. This ensures compatibility with the testnet environment.

```bash
git fetch --tags
git checkout tags/v20.0.0-rc.2.1 -b soroban-testnet-release
```

--------------------------------

### Generate RPC Configuration File

Source: https://github.com/stellar/stellar-rpc/blob/main/cmd/stellar-rpc/README.md

Generates a TOML configuration file for the Stellar-RPC server. This command outputs the configuration to standard output, which can then be saved to a file.

```bash
./stellar-rpc gen-config-file
```

--------------------------------

### Query Smart Contract Events with Filters (Bash)

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Queries smart contract events using the getEvents RPC method. It allows filtering by contract ID, event type, and topics, with support for pagination to handle large datasets.

```bash
curl -X POST "https://soroban-testnet.stellar.org" \
  -H "Content-Type: application/json" \
  -d '{ \
    "jsonrpc": "2.0", \
    "id": 1, \
    "method": "getEvents", \
    "params": { \
      "startLedger": 1234500, \
      "filters": [ \
        { \
          "type": "contract", \
          "contractIds": ["CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC"], \
          "topics": [ \
            ["AAAADwAAAAh0cmFuc2Zlcg==", "*"] \
          ] \
        } \
      ], \
      "pagination": { \
        "limit": 100 \
      }, \
      "format": "json" \
    } \
  }'
```

--------------------------------

### POST /simulateTransaction - Simulate Smart Contract Execution

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Simulates a Soroban transaction without submitting it to the network. Returns resource estimates (CPU instructions, memory, fees), authorization requirements, and state changes. Essential for building production-ready transactions with accurate resource limits.

```APIDOC
## POST /simulateTransaction

### Description
Simulates a Soroban transaction without submitting it to the network. Returns resource estimates (CPU instructions, memory, fees), authorization requirements, and state changes. Essential for building production-ready transactions with accurate resource limits.

### Method
POST

### Endpoint
/simulateTransaction

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **jsonrpc** (string) - Required - JSON-RPC protocol version, must be "2.0".
- **id** (integer) - Required - A unique identifier for the request.
- **method** (string) - Required - The name of the method to call, must be "simulateTransaction".
- **params** (object) - Required - Parameters for the simulateTransaction method.
  - **transaction** (string) - Required - The base64-encoded transaction envelope to simulate.
  - **resourceConfig** (object) - Optional - Configuration for resource limits during simulation.
    - **instructionLeeway** (integer) - Optional - The amount of leeway to provide for instruction count.
  - **format** (string) - Optional - The desired format for the output, either "json" or "xdr". Defaults to "xdr" if not specified.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "simulateTransaction",
  "params": {
    "transaction": "AAAAAgAAAABv...base64_encoded_transaction_envelope...",
    "resourceConfig": {
      "instructionLeeway": 3000000
    },
    "format": "json"
  }
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - JSON-RPC protocol version.
- **id** (integer) - The identifier of the request.
- **result** (object) - The simulation results.
  - **transactionDataJSON** (object) - The JSON representation of the simulated transaction data.
  - **minResourceFee** (string) - The minimum resource fee required for the transaction.
  - **results** (array) - An array of results for each operation in the transaction.
    - **returnValueJSON** (object) - The JSON representation of the return value from a contract call.
    - **authJSON** (array) - The JSON representation of authorization requirements.
  - **stateChanges** (array) - An array of state changes that occurred during the simulation.
    - **type** (string) - The type of state change (e.g., "created", "updated", "deleted").
    - **keyJSON** (object) - The JSON representation of the ledger entry key that was changed.
    - **beforeJSON** (object) - The JSON representation of the ledger entry data before the change (if applicable).
    - **afterJSON** (object) - The JSON representation of the ledger entry data after the change (if applicable).

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "transactionDataJSON": {...},
    "minResourceFee": "100000",
    "results": [
      {
        "returnValueJSON": {"type": "i128", "value": "1000000"},
        "authJSON": [...] 
      }
    ],
    "stateChanges": [
      {
        "type": "created",
        "keyJSON": {...},
        "afterJSON": {...}
      }
    ]
  }
}
```
```

--------------------------------

### Query Ledger Metadata in a Range (Bash)

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Retrieves metadata for a range of ledgers using the getLedgers RPC method. This method can fetch data from both local and external datastores for historical ledger information.

```bash
curl -X POST "https://soroban-testnet.stellar.org" \
  -H "Content-Type: application/json" \
  -d '{ \
    "jsonrpc": "2.0", \
    "id": 1, \
    "method": "getLedgers", \
    "params": { \
      "startLedger": 1234500, \
      "pagination": { \
        "limit": 5 \
      }, \
      "format": "json" \
    } \
  }'
```

--------------------------------

### Rename Protocol Configuration Files

Source: https://github.com/stellar/stellar-rpc/blob/main/cmd/stellar-rpc/internal/integrationtest/infrastructure/docker/README.md

Automates the renaming of old protocol configuration files (JSON and XDR) to new protocol versions. This script is useful during Stellar protocol upgrades to update configuration files efficiently.

```bash
OLD=23 NEW=25; ls -1 *.p$OLD.* | awk '{printf $1 " " $1 "\n"}' | sed -E "s/p$OLD.(json|xdr)$/p$NEW.\1/" | xargs -n 2 mv $1 $2
```

--------------------------------

### Query Stellar Ledger Entries

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Fetches current ledger entries, including contract data and account balances, using their keys. This method supports up to 200 keys per request and can return results in XDR or JSON format, providing last modified ledger and TTL information for Soroban data.

```bash
# Query a contract instance ledger key
curl -X POST "https://soroban-testnet.stellar.org" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getLedgerEntries",
    "params": {
      "keys": [
        "AAAABgAAAAHvBi7m9cYbASoJKlxm0yfT+kxyG7Z7QoO4kWGI6T/nEgAAAA8AAAAJaW5zdGFuY2UAAAA="
      ],
      "format": "json"
    }
  }'
```

--------------------------------

### Simulate Soroban Transaction Execution

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Simulates a Soroban transaction without deploying it to the network. This function returns resource estimates (CPU, memory, fees), authorization requirements, and state changes, which are essential for creating production-ready transactions with accurate resource limits.

```bash
curl -X POST "https://soroban-testnet.stellar.org" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "simulateTransaction",
    "params": {
      "transaction": "AAAAAgAAAABv...base64_encoded_transaction_envelope...",
      "resourceConfig": {
        "instructionLeeway": 3000000
      },
      "format": "json"
    }
  }'
```

--------------------------------

### POST /getLedgerEntries - Query Ledger State

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Retrieves current ledger entries (contract data, account balances, etc.) by their keys. Supports up to 200 keys per request and returns results in either XDR or JSON format. Each entry includes its last modified ledger and TTL information for Soroban data.

```APIDOC
## POST /getLedgerEntries

### Description
Retrieves current ledger entries (contract data, account balances, etc.) by their keys. Supports up to 200 keys per request and returns results in either XDR or JSON format. Each entry includes its last modified ledger and TTL information for Soroban data.

### Method
POST

### Endpoint
/getLedgerEntries

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **jsonrpc** (string) - Required - JSON-RPC protocol version, must be "2.0".
- **id** (integer) - Required - A unique identifier for the request.
- **method** (string) - Required - The name of the method to call, must be "getLedgerEntries".
- **params** (object) - Required - Parameters for the getLedgerEntries method.
  - **keys** (array of strings) - Required - An array of ledger entry keys to retrieve.
  - **format** (string) - Optional - The desired format for the entry data, either "json" or "xdr". Defaults to "xdr" if not specified.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getLedgerEntries",
  "params": {
    "keys": [
      "AAAABgAAAAHvBi7m9cYbASoJKlxm0yfT+kxyG7Z7QoO4kWGI6T/nEgAAAA8AAAAJaW5zdGFuY2UAAAA="
    ],
    "format": "json"
  }
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - JSON-RPC protocol version.
- **id** (integer) - The identifier of the request.
- **result** (object) - The result of the ledger entry query.
  - **entries** (array) - An array of ledger entry objects.
    - **keyJSON** (object) - The JSON representation of the ledger entry key (if format is "json").
    - **dataJSON** (object) - The JSON representation of the ledger entry data (if format is "json").
    - **lastModifiedLedger** (integer) - The sequence number of the ledger where the entry was last modified.
    - **liveUntilLedgerSeq** (integer) - The sequence number until which the entry is valid (for Soroban data).
  - **latestLedger** (integer) - The sequence number of the latest ledger available on the server.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "entries": [
      {
        "keyJSON": {"type": "contractData", ...},
        "dataJSON": {...},
        "lastModifiedLedger": 1234560,
        "liveUntilLedgerSeq": 1300000
      }
    ],
    "latestLedger": 1234567
  }
}
```
```

--------------------------------

### getEvents

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Queries contract events with filtering by contract ID, event type, and topics. Supports pagination for processing large event sets. Event types include "contract", "system", and "diagnostic".

```APIDOC
## POST /getEvents

### Description
Queries contract events with filtering by contract ID, event type, and topics. Supports pagination.

### Method
POST

### Endpoint
https://soroban-testnet.stellar.org

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - JSON RPC version, must be "2.0".
- **id** (integer) - Required - A unique identifier for the request.
- **method** (string) - Required - The method name, must be "getEvents".
- **params** (object) - Required - Parameters for the method.
  - **startLedger** (integer) - Required - The starting ledger number for the query.
  - **filters** (array) - Optional - An array of filter objects.
    - **type** (string) - Required - The event type ("contract", "system", "diagnostic").
    - **contractIds** (array) - Optional - Array of contract IDs to filter by.
    - **topics** (array) - Optional - Array of topics to filter by.
  - **pagination** (object) - Optional - Pagination parameters.
    - **limit** (integer) - Optional - The maximum number of events to return per page.
    - **cursor** (string) - Optional - A cursor for fetching the next page of results.
  - **format** (string) - Optional - The desired response format, typically "json".

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getEvents",
  "params": {
    "startLedger": 1234500,
    "filters": [
      {
        "type": "contract",
        "contractIds": ["CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC"],
        "topics": [
          ["AAAADwAAAAh0cmFuc2Zlcg==", "*"]
        ]
      }
    ],
    "pagination": {
      "limit": 100
    },
    "format": "json"
  }
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - The JSON RPC version.
- **id** (integer) - The request ID.
- **result** (object) - The list of events.
  - **events** (array) - An array of event objects.
    - **type** (string) - The event type.
    - **ledger** (integer) - The ledger number.
    - **ledgerClosedAt** (string) - The ledger close time.
    - **contractId** (string) - The contract ID associated with the event.
    - **id** (string) - The unique event ID.
    - **topicJSON** (array) - The event topics.
    - **valueJSON** (object) - The event value.
    - **inSuccessfulContractCall** (boolean) - Indicates if the event occurred during a successful contract call.
    - **transactionHash** (string) - The hash of the transaction that emitted the event.
  - **cursor** (string) - A cursor for fetching the next page of results.
  - **latestLedger** (integer) - The latest ledger number.

### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "events": [
      {
        "type": "contract",
        "ledger": 1234505,
        "ledgerClosedAt": "2024-01-15T10:30:00Z",
        "contractId": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
        "id": "1234505-0-0",
        "topicJSON": [
          {"type": "symbol", "value": "transfer"},
          {"type": "address", "value": "GA..."}
        ],
        "valueJSON": {"type": "i128", "value": "1000000"},
        "inSuccessfulContractCall": true,
        "transactionHash": "abc123..."
      }
    ],
    "cursor": "1234505-0-0",
    "latestLedger": 1234567
  }
}
```
```

--------------------------------

### Query Multiple Transactions in a Ledger Range (Bash)

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Retrieves multiple transactions within a specified ledger range using the getTransactions RPC method. This method supports pagination, making it suitable for building transaction history explorers.

```bash
curl -X POST "https://soroban-testnet.stellar.org" \
  -H "Content-Type: application/json" \
  -d '{ \
    "jsonrpc": "2.0", \
    "id": 1, \
    "method": "getTransactions", \
    "params": { \
      "startLedger": 1234500, \
      "pagination": { \
        "limit": 10 \
      }, \
      "format": "json" \
    } \
  }'
```

--------------------------------

### Convert JSON to Base64 XDR using Stellar CLI

Source: https://github.com/stellar/stellar-rpc/blob/main/cmd/stellar-rpc/internal/integrationtest/infrastructure/docker/README.md

Converts a JSON configuration file into a base64 encoded XDR file using the `stellar xdr encode` command. This is a crucial step for applying configuration changes.

```bash
stellar xdr encode --type ConfigUpgradeSet < testnet.p23.json > testnet.p23.xdr
```

--------------------------------

### Retrieve Transaction by Hash from Stellar Network (Bash)

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Retrieves a specific transaction from the Stellar network using its hash via the getTransaction RPC method. The response includes the transaction envelope, result, metadata, and diagnostic events.

```bash
curl -X POST "https://soroban-testnet.stellar.org" \
  -H "Content-Type: application/json" \
  -d '{ \
    "jsonrpc": "2.0", \
    "id": 1, \
    "method": "getTransaction", \
    "params": { \
      "hash": "abc123def456789...", \
      "format": "json" \
    } \
  }'
```

--------------------------------

### getLedgers

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Retrieves ledger metadata for a range of ledgers. Supports fetching from both local database and external datastore for historical data beyond the retention window.

```APIDOC
## POST /getLedgers

### Description
Retrieves ledger metadata for a range of ledgers.

### Method
POST

### Endpoint
https://soroban-testnet.stellar.org

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - JSON RPC version, must be "2.0".
- **id** (integer) - Required - A unique identifier for the request.
- **method** (string) - Required - The method name, must be "getLedgers".
- **params** (object) - Required - Parameters for the method.
  - **startLedger** (integer) - Required - The starting ledger number for the query.
  - **pagination** (object) - Optional - Pagination parameters.
    - **limit** (integer) - Optional - The maximum number of ledgers to return per page.
    - **cursor** (string) - Optional - A cursor for fetching the next page of results.
  - **format** (string) - Optional - The desired response format, typically "json".

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getLedgers",
  "params": {
    "startLedger": 1234500,
    "pagination": {
      "limit": 5
    },
    "format": "json"
  }
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - The JSON RPC version.
- **id** (integer) - The request ID.
- **result** (object) - The list of ledger metadata.
  - **ledgers** (array) - An array of ledger metadata objects.
    - **sequence** (integer) - The ledger sequence number.
    - **hash** (string) - The hash of the ledger.
    - **prevHash** (string) - The hash of the previous ledger.
    - **closeTime** (integer) - The ledger close time.
    - **totalCoins** (string) - The total number of coins in circulation.
    - **feePool** (string) - The fee pool balance.
    - **baseFee** (integer) - The base fee for transactions in this ledger.
    - **baseReserve** (string) - The base reserve for accounts.
    - **maxTxSetSize** (integer) - The maximum number of transactions in the ledger.
  - **latestLedger** (integer) - The latest ledger number.
  - **cursor** (string) - A cursor for fetching the next page of results.

### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "ledgers": [
      {
        "sequence": 1234500,
        "hash": "...",
        "prevHash": "...",
        "closeTime": 1699899000,
        "totalCoins": "10000000000.0000000",
        "feePool": "100000.0000000",
        "baseFee": 100,
        "baseReserve": "10000000.0000000",
        "maxTxSetSize": 1000
      }
    ],
    "latestLedger": 1234567,
    "cursor": "..."
  }
}
```
```

--------------------------------

### Submit Transaction to Stellar Network (Bash)

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Submits a signed transaction envelope to the Stellar network using the sendTransaction RPC method. It returns the transaction hash and its submission status (e.g., PENDING, DUPLICATE, ERROR).

```bash
curl -X POST "https://soroban-testnet.stellar.org" \
  -H "Content-Type: application/json" \
  -d '{ \
    "jsonrpc": "2.0", \
    "id": 1, \
    "method": "sendTransaction", \
    "params": { \
      "transaction": "AAAAAgAAAABv...base64_encoded_signed_transaction...", \
      "format": "json" \
    } \
  }'
```

--------------------------------

### Check Stellar RPC Server Health Status

Source: https://context7.com/stellar/stellar-rpc/llms.txt

Retrieves the health status of the Stellar RPC server, including the latest and oldest ledger sequences within the retention window. This endpoint is crucial for monitoring and load balancer health checks.

```bash
curl -X POST "https://soroban-testnet.stellar.org" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getHealth"
  }'
```
Tokens:
Raw