Saltar al contenido principal

Contract Data Snapshot

Table Metadata​

PropertyConfiguration
Natural Key(s)contract_id, ledger_key_hash, valid_from
Partition Field(s)valid_to (MONTH partition)
Clustered Field(s)contract_id, ledger_key_hash
Documentationdbt docs

Column Details​

NameDescriptionData TypeDomain ValuesRequired?Notes
contract_idSoroban contract id.STRINGYes
contract_key_typeContract key type which is an ScVal.STRINGScValTypeScvContractInstance, ScValTypeScvLedgerKeyContractInstance, ScValTypeScvLedgerKeyNonceNo
contract_durabilityContract can either be temporary or persistent.STRINGNo
asset_codeThe 4 or 12 character code representation of the asset on the network.STRINGNoAsset codes have no guarantees of uniqueness. The combination of asset code, issuer and type represents a distinct asset.
asset_issuerThe account address of the original asset issuer that created the asset.STRINGNo
asset_typeThe identifier for type of asset code, can be alphanumeric (4 or 12 characters) or the native asset to the network, XLM.STRINGnative, alphanum4, alphanum12NoXLM is the native asset. XLM has no asset code or issuer and is displayed with asset type = 'native'.
balance_holderThe address/account that holds the balance of the asset in contract data.STRINGNo
balanceThe number of units of XLM held by the account.STRINGNoThe accounts table only reports balances for XLM. Any other asset class is reported in trust_lines.
last_modified_ledgerThe ledger sequence number when the ledger entry was last modified.INTEGERYesNatural Key. Cluster Field. Deletion does not count as modification.
ledger_entry_changeCode describing the ledger entry change type applied.INTEGER
  • 0 - Ledger Entry Created
  • 1 - Ledger Entry Updated
  • 2 - Ledger Entry Deleted
  • 3 - Ledger Entry State (value of the entry)
YesNot every entry can be updated. Updates not valid for claimable balances.
ledger_sequenceINTEGERYes
ledger_key_hashSTRINGYes
keyThe encoded key used to identify a specific piece of contract data. Has two components: type and value.JSONNo
key_decodedThe human-readable/decoded version of the key.JSONNo
valThe encoded value associated with the key in the contract data. Has two components: type and value.JSONNo
val_decodedThe human-readable/decoded version of the value.JSONNo
contract_data_xdrThe XDR (External Data Representation) encoding of the contract data.STRINGNoXDR ensures interoperability across systems.
closed_atTimestamp in UTC when this ledger closed and committed.TIMESTAMPYesLedgers close ~every 5 seconds.
deletedIndicates whether the ledger entry has been deleted.BOOLEANYesOnce deleted, cannot be recovered. History is maintained.
batch_idString representation of the run id for a given DAG in Airflow. Takes the form of "scheduled__<batch_end_date>-<dag_alias>". Batch ids are unique to the batch and help with monitoring and rerun capabilitiesstringYes
batch_run_dateThe start date for the batch interval.DATETIMEYesProxy for closed_at for a ledger.
batch_insert_tsThe timestamp in UTC when a batch of records was inserted.TIMESTAMPYesFor data engineering purposes, not ad hoc analysis.
airflow_start_tsThe timestamp when the airflow job starts.STRINGNoUsed to detect backfill jobs.
valid_fromThe timestamp when this snapshot row was first inserted and became effective.TIMESTAMPYesTracks changes over time.
valid_toThe timestamp when this row is no longer valid.TIMESTAMPNoIf null, the setting is currently active.

Example Business Questions​

  1. Point-in-time query (balance/value as of a given date)
SELECT contract_id, ledger_key_hash, val_decoded
FROM `crypto-stellar.snapshots.contract_data_snapshot`
WHERE contract_id = 'C123'
AND ledger_key_hash = 'abc123'
DATE('2025-02-10') BETWEEN DATE(valid_from) AND COALESCE(DATE(valid_to), '9999-12-31')
LIMIT 100
  1. All active contracts (latest state only)
SELECT contract_id, ledger_key_hash, val_decoded, balance, contract_durability
FROM `crypto-stellar.snapshots.contract_data_snapshot`
WHERE valid_to IS NULL
LIMIT 100
  1. Recent updates
SELECT contract_id, ledger_key_hash, closed_at, ledger_entry_change
FROM `crypto-stellar.snapshots.contract_data_snapshot`
WHERE closed_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 2 DAY)
LIMIT 100