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 with custom CBOR Tag 1016, which instructs Alphabill to execute a transaction with a unit. TransactionOrder is always encoded as an array of data items in the exact order as defined below.

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

/TransactionOrder/ 1016([
    /Version/        1,
    /NetworkID/      3,
    /PartitionID/    1,
    /UnitID/         h'000000000000000000000000000000000000000000000000000000000000000101',
    /Type/           1,
    /Attributes/     [/omitted, Type dependent/],
    /StateLock/      [/omitted/],
    /ClientMetadata/ [/omitted/]
    /StateUnlock/    h''
    /AuthProof/      [/omitted, Type dependent/],
    /FeeProof/       h''
])

Data items in the top-level array:

0. Version (unsigned integer) is the version of the transaction order format. The current version is 1.
1. NetworkID (unsigned integer) is the identifier of the network that is supposed to execute the transaction. Common values are:
   • 1 - mainnet
   • 2 - testnet
   • 3 - local
2. PartitionID (unsigned integer) is the identifier of the partition that is supposed to execute the transaction. PartitionIDs currently in use:
   • 1 - Money Partition
   • 2 - User Token Partition
   • 3 - EVM Partition
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. Type (text string) is the type of the transaction. See section Transaction Types for the list of supported values and their corresponding Attributes and AuthProofs.
5. Attributes (array) is an array of transaction attributes that depends on the transaction type and are described in section Transaction Types.
6. StateLock (array) is an array of conditional execution predicates, nil for ordinary transactions.
7. ClientMetadata (array) is described in section Client Metadata.
8. StateUnlock (byte string) two CBOR data items: [0|1]+[<state lock/rollback predicate input>] related to conditional execution, nil for ordinary transactions.
9. AuthProof (array) is described in section Auth Proofs.
10. FeeProof (byte string) is described in section Fee Proof.

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',
    /ReferenceNumber/   h'1234567890ABCDEF'
]

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.
4. ReferenceNumber (byte string, up to 32 bytes) is an optional byte string with user defined meaning.

Auth Proof

AuthProof is an array of transaction auth proofs (predicate signatures/arguments/proofs). The most common example of AuthProof is a single element array which contains the OwnerProof digital signature signing the CBOR encoded array of all transaction order fields up until the AuthProof field. AuthProof is mandatory for ordinary transactions.

/AuthProof/ [
  /OwnerProof/ h'8258411937fea58c74c534cd389ebb36ce9dde86a4dc04fabc3afa16e7a8ed78bf826b5fe47070f5d37ee319e9f027fe71ef28cc9d0dce86093e38a4cb5209cb3c554900582103c30573dc0c7fd43fcb801289a6a96cb78c27f4ba398b89da91ece23e9a99aca3',
],

Fee Proof

FeeProof (byte string) contains the arguments to satisfy the owner predicate of the fee credit record specified by TransactionOrder.ClientMetadata.FeeCreditRecordID. The most common example of FeeProof is a digital signature signing the CBOR encoded array of all transaction order field up until the FeeProof, this also includes the AuthProof field. In other words, FeeProof is a counter signature over transaction AuthProof. FeeProof is mandatory for ordinary transactions.

/FeeProof/ h'8258411937fea58c74c534cd389ebb36ce9dde86a4dc04fabc3afa16e7a8ed78bf826b5fe47070f5d37ee319e9f027fe71ef28cc9d0dce86093e38a4cb5209cb3c554900582103c30573dc0c7fd43fcb801289a6a96cb78c27f4ba398b89da91ece23e9a99aca3',

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 and auth proofs is defined.

A common attribute for many transaction types is Counter, which is incremented by one for each transaction with a unit and thus makes the order of transactions unambiguous. Counter value in a transaction order must be equal to the current Counter value in the state tree. Upon successful execution of the transaction, the Counter value is incremented by 1.

Alphabill transaction types are documented in following sections:

• Money Partition Transaction Types
• User Token Partition Transaction Types
• Fee Credit Transaction Types
• Permissioned User Token Partition Transaction Types.