Module coin_reservation

This module defines the protocol for specifying an address balance reservation via an ObjectRef, in order to provide backward compatibility for clients that do not understand address balances.

The layout of the reservation ObjectRef is as follows:

(ObjectID, SequenceNumber, ObjectDigest)

The ObjectID points to an accumulator object (i.e. a dynamic field of the accumulator root object). This identifies both the owner and type (e.g. SUI, USDC, etc) of the balance being spent.

It is masked by XORing with the current chain identifier (i.e. genesis checkpoint digest). This prevents cross-chain replay, as an attacker would have to mine an address and currency type such that dynamic_field_key(address, type) = V such that V ^ FOREIGN_CHAIN_IDENTIFIER = TARGET_ACCUMULATOR_OBJECT_ID ^ TARGET_CHAIN_IDENTIFIER and then trick the target into signing a transaction as V on the foreign chain.

The masking also allows read APIs to positively identify attempts to read a “fake” object ID, as follows:

1. First, read the requested object ID.
2. If it does not exist, unmask the ID using the local chain identifier and read it again.
3. If it exists on the second attempt, the ID must have originated by masking an accumulator object ID.

The SequenceNumber is a monotonically increasing version number, typically the version of the accumulator root object. It is not used by the protocol, but is intended to help the caching behavior of old clients.

ObjectDigest contains the remainder of the payload:

1. The amount of the reservation [8 bytes]
2. The epoch(s) in which the tx is valid [4 bytes] (good enough for 12 million years of 24 hour epochs).
3. A magic number to identify this ObjectRef as a coin reservation [20 bytes].

Structs

ParsedDigest

ParsedDigestError

ParsedObjectRefWithdrawal

Constants

COIN_RESERVATION_MAGIC

Traits

CoinReservationResolverTrait

Trait for resolving funds withdrawal from a coin reservation

Functions

mask_or_unmask_id