# Jael 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` <a href="#public-keys-result" id="public-keys-result"></a>

```hoon
+$  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`](/urbit-os/kernel/jael/tasks.md#public-keys) gift) to subcribers who are tracking public key information for a `+set` of `$ship`s.

Typically the `%full` kind with a `+map` of `$ship`s to [`$point:point`](#pointpoint)s 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`](#diffpoint)) 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` <a href="#seed" id="seed"></a>

```hoon
+$  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` <a href="#dawn-event" id="dawn-event"></a>

```hoon
+$  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`](#seed) contains the private boot parameters.
* `.spon` is a `+list` of ships and their [`$point`](#pointpoint)s 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` <a href="#source" id="source"></a>

```hoon
+$  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` <a href="#source-id" id="source-id"></a>

```hoon
+$  source-id  @udsourceid
```

Numerical index for Jael to organise its `$source`s. Jael assigns its `$source-id`s sequentially, starting from `0`.

### `$state-eth-node` <a href="#state-eth-node" id="state-eth-node"></a>

```hoon
+$  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 `$source`s 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-id`](#source-id)s to [`$source`](#source)s.
* `.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 `$ship`s to `$source-id`s 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 <a href="#block" id="block"></a>

Structures for Ethereum blocks.

### `$hash:block` <a href="#hashblock" id="hashblock"></a>

```hoon
+$  hash  @uxblockhash
```

Ethereum block hash.

### `$number:block` <a href="#numberblock" id="numberblock"></a>

```hoon
+$  number  @udblocknumber
```

Ethereum block number.

### `$id:block` <a href="#idblock" id="idblock"></a>

```hoon
+$  id  [=hash =number]
```

Ethereum block identifier - contains both the [$hash:block](#hashblock) and [$number:block](#numberblock).

### `$block:block` <a href="#blockblock" id="blockblock"></a>

```hoon
+$  block  [=id =parent=hash]
```

A reference to an Ethereum block - contains the [$id:block](#idblock) and the [$hash:block](#hashblock) of its parent for ordering purposes.

## point <a href="#point" id="point"></a>

Structures for points (Ship IDs in Azimuth).

### `$point:point` <a href="#pointpoint" id="pointpoint"></a>

```hoon
+$  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` <a href="#key-updatepoint" id="key-updatepoint"></a>

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

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

### `$diffs:point` <a href="#diffspoint" id="diffspoint"></a>

```hoon
+$  diffs  (list diff)
```

A list of invertible [$diff:point](#diffpoint)s.

### `$diff:point` <a href="#diffpoint" id="diffpoint"></a>

```hoon
+$  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`](#key-updatepoint).
* `%spon` is a change to a ship's sponsor.

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

### `$udiffs:point` <a href="#udiffspoint" id="udiffspoint"></a>

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

A list of non-invertible [$udiff:point](#udiffpoint)s.

### `$udiff:point` <a href="#udiffpoint" id="udiffpoint"></a>

```hoon
+$  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](#idblock) 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`](#key-updatepoint) 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](#diffpoint) with the `+udiff-to-diff:point` function.

## pki <a href="#pki" id="pki"></a>

This structure is mostly a holdover from prior versions of Jael and is unused apart from [$oath:pki](#oathpki).

### `$hand:pki` <a href="#handpki" id="handpki"></a>

```hoon
+$  hand  @uvH
```

128-bit Hash.

### `$mind:pki` <a href="#mindpki" id="mindpki"></a>

```hoon
+$  mind  [who=ship lyf=life]
```

Key identifier.

### `$name:pki` <a href="#namepki" id="namepki"></a>

```hoon
+$  name  (pair @ta @t)
```

Name in both ASCII and Unicode.

### `$oath:pki` <a href="#oathpki" id="oathpki"></a>

```hoon
+$  oath  @
```

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.urbit.org/urbit-os/kernel/jael/data-types.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.