5212a52 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

Apply suggestions from code review

5212a52poprox5 years ago

content/docs/azimuth/ecliptic.md+23−23

compare with master

unifiedsplit

@@ -13,7 +13,7 @@ valid.

13Ecliptic uses external contracts such as

14[Azimuth.eth](/docs/azimuth/azimuth-eth) and

15[Polls](https://github.com/urbit/azimuth/blob/master/contracts/Polls.sol) for

16−data storage so that it can easily be replaced incase the logic needs to be

16+data storage so that it can easily be replaced in case the logic needs to be

17changed without affecting the data. These data contracts are owned by the

18Ecliptic contract, and this ownership is passed to the new Ecliptic contract

19whenever it is replaced. Thus it is advised for clients to not store Ecliptic's

@@ -58,7 +58,7 @@ to its [proxies](#proxies). All of these actions may be performed from Bridge.

59#### `configureKeys`

61−```

61+```solidity

62 function configureKeys(uint32 _point,

63 bytes32 _encryptionKey,

64 bytes32 _authenticationKey,

@@ -74,7 +74,7 @@ Corresponds to the layer 2 `%configure-keys` action.

75#### `spawn`

77−```

77+```solidity

78 function spawn(uint32 _point, address _target)

79```

@@ -93,7 +93,7 @@ Corresponds to the layer 2 `%spawn` action.

94#### `transferPoint`

96−```

96+```solidity

97 function transferPoint(uint32 _point, address _target, bool _reset)

98```

@@ -112,7 +112,7 @@ Corresponds to the layer 2 `%transfer-point` action.

112

113#### `escape`

114

115−```

115+```solidity

116 function escape(uint32 _point, uint32 _sponsor)

117```

118

@@ -128,7 +128,7 @@ Requirements:

128

129#### `cancelEscape`

130

131−```

131+```solidity

132 function cancelEscape(uint32 _point)

133```

134

@@ -138,7 +138,7 @@ Corresponds to the layer 2 `%cancel-escape` action.

138

139#### `adopt`

140

141−```

141+```solidity

142 function adopt(uint32 _point)

143```

144

@@ -152,7 +152,7 @@ Corresponds to the layer 2 `%adopt` action.

152

153#### `reject`

154

155−```

155+```solidity

156 function reject(uint32 _point)

157```

158

@@ -166,7 +166,7 @@ Corresponds to the layer 2 `%reject` action.

166

167#### `detach`

168

169−```

169+```solidity

170 function detach(uint32 _point)

171```

172

@@ -189,7 +189,7 @@ These functions are used to manage the various

189

190#### `setManagementProxy`

191

192−```

192+```solidity

193 function setManagementProxy(uint32 _point, address _manager)

194```

195

@@ -206,7 +206,7 @@ Corresponds to the layer 2 `%set-management-proxy` action.

206

207#### `setSpawnProxy`

208

209−```

209+```solidity

210 function setSpawnProxy(uint16 _prefix, address _spawnProxy)

211```

212

@@ -220,7 +220,7 @@ Corresponds to the layer 2 `%set-spawn-proxy` action.

220

221#### `setVotingProxy`

222

223−```

223+```solidity

224 function setVotingProxy(uint8 _galaxy, address _voter)

225```

226

@@ -235,7 +235,7 @@ There is no corresponding layer 2 action since voting must occur on layer 1.

235

236#### `setTransferProxy`

237

238−```

238+```solidity

239 function setTransferProxy(uint32 _point, address _transferProxy)

240```

241

@@ -263,7 +263,7 @@ expired, then _any_ Ethereum address may call `updateUpgradePoll` or

263

264#### `startUpgradePoll`

265

266−```

266+```solidity

267 function startUpgradePoll(uint8 _galaxy, EclipticBase _proposal)

268```

269

@@ -278,7 +278,7 @@ This action must be performed manually - it is not available in Bridge.

278

279#### `startDocumentPoll`

280

281−```

281+```solidity

282 function startDocumentPoll(uint8 _galaxy, bytes32 _proposal)

283```

284

@@ -292,7 +292,7 @@ This action must be performed manually - it is not available in Bridge.

292

293#### `castUpgradeVote`

294

295−```

295+```solidity

296 function castUpgradeVote(uint8 _galaxy,

297 EclipticBase _proposal,

298 bool _vote)

@@ -306,7 +306,7 @@ This action may be performed from Bridge.

306

307#### `castDocumentVote`

308

309−```

309+```solidity

310 function castDocumentVote(uint8 _galaxy, bytes32 _proposal, bool _vote)

311```

312

@@ -318,7 +318,7 @@ This action may be performed from Bridge.

318

319#### `updateUpgradePoll`

320

321−```

321+```solidity

322 function updateUpgradePoll(EclipticBase _proposal)

323```

324

@@ -330,7 +330,7 @@ performed manually. It is not available in Bridge.

330

331#### `updateDocumentPoll`

332

333−```

333+```solidity

334 function updateDocumentPoll(bytes32 _proposal)

335```

336

@@ -346,7 +346,7 @@ galaxies have already been spawned, it is no longer of any use. Thus only

346

347#### `createGalaxy`

348

349−```

349+```solidity

350 function createGalaxy(uint8 _galaxy, address _target)

351```

352

@@ -356,7 +356,7 @@ this function has no valid arguments.

356

357#### `setDnsDomains`

358

359−```

359+```solidity

360 function setDnsDomains(string _primary, string _secondary, string _tertiary)

361```

362

@@ -383,7 +383,7 @@ controlled on layer 2 instead of via Ecliptic.

383

384#### `canEscapeTo`

385

386−```

386+```solidity

387 function canEscapeTo(uint32 _point, uint32 _sponsor)

388```

389

@@ -411,7 +411,7 @@ Returns the address of the previous Ecliptic address.

411

412#### `getSpawnLimit`

413

414−```

414+```solidity

415 function getSpawnLimit(uint32 _point, uint256 _time)

416```

417

content/docs/azimuth/flow.md+1−1

@@ -93,7 +93,7 @@ not particular to Azimuth. It sends collected transactions to `+on-agent` in

93`%azimuth`, which then obtains the resulting PKI transitions by passing them through

94[`naive.hoon`](#naive).

96−![Eth-watcher](https://media.urbit.org/docs/layer2/roller-agents.png)

96+[![Eth-watcher](https://media.urbit.org/docs/layer2/roller-agents.png)](https://media.urbit.org/docs/layer2/roller-agents.png)

98#### `%roller` {#roller}

content/docs/azimuth/l2/layer2.md+1−1

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

7This document provides technical details on Azimuth's "Layer 2" scaling solution

8for Azimuth, known more formally as "naive rollups". We focus here primarily on the

9"Hoon smart contract" located at `/lib/naive.hoon` in your ship's pier, as well

10−as other proximal topis.

10+as other proximal topics.

12This is intended for developers that desire a deeper understanding of how this

13protocol works, how secure it is, and how to extract data from layer 2 to obtain

content/using/id/overview.md+36−30

@@ -54,11 +54,13 @@ However, Urbit is yours and it's forever. You shouldn't have to change your name

54every time you change your keys. So, we go back and take the other choice as well: you

55must be able to change your keys.

57+<a name="0"></a>

57To change keys, you must sign a message with the old keys revoking them and

58To change keys, you must sign a message with the old keys revoking them and

58−supplying the new ones[^0]. The question is what happens if the old keys also

59+supplying the new ones<a href="#f0">[0]</a>. The question

59−sign a second set of new keys. This could happen if an attacker obtained your

60+is what happens if the old keys also sign a second set of new keys. This could

60−old keys after the fact. This is important because one of the reasons to be able

61+happen if an attacker obtained your old keys after the fact. This is important

62+because one of the reasons to be able to change your keys is to invalidate the

61−to change your keys is to invalidate the old ones so that they have no power.

63+old ones so that they have no power.

63We have two options again: the PKI may be globally consistent or not. To be

65We have two options again: the PKI may be globally consistent or not. To be

64globally consistent means that if you believe a name is bound to a set of keys,

66globally consistent means that if you believe a name is bound to a set of keys,

@@ -108,13 +110,15 @@ signed before another without a central party. Blockchain was discovered by

108someone trying to create digital money, and he needed that primitive, but that

110someone trying to create digital money, and he needed that primitive, but that

109doesn't mean that's all it's good for.

111doesn't mean that's all it's good for.

110

112

113+<a name="2"></a>

111Thus, we store our PKI data on a blockchain for our second kind of name:

114Thus, we store our PKI data on a blockchain for our second kind of name:

112−[planets](/docs/glossary/planet). A planet is a 32-bit address which has key information stored on the

115+[planets](/docs/glossary/planet). A planet is a 32-bit address which has key

116+information stored on the blockchain.<a href="#f2">[2]</a>

113−blockchain.[^2] The owner of a planet may broadcast new PKI data by adding it to

117+The owner of a planet may broadcast new PKI data by adding it to the

114−the blockchain. Any later messages by the old keys will be rejected, and

118+blockchain. Any later messages by the old keys will be rejected, and everyone

115−everyone on the network will listen to the blockchain for key data. Thus, we

119+on the network will listen to the blockchain for key data. Thus, we have global

116−have global consistency, permanence, and self sovereignty. We know of no other

120+consistency, permanence, and self sovereignty. We know of no other solution

117−solution that can provide these properties.

121+that can provide these properties.

118

122

119While small individually, the aggregate PKI data for all nodes on the

123While small individually, the aggregate PKI data for all nodes on the

120network may become very large. This is not an issue for comets because nobody

124network may become very large. This is not an issue for comets because nobody

@@ -162,34 +166,36 @@ are three other properties; pick any two:

162

166

163- Moons are permanent, not self sovereign, and plentiful.

167- Moons are permanent, not self sovereign, and plentiful.

164

168

169+<a name="4"></a>

165Fancifully, comets are wayward celestial bodies that are great for testing and

170Fancifully, comets are wayward celestial bodies that are great for testing and

166miscellaneous low-value things that won't last for long. Planets are where you

171miscellaneous low-value things that won't last for long. Planets are where you

167can build a home and shape it into anything you want it to be. People can always

172can build a home and shape it into anything you want it to be. People can always

168find your planet; it's not going anywhere. Moons are useful for special

173find your planet; it's not going anywhere. Moons are useful for special

169purposes, like storage, heavy industry, and anything else you might want to do

174purposes, like storage, heavy industry, and anything else you might want to do

170−off-planet.[^4]

175+off-planet.<a href="#f4">[4]</a>

171

176

172

177

173−[^0]: Or the equivalent with a hierarchical key structure. In practice, you want

178+<a name="f0" href="#0">[0]</a>: Or the equivalent with a hierarchical key

174− to have a master key which signs a junior key for everyday use. You use the

179+structure. In practice, you want to have a master key which signs a junior key

175− master key to rotate the junior key.

180+for everyday use. You use the master key to rotate the junior key.

176

181

177−[^1]: More strictly: it proves that he didn't mine it after the other blocks

182+<a name="f1" href="#1">[1]</a>: More strictly: it proves that he didn't mine it

178− currently on the Bitcoin blockchain. It only gives an ordering within the

183+after the other blocks currently on the Bitcoin blockchain. It only gives an

179− chain, not a literal timestamp.

184+ordering within the chain, not a literal timestamp.

180

185

181−[^2]: In addition to planets, there are stars and galaxies. From a PKI

186+<a name="f2" href="#2">[2]</a>: In addition to planets, there are stars and

182− perspective they're treated exactly like planets, but on the network they

187+galaxies. From a PKI perspective they're treated exactly like planets, but on

183− provide infrastructure services like routing.

188+the network they provide infrastructure services like routing.

184

189

185−[^3]: In practice, this will likely be an included service by your sponsoring

190+<a name="f3" href="#3">[3]</a>: In practice, this will likely be an included

186− star. It could be a separate service, but it will be very cheap because it's

191+service by your sponsoring star. It could be a separate service, but it will be

187− a commodity and the "cost of production" is very cheap. At any rate, it

192+very cheap because it's a commodity and the "cost of production" is very cheap.

188− should never rise above the capital cost of a 400GB hard drive.

193+At any rate, it should never rise above the capital cost of a 400GB hard drive.

189

194

190−[^4]: To extend the metaphor, stars are a neighborhood to live in -- they're

195+<a name="f4" href="#4">[4]</a>: To extend the metaphor, stars are a

191− easier for other planets to see, so when they want to send you a message

196+neighborhood to live in -- they're easier for other planets to see, so when

192− they look for your star first. If they don't even know where your star is,

197+they want to send you a message they look for your star first. If they don't

193− they can certainly find your star's galaxy, and that will be enough to

198+even know where your star is, they can certainly find your star's galaxy, and

194− locate the star. Of course, if your star is not providing satisfactory

199+that will be enough to locate the star. Of course, if your star is not

195− service, you can take your planet and move to another star.

200+providing satisfactory service, you can take your planet and move to another

201+star.