Line data    Source code

       1             : #ifndef HEADER_fd_src_flamenco_capture_fd_solcap_proto_h
       2             : #define HEADER_fd_src_flamenco_capture_fd_solcap_proto_h
       3             : 
       4             : #include "../types/fd_types.h"
       5             : #include "../../util/net/fd_pcapng_private.h"
       6             : #include <stdbool.h>
       7             : 
       8             : /* fd_solana_account_meta_t is the metadata for a Solana account */
       9             : struct __attribute__((packed)) fd_solana_account_meta {
      10             :   ulong lamports;
      11             :   uchar owner[32];
      12             :   uchar executable;
      13             :   uchar padding[3];
      14             : };
      15             : typedef struct fd_solana_account_meta fd_solana_account_meta_t;
      16             : 
      17             : static inline fd_solana_account_meta_t* fd_solana_account_meta_init(
      18             :     fd_solana_account_meta_t* meta, ulong lamports, void const* owner,
      19           0 :     int exec_bit) {
      20           0 :   meta->lamports = lamports;
      21           0 :   fd_memcpy(meta->owner, owner, sizeof(fd_pubkey_t));
      22           0 :   meta->executable = !!exec_bit;
      23           0 :   return meta;
      24           0 : }
      25             : 
      26             : /* fd_solcap_proto defines the capture of "solcap" data.
      27             : 
      28             :    It is built as a PCapNG format, adhering completely to specification.
      29             : 
      30             :    .solcap is a format for capturing Solana runtime data suitable for
      31             :    replay and debugging. The format is described below:
      32             : 
      33             : 
      34             :    [Section Header Block (file header) ]
      35             :    [Interface Description Block (IDB, linktype=147, snaplen=0) ]
      36             :    [Enhanced Packet Block #1 (interface_id=0)]
      37             :       -- payload start: fd_solcap_chunk_int_hdr
      38             :       -- payload rest: packet data (solcap custom format)
      39             :    [Enhanced Packet Block #2]
      40             :       -- ...
      41             : 
      42             :    The solcap format is built as the pcapng format, allowing for easy
      43             :    interoperability with existing tools that support pcapng. The format
      44             :    of the chunk headers is determined by the pcapng packet blocks.
      45             :    See https://pcapng.com/ for more information.
      46             : 
      47             :    Section Header Block (SHB) - The file header.
      48             :    Interface Description Block (IDB) - The header of the interface.
      49             : 
      50             :    Enhanced Packet Block (EPB) - A single solcap message.
      51             :    The internal chunk header contains additional metadata about the
      52             :    message, used for identifying the message and its position in the
      53             :    stream.
      54             : 
      55             :       There can be a variety of messages within the EPB blocks, each
      56             :       differentiated via an internal chunk header. This internal chunk
      57             :       header allows for the reader to process the message in the correct
      58             :       encoding scheme. Currently the list of messages is:
      59             :       - Account Updates
      60             :       - Bank Preimages
      61             : 
      62             :       The dumping of the exectuion can be done in multiple ways:
      63             :          1. To a 'capture link' which is read by a solcap tile and then
      64             :          subsequently written to a file. This is the default when running
      65             :          firedancer live or a subcommand that uses a topo (backtest).
      66             : 
      67             :          2. To a file directly. This is currently used for block harnesses.
      68             :          The neccessity of this path is for the single threaded execution
      69             :          mode of the harness.
      70             : */
      71             : 
      72           0 : #define SOLCAP_WRITE_ACCOUNT        (1UL)
      73           0 : #define SOLCAP_WRITE_BANK_PREIMAGE  (2UL)
      74           0 : #define SOLCAP_STAKE_ACCOUNT_PAYOUT (3UL)
      75           0 : #define SOLCAP_STAKE_REWARD_EVENT   (4UL)
      76           0 : #define SOLCAP_STAKE_REWARDS_BEGIN  (5UL)
      77             : 
      78             : struct __attribute__((packed)) fd_solcap_buf_msg {
      79             :   ushort sig;
      80             :   ulong  slot;
      81             :   ulong  txn_idx;
      82             :   /* Data follows immediately after this struct in memory */
      83             : };
      84             : typedef struct fd_solcap_buf_msg fd_solcap_buf_msg_t;
      85             : 
      86             : /* FD_SOLCAP_V2_FILE_MAGIC identifies a solcap version 2 file. */
      87             : 
      88             : #define FD_SOLCAP_V1_FILE_MAGIC       (0x806fe7581b1da4b7UL) /* deprecated */
      89             : #define FD_SOLCAP_V2_FILE_MAGIC       FD_PCAPNG_BLOCK_TYPE_SHB /* 0x0A0D0D0A */
      90             : #define FD_SOLCAP_V2_BYTE_ORDER_MAGIC FD_PCAPNG_BYTE_ORDER_MAGIC /* 0x1A2B3C4D */
      91             : 
      92             : /* Solcap uses standard PCapNG structures for file framing:
      93             :    - fd_pcapng_shb_t: Section Header Block (file header)
      94             :    - fd_pcapng_idb_t: Interface Description Block
      95             :    - fd_pcapng_epb_t: Enhanced Packet Block (wraps each message)
      96             : 
      97             :    These are defined in fd_pcapng_private.h and provide correct
      98             :    PCapNG compatibility for interoperability with standard tools.
      99             : */
     100             : 
     101             : /* PCapNG block type constants for solcap */
     102             : #define SOLCAP_PCAPNG_BLOCK_TYPE_IDB FD_PCAPNG_BLOCK_TYPE_IDB /* 1 */
     103             : #define SOLCAP_PCAPNG_BLOCK_TYPE_EPB FD_PCAPNG_BLOCK_TYPE_EPB /* 6 */
     104           0 : #define SOLCAP_IDB_HDR_LINK_TYPE     147 /* DLT_USER(0) */
     105           0 : #define SOLCAP_IDB_HDR_SNAP_LEN      0   /* unlimited */
     106             : 
     107             : /* fd_solcap_chunk_int_hdr: Internal chunk header (muxing layer)
     108             : 
     109             :    This header immediately follows the fd_pcapng_epb_t header within
     110             :    each Enhanced Packet Block. It serves as the muxing layer that
     111             :    identifies which type of solcap message follows via the block_type
     112             :    field, and provides temporal context (slot) and ordering (txn_idx).
     113             : */
     114             : 
     115             : struct __attribute__((packed)) fd_solcap_chunk_int_hdr {
     116             :    /* 0x00 */ uint block_type; /* Message type (SOLCAP_WRITE_*) */
     117             :    /* 0x04 */ uint slot; /* Solana slot number */
     118             :    /* 0x08 */ ulong txn_idx; /* Transaction index within slot */
     119             : };
     120             : typedef struct fd_solcap_chunk_int_hdr fd_solcap_chunk_int_hdr_t;
     121             : /*
     122             :    The following structures are the solcap messages that can be encoded.
     123             :    They are used by the runtime to write messages to the shared buffer
     124             :    and written to the file.
     125             : */
     126             : struct __attribute__((packed)) fd_solcap_account_update_hdr {
     127             :    fd_pubkey_t key;
     128             :    fd_solana_account_meta_t info; /* TODO: merge into solcap remove from types.json in future */
     129             :    ulong data_sz;
     130             : };
     131             : typedef struct fd_solcap_account_update_hdr fd_solcap_account_update_hdr_t;
     132             : 
     133             : struct __attribute__((packed))fd_solcap_bank_preimage {
     134             :    fd_hash_t bank_hash;
     135             :    fd_hash_t prev_bank_hash;
     136             :    fd_hash_t accounts_lt_hash_checksum;
     137             :    fd_hash_t poh_hash;
     138             :    ulong     signature_cnt;
     139             : };
     140             : typedef struct fd_solcap_bank_preimage fd_solcap_bank_preimage_t;
     141             : 
     142             : struct __attribute__((packed)) fd_solcap_stake_rewards_begin {
     143             :    ulong   payout_epoch;
     144             :    ulong   reward_epoch;
     145             :    ulong   inflation_lamports;
     146             :    ulong   total_points;
     147             : };
     148             : typedef struct fd_solcap_stake_rewards_begin fd_solcap_stake_rewards_begin_t;
     149             : 
     150             : struct __attribute__((packed)) fd_solcap_stake_reward_event {
     151             :    fd_pubkey_t stake_acc_addr;
     152             :    fd_pubkey_t vote_acc_addr;
     153             :    uint        commission;
     154             :    long        vote_rewards;
     155             :    long        stake_rewards;
     156             :    long        new_credits_observed;
     157             : };
     158             : typedef struct fd_solcap_stake_reward_event fd_solcap_stake_reward_event_t;
     159             : 
     160             : struct __attribute__((packed)) fd_solcap_stake_account_payout {
     161             :    fd_pubkey_t stake_acc_addr;
     162             :    ulong       update_slot;
     163             :    ulong       lamports;
     164             :    long        lamports_delta;
     165             :    ulong       credits_observed;
     166             :    long        credits_observed_delta;
     167             :    ulong       delegation_stake;
     168             :    long        delegation_stake_delta;
     169             : };
     170             : typedef struct fd_solcap_stake_account_payout fd_solcap_stake_account_payout_t;
     171             : 
     172             : #endif /* HEADER_fd_src_flamenco_capture_fd_solcap_proto_h */