packages feed

haskoin-store-1.16.0: cbits/haskoin_store_merge.h

/*
 * The merge operators of haskoin-store: the C functions that RocksDB calls
 * to work out an address balance and a group of spenders from the merge
 * records that the import of a block writes.
 *
 * Why: importing a block changes the balance of every address that it pays
 * or spends from, and adds a spender to the group of every output that it
 * spends. Each of those was read from the database, changed and written
 * back, and on a store of Bitcoin those reads were most of the time of a
 * block. A merge record says how a value changes and is written without
 * reading it. RocksDB works out the value later, when it is read or when a
 * compaction brings the records and the value together, with the functions
 * below. They run on the threads of RocksDB, so they are C.
 *
 * Both formats are made so that a merge record looks like a value. Then
 * applying records to a value and combining records with each other are
 * the same operation, and a record that is merged with no value is the
 * value.
 *
 * The functions have the types that rocksdb_mergeoperator_create of
 * rocksdb/c.h asks for. They return memory from malloc(), which RocksDB
 * frees. When their input is not of the format they fail: they store 0 in
 * "*success" and in "*new_value_length" and return NULL. They do nothing
 * else about such input.
 *
 * Haskoin.Store.Database.Merge gives them to RocksDB, and
 * docs/layered-database.md has the reasons.
 */

#ifndef HASKOIN_STORE_MERGE_H
#define HASKOIN_STORE_MERGE_H

#include <stddef.h>

/* Bytes of an address balance: five numbers of eight bytes. */
#define HASKOIN_STORE_BALANCE_SIZE 40

/*
 * Bytes of an entry of a group of spenders: the number of the output in
 * its transaction (4), the hash of the transaction that spends it (32) and
 * the number of the input that does (4).
 */
#define HASKOIN_STORE_SPENDER_SIZE 40

/*
 * Address balances: the values of the "balance" column family.
 *
 * A value is five unsigned numbers of 64 bits, most significant byte
 * first: the confirmed balance, the unconfirmed balance, the number of
 * unspent outputs, the number of transactions, and the amount received. It
 * is what the store has always written (BalVal).
 *
 * A merge record has the same forty bytes: five differences, each to be
 * added to its number modulo 2^64, so that a number goes down by adding
 * its two's complement. A key without a value counts from five zeros.
 *
 * The full merge adds the records to the value, and the partial merge adds
 * records to each other. Addition modulo 2^64 does not care about order or
 * grouping, so both are the same sum.
 */
char *haskoin_store_balance_full_merge(
    void *state,
    const char *key,
    size_t key_length,
    const char *existing_value,
    size_t existing_value_length,
    const char *const *operands_list,
    const size_t *operands_list_length,
    int num_operands,
    unsigned char *success,
    size_t *new_value_length);

char *haskoin_store_balance_partial_merge(
    void *state,
    const char *key,
    size_t key_length,
    const char *const *operands_list,
    const size_t *operands_list_length,
    int num_operands,
    unsigned char *success,
    size_t *new_value_length);

/*
 * Groups of spenders: the values of the "spender" column family.
 *
 * A value is one byte with the number of its entries, then the entries in
 * ascending order of their first field, each of
 * HASKOIN_STORE_SPENDER_SIZE bytes: the number of an output in its
 * transaction, the hash of the transaction that spends it, and the number
 * of the input that does, the two numbers of 32 bits with the most
 * significant byte first. It is what the store has written since database
 * version 22 (SpenderVal).
 *
 * A merge record is a value of the same format, with the entries to add.
 * Merging is the union: every entry of the value and of the records, and
 * for an output that several have, the entry of the newest. The result is
 * in ascending order of output again.
 *
 * The full merge and the partial merge are the same union, the first with
 * the value as the oldest of what it is given.
 */
char *haskoin_store_spender_full_merge(
    void *state,
    const char *key,
    size_t key_length,
    const char *existing_value,
    size_t existing_value_length,
    const char *const *operands_list,
    const size_t *operands_list_length,
    int num_operands,
    unsigned char *success,
    size_t *new_value_length);

char *haskoin_store_spender_partial_merge(
    void *state,
    const char *key,
    size_t key_length,
    const char *const *operands_list,
    const size_t *operands_list_length,
    int num_operands,
    unsigned char *success,
    size_t *new_value_length);

#endif