Contract Execution Receipts

Every successful ContractCall transaction produces a ContractExecutionReceipt — a persistent record stored in redb that survives node restarts. Receipts capture what happened inside the execution: which entrypoint ran, what arguments were passed, what the contract returned, the effects summary, and the cost breakdown.

Simulation (dry-run) calls do not generate receipts.

Endpoints

List receipts for a contract

GET /api/contracts/:contract_id/receipts

Query parameters:

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | entrypoint | string | — | Filter by entrypoint name | | from_block | u64 | 0 | Inclusive lower bound on block height | | to_block | u64 | ∞ | Inclusive upper bound on block height | | limit | usize | 50 | Max results (hard cap 500) | | offset | usize | 0 | Skip first N matching results |

Response:

{
  "status": "ok",
  "contract_id": "loan-001",
  "count": 2,
  "receipts": [
    {
      "tx_id": "abc123...",
      "contract_id": "loan-001",
      "entrypoint": "originate",
      "args": [{ "type": "u64", "value": "500000" }],
      "returns": [],
      "effects_summary": {
        "move_count": 0,
        "post_count": 1,
        "write_count": 2,
        "delete_count": 0,
        "emit_count": 1,
        "operation_kinds": ["loan_origination"]
      },
      "cost": {
        "total_cost_units": 14,
        "storage_reads": 2,
        "storage_writes": 2,
        "storage_deletes": 0,
        "event_emits": 1,
        "move_ops": 0,
        "post_ops": 1
      },
      "block_height": 42,
      "timestamp": 1700000000
    }
  ]
}

Get receipt for a transaction

GET /api/transactions/:tx_id/receipt

Returns the single receipt associated with a tx_id, or null if the transaction was not a ContractCall (or the receipt was not yet persisted).

Response:

{
  "status": "ok",
  "receipt": {
    "tx_id": "abc123...",
    "contract_id": "loan-001",
    "entrypoint": "originate",
    ...
  }
}

When no receipt exists for the given tx_id:

{
  "status": "ok",
  "receipt": null
}

Storage

Receipts are persisted in receipts.redb inside the node's data directory. Two redb tables are maintained:

| Table | Key | Value | Purpose | |-------|-----|-------|---------| | receipts_by_tx | tx_id | serialized receipt (JSON bytes) | O(1) lookup by transaction hash | | receipts_by_contract | "{contract_id}\x00{block_height:020}\x00{tx_id}" | tx_id | Range scan by contract and block range |

The zero-padded 20-digit block height in the secondary key ensures lexicographic order matches numeric block order, enabling efficient block-range queries.

Persistence is asynchronous (via an mpsc channel + background worker, consistent with KYC persistence). If the queue is full, the node falls back to a synchronous insert so no receipt is silently dropped.

effects_summary fields

| Field | Description | |-------|-------------| | move_count | Number of balance transfer effects | | post_count | Number of accounting posting effects | | write_count | Number of contract storage writes | | delete_count | Number of contract storage deletes | | emit_count | Number of events emitted | | operation_kinds | Distinct operation kind names (snake_case) from all posts |

See Operation Kind Catalog for the full list of valid operation_kinds values.

cost fields

| Field | Description | |-------|-------------| | total_cost_units | Sum of all cost contributions | | storage_reads | Number of contract storage reads | | storage_writes | Number of contract storage writes | | storage_deletes | Number of contract storage deletes | | event_emits | Number of events emitted | | move_ops | Number of balance move operations | | post_ops | Number of posting operations |