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.
Byte format
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 the @ is actual atom.
Batches
A 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-nsignature-naction-(n-1)signature-(n-1)...action-2signature-2action-1signature-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 above 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.
Actions
The byte format of an action as they appear in a batch is as follows. They are parsed by the +parse-tx arm in naive.hoon.
remainder: arguments7 bits: operation4 bytes: ship sending the transaction5 bits: padding3 bits: proxy
The proxy is an atom between 0 and 4, which corresponds as follows:
%0 %own%1 %spawn%2 %manage%3 %vote%4 %transfer
Note that %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 0 and 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.
%transfer-point
20 bytes: address to transfer to1 bit: breach?
%spawn
As before, the length of the ship argument is always 4 bytes.
20 bytes: address to set transfer proxy of spawned ship to4 bytes: ship to spawn1 bit: padding
%configure-keys
4 bytes: crypto suite32 bytes: encryption public key32 bytes: authentication public key1 bit: breach?
%escape, %cancel-escape, %adopt, %reject, %detach
Each of these actions have the same argument - a single ship. Again, the length of the ship argument is always 4 bytes.
4 bytes: ship1 bit: padding
%set-management-proxy, %set-spawn-proxy, %set-transfer-proxy
Each of these actions have the same argument - an Ethereum address:
20 bytes: address1 bit: padding
Unsigned transactions
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 326^'\19Ethereum Signed Message:\0a'(met 3 len)^len14^'UrbitIDV1Chain'(met 3 chain-t)^chain-t1^':'4^nonceaction~==
Here +cad is a gate in /lib/tiny.hoon that concatenates atoms given in octs format. The argument 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 signature. 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 len and chain-t are both ASCII decimals (@t in Hoon), while nonce and action are @uds.
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.
Signatures
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.