simplicity-sys 0.6.2

FFI bindings to libsimplicity
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

/* This module provides functions for initializing and reading from a stream of bits from a 'FILE'. */
#ifndef SIMPLICITY_BITSTREAM_H
#define SIMPLICITY_BITSTREAM_H

#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
#include <simplicity/errorCodes.h>
#include "bitstring.h"

/* :TODO: consider adding an 'invalid' state that can be set when parsing has failed and should not be resumed. */
/* Datatype representing a bit stream.
 * Bits are streamed from MSB to LSB.
 *
 * Invariant: unsigned char arr[len]
 *            0 <= offset < CHAR_BIT
 *            0 == len implies 0 == offset
 */
typedef struct bitstream {
  const unsigned char *arr;  /* Underlying byte array */
  size_t len;                /* Length of arr (in bytes) */
  unsigned char offset;      /* Number of bits parsed from the beginning of arr */
} bitstream;

/* Initialize a bit stream, 'stream', from a given byte array.
 * Precondition: unsigned char arr[len];
 */
static inline bitstream initializeBitstream(const unsigned char* arr, size_t len) {
  return (bitstream){ .arr = arr, .len = len };
}

/* Closes a bitstream by consuming all remaining bits.
 * Returns 'SIMPLICITY_ERR_BITSTREAM_TRAILING_BYTES' if CHAR_BIT or more bits remain in the stream.
 * Otherwise, returns 'SIMPLICITY_ERR_BITSTREAM_ILLEGAL_PADDING' if any remaining bits are non-zero.
 * Otherwise returns 'SIMPLICITY_NO_ERROR'.
 *
 * Precondition: NULL != stream
 */
simplicity_err rustsimplicity_0_6_closeBitstream(bitstream* stream);

/* Fetches up to 31 bits from 'stream' as the 'n' least significant bits of return value.
 * The 'n' bits are set from the MSB to the LSB.
 * Returns 'SIMPLICITY_ERR_BITSTREAM_EOF' if not enough bits are available.
 *
 * Precondition: 0 <= n < 32
 *               NULL != stream
 */
int32_t rustsimplicity_0_6_readNBits(int n, bitstream* stream);

/* Returns one bit from 'stream', 0 or 1.
 * Returns 'SIMPLICITY_ERR_BITSTREAM_EOF' if no bits are available.
 *
 * Precondition: NULL != stream
 */
static inline int32_t read1Bit(bitstream* stream) {
  return rustsimplicity_0_6_readNBits(1, stream);
}

/* Decode an encoded number between 1 and 2^31 - 1 inclusive.
 * When successful returns the decoded result.
 * If the decoded value would be too large, 'SIMPLICITY_ERR_DATA_OUT_OF_RANGE' is returned.
 * If more bits are needed than available in the 'stream', 'SIMPLICITY_ERR_BITSTRING_EOF' is returned.
 * If an I/O error occurs when reading from the 'stream', 'SIMPLICITY_ERR_BISTRING_ERROR' is returned.
 *
 * Precondition: NULL != stream
 */
int32_t rustsimplicity_0_6_decodeUptoMaxInt(bitstream* stream);

/* Fills a 'bitstring' containing 'n' bits from 'stream'.
 * Returns 'SIMPLICITY_ERR_BITSTREAM_EOF' if not enough bits are available.
 * If successful, '*result' is set to a bitstring with 'n' bits read from 'stream' and 'SIMPLICITY_NO_ERROR' is returned.
 *
 * If an error is returned '*result' might be modified.
 *
 * Precondition: NULL != result
 *               n <= 2^31
 *               NULL != stream
 */
simplicity_err rustsimplicity_0_6_readBitstring(bitstring* result, size_t n, bitstream* stream);
#endif