-
Notifications
You must be signed in to change notification settings - Fork 28
ABI 1.3: bitset type
Add a new type to Antelope ABI -- bitset -- which represents a variable sized sequence of bits.
- 17 Apr 2025: Initial public release
-
06 May 2025: Remove
0bprefix from string representation
The QC block extension has a fc::dynamic_bitset type that is not representable by Antelope ABI. It's desirable that all protocol structures can be represented in ABI to allow for interoperability with tooling outside of nodeos that wants to inspect protocol structures.
The bitset first encodes the number of bits it contains as a varuint32, then encodes (size+8-1)/8 bytes in to the stream. The first byte represents bits 0-7, the next 8-15, and so on; i.e. LSB first. Unused bits should be written as 0.
Within a byte, the least significant bit stores the smaller bitset index.
Decoding a bitset first reads the varuint32 to establish the bitset size and then reads (size+8-1)/8 bytes representing the bits. Unused bits in the MSB (last encoded byte) must be ignored no matter their encoded value. This means the binary encoding 0x03 0x03 and 0x03 0x83 effectively represent the same bitset value because unused bits in the MSB are ignored.
There is a limit of 8388608 bits (derived from MAX_NUM_ARRAY_ELEMENTS) in nodeos' serialization code. ABI implementations do not need to support more than 8388608 bits.
The bitset is represented as a string containing a sequence of 0 and 1 characters in decreasing bit order, so that the first character represents bit N and the last character bit 0. The number of 0 and 1 characters defines the size of the bitset. Any non-0/1 characters in the string result in failure.
| String | Number of bits in set | Binary Representation |
|---|---|---|
| "" | 0 | 0x00 |
| "0" | 1 | 0x01 0x00 |
| "11" | 2 | 0x02 0x03 |
| "011" | 3 | 0x03 0x03 |
| "110001011" | 9 | 0x09 0x8b 0x01 |