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.
- Fixed
Format - An explicit signed/unsigned byte-aligned field of 8..=256 bits and 0..=80 decimals.
- Fixed
Point - 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.
- Hash32
Error - A hash must contain exactly 64 hexadecimal digits after lowercase
0x. - QiAddress
- An address with a published zone and the Qi ledger bit.
- Quai
Address - An address with a published zone and the Quai ledger bit.
- Shard
Metadata - Immutable published shard labels. These labels do not establish network activation, endpoint identity or finality.
- Signed
Units - 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§
- Address
Error - Failure to parse an address or validate its ledger and zone.
- Amount
Error - Errors converting human decimal input to exact integer units.
- Encoding
Error - Invalid encoding, width or arithmetic input; errors never retain input content.
- Error
Class - What a caller, such as a background sync loop, can do about an error.
- Fixed
Error - 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.
- Shard
Error - An invalid shard identifier. No unknown zone is silently mapped to a default.
- Utf8
Normalization - 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
0Xprefix, odd nibbles, whitespace and invalid digits are rejected. - hexlify
- Lowercase even-width hexadecimal with a
0xprefix, preserving leading zeros. - mask
- Keep the lowest
bitsbits, 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 mostMAX_ENCODING_BYTESscalars. - 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.