Data Types

Jael's section in lull.hoon contains three ancillary cores with their own type definitions as well as Jael's general types.

$public-keys-result

+$  public-keys-result
  $%  [%full points=(map ship point)]
      [%diff who=ship =diff:point]
      [%breach who=ship]
  ==

This is what Jael gives (in a %public-keys gift) to subcribers who are tracking public key information for a set of ships.

Typically the %full kind with a map of ships to $point:points is given immediately upon subscription and contains all public key records for the ships in question. After the %full, a %diff (including a $diff:point) will be given whenever a change (such as the sponsor or pubkey) has occurred for one of the ships being tracked, and a %breach will be given whenever a continuity breach for a tracked ship occurs.

$seed

+$  seed  [who=ship lyf=life key=ring sig=(unit oath:pki)]

Private boot parameters. The who field is the name of the ship, lyf is the life (key revision number), key is the private key and sig is the signature of the parent ship if it's a moon, and ~ otherwise.

$dawn-event

+$  dawn-event
  $:  =seed
      spon=(list [=ship point:azimuth-types])
      czar=(map ship [=rift =life =pass])
      turf=(list turf)
      bloq=@ud
      node=(unit purl:eyre)
  ==

Ship initialisation parameters.

• $seed contains the private boot parameters.
• spon is a list of ships and their $points in the ship's sponsorship chain, all the way to the galaxy level.
• czar is a map from each galaxy's @p to its rift, life, and public key (pass).
• turf is a list of DNS suffixes used for galaxies, which is urbit.org by default.
• bloq is the number of the Ethereum block in which the ship registered its keys with the Azimuth smart contract.
• node is the URL of the Ethereum node used to monitor Azimuth.

$source

+$  source  (each ship term)

Source of public key updates for Jael. If it's a term it's a Gall agent e.g %azimuth-tracker. If it's a ship, Jael will subscribe to that ship's Jael for updates - e.g. Jael will subscribe to the parent planet of moons for updates about the moons.

$source-id

+$  source-id  @udsourceid

Numerical index for Jael to organise its sources. Jael assigns its source-ids sequentially, starting from 0.

$state-eth-node

+$  state-eth-node  ::  node config + meta
  $:  top-source-id=source-id
      sources=(map source-id source)
      sources-reverse=(map source source-id)
      default-source=source-id
      ship-sources=(map ship source-id)
      ship-sources-reverse=(jug source-id ship)
  ==

Jael's data about sources for PKI updates about ships.

• top-source-id tracks the highest source-id so Jael can easily determine what the next source-id should be.
• sources is a map of $source-ids to $sources.
• sources-reverse the same as sources but in reverse.
• default-source is the default source to use (typically 0 - %azimuth-tracker).
• ship-sources is a map from ships to source-ids and records where to get updates from for the ships in question. Typically these will map moons to their parent ships.
• ship-sources-reverse is the same as ship-sources but in reverse.

block

Structures for Ethereum blocks.

$hash:block

+$  hash  @uxblockhash

Ethereum block hash.

$number:block

+$  number  @udblocknumber

Ethereum block number.

$id:block

+$  id  [=hash =number]

Ethereum block identifier - contains both the $hash:block and $number:block.

$block:block

+$  block  [=id =parent=hash]

A reference to an Ethereum block - contains the $id:block and the $hash:block of its parent for ordering purposes.

point

Structures for points (Ship IDs in Azimuth).

$point:point

+$  point
  $:  =rift
      =life
      keys=(map life [crypto-suite=@ud =pass])
      sponsor=(unit @p)
  ==

Public key data for a particular ship. The rift is the current continuity breach number and life is the current key revision number. The keys map contains the public key (pass) for each life up to the current one. The sponsor is the current sponsor of the ship in question, if it has one.

$key-update:point

+$  key-update  [=life crypto-suite=@ud =pass]

An update to a ship's keys. The life is the key revision number, crypt-suite is a version number for the cryptographic suite used for keys in Azimuth, and pass is the public key itself.

$diffs:point

+$  diffs  (list diff)

A list of invertible $diff:points.

$diff:point

+$  diff
  $%  [%rift from=rift to=rift]
      [%keys from=key-update to=key-update]
      [%spon from=(unit @p) to=(unit @p)]
  ==

An invertible diff for public key (and related) changes to the state of an Azimuth point (ship ID).

• %rift is a change to the rift (continuity breach number) that occurs when a ship undergoes a continuity breach.
• %keys is a change to a ship's life and public key, specified in the $key-update:point.
• %spon is a change to a ship's sponsor.

The from and to field specify the old a new values respectively.

$udiffs:point

+$  udiffs  (list [=ship =udiff])

A list of non-invertible $udiff:points.

$udiff:point

+$  udiff
  $:  =id:block
  $%  [%rift =rift]
      [%keys key-update]
      [%spon sponsor=(unit @p)]
      [%disavow ~]
  ==  ==

A non-invertible diff for public key (and related) changes to the state of an Azimuth point (ship ID).

The $id:block contains the block number and block hash of the Ethereum block in which the change occurred. The next part specifies what changed, where:

• %rift means the ship has undergone a continuity breach and therefore the rift (continuity revision number) has changed.
• %keys means the ship's life (key revision number) has changed, the $key-update:point contains the new life and pubkeys.
• %spon means the ship's sponsor has changed.
• %disavow means a previous Ethereum block has been disavowed.

A udiff:point can be converted to a $diff:point with the +udiff-to-diff:point function.

pki

This structure is mostly a holdover from prior versions of Jael and is unused apart from $oath:pki.

$hand:pki

+$  hand  @uvH

128-bit Hash.

$mind:pki

+$  mind  [who=ship lyf=life]

Key identifier.

$name:pki

+$  name  (pair @ta @t)

Name in both ASCII and Unicode.

$oath:pki

+$  oath  @

Signature. This type is used in the $seed for moons as a signature from the moon's parent.