@@ -0,0 +1,179 @@
1++++
2+title = "Bytestring Format"
3+weight = 7
4+template = "doc.html"
5++++
6+
7+This document gives the bytestring format for Layer 2 transactions and batches.
8+
9+[Recall](/docs/azimuth/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+an aggregator. 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.
18+
19+## Byte format
20+
21+We describe the byte format of a `batch` and its components in the following.
22+
23+### Batch
24+
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:
28+
29+```
30+action-n
31+signature-n
32+action-(n-1)
33+signature-(n-1)
34+...
35+action-2
36+signature-2
37+action-1
38+signature-1
39+```
40+
41+Be careful to distinguish between an "action" and an "unsigned transaction". An
42+action 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.
50+
51+### Actions
52+
53+The hex format of an action as they appear in a `batch` is as
54+follows. They are parsed by the `+parse-tx` arm in `naive.hoon`.
55+
56+```
57+remainder: arguments
58+7 bits: operation
59+4 bytes: ship sending the transaction
60+5 bits: padding
61+3 bits: proxy
62+```
63+
64+The `proxy` is one of:
65+```
66+%0 %own
67+%1 %spawn
68+%2 %manage
69+%3 %vote
70+%4 %transfer
71+```
72+Note that `%vote` proxies are not supported by layer 2.
73+
74+The ship is its `@p` encoded as an `@`.
75+
76+The operation is one of the following:
77+
78+```
79+%0 %transfer-point
80+%1 %spawn
81+%2 %configure-keys
82+%3 %escape
83+%4 %cancel-escape
84+%5 %adopt
85+%6 %reject
86+%7 %detach
87+%8 %set-management-proxy
88+%9 %set-spawn-proxy
89+%10 %set-transfer-proxy
90+```
91+
92+Since the operation is represented with 7 bits, to complete the byte the
93+arguments either use the remaining bit as a binary flag or as padding.
94+
95+#### `%transfer-point`
96+
97+```
98+20 bytes: address to transfer to
99+1 bit: reset?
100+```
101+
102+#### `%spawn`
103+
104+```
105+20 bytes: address to set transfer proxy of spawned ship to
106+4 bytes: ship to spawn
107+1 bit: padding
108+```
109+
110+#### `%configure-keys`
111+
112+```
113+4 bytes: crypto suite
114+32 bytes: encryption public key
115+32 bytes: authentication public key
116+1 bit: breach?
117+```
118+
119+#### `%escape`, `%cancel-escape`, `%adopt`, `%reject`, `%detach`
120+
121+Each of these actions have the same argument - a single ship:
122+
123+```
124+4 bytes: ship
125+1 bit: padding
126+```
127+
128+#### `%set-management-proxy`, `%set-spawn-proxy`, `%set-transfer-proxy`
129+
130+Each of these actions have the same argument - an Ethereum address:
131+
132+```
133+20 bytes: address
134+1 bit: padding
135+```
136+
137+### Unsigned transactions
138+
139+An unsigned transaction is an atom consisting of the concatentation of an Ethereum signed
140+message header, an Urbit ID header, a chain ID, a nonce, and an action. This has the following format:
141+
142+```hoon
143+%: cad 3
144+ 26^'\19Ethereum Signed Message:\0a'
145+ (met 3 len)^len
146+ 14^'UrbitIDV1Chain'
147+ (met 3 chain-t)^chain-t
148+ 1^':'
149+ 4^nonce
150+ action
151+ ~
152+==
153+```
154+
155+Here `+cad` is a gate that concatenates atoms given in `octs` (`(pair @ud @)`) format. The
156+argument `3` is a `bloq` size meaning `2^3=8` bits (one byte), and the head of
157+each 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 padding.
160+
161+`len` is the length in bytes of everything following it except the signature.
162+`chain-t` is the chain ID, which is to distinguish between e.g. the Ethereum
163+test net and main net, to ensure that transaction used in one cannot be
164+rebroadcast on the other.
165+
166+Again we emphasize that unsigned transactions are _not_ what is submitted in a
167+batch - an action and a signature are. A ship submitting a layer 2 transaction
168+to an aggregator signs an unsigned transaction and this signature is included
169+along with the action, which does not include the additional data listed above.
170+When a ship determines whether or not a given layer 2 action is valid, it adds
171+the additional data to the action and verifies the signature against that.
172+
173+### Signature
174+
175+The signature is a 65-byte ECDSA signature. The precise format of the signature depends
176+on which wallet was used to sign it. Layer 2 supports all major signature
177+formats, including Metamask, Trezor, Ledger, and others. Signatures in batches
178+are got by signing an unsigned transaction.
179+