52ef773 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

bytestring rewrites

52ef773drbeefsupreme5 years ago

content/docs/azimuth/l2/bytestring.md+49−32

compare with master

unifiedsplit

@@ -7,24 +7,33 @@ template = "doc.html"

7This document gives the bytestring format for layer 2 transactions and batches.

9[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

10+representation of an Azimuth action (format given below), along with a 65-byte

11−a 65-byte ECDSA signature. A `batch` is an atom that is a concatenation of one or more

11+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

12+layer 2 transactions and associated signatures. This atom is what is posted on

13+the Ethereum blockchain by a roller.

14+

13−a roller. We remark that multiple transactions from a single ship in a

15+We remark that each transaction from a given ship in a batch needs a separate

14−given batch each need their own signature, since data such as the nonce are not

16+signature, since data such as the nonce are not included in the transaction but

15−included in the data but are derived from the signature. Thus a ship cannot

17+are used in the signature. Thus a ship cannot submit multiple transactions with

16−generate multiple transactions and generate a single signature for all of them -

17−a different signature is needed for each transaction.

18+a single signature for all of them - a different signature is needed for each

19+transaction.

19## Byte format

21## Byte format

21We describe the byte format of a `batch` and its components in the following.

23We 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.

23### Batches {#batch}

32### Batches {#batch}

25−A `batch` is an atom that is the concatenation of several raw transactions, which

34+A `batch` is an atom that is the concatenation of several raw transactions,

26−are themselves atoms. `naive.hoon` starts reading the `batch` from the end and

35+which are themselves atoms. `naive.hoon` starts reading the `batch` from the end

27−working backwards. Thus a `batch` looks like:

36+and working backwards (little-endian). A `batch` looks like:

29```

38```

30action-n

39action-n

@@ -40,17 +49,17 @@ signature-1

41Be careful to distinguish between an "action" and an "unsigned transaction". An

50Be careful to distinguish between an "action" and an "unsigned transaction". An

42action is a short bytestring that describes an Azimuth action as given in the

51action 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,

52+[following section](#actions), while an unsigned transaction is an action plus

44−chain ID, header. Actions are what are submitted to Ethereum, while unsigned

53+the nonce, chain ID, header. Actions are what are submitted to Ethereum, while

45−transactions are what are signed and used as the signatures in the above `batch`

54+unsigned transactions are what are signed and used as the signatures in the

46−format. When `naive.hoon` parses a batch it adds the appropriate nonce, chain

55+above `batch` format. When `naive.hoon` parses a batch it adds the appropriate

47−ID, and header to a given action and uses that to verify the corresponding

56+nonce, chain ID, and header to a given action and uses that to verify the

48−signature, rather than just the action itself. This reduces the number of bytes

57+corresponding signature, rather than just the action itself. This reduces the

49−in the batch, making transactions cheaper.

58+number of bytes in the batch, making transactions cheaper.

51### Actions {#actions}

60### Actions {#actions}

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

54follows. They are parsed by the `+parse-tx` arm in `naive.hoon`.

63follows. They are parsed by the `+parse-tx` arm in `naive.hoon`.

56```

65```

@@ -61,7 +70,7 @@ remainder: arguments

613 bits: proxy

703 bits: proxy

62```

71```

64−The `proxy` is one of:

73+The `proxy` is an atom between `0` and `4`, which corresponds as follows:

65```

74```

66%0 %own

75%0 %own

67%1 %spawn

76%1 %spawn

@@ -71,9 +80,10 @@ The `proxy` is one of:

71```

80```

72Note that `%vote` proxies are not supported by layer 2.

81Note that `%vote` proxies are not supported by layer 2.

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.

76−The operation is one of the following:

86+The operation is an atom between `0` and `10` corresponding as follows:

78```

88```

79%0 %transfer-point

89%0 %transfer-point

@@ -96,11 +106,13 @@ arguments either use the remaining bit as a binary flag or as padding.

106

97```

107```

9820 bytes: address to transfer to

10820 bytes: address to transfer to

99−1 bit: reset?

109+1 bit: breach?

100```

110```

101

111

102#### `%spawn`

112#### `%spawn`

103

113

114+As before, the length of the ship argument is always 4 bytes.

115+

104```

116```

10520 bytes: address to set transfer proxy of spawned ship to

11720 bytes: address to set transfer proxy of spawned ship to

1064 bytes: ship to spawn

1184 bytes: ship to spawn

@@ -118,7 +130,8 @@ arguments either use the remaining bit as a binary flag or as padding.

118

130

119#### `%escape`, `%cancel-escape`, `%adopt`, `%reject`, `%detach`

131#### `%escape`, `%cancel-escape`, `%adopt`, `%reject`, `%detach`

120

132

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.

122

135

123```

136```

1244 bytes: ship

1374 bytes: ship

@@ -152,11 +165,10 @@ message header, an Urbit ID header, a chain ID, a nonce, and an action. This has

152==

165==

153```

166```

154

167

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

156argument `3` is a `bloq` size meaning `2^3=8` bits (one byte), and the head of

169argument `3` is a `bloq` size meaning `2^3=8` bits (one byte), and the head of

157each cell (which are `octs`) in the arguments that follow is the number of blocks (number of bytes

170each 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

171+in this scenario) of each entry, with the tail being the actual data.

159−to use `octs` rather than just atoms is to account for leading zeroes.

160

172

161`len` is the length measured in bytes of everything following it except the

173`len` is the length measured in bytes of everything following it except the

162signature. `chain-t` is the chain ID, which is to distinguish between e.g. the

174signature. `chain-t` is the chain ID, which is to distinguish between e.g. the

@@ -167,11 +179,12 @@ rebroadcast on the other (see

167`@ud`s.

179`@ud`s.

168

180

169Again we emphasize that unsigned transactions are _not_ what is submitted in a

181Again 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

182+batch - an [action](#actions) and a [signature](#signatures) are. A ship

171−to a roller signs an unsigned transaction and this signature is included

183+submitting a layer 2 transaction to a roller signs an unsigned transaction and

172−along with the action, which does not include the additional data listed above.

184+this signature is included along with the action, which does not include the

173−When a ship determines whether or not a given layer 2 action is valid, it adds

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

174−the additional data to the action and verifies the signature against that.

187+unsigned transaction and verifies the signature against that.

175

188

176### Signatures {#signatures}

189### Signatures {#signatures}

177

190

@@ -182,3 +195,7 @@ used to sign it. Layer 2 supports all major signature formats, including

182Metamask, Trezor, Ledger, and others. Signatures in batches are obtained by signing

195Metamask, Trezor, Ledger, and others. Signatures in batches are obtained by signing

183an [unsigned transaction](#unsigned).

196an [unsigned transaction](#unsigned).

184

197

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+