@@ -0,0 +1,179 @@
2+title = "Bytestring Format"
7+This document gives the bytestring format for Layer 2 transactions and batches.
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.
21+We describe the byte format of a `batch` and its components in the following.
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:
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.
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`.
59+4 bytes: ship sending the transaction
64+The `proxy` is one of:
72+Note that `%vote` proxies are not supported by layer 2.
74+The ship is its `@p` encoded as an `@`.
76+The operation is one of the following:
87+%8 %set-management-proxy
89+%10 %set-transfer-proxy
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.
95+#### `%transfer-point`
98+20 bytes: address to transfer to
105+20 bytes: address to set transfer proxy of spawned ship to
106+4 bytes: ship to spawn
110+#### `%configure-keys`
113+4 bytes: crypto suite
114+32 bytes: encryption public key
115+32 bytes: authentication public key
119+#### `%escape`, `%cancel-escape`, `%adopt`, `%reject`, `%detach`
121+Each of these actions have the same argument - a single ship:
128+#### `%set-management-proxy`, `%set-spawn-proxy`, `%set-transfer-proxy`
130+Each of these actions have the same argument - an Ethereum address:
137+### Unsigned transactions
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:
144+ 26^'\19Ethereum Signed Message:\0a'
147+ (met 3 chain-t)^chain-t
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.
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.
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.
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.