@@ -7,24 +7,33 @@ template = "doc.html"
77This document gives the bytestring format for layer 2 transactions and batches.
88
99[Recall](/docs/azimuth/l2/layer2.md) that a layer 2 transaction is a compact
10−representation of an Azimuth action whose format will be given below, along with
11−a 65-byte ECDSA signature. A `batch` is an atom that is a concatenation of one or more
12−layer 2 transactions. This atom is what is posted on the Ethereum blockchain by
13−a roller. We remark that multiple transactions from a single ship in a
14−given batch each need their own signature, since data such as the nonce are not
15−included in the data but are derived from the signature. Thus a ship cannot
16−generate multiple transactions and generate a single signature for all of them -
17−a different signature is needed for each transaction.
10+representation of an Azimuth action (format given below), along with a 65-byte
11+ECDSA signature. A `batch` is an atom that is a concatenation of one or more
12+layer 2 transactions and associated signatures. This atom is what is posted on
13+the Ethereum blockchain by a roller.
14+
15+We remark that each transaction from a given ship in a batch needs a separate
16+signature, since data such as the nonce are not included in the transaction but
17+are used in the signature. Thus a ship cannot submit multiple transactions with
18+a single signature for all of them - a different signature is needed for each
19+transaction.
1820
1921## Byte format
2022
2123We describe the byte format of a `batch` and its components in the following.
24+All atoms described here are read by the parser as little-endian - i.e. it reads
25+the last digit first and proceeds backwards.
26+
27+For the purposes of concatenation, all atoms are encoded using `octs=(pair @ud
28+@)`, which is a way to represent atoms with a fixed width in order to account
29+for leading zeroes. Here `@ud` will be the length of the atom in bytes, while
30+the `@` is actual atom.
2231
2332### Batches {#batch}
2433
25−A `batch` is an atom that is the concatenation of several raw transactions, which
26−are themselves atoms. `naive.hoon` starts reading the `batch` from the end and
27−working backwards. Thus a `batch` looks like:
34+A `batch` is an atom that is the concatenation of several raw transactions,
35+which are themselves atoms. `naive.hoon` starts reading the `batch` from the end
36+and working backwards (little-endian). A `batch` looks like:
2837
2938```
3039action-n
@@ -40,17 +49,17 @@ signature-1
4049
4150Be careful to distinguish between an "action" and an "unsigned transaction". An
4251action is a short bytestring that describes an Azimuth action as given in the
43−following section, while an unsigned transaction is an action plus the nonce,
44−chain ID, header. Actions are what are submitted to Ethereum, while unsigned
45−transactions are what are signed and used as the signatures in the above `batch`
46−format. When `naive.hoon` parses a batch it adds the appropriate nonce, chain
47−ID, and header to a given action and uses that to verify the corresponding
48−signature, rather than just the action itself. This reduces the number of bytes
49−in the batch, making transactions cheaper.
52+[following section](#actions), while an unsigned transaction is an action plus
53+the nonce, chain ID, header. Actions are what are submitted to Ethereum, while
54+unsigned transactions are what are signed and used as the signatures in the
55+above `batch` format. When `naive.hoon` parses a batch it adds the appropriate
56+nonce, chain ID, and header to a given action and uses that to verify the
57+corresponding signature, rather than just the action itself. This reduces the
58+number of bytes in the batch, making transactions cheaper.
5059
5160### Actions {#actions}
5261
53−The hex format of an action as they appear in a `batch` is as
62+The byte format of an action as they appear in a `batch` is as
5463follows. They are parsed by the `+parse-tx` arm in `naive.hoon`.
5564
5665```
@@ -61,7 +70,7 @@ remainder: arguments
61703 bits: proxy
6271```
6372
64−The `proxy` is one of:
73+The `proxy` is an atom between `0` and `4`, which corresponds as follows:
6574```
6675%0 %own
6776%1 %spawn
@@ -71,9 +80,10 @@ The `proxy` is one of:
7180```
7281Note that `%vote` proxies are not supported by layer 2.
7382
74−The ship is its `@p` encoded as an `@`.
83+The ship is its `@p` encoded as an `@`. As we are working with fixed width
84+atoms, the full 4 bytes is used, even if the bit length of the `@p` is shorter.
7585
76−The operation is one of the following:
86+The operation is an atom between `0` and `10` corresponding as follows:
7787
7888```
7989%0 %transfer-point
@@ -96,11 +106,13 @@ arguments either use the remaining bit as a binary flag or as padding.
96106
97107```
9810820 bytes: address to transfer to
99−1 bit: reset?
109+1 bit: breach?
100110```
101111
102112#### `%spawn`
103113
114+As before, the length of the ship argument is always 4 bytes.
115+
104116```
10511720 bytes: address to set transfer proxy of spawned ship to
1061184 bytes: ship to spawn
@@ -118,7 +130,8 @@ arguments either use the remaining bit as a binary flag or as padding.
118130
119131#### `%escape`, `%cancel-escape`, `%adopt`, `%reject`, `%detach`
120132
121−Each of these actions have the same argument - a single ship:
133+Each of these actions have the same argument - a single ship. Again, the length
134+of the ship argument is always 4 bytes.
122135
123136```
1241374 bytes: ship
@@ -152,11 +165,10 @@ message header, an Urbit ID header, a chain ID, a nonce, and an action. This has
152165==
153166```
154167
155−Here `+cad` is a gate that concatenates atoms given in `octs` (`(pair @ud @)`) format. The
168+Here `+cad` is a gate in `/lib/tiny.hoon` that concatenates atoms given in `octs` format. The
156169argument `3` is a `bloq` size meaning `2^3=8` bits (one byte), and the head of
157170each cell (which are `octs`) in the arguments that follow is the number of blocks (number of bytes
158−in this scenario) of each entry, with the tail being the actual data. The reason
159−to use `octs` rather than just atoms is to account for leading zeroes.
171+in this scenario) of each entry, with the tail being the actual data.
160172
161173`len` is the length measured in bytes of everything following it except the
162174signature. `chain-t` is the chain ID, which is to distinguish between e.g. the
@@ -167,11 +179,12 @@ rebroadcast on the other (see
167179`@ud`s.
168180
169181Again we emphasize that unsigned transactions are _not_ what is submitted in a
170−batch - an action and a signature are. A ship submitting a layer 2 transaction
171−to a roller signs an unsigned transaction and this signature is included
172−along with the action, which does not include the additional data listed above.
173−When a ship determines whether or not a given layer 2 action is valid, it adds
174−the additional data to the action and verifies the signature against that.
182+batch - an [action](#actions) and a [signature](#signatures) are. A ship
183+submitting a layer 2 transaction to a roller signs an unsigned transaction and
184+this signature is included along with the action, which does not include the
185+additional data listed above. When a ship determines whether or not a given
186+layer 2 action is valid, it adds the additional data to the action to form an
187+unsigned transaction and verifies the signature against that.
175188
176189### Signatures {#signatures}
177190
@@ -182,3 +195,7 @@ used to sign it. Layer 2 supports all major signature formats, including
182195Metamask, Trezor, Ledger, and others. Signatures in batches are obtained by signing
183196an [unsigned transaction](#unsigned).
184197
198+Because of the format of signatures, it may have leading zeroes resulting in a
199+64-byte signature, and so it is important to use `octs` to ensure that it is
200+interpreted as being 65 bytes.
201+