git.iko.soy/urbit.org
on master help sign in
Merge pull request #1074 from urbit/fix-life-rift
4d6693cpoprox
azimuth/_index.md+5
compare with master
unifiedsplit
@@ -11,6 +11,11 @@ insert_anchor_links = "right"
11
11
12An overview of the Ethereum-based public key infrastructure utilized by Urbit.
12An overview of the Ethereum-based public key infrastructure utilized by Urbit.
13
13
14+## [Life and Rift](@/docs/azimuth/azimuth.md)
15+
16+An explanation of how Azimuth keeps track of the most recent set of networking
17+keys necessary to communicate with a ship.
18+
14## [Advanced Azimuth Tools](@/docs/azimuth/advanced-azimuth-tools.md)
19## [Advanced Azimuth Tools](@/docs/azimuth/advanced-azimuth-tools.md)
15
20
16Expert-level tooling for generating, signing, and sending Azimuth-related
21Expert-level tooling for generating, signing, and sending Azimuth-related
azimuth/advanced-azimuth-tools.md+1−1
@@ -1,6 +1,6 @@
1+++
1+++
2title = "Advanced Azimuth Tools"
2title = "Advanced Azimuth Tools"
3−weight = 3
3+weight = 4
4template = "doc.html"
4template = "doc.html"
5+++
5+++
6
6
azimuth/life-and-rift.mdnew file+59
@@ -0,0 +1,59 @@
1++++
2+title = "Life and Rift"
3+weight = 3
4+template = "doc.html"
5+aliases = ["/docs/learn/azimuth"]
6++++
7+
8+Associated to every Azimuth point are two non-negative integers known as _life_
9+and _rift_. This numbering system partition messages according to the quantity
10+of networking key changes and quantity of
11+[breaches](@/using/id/guide-to-breaches.md), respectively. This is explained in
12+more detail below. These values are utilized by [Ames](@/docs/arvo/ames/ames.md)
13+and [Jael](@/docs/arvo/jael/jael-api.md) to ensure that communication between
14+ships is always done with the most recent set of networking keys, and that
15+networking state is appropriately reset when a breach has occurred.
16+
17+Every ship begins with a `life` and `rift` of 0. For
18+galaxies, stars, and planets, these values are stored in the Azimuth PKI, while
19+for moons, these values are stored by their parent. Comets cannot change their
20+networking keys, nor can they breach, and so their `life` and `rift` are always 0.
21+
22+You can check your current `life` and `rift` number by running the `+keys our`
23+generator in dojo. You can inspect another ship's `life` and `rift` by running
24+`+keys ~sampel-palnet`.
25+
26+## Life
27+
28+A ship's `life`, or _key revision number_, is a count of the number of times which
29+a ship's networking keys have been altered. The initial value of each key is
30+always zero, and the initial `life` is always 0.
31+
32+Thus, setting the keys of a ship to a nonzero value for the first time will
33+increment the `life` from 0 to 1. Rotating to a new set of keys will then
34+increment the `life` to 2. Setting the keys back to zero would increment the
35+`life` once more, to 3.
36+
37+## Rift
38+
39+A ship's `rift`, or _continuity number_, is a count of the number of times that
40+a ship has breached, also known as broken continuity.
41+
42+In other words, a ship's `rift` will remain at 0 until the first time it is
43+breached.
44+
45+Network-wide breaches do not affect the `rift` of any ship. They are only used to
46+count the number of personal breaches.
47+
48+## Edge cases
49+
50+Configuring the keys to the same value they already were (i.e. a no-op) is
51+possible, but has no effect on the `life`. Thus `life` is actually a measure of
52+networking key _revisions_, and not the number of times they've been set.
53+
54+Thus under ordinary circumstances, a breach will increment both `life` and
55+`rift` since a breach typically also involves changing the networking keys.
56+However, it is possible to breach without changing the networking keys.
57+If the new keys specified
58+as part of a breach are the same as the old, `rift` will increment while
59+`life` will not.
glossary/breach.md+12−19
@@ -5,28 +5,21 @@ template = "doc.html"
5category = "arvo"
5category = "arvo"
6+++
6+++
7
7
8−Continuity on the [Ames](../ames) network occasionally needs to be broken at
8+Continuity on the [Ames](../ames) network occasionally needs to be broken
9−this early stage in order to correct a networking error or make major changes to
9+(though with increasing rarity) in order to correct a networking error. These
10−Arvo. These infrequent events are known as
11−**breaches** which either cause an individual ship to forget its network message
10+infrequent events are known as **breaches**, which cause an individual ship to
12−history, called a **personal breach**, or cause the entire network to forget its
11+forget its network message history.
13−history, called a **network breach**.
14
12
15−Personal breaches are always initiated by the user, frequently in response to a
13+Breaches are always initiated by the user, frequently in response to a
16connectivity error. The easiest way to do this is with [Bridge](../bridge).
14connectivity error. The easiest way to do this is with [Bridge](../bridge).
17−There are two types of personal breaches: changing private keys, and changing
15+There are two types of personal breaches: changing networking keys, and changing
18−the Urbit ID ownership address. Each one increments the _life_ number of the ship by one, which is
16+the Urbit ID ownership address.
19−an integer that represents how many personal breaches have been performed on
20−that ship. Transferring the ID to a new address will also increase the _rift_
21−number of the ship in addition to the life number.
22
17
23−You can check your life and rift number by typing `+keys our`
18+Historically, there were also "network breaches", which happened when a major
24−into dojo and pressing Enter.
25−
26−Network breaches happen when a major Arvo revision that cannot be implemented
19+Arvo revision that could not be implemented via an [OTA update](../ota-updates)
27−via an [OTA update](../ota-updates) occurs. When this happens, a new binary
20+occured. Network breaches were effectively breaching every ship on the network
28−will need to be downloaded, and your ship's [pier](../pier) needs to be moved to the
21+at once. The most recent network breach occurred in December 2020, and we expect
29−directory containing the new binary.
22+it to be the final one.
30
23
31### Further Reading
24### Further Reading
32
25