Line data    Source code

       1             : #ifndef HEADER_fd_src_flamenco_snapshot_fd_snapshot_create_h
       2             : #define HEADER_fd_src_flamenco_snapshot_fd_snapshot_create_h
       3             : 
       4             : /* fd_snapshot_create.h provides APIs for creating a Agave-compatible
       5             :    snapshot from a slot execution context. */
       6             : 
       7             : #include "fd_snapshot_base.h"
       8             : #include "../runtime/fd_runtime_init.h"
       9             : #include "../runtime/fd_txncache.h"
      10             : #include "../../util/archive/fd_tar.h"
      11             : #include "../types/fd_types.h"
      12             : 
      13           0 : #define FD_BLOCKHASH_QUEUE_SIZE           (300UL)
      14           0 : #define FD_TICKS_PER_SLOT                 (64UL)
      15             : 
      16             : #define FD_SNAPSHOT_DIR_MAX               (256UL)
      17           0 : #define FD_SNAPSHOT_VERSION_FILE          ("version")
      18           0 : #define FD_SNAPSHOT_VERSION               ("1.2.0")
      19           0 : #define FD_SNAPSHOT_VERSION_LEN           (5UL)
      20           0 : #define FD_SNAPSHOT_STATUS_CACHE_FILE     ("snapshots/status_cache")
      21             : 
      22             : #define FD_SNAPSHOT_TMP_ARCHIVE           (".tmp.tar")
      23             : #define FD_SNAPSHOT_TMP_INCR_ARCHIVE      (".tmp_inc.tar")
      24             : #define FD_SNAPSHOT_TMP_FULL_ARCHIVE_ZSTD (".tmp.tar.zst")
      25             : #define FD_SNAPSHOT_TMP_INCR_ARCHIVE_ZSTD (".tmp_inc.tar.zst")
      26             : 
      27           0 : #define FD_SNAPSHOT_APPEND_VEC_SZ_MAX     (16UL * 1024UL * 1024UL * 1024UL) /* 16 MiB */
      28             : 
      29             : FD_PROTOTYPES_BEGIN
      30             : 
      31             : /* fd_snapshot_ctx_t holds various data structures needed for snapshot
      32             :    creation. It contains the snapshot slot, the snapshot directory,
      33             :    whether the snapshot is incremental, the tarball writer, the allocator,
      34             :    and holds the snapshot hash.
      35             : 
      36             :   FIXME: The snapshot service will currently not correctly free memory that is
      37             :          allocated unless a bump allocator like fd_scratch or fd_spad are used. */
      38             : 
      39             : struct fd_snapshot_ctx {
      40             : 
      41             :   /* These parameters are setup by the caller of the snapshot service. */
      42             :   ulong             slot;                      /* Slot for the snapshot. */
      43             :   char const *      out_dir;                   /* Output directory. */
      44             :   fd_valloc_t       valloc;                    /* Allocator */
      45             : 
      46             :   /* The two data structures from the runtime referenced by the snapshot service. */
      47             :   fd_funk_t *       funk;                      /* Funk handle. */
      48             :   fd_txncache_t *   status_cache;              /* Status cache handle. */
      49             : 
      50             :   uchar             is_incremental;            /* If it is incremental, set the fields and pass in data from the previous full snapshot. */
      51             :   ulong             last_snap_slot;            /* Full snapshot slot. */
      52             :   ulong             last_snap_capitalization;  /* Full snapshot capitalization. */
      53             :   fd_hash_t *       last_snap_acc_hash;        /* Full snapshot account hash. */
      54             : 
      55             :   fd_tpool_t *      tpool;
      56             : 
      57             :   /* We need two files to represent the snapshot file because can not directly
      58             :      stream out the compressed snapshot with the current implementation of the
      59             :      snapshot service. This is because we write back into the tar archive.
      60             :      So, we first write out a tar archive, then this is compressed into a
      61             :      second file. The tmp_fd is the file used to write the tar archive and
      62             :      the snapshot_fd is used to write out the compressed file. */
      63             :   int               tmp_fd;
      64             :   int               snapshot_fd;
      65             : 
      66             :   /* This gets setup within the context and not by the user. */
      67             :   fd_tar_writer_t * writer;     /* Tar writer. */
      68             :   fd_hash_t         snap_hash;  /* Snapshot hash. */
      69             :   fd_hash_t         acc_hash;   /* Account hash. */
      70             :   fd_slot_bank_t    slot_bank;  /* Obtained from funk. */
      71             :   fd_epoch_bank_t   epoch_bank; /* Obtained from funk. */
      72             :   fd_acc_mgr_t *    acc_mgr;    /* Wrapper for funk. */
      73             : 
      74             : };
      75             : typedef struct fd_snapshot_ctx fd_snapshot_ctx_t;
      76             : 
      77             : /* fd_snapshot_create_populate_fseq, fd_snapshot_create_is_incremental, and
      78             :    fd_snapshot_create_get_slot are helpers used to pack and unpack the fseq
      79             :    used to indicate if a snapshot is ready to be created and if the snapshot
      80             :    shoudl be incremental. The other bytes represent the slot that the snapshot
      81             :    will be created for. The most significant 8 bits determine if the snapshot
      82             :    is incremental and the least significant 56 bits are reserved for the slot.
      83             : 
      84             :    These functions are used for snapshot creation in the full client. */
      85             : 
      86             : static ulong FD_FN_UNUSED
      87           0 : fd_snapshot_create_pack_fseq( ulong is_incremental, ulong smr ) {
      88           0 :   return (is_incremental << 56UL) | (smr & 0xFFFFFFFFFFFFFFUL);
      89           0 : }
      90             : 
      91             : static ulong FD_FN_UNUSED
      92           0 : fd_snapshot_create_get_is_incremental( ulong fseq ) {
      93           0 :   return (fseq >> 56UL) & 0xFF;
      94           0 : }
      95             : 
      96             : static ulong FD_FN_UNUSED
      97           0 : fd_snapshot_create_get_slot( ulong fseq ) {
      98           0 :   return fseq & 0xFFFFFFFFFFFFFFUL;
      99           0 : }
     100             : 
     101             : /* fd_snapshot_create_new_snapshot is responsible for creating the different
     102             :    structures used for snapshot generation and outputting them to a servable,
     103             :    compressed tarball. The main components of a Solana snapshot are as follows:
     104             : 
     105             :    1. Version - This is a file that contains the version of the snapshot.
     106             :    2. Manifest - The manifest contains data about the state of the network
     107             :                  as well as the index of the append vecs.
     108             :       a. The bank. This is the equivalent of the firedancer slot/epoch context.
     109             :          This contains almost all of the state of the network that is not
     110             :          encapsulated in the accounts.
     111             :       b. Append vec index. This is a list of all of the append vecs that are
     112             :          used to store the accounts. This is a slot indexed file.
     113             :       c. The manifest also contains other relevant metadata including the
     114             :          account/snapshot hash.
     115             :    3. Status cache - the status cache holds the transaction statuses for the
     116             :       last 300 rooted slots. This is a nested data structure which is indexed
     117             :       by blockhash. See fd_txncache.h for more details on the status cache.
     118             :    4. Accounts directory - the accounts directory contains the state of all
     119             :       of the accounts and is a set of files described by <slot#.id#>. These
     120             :       are described by the append vec index in the manifest.
     121             : 
     122             :   The files are written out into a tar archive which is then zstd compressed.
     123             : 
     124             :   This can produce either a full snapshot or an incremental snapshot depending
     125             :   on the value of is_incremental. An incremental snapshot will contain all of
     126             :   the information described above, except it will only contain accounts that
     127             :   have been modified or deleted since the creation of the last incremental
     128             :   snapshot. */
     129             : 
     130             : void
     131             : fd_snapshot_create_new_snapshot( fd_snapshot_ctx_t * snapshot_ctx,
     132             :                                  fd_hash_t *         out_hash,
     133             :                                  ulong *             out_capitalization );
     134             : 
     135             : FD_PROTOTYPES_END
     136             : 
     137             : #endif /* HEADER_fd_src_flamenco_snapshot_fd_snapshot_create_h */