getLedgerEntries

For reading the current value of ledger entries directly.

Allows you to directly inspect the current state of a contract, a contract's code, or any other ledger entry. This is a backup way to access your contract data which may not be available via events or simulateTransaction.

To fetch contract wasm byte-code, use the ContractCode ledger entry key.

Params

(1)

1. keys (required)

Array containing the keys of the ledger entries you wish to retrieve. (an array of serialized base64 strings)

array[string]

Array containing ledger keys.

Result

(getLedgerEntriesResult)

latestLedger

string

required

The latest ledger known to Soroban RPC at the time it handled the request.

entries

array[object]

Array of objects containing all found ledger entries

key

string

The key of the ledger entry (serialized in a base64 string).

xdr

string

The current value of the given ledger entry (serialized in a base64 string).

lastModifiedLedgerSeq

string

The ledger sequence number of the last time this entry was updated.

liveUntilLedgerSeq

string

Stringified sequence number of the ledger.

Examples

Example request to the getNetwork method for a Counter(Address) ledger entry.

Request

cURL
JavaScript
Python
JSON

curl -X POST \
-H 'Content-Type: application/json' \
-d '{
  "jsonrpc": "2.0",
  "id": 8675309,
  "method": "getLedgerEntries",
  "params": {
    "keys": [
      "AAAABgAAAAHMA/50/Q+w3Ni8UXWm/trxFBfAfl6De5kFttaMT0/ACwAAABAAAAABAAAAAgAAAA8AAAAHQ291bnRlcgAAAAASAAAAAAAAAAAg4dbAxsGAGICfBG3iT2cKGYQ6hK4sJWzZ6or1C5v6GAAAAAE="
    ]
  }
}' \
https://soroban-testnet.stellar.org:443 | jq

let requestBody = {
  "jsonrpc": "2.0",
  "id": 8675309,
  "method": "getLedgerEntries",
  "params": {
    "keys": [
      "AAAABgAAAAHMA/50/Q+w3Ni8UXWm/trxFBfAfl6De5kFttaMT0/ACwAAABAAAAABAAAAAgAAAA8AAAAHQ291bnRlcgAAAAASAAAAAAAAAAAg4dbAxsGAGICfBG3iT2cKGYQ6hK4sJWzZ6or1C5v6GAAAAAE="
    ]
  }
}
let res = await fetch('https://soroban-testnet.stellar.org', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(requestBody),
})
let json = await res.json()
console.log(json)

import json, requests
res = requests.post('https://soroban-testnet.stellar.org', json={
    "jsonrpc": "2.0",
    "id": 8675309,
    "method": "getLedgerEntries",
    "params": {
        "keys": [
            "AAAABgAAAAHMA/50/Q+w3Ni8UXWm/trxFBfAfl6De5kFttaMT0/ACwAAABAAAAABAAAAAgAAAA8AAAAHQ291bnRlcgAAAAASAAAAAAAAAAAg4dbAxsGAGICfBG3iT2cKGYQ6hK4sJWzZ6or1C5v6GAAAAAE="
        ]
    }
})
print(json.dumps(res.json(), indent=4))

{
  "jsonrpc": "2.0",
  "id": 8675309,
  "method": "getLedgerEntries",
  "params": {
    "keys": [
      "AAAABgAAAAHMA/50/Q+w3Ni8UXWm/trxFBfAfl6De5kFttaMT0/ACwAAABAAAAABAAAAAgAAAA8AAAAHQ291bnRlcgAAAAASAAAAAAAAAAAg4dbAxsGAGICfBG3iT2cKGYQ6hK4sJWzZ6or1C5v6GAAAAAE="
    ]
  }
}

Result

{
  "jsonrpc": "2.0",
  "id": 8675309,
  "result": {
    "entries": [
      {
        "key": "AAAAB+qfy4GuVKKfazvyk4R9P9fpo2n9HICsr+xqvVcTF+DC",
        "xdr": "AAAABgAAAAAAAAABzAP+dP0PsNzYvFF1pv7a8RQXwH5eg3uZBbbWjE9PwAsAAAAQAAAAAQAAAAIAAAAPAAAAB0NvdW50ZXIAAAAAEgAAAAAAAAAAIOHWwMbBgBiAnwRt4k9nChmEOoSuLCVs2eqK9Qub+hgAAAABAAAAAwAAAAw=",
        "lastModifiedLedgerSeq": "2552504"
      }
    ],
    "latestLedger": "2552990"
  }
}

Generating `keys` Parameters

The example above is querying a deployment of the increment example contract to find out what value is stored in the COUNTER ledger entry. This value can be derived using the following code snippets. You should be able to extrapolate from the provided examples how to get keys parameters for other types and values.

Python

note

If you are using the Python stellar_sdk to generate these keys, you will need to install the latest pre-release version of the SDK. This can be done like so:

pip install --upgrade --pre stellar-sdk

from stellar_sdk import xdr
from stellar_sdk.strkey  import StrKey
from stellar_sdk.soroban import Symbol

def get_ledger_key_symbol(contract_id: str, symbol_text: str) -> str:
  ledger_key = xdr.LedgerKey(
    type=xdr.LedgerEntryType.CONTRACT_DATA,
    contract_data=xdr.LedgerKeyContractData(
      contract_id=xdr.hash.Hash(StrKey.decode_contract(contract_id)),
      key=Symbol(symbol_text).to_xdr_sc_val(),
    ),
  )
  return ledger_key.to_xdr()

print(
  get_ledger_key_symbol(
    "CA3D5KRYM6CB7OWQ6TWYRR3Z4T7GNZLKERYNZGGA5SOAOPIFY6YQGAXE",
    "COUNTER"
  )
)

JavaScript

If you are using the JavaScript stellar-sdk to generate these keys, you will need to install the latest pre-release version of the SDK. This can be done like so:

yarn add stellar-sdk@beta

import { xdr, StrKey } from 'stellar-sdk';

const getLedgerKeySymbol = (contractId, symbolText) => {
  const ledgerKey = xdr.LedgerKey.contractData(
    new xdr.LedgerKeyContractData({
      contractId: StrKey.decodeContract(contractId),
      key: xdr.ScVal.scvSymbol(symbolText)
    })
  );
  return ledgerKey.toXDR('base64');
};

console.log(
  getLedgerKeySymbol(
    'CA3D5KRYM6CB7OWQ6TWYRR3Z4T7GNZLKERYNZGGA5SOAOPIFY6YQGAXE',
    'COUNTER'
  )
);

Requesting an Account

note

This functionality is included in the JavaScript stellar-sdk package as SorobanRpc.Server.getAccount(address).

Accounts are stored as ledger entries, so we can use this method to look up an account along with it's current sequence number.

import { xdr, Keypair, StrKey } from 'stellar-sdk'

const getLedgerKeyAccount = (address) => {
  const publicKey = StrKey.decodeEd25519PublicKey(address)
  const ledgerKey = xdr.LedgerKey.account(
    new xdr.LedgerKeyAccount({
      accountId: Keypair.fromPublicKey(publicKey).xdrPublicKey(),
    })
  )
  return ledgerKey.toXDR('base64')
}

console.log(getLedgerKeyAccount(
  'GCU5YE6IVBOEZ5LUU5N2NB55VPB5YZNFERT65SSTVXTNMS7IEQWXKBM2'
))

# OUTPUT: AAAAAAAAAACp3BPIqFxM9XSnW6aHvavD3GWlJGfuylOt5tZL6CQtdQ==

We then take our output from this function, and use it as the element in the keys array parameter in our call to the getLedgerEntries method.

{
  "jsonrpc": "2.0",
  "id": 8675309,
  "method": "getLedgerEntries",
  "params": {
    "keys": ["AAAAAAAAAACp3BPIqFxM9XSnW6aHvavD3GWlJGfuylOt5tZL6CQtdQ=="]
  }
}

And the response we get contains the LedgerEntryData with the current information about this account.

{
  "jsonrpc": "2.0",
  "id": 8675309,
  "result": {
    "entries":[
      {
        "key": "AAAAAAAAAACp3BPIqFxM9XSnW6aHvavD3GWlJGfuylOt5tZL6CQtdQ==",
        "xdr": "AAAAAAAAAACp3BPIqFxM9XSnW6aHvavD3GWlJGfuylOt5tZL6CQtdQAAABdIdugAAAAADAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAA",
        "lastModifiedLedgerSeq": "164303"
      }
    ],
    "latestLedger": "246819"
  }
}

We can then parse this result as an xdr.LedgerEntryData type.

const parsed = xdr.LedgerEntryData.fromXDR(
  'AAAAAAAAAACp3BPIqFxM9XSnW6aHvavD3GWlJGfuylOt5tZL6CQtdQAAABdIdugAAAAADAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAA',
  'base64'
)
console.log(parsed);

Requesting a Contract's Wasm Code

This can be a bit tricky to wrap your head around, but the conventions do make sense once you let it sink in.

In the previous examples, the COUNTER key was used as a LedgerKey while the incremented value was stored in a LedgerEntry. "Ledger Entry" is the relevant term to keep in mind during this discussion. That LedgerEntry was stored on the Stellar ledger, and was associated with a corresponding LedgerKey. LedgerKey: LedgerEntry works the same way you would think of almost any key: value storage system.

How Soroban Contract Deployment Works

When you deploy a contract, first the code is "installed" (i.e. it is uploaded onto the blockchain). This creates a LedgerEntry containing the Wasm byte-code, which is uniquely identified by its hash (that is, the hash of the uploaded code itself). Then, when the contract is "deployed," we create a LedgerEntry with a reference to that code's hash. So fetching the contract code is a two-step process:

First, we look up the contract itself, to see which code hash it is referencing.
Then, we can look up the raw Wasm byte-code using that hash.

Request the `LedgerKey` for the Contract Code

Python

from stellar_sdk import xdr
from stellar_sdk.strkey import StrKey

def get_ledger_key_contract_code(contract_id: str) -> str:
  ledger_key = xdr.LedgerKey(
    type=xdr.LedgerEntryType.CONTRACT_DATA,
    contract_data=xdr.LedgerKeyContractData(
      contract_id=xdr.Hash(StrKey.decodeContract(contract_id)),
      key=xdr.SCVal(
        type=xdr.SCValType.SCV_LEDGER_KEY_CONTRACT_EXECUTABLE,
      ),
    ),
  )
  return ledger_key.to_xdr()

print(
  get_ledger_key_contract_code(
    "CA3D5KRYM6CB7OWQ6TWYRR3Z4T7GNZLKERYNZGGA5SOAOPIFY6YQGAXE"
  )
)
# OUTPUT: AAAABq+aJSfjs7VXHWOwJGujK30xpTI3Zt98YN/As+O6b98jAAAAFA==

JavaScript

import { Address, xdr } from 'stellar-sdk';

function getLedgerKeyContractCode(contractId) {
  const [ _, instance ] = new ContractId(contractId).getFootprint();
  return instance.toXDR('base64');
}

console.log(
  getLedgerKeyContractCode(
    "CA3D5KRYM6CB7OWQ6TWYRR3Z4T7GNZLKERYNZGGA5SOAOPIFY6YQGAXE"
  )
)
// OUTPUT: AAAABq+aJSfjs7VXHWOwJGujK30xpTI3Zt98YN/As+O6b98jAAAAFA==

We then take our output from this function, and use it as the element in the keys array parameter in our call to the getLedgerEntries method.

{
  "jsonrpc": "2.0",
  "id": 8675309,
  "method": "getLedgerEntries",
  "params": {
    "keys": [
      "AAAABq+aJSfjs7VXHWOwJGujK30xpTI3Zt98YN/As+O6b98jAAAAFA=="
    ]
  }
}

And the response we get contains the LedgerEntryData that can be used to find the hash we must use to request the Wasm byte-code. This hash is the LedgerKey that's been associated with the deployed contract code.

{
  "jsonrpc": "2.0",
  "id": 8675309,
  "result": {
    "entries": [
      {
        "key": "AAAABq+aJSfjs7VXHWOwJGujK30xpTI3Zt98YN/As+O6b98jAAAAFA==",
        "xdr": "AAAABq+aJSfjs7VXHWOwJGujK30xpTI3Zt98YN/As+O6b98jAAAAFAAAABIAAAAAZBYoEJT3IaPMMk3FoRmnEQHoDxewPZL+Uor+xWI4uII=",
        "lastModifiedLedgerSeq": "261603"
      }
    ],
    "latestLedger": "262322"
  }
}

Request the `ContractCode` Using the Retrieved `LedgerKey`

Now take the xdr field from the previous response's result object, and create a LedgerKey from the hash contained inside.

Python

from stellar_sdk import xdr

def get_ledger_key_wasm_id(contract_code_ledger_entry_data: str) -> str:
    # First, we dig the wasm_id hash out of the xdr we received from RPC
    contract_code_wasm_hash = xdr.LedgerEntryData.from_xdr(
        contract_code_ledger_entry_data
    ).contract_data.val.exec.wasm_id.hash
    # Now, we can create the `LedgerKey` as we've done in previous examples
    ledger_key = xdr.LedgerKey(
        type=xdr.LedgerEntryType.CONTRACT_CODE,
        contract_code=xdr.LedgerKeyContractCode(
            hash=xdr.hash.Hash(contract_code_wasm_hash)
        ),
    )
    return ledger_key.to_xdr()

print(
    get_ledger_key_wasm_id(
        "AAAABq+aJSfjs7VXHWOwJGujK30xpTI3Zt98YN/As+O6b98jAAAAFAAAABIAAAAAZBYoEJT3IaPMMk3FoRmnEQHoDxewPZL+Uor+xWI4uII="
    )
)
# OUTPUT: AAAAB2QWKBCU9yGjzDJNxaEZpxEB6A8XsD2S/lKK/sViOLiC

JavaScript

const { xdr } = require("soroban-client");

function getLedgerKeyWasmId(contractCodeLedgerEntryData) {
  const entry = xdr.LedgerEntryData.fromXDR(
    contractCodeLedgerEntryData,
    "base64"
  );

  const instance = entry.contractData().val().instance();

  let ledgerKey = xdr.LedgerKey.contractCode(
    new xdr.LedgerKeyContractCode({
      hash: instance.wasmHash()
    })
  );

  return ledgerKey.toXDR('base64');
}

console.log(
  getLedgerKeyWasmId(
    "AAAABq+aJSfjs7VXHWOwJGujK30xpTI3Zt98YN/As+O6b98jAAAAFAAAABIAAAAAZBYoEJT3IaPMMk3FoRmnEQHoDxewPZL+Uor+xWI4uII="
  )
)
// OUTPUT: AAAAB2QWKBCU9yGjzDJNxaEZpxEB6A8XsD2S/lKK/sViOLiC

Now, finally we have a LedgerKey that correspond to the Wasm byte-code that has been deployed under the ContractId we started out with so very long ago. This LedgerKey can be used in a final request to the Soroban-RPC endpoint.

{
  "jsonrpc": "2.0",
  "id": 8675309,
  "method": "getLedgerEntries",
  "params": {
    "keys": ["AAAAB2QWKBCU9yGjzDJNxaEZpxEB6A8XsD2S/lKK/sViOLiC"]
  }
}

And the response we get contains (even more) LedgerEntryData that we can decode and parse to get the actual, deployed, real-life contract byte-code. We'll leave that exercise up to you. You can check out what is contained using the "View XDR" page of the Stellar Laboratory.

{
  "jsonrpc": "2.0",
  "id": 8675309,
  "result": {
    "entries": [
      {
        "key": "AAAAB2QWKBCU9yGjzDJNxaEZpxEB6A8XsD2S/lKK/sViOLiC",
        "xdr": "AAAABwAAAABkFigQlPcho8wyTcWhGacRAegPF7A9kv5Siv7FYji4ggAAAlQAYXNtAQAAAAEPA2ACfn4BfmABfgF+YAAAAgcBAXYBRwAAAwQDAQICBQMBABEGGQN/AUGAgMAAC38AQYWAwAALfwBBkIDAAAsHMQUGbWVtb3J5AgAFaGVsbG8AAQFfAAMKX19kYXRhX2VuZAMBC19faGVhcF9iYXNlAwIK4QID1gIDAn8CfgF/I4CAgIAAQSBrIgEkgICAgAACQAJAIACnQf8BcSICQQ5GDQAgAkHKAEcNAQtCACEDQXshAgNAAkACQAJAAkAgAkUNAEIBIQQgAkGFgMCAAGotAAAiBUHfAEYNAyAFrSEEIAVBUGpBCkkNAiAFQb9/akEaSQ0BAkAgBUGff2pBGk8NACAEQkV8IQQMBAsQgoCAgAAACyABIAA3AwggASADQgiGQg6ENwMAQQAhAgNAAkAgAkEQRw0AQQAhAgJAA0AgAkEQRg0BIAFBEGogAmogASACaikDADcDACACQQhqIQIMAAsLIAFBEGqtQiCGQgSEQoSAgIAgEICAgIAAIQQgAUEgaiSAgICAACAEDwsgAUEQaiACakICNwMAIAJBCGohAgwACwsgBEJLfCEEDAELIARCUnwhBAsgAkEBaiECIAQgA0IGhoQhAwwACwsAAAsEAAAACwIACwsOAQBBgIDAAAsFSGVsbG8AHhFjb250cmFjdGVudm1ldGF2MAAAAAAAAAAUAAAAJQBDDmNvbnRyYWN0c3BlY3YwAAAAAAAAAAAAAAAFaGVsbG8AAAAAAAABAAAAAAAAAAJ0bwAAAAAAEQAAAAEAAAPqAAAAEQ==",
        "lastModifiedLedgerSeq": "75206",
        "liveUntilLedgerSeq": "320384"
      }
    ],
    "latestLedger": "262384"
  }
}

getLedgerEntries

Params

1. keys (required)

Result

Examples

Request

Result

Generating keys Parameters​

Python​

JavaScript​

Requesting an Account​

Requesting a Contract's Wasm Code​

How Soroban Contract Deployment Works​

Request the LedgerKey for the Contract Code​

Python​

JavaScript​

Request the ContractCode Using the Retrieved LedgerKey​

Python​

JavaScript​

Generating `keys` Parameters

Python

JavaScript

Requesting an Account

Requesting a Contract's Wasm Code

How Soroban Contract Deployment Works

Request the `LedgerKey` for the Contract Code

Python

JavaScript

Request the `ContractCode` Using the Retrieved `LedgerKey`

Python

JavaScript