Skip to main content

Crate quai_primitives

Crate quai_primitives 

Source
Expand description

Validated, allocation-free representations of Quai addresses and shards.

Address accepts any 20-byte address, matching quais.js’s getAddress. QuaiAddress and QiAddress additionally require a known zone and the appropriate ledger bit. A known zone does not imply that a chain has activated that zone; providers must check network capabilities separately.

Address strings use the same mixed-case Keccak checksum as quais.js. Lowercase and uppercase inputs are accepted; mixed-case inputs are checked.

Modules§

numeric
Exact bounded integer interchange. Floating-point bridges are explicit and limited to JavaScript’s safe integer range; chain quantities remain U256.

Structs§

Address
An arbitrary 20-byte address with validated string parsing.
FixedFormat
An explicit signed/unsigned byte-aligned field of 8..=256 bits and 0..=80 decimals.
FixedPoint
An exact decimal value with a checked integer field. Arithmetic never uses floating point or silently wraps overflow. Explicit wrapping methods opt into modular arithmetic, and to_f64_lossy is a separate presentation conversion. Comparisons compare numeric value across formats; arithmetic requires equal formats unless explicitly rescaled.
Hash32
Exactly 32 bytes, used for RPC hashes and storage words; no ledger is implied.
Hash32Error
A hash must contain exactly 64 hexadecimal digits after lowercase 0x.
QiAddress
An address with a published zone and the Qi ledger bit.
QuaiAddress
An address with a published zone and the Quai ledger bit.
ShardMetadata
Immutable published shard labels. These labels do not establish network activation, endpoint identity or finality.
SignedUnits
Signed 512-bit integer units for display arithmetic and legacy JS conversion.
Unit
A validated decimal scale. Quai uses 18 decimals; Qi uses 3 decimals.

Enums§

AddressError
Failure to parse an address or validate its ledger and zone.
AmountError
Errors converting human decimal input to exact integer units.
EncodingError
Invalid encoding, width or arithmetic input; errors never retain input content.
ErrorClass
What a caller, such as a background sync loop, can do about an error.
FixedError
Fixed-point validation and arithmetic errors never retain input strings.
Ledger
The ledger selected by the high bit of an address’s second byte.
Region
One of the three regions defined by the published protocol constants.
Rounding
How to handle discarded fractional units. Overflow is always an error.
Shard
A validated chain at any level of the network hierarchy.
ShardError
An invalid shard identifier. No unknown zone is silently mapped to a default.
Utf8Normalization
Explicit Unicode normalization. None at the call site preserves exact input.
Zone
One of the nine published zones. Availability is a network-level property.

Constants§

MAX_BASE58_BYTES
Base58 uses quadratic radix conversion and therefore has a smaller input cap.
MAX_ENCODING_BYTES
Maximum general byte utility input/output, excluding hexadecimal expansion.
QUAIS_SYMBOL
The published reference’s legacy display symbol (Greek capital Xi). Presentation metadata, not an amount unit or protocol discriminator.
UTF8_UNICODE_VERSION
Unicode tables used by explicit normalization (independent of browser engine).

Functions§

concat_bytes
Concatenate byte slices after bounding their total size before allocation.
contract_address
Predict the Quai CREATE address from exact init code and a 64-bit nonce.
create2_address
Predict CREATE2 from a 32-byte salt and the hash of exact init code.
data_slice
Checked borrowed byte slice; negative/JS-coerced indexes are not accepted.
decode_base58
Numeric Base58 decode, matching JS zero stripping within an explicit U256 range.
decode_base64
Strict standard padded Base64; URL alphabet, whitespace, missing padding and nonzero trailing bits are rejected rather than accepting Node Buffer coercions.
decode_base58_bytes
Base58 to bytes, preserving leading zeros. This is preferable for key material.
decode_bytes32
Decode strict UTF-8 after stripping trailing zero padding. Internal null bytes are preserved; the final word byte must be zero, matching the pinned JS helper.
encode_base58
Bitcoin-alphabet Base58, preserving each leading zero byte as 1.
encode_base64
Standard padded RFC 4648 Base64 encoding.
encode_bytes32
Encode at most 31 UTF-8 bytes plus null termination into an ABI bytes32 word.
format_qi
Format Qits as a human Qi amount.
format_quai
Format base units as a human Quai amount.
format_units
Format a 256-bit chain amount in the selected decimal unit.
from_twos
Interpret an unsigned bit pattern as signed two’s complement at 1..=256 bits. Bits outside the selected width are rejected instead of silently truncated.
get_bytes
Decode strict prefixed, even-width hexadecimal into owned bytes. A 0X prefix, odd nibbles, whitespace and invalid digits are rejected.
hexlify
Lowercase even-width hexadecimal with a 0x prefix, preserving leading zeros.
mask
Keep the lowest bits bits, with the full supported range 0..=256.
parse_qi
Parse a human Qi amount (3 decimals) to Qits.
parse_quai
Parse a human Quai amount (18 decimals) to base units.
parse_signed_units
Parse an exact signed decimal with reference 512-bit range and no rounding.
parse_units
Parse a nonnegative 256-bit chain amount without rounding or floating point.
strip_zeros_left
Borrow the bytes after all leading zero bytes. All-zero input returns empty.
to_twos
Convert a checked signed value to its two’s-complement representation at 1..=256 bits.
to_utf8_bytes
Encode valid Rust text as UTF-8, optionally normalizing explicitly. Both input and output are limited to MAX_ENCODING_BYTES; expansion is checked as it is streamed. No implicit normalization is applied to messages or addresses.
to_utf8_code_points
Return Unicode scalar values for optionally normalized text. Uses the same input/normalized-byte bounds as to_utf8_bytes; at most MAX_ENCODING_BYTES scalars.
to_utf8_string
Borrow strictly valid bounded UTF-8 without replacement, skipping or loss. Surrogates, overlong forms, invalid continuations and truncated sequences fail.
uuid_v4
Format exactly 16 caller-supplied random bytes as a version-4 UUID, setting version/variant bits in a copy. This function does not generate entropy or mutate the input; use a cryptographic random source when uniqueness matters.
zero_pad_bytes
Right-pad a fixed-byte representation with zero bytes, without truncation.
zero_pad_value
Left-pad an integer byte representation with zero bytes, without truncation.