This document gives the bytestring format for layer 2 transactions and batches.
Recall that a layer 2 transaction is a compact
representation of an Azimuth action (format given below), along with a 65-byte
ECDSA signature. A
batch is an atom that is a concatenation of one or more
layer 2 transactions and associated signatures. This atom is what is posted on
the Ethereum blockchain by a roller.
We remark that each transaction from a given ship in a batch needs a separate signature, since data such as the nonce are not included in the transaction but are used in the signature. Thus a ship cannot submit multiple transactions with a single signature for all of them - a different signature is needed for each transaction.
We describe the byte format of a
batch and its components in the following.
All atoms described here are read by the parser as little-endian - i.e. it reads
the last digit first and proceeds backwards.
For the purposes of concatenation, all atoms are encoded using
octs=(pair @ud @), which is a way to represent atoms with a fixed width in order to account
for leading zeroes. Here
@ud will be the length of the atom in bytes, while
@ is actual atom.
batch is an atom that is the concatenation of several raw transactions,
which are themselves atoms.
naive.hoon starts reading the
batch from the end
and working backwards (little-endian). A
batch looks like:
action-n signature-n action-(n-1) signature-(n-1) ... action-2 signature-2 action-1 signature-1
Be careful to distinguish between an "action" and an "unsigned transaction". An
action is a short bytestring that describes an Azimuth action as given in the
following section, while an unsigned transaction is an action plus
the nonce, chain ID, header. Actions are what are submitted to Ethereum, while
unsigned transactions are what are signed and used as the signatures in the
batch format. When
naive.hoon parses a batch it adds the appropriate
nonce, chain ID, and header to a given action and uses that to verify the
corresponding signature, rather than just the action itself. This reduces the
number of bytes in the batch, making transactions cheaper.
The byte format of an action as they appear in a
batch is as
follows. They are parsed by the
+parse-tx arm in
remainder: arguments 7 bits: operation 4 bytes: ship sending the transaction 5 bits: padding 3 bits: proxy
proxy is an atom between
4, which corresponds as follows:
%0 %own %1 %spawn %2 %manage %3 %vote %4 %transfer
%vote proxies are not supported by layer 2.
The ship is its
@p encoded as an
@. As we are working with fixed width
atoms, the full 4 bytes is used, even if the bit length of the
@p is shorter.
The operation is an atom between
10 corresponding as follows:
%0 %transfer-point %1 %spawn %2 %configure-keys %3 %escape %4 %cancel-escape %5 %adopt %6 %reject %7 %detach %8 %set-management-proxy %9 %set-spawn-proxy %10 %set-transfer-proxy
Since the operation is represented with 7 bits, to complete the byte the arguments either use the remaining bit as a binary flag or as padding.
20 bytes: address to transfer to 1 bit: breach?
As before, the length of the ship argument is always 4 bytes.
20 bytes: address to set transfer proxy of spawned ship to 4 bytes: ship to spawn 1 bit: padding
4 bytes: crypto suite 32 bytes: encryption public key 32 bytes: authentication public key 1 bit: breach?
Each of these actions have the same argument - a single ship. Again, the length of the ship argument is always 4 bytes.
4 bytes: ship 1 bit: padding
Each of these actions have the same argument - an Ethereum address:
20 bytes: address 1 bit: padding
An unsigned transaction is an atom consisting of the concatentation of an Ethereum signed message header, an Urbit ID header, a chain ID, a nonce, and an action. This has the following format:
%: cad 3 26^'\19Ethereum Signed Message:\0a' (met 3 len)^len 14^'UrbitIDV1Chain' (met 3 chain-t)^chain-t 1^':' 4^nonce action ~ ==
+cad is a gate in
/lib/tiny.hoon that concatenates atoms given in
octs format. The
3 is a
bloq size meaning
2^3=8 bits (one byte), and the head of
each cell (which are
octs) in the arguments that follow is the number of blocks (number of bytes
in this scenario) of each entry, with the tail being the actual data.
len is the length measured in bytes of everything following it except the
chain-t is the chain ID, which is to distinguish between e.g. the
Ethereum test net and main net, to ensure that transaction used in one cannot be
rebroadcast on the other (see
EIP-155). We note that
chain-t are both ASCII decimals (
@t in Hoon), while
Again we emphasize that unsigned transactions are not what is submitted in a batch - an action and a signature are. A ship submitting a layer 2 transaction to a roller signs an unsigned transaction and this signature is included along with the action, which does not include the additional data listed above. When a ship determines whether or not a given layer 2 action is valid, it adds the additional data to the action to form an unsigned transaction and verifies the signature against that.
The signature is a 65-byte ECDSA signature as described in
EIP-191 and is compatible with
personal_sign. The precise format of the signature depends on which wallet was
used to sign it. Layer 2 supports all major signature formats, including
Metamask, Trezor, Ledger, and others. Signatures in batches are obtained by signing
an unsigned transaction.
Because of the format of signatures, it may have leading zeroes resulting in a
64-byte signature, and so it is important to use
octs to ensure that it is
interpreted as being 65 bytes.