Line data    Source code

       1             : #ifndef HEADER_fd_src_flamenco_runtime_fd_hashes_h
       2             : #define HEADER_fd_src_flamenco_runtime_fd_hashes_h
       3             : 
       4             : #include "../fd_flamenco_base.h"
       5             : #include "../types/fd_types.h"
       6             : #include "../../ballet/lthash/fd_lthash.h"
       7             : 
       8             : /* fd_hashes.h provides functions for computing and updating the bank hash
       9             :    for a completed slot.  The bank hash is a cryptographic hash of the
      10             :    slot's state including all account modifications and transaction
      11             :    signatures.
      12             : 
      13             :    The bank hash is computed as:
      14             :      sha256( sha256( prev_bank_hash || signature_count || last_blockhash ) || lthash )
      15             : 
      16             :    Where:
      17             :    - lthash is the cumulative lattice hash of all accounts
      18             :    - prev_bank_hash is the bank hash of the parent slot
      19             :    - last_blockhash is the last proof-of-history blockhash
      20             :    - signature_count is the number of signatures processed in the slot
      21             : 
      22             :    To compute the lthash, whenever any account is modified during transaction
      23             :    execution, we must remove the old version of the account hash from the
      24             :    cumulative lthash, hash the account, and add the new hash to the lthash.
      25             : */
      26             : 
      27             : 
      28             : FD_PROTOTYPES_BEGIN
      29             : 
      30             : /* fd_hashes_account_lthash computes the lattice hash (lthash) of a
      31             :    single account for use in the bank hash calculation.  The lthash is a
      32             :    cryptographic hash that supports incremental updates via addition and
      33             :    subtraction operations.
      34             : 
      35             :    For accounts with non-zero lamports, the hash is computed as:
      36             :      blake3( lamports || data || executable || owner || pubkey )
      37             : 
      38             :    For accounts with zero lamports, the hash is zero (these accounts are
      39             :    excluded from the bank hash).
      40             : 
      41             :    pubkey points to the account's public key (32 bytes).  account points
      42             :    to the account metadata containing lamports, data length, executable
      43             :    flag, and owner.  data points to the account data of size
      44             :    account->dlen bytes.  lthash_out points to where the computed lthash
      45             :    value will be written (FD_LTHASH_LEN_BYTES).
      46             : 
      47             :    On return, lthash_out contains the computed lthash.  For zero-lamport
      48             :    accounts, lthash_out will be zeroed via fd_lthash_zero.
      49             : 
      50             :    This function assumes all pointers are valid and properly aligned.
      51             :    The account data pointer must be readable for account->dlen bytes. */
      52             : 
      53             : void
      54             : fd_hashes_account_lthash( fd_pubkey_t const       * pubkey,
      55             :                           fd_account_meta_t const * account,
      56             :                           uchar const             * data,
      57             :                           fd_lthash_value_t *       lthash_out );
      58             : 
      59             : /* fd_hashes_account_lthash_simple is functionally the same as
      60             :    fd_hashes_account_lthash, but with simpler arguments that detail
      61             :    the exact parameters that go into the lthash.
      62             : 
      63             :    pubkey points to the account's public key (32 bytes).  owner points
      64             :    to the account's owner (32 bytes).  lamports is the account's
      65             :    lamports.  executable is the account's executable flag.  data points
      66             :    to the account data.  data_len is the length of the account data.
      67             :    lthash_out points to where the computed lthash value will be written
      68             :    (2048 bytes).
      69             : 
      70             :    On return, lthash_out contains the computed lthash.  This function
      71             :    assumes all pointers are valid and properly aligned.  The account
      72             :    data pointer must be readable for data_len bytes. */
      73             : void
      74             : fd_hashes_account_lthash_simple( uchar const         pubkey[ static FD_HASH_FOOTPRINT ],
      75             :                                  uchar const         owner[ static FD_HASH_FOOTPRINT ],
      76             :                                  ulong               lamports,
      77             :                                  uchar               executable,
      78             :                                  uchar const *       data,
      79             :                                  ulong               data_len,
      80             :                                  fd_lthash_value_t * lthash_out );
      81             : 
      82             : /* fd_hashes_update_lthash updates the bank's incremental lthash when an
      83             :    account is modified during transaction execution.  The bank lthash is
      84             :    maintained incrementally by subtracting the old account hash and
      85             :    adding the new account hash.
      86             : 
      87             :    meta is a pointer to the modified account's metadata and data.
      88             :    prev_hash contains the lthash of the account before modification (or
      89             :    zero for newly created accounts).  bank is the bank whose lthash
      90             :    should be updated.  capture_ctx is an optional capture context for
      91             :    recording account changes (can be NULL).
      92             : 
      93             :    This function:
      94             :    - Acquires a write lock on the bank's lthash
      95             :    - Subtracts prev_hash from the bank lthash
      96             :    - Computes the new account hash
      97             :    - Adds the new hash to the bank lthash
      98             :    - Releases the lock
      99             :    - If capture_ctx is provided, writes the account state to the capture
     100             : 
     101             :    On capture write failure, the function will FD_LOG_ERR and terminate.
     102             :    The function assumes all non-optional pointers are valid.
     103             : 
     104             :    IMPORTANT: fd_hashes_update_lthash, or fd_hashes_update_lthash_from_funk,
     105             :    must be called whenever an account is modified during transaction
     106             :    execution. This includes sysvar accounts. */
     107             : 
     108             : void
     109             : fd_hashes_update_lthash1( fd_lthash_value_t *       lthash_post, /* out */
     110             :                           fd_lthash_value_t const * lthash_prev, /* in */
     111             :                           fd_pubkey_t const *       pubkey,
     112             :                           fd_account_meta_t const * meta,
     113             :                           fd_bank_t               * bank,
     114             :                           fd_capture_ctx_t        * capture_ctx );
     115             : 
     116             : FD_FN_UNUSED static void
     117             : fd_hashes_update_lthash( fd_pubkey_t const *       pubkey,
     118             :                          fd_account_meta_t const * meta,
     119             :                          fd_lthash_value_t const * prev_account_hash,
     120             :                          fd_bank_t               * bank,
     121         645 :                          fd_capture_ctx_t        * capture_ctx ) {
     122         645 :   fd_lthash_value_t post[1];
     123         645 :   fd_hashes_update_lthash1( post, prev_account_hash, pubkey, meta, bank, capture_ctx );
     124         645 : }
     125             : 
     126             : /* fd_hashes_hash_bank computes the bank hash for a completed slot.  The
     127             :    bank hash is a deterministic hash of the slot's state including all
     128             :    account modifications and transaction signatures.
     129             : 
     130             :    The hash is computed as:
     131             :      sha256( sha256( prev_bank_hash || signature_count || last_blockhash ) || lthash )
     132             : 
     133             :    Where:
     134             :    - lthash is the cumulative lattice hash of all accounts
     135             :    - prev_bank_hash is the bank hash of the parent slot
     136             :    - last_blockhash is the last proof-of-history blockhash
     137             :    - signature_count is the number of signatures processed in the slot
     138             : 
     139             :    The resulting bank hash is written to hash_out.
     140             : */
     141             : 
     142             : void
     143             : fd_hashes_hash_bank( fd_lthash_value_t const * lthash,
     144             :                      fd_hash_t const *        prev_bank_hash,
     145             :                      fd_hash_t const *        last_blockhash,
     146             :                      ulong                    signature_count,
     147             :                      fd_hash_t *              hash_out );
     148             : 
     149             : FD_PROTOTYPES_END
     150             : 
     151             : #endif /* HEADER_fd_src_flamenco_runtime_fd_hashes_h */