@@ -35,7 +35,7 @@ your _Azimuth keys_.
3535Only [planets](@/docs/glossary/planet.md), [stars](@/docs/glossary/star.md), and
3636[galaxies](@/docs/glossary/galaxy.md) have Azimuth keys.
3737[Moons](@/docs/glossary/moon.md) and [comets](@/docs/glossary/comet.md) do not,
38−as they do not utilize the Ethereum blockchain.
38+as they do not exist on the Ethereum blockchain.
3939
4040It is important to note that no Azimuth keys are stored anywhere within your
4141ship's [pier](@/docs/glossary/pier.md) - Ethereum and Urbit ID are entirely
@@ -47,37 +47,41 @@ the [Azimuth documentation](@/docs/azimuth/azimuth.md).
4747
4848#### Networking keys
4949
50−All communications in Urbit over the [Ames](@/docs/glossary/ames.md) networking
50+All communications in Urbit over the [Ames](@/docs/glossary/ames.md) network
5151are end-to-end encrypted, and thus your ship stores its own public/private pair
5252of _networking keys_ utilized for encryption and authentication. Networking keys
53−for all ship types are stored within the ship's Jael vane.
54−
55−For planets, stars, and galaxies, your private networking key is a
56−necessary input (the [keyfile](@/docs/glossary/keyfile.md)) for the initial boot
57−sequence of your ship (sometime called its `%dawn`). The associated public key
58−is then uploaded to the Ethereum blockchain using one of your Azimuth private
59−keys - either the one associated to the wallet which owns the ship, or the one
60−which holds the management proxy.
61−
62−For moons, the private networking key is generated by the parent ship and
63−injected into the `%dawn` sequence for the moon, and its public key is stored by
64−the parent in its Jael vane. Moon networking keys may be changed by the parent
65−ship, but not by the moon itself.
66−
67−For comets, their 128-bit `@p` name is actually their public key, and the
68−"mining" process to generate a comet consists of guessing a private key for
69−which the associated public key has a galaxy that has already been pre-assigned
70−to assist its peer discovery process. Thus, comets cannot change their
71−networking keys - to get a new private networking key, a new comet must be
72−generated. A comet utilizes its private networking key stored in Jael to sign an
73−unencrypted attestation packet to verify that it is the owner of the associated
74−public key. Because of this, it is currently impossible for a ship to initiate
75−communication with a comet - the comet must always be the initiator. This means
76−that ultimately two comets cannot communicate with one another unless they have
77−somehow verified each others' public keys via some other method. This is merely
78−a technical limitation imposed by the design of the system, not an intentional
79−handicapping of comet abilities. It is expected that this limitation will
80−someday be lifted.
53+for all ship types are stored within the ship's [Jael](@/docs/glossary/jael.md)
54+[vane](@/docs/glossary/vane.md).
55+
56+For planets, stars, and galaxies, your networking public key is configured on
57+the Ethereum blockchain using one of your Azimuth private keys - either the one
58+associated to the wallet which owns the ship, or the one which holds the
59+[management proxy](@/docs/glossary/proxies.md). This is typically accomplished
60+with Bridge. Your networking private key is a necessary input (the
61+[keyfile](@/docs/glossary/keyfile.md)) for the initial boot sequence of your
62+ship (sometime called its `%dawn`), and this is also provided by Bridge.
63+
64+Public keys for moons are not tracked on the blockchain; instead they are
65+tracked by their parent ship. The networking private key is generated by the
66+parent ship and injected into the `%dawn` sequence for the moon, and its public
67+key is stored by the parent in its Jael vane. Networking keys for moons may be
68+changed by the parent ship, but not by the moon itself.
69+
70+For comets, their 128-bit `@p` name is actually their networking public key, and
71+the "mining" process to generate a comet consists of guessing a private key for
72+which the associated public key for which the last two bytes of their `@p`
73+matches one of the stars on the comet sponsors list downloaded during boot.
74+Thus, comets cannot change their networking keys - to get a new private
75+networking key, a new comet must be generated. For a comet to perform an initial
76+handshake with another ship, it utilizes its networking private key stored in
77+Jael to sign an unencrypted attestation packet to verify that it is the owner of
78+the associated public key. Because of this, it is currently impossible for a
79+ship to initiate communication with a comet - the comet must always be the
80+initiator. This means that ultimately two comets cannot communicate with one
81+another unless they have somehow verified each others' public keys via some
82+other method. This is merely a technical limitation imposed by the design of the
83+system, not an intentional handicapping of comet abilities. A workaround to this
84+limitation is slated to be implemented as of May 2021.
8185
8286### System components
8387
@@ -99,17 +103,13 @@ are utilized by Ames. All cryptographic primitives are
99103[jetted](@/docs/vere/jetting.md) in Vere with standard vetted implementations of
100104cryptographic libraries.
101105
102−[Vere](@/docs/vere/_index.md) is Urbit's Nock runtime system, written in C.
103−Correct implementation of cryptographic libraries is difficult, and so all
104−cryptographic functions implemented in Hoon are hinted to the interpreter to run
105−vetted cryptographic libraries reviewed by experts instead.
106−
107−[Azimuth](@/docs/azimuth/_index.md) is Urbit's Ethereum-based public key
108−infrastructure. `azimuth-tracker` obtains networking public keys for planets,
109−stars, and galaxies from this store, which are then stored in Jael and utilized
110−by Ames for end-to-end encrypted communication.
111−
112−
113−
106+[Vere](@/docs/vere/_index.md) is Urbit's Nock runtime system, written in C. All
107+cryptographic functions implemented in Hoon are hinted to the interpreter use
108+the [jet system](@/docs/vere/jetting.md) to run standard vetted cryptographic
109+libraries.
114110
111+[Azimuth](@/docs/azimuth/_index.md) is an Ethereum-based public key
112+infrastructure utilized by Urbit. `azimuth-tracker` obtains networking public
113+keys for planets, stars, and galaxies from this store, which are then stored in
114+Jael and utilized by Ames for end-to-end encrypted communication.
115115