Skip to main content

Alphabill Raw Transaction Format

The following sections specify the format used for Alphabill raw transactions.

Transaction Order​

Alphabill transactions are encoded using a deterministic CBOR data format. The top-level data item is TransactionOrder, which instructs Alphabill to execute a transaction with a unit. TransactionOrder is always encoded as an array of 3 data items in the exact order: Payload, OwnerProof and FeeProof.

Using the CBOR Extended Diagnostic Notation and omitting the subcontent of these array items, the top-level array can be expressed as:

/TransactionOrder/ [
    /Payload/    [/omitted/],
    /OwnerProof/ h'',
    /FeeProof/   h''
]

Data items in the top-level array:

  1. Payload (array) is described in section Payload.
  2. OwnerProof (byte string) contains the arguments to satisfy the owner predicate of the unit specified by Payload.UnitID. The most common example of OwnerProof is a digital signature signing the CBOR encoded Payload.
  3. FeeProof (byte string) contains the arguments to satisfy the owner predicate of the fee credit record specified by Payload.ClientMetadata.FeeCreditRecordID. The most common example of FeeProof is a digital signature signing the CBOR encoded Payload. FeeProof can be set to null (CBOR simple value 22) in case OwnerProof also satisfies the owner predicate of the fee credit record.

Payload​

Payload is an array of data items which is usually covered by signature and consists of the following (with example values):

/Payload/ [
    /SystemID/       1,
    /Type/           "trans",
    /UnitID/         h'000000000000000000000000000000000000000000000000000000000000000100',
    /Attributes/     [/omitted, Type dependent/],
    /ClientMetadata/ [/omitted/]
]

Data items in the Payload array:

  1. SystemID (unsigned integer) is the identifier of the transaction system/partition that is supposed to execute the transaction. SystemIDs currently in use:
    • 1 - Money Partition
    • 2 - User Token Partition
    • 3 - EVM Partition
  2. Type (text string) is the type of the transaction. See section Transaction Types for the list of supported values and their corresponding Attributes.
  3. UnitID (byte string) uniquely identifies the unit involved in the transaction. Partitions can have different types of units and each UnitID consists of two concatenated parts: the unit part and the type part. The length of each part is constant within a partition and thus the overall length of UnitID is also constant within a partition.
  4. Attributes (array) is an array of transaction attributes that depends on the transaction type and are described in section Transaction Types.
  5. ClientMetadata (array) is described in section Client Metadata.

Client Metadata​

ClientMetadata is an array of data items that sets the conditions for the execution of the transaction. It consists of the following (with example values):

/ClientMetadata/ [
    /Timeout/           1344,
    /MaxTransactionFee/ 1,
    /FeeCreditRecordID/ h'A0227AC5202427DB551B8ABE08645378347A3C5F70E0E5734F147AD45CBC1BA50F'
]

Data items in the ClientMetadata array:

  1. Timeout (unsigned integer) is the highest block number that this transaction can be executed in.
  2. MaxTransactionFee (unsigned integer) is the maximum fee the user is willing to pay for the execution of this transaction.
  3. FeeCreditRecordID (byte string) is an optional identifier of the fee credit record used to pay for the execution of this transaction. Fee credit records are created with Transfer to Fee Credit and Add Fee Credit transactions.

Transaction Types​

Each partition defines its own unit types. For each unit type, a set of valid transaction types is defined. And for each transaction type, an array of valid attributes is defined.

A common attribute for many transaction types is Backlink, which links a transaction back to the previous transaction with the same unit and thus makes the order of transactions unambiguous. Backlink is calculated as the hash of the raw CBOR encoded bytes of the TransactionOrder data item. Hash algorithm is defined by each partition.

Alphabill transaction types are documented in sections Money Partition Transaction Types and User Token Partition Transaction Types.