# Ames Data Types Here are the data types used by Ames, as defined in `lull.hoon`. ## `$address` ```hoon +$ address @uxaddress ``` Opaque atomic transport address to or from Unix. For Ames over UDP, it will encode the IP address and port. ## `$verb` ```hoon +$ verb ?(%snd %rcv %odd %msg %ges %for %rot) ``` Verbosity flag for Ames. Use with `|ames/verb %flag1 %flag2 ...` and turn off with `|ames/verb`. * `%snd` - Sending packets. * `%rcv` - Receiving packets. * `%odd` - Unusual events. * `%msg` - Message-level events. * `%ges` - Congestion control. * `%for` - Packet forwarding. * `%rot` - Routing attempts. ## `$blob` ```hoon +$ blob @uxblob ``` Raw atom to or from Unix, representing a packet. ## `$error` ```hoon +$ error [tag=@tas =tang] ``` Tagged diagnostic trace. ## `$lane` ```hoon +$ lane (each @pC address) ``` Ship transport address; either opaque [$address](#address) or galaxy. The runtime knows how to look up galaxies, so we don't need to know their transport addresses. ## `$plea` ```hoon +$ plea [vane=@tas =path payload=*] ``` Application-level message, as a `%pass`. * `.vane` - Destination vane on remote ship. * `.path` - Internal route on the receiving ship. * `.payload` - Semantic message contents. ## `$spar` ```hoon +$ spar [=ship =path] ``` Instead of a fully qualifying scry path, Ames infers rift and life based on the ship. ## `$bone` ```hoon +$ bone @udbone ``` Message flow index - mapped to `$duct`s in the [$ossuary](#ossuary). The first `$bone` is 0. They increment by 4, since each flow includes a bit for each message determining forward vs. backward and a second bit for whether the message is on the normal flow or the associated diagnostic flow (for naxplanations). The least significant bit of a `$bone` is: * 1 if "forward", i.e. we send `%plea`s on this flow. * 0 if "backward", i.e. we receive `%plea`s on this flow. The second-least significant bit is 1 if the `$bone` is a naxplanation `$bone`, and 0 otherwise. Only naxplanation messages can be sent on a naxplanation `$bone`, as `%boon`s. ## `$fragment` ```hoon +$ fragment @uwfragment ``` A message fragment. ## `$fragment-num` ```hoon +$ fragment-num @udfragmentnum ``` Message fragment count. ## `$message-blob` ```hoon +$ message-blob @udmessageblob ``` Unfragmented message blob. ## `$message-num` ```hoon +$ message-num @udmessagenum ``` Message count. ## `$public-key` ```hoon +$ public-key @uwpublickey ``` A peer's public key. ## `$symmetric-key` ```hoon +$ symmetric-key @uwsymmetrickey ``` A symmetric key for encrypting messages to a peer. This is produced by performing an elliptic curve Diffie-Hellman using our private key and the peer's public key. ## `$ack` ```hoon +$ ack $% [%ok ~] [%nack ~] [%naxplanation =error] == ``` A message acknowledgement. * `%ok` - Positive acknowledgement. * `%nack` - Negative acknowledgement. * `%naxplanation` - Nack trace. ## `$ship-state` ```hoon +$ ship-state $% [%alien alien-agenda] [%known peer-state] == ``` All Ames knows about a peer. * `%alien` - No PKI data, so enqueue actions to perform once we learn it. * `%known` - We know their `$life` and public keys, so we have a channel. ## `$alien-agenda` ```hoon +$ alien-agenda $: messages=(list [=duct =plea]) packets=(set =blob) heeds=(set duct) keens=(jug path duct) == ``` What to do when Ames learns a peer's life and keys. * `messages` - [$plea](#plea)s local vanes have asked Ames to send. * `packets` - Packets we've tried to send. * `heeds` - Local tracking requests; passed through into [$peer-state](#peer-state). * `keens` - Subscribers to remote scry paths. ## `$peer-state` ```hoon +$ peer-state $: $: =symmetric-key =life =rift =public-key sponsor=ship == route=(unit [direct=? =lane]) =qos =ossuary snd=(map bone message-pump-state) rcv=(map bone message-sink-state) nax=(set [=bone =message-num]) heeds=(set duct) closing=(set bone) corked=(set bone) keens=(map path keen-state) == ``` State for a peer with known life and keys. * `.route` - Transport-layer destination for packets to the peer. * `.qos` - Quality of service; connection status to the peer. * `.ossuary` - [$bone](#bone) to `$duct` mapper. * `.snd` - Per-`$bone` message pumps to send messages as fragments. * `.rcv` - Per-`$bone` message sinks to assemble messages from fragments. * `.nax` - Unprocessed nacks (negative acknowledgments). * `.heeds` - Listeners for `%clog` notifications. * `.closing`: Bones closed on the sender side. * `.corked`: Bones closed on both sender and receiver. * `.keens`: Remote scry state. ## `$keen-state` ```hoon +$ keen-state $: wan=((mop @ud want) lte) :: request packets, sent nex=(list want) :: request packets, unsent hav=(list have) :: response packets, backward num-fragments=@ud num-received=@ud next-wake=(unit @da) listeners=(set duct) metrics=pump-metrics == ``` Remote scry state for a peer. * `wan`: Request packets, sent. * `nex`: Request packets, unsent. * `hav`: Response packets, backwards. * `num-fragments`: Total fragment count. * `num-received`: Fragments received. * `next-wake`: Retry timing. * `listeners`: Ducts waiting for a response. * `metrics`: Stats. ## `$want` ```hoon +$ want $: fra=@ud =hoot packet-state == ``` Remote scry request fragment. ## `$have` ```hoon +$ have $: fra=@ud meow == ``` Remote scry response fragment. ## `$meow` ```hoon +$ meow $: sig=@ux num=@ud dat=@ux == ``` Remote scry response fragment data. * `sig`: signature. * `num`: number of fragments. * `dat`: contents. ## `$peep` ```hoon +$ peep $: =path num=@ud == ``` Remote scry fragment request. ## `$wail` ```hoon +$ wail $% [%0 peep] == ``` Tagged remote scry request fragment. ## `$roar` ```hoon +$ roar (tale:pki:jael (pair path (unit (cask)))) ``` Remote scry response message. A `tale:pki:jael` is a: ```hoon ++ tale :: urbit-signed * |$ [typ] :: payload mold $: dat=typ :: data syg=(map ship (pair life oath)) :: signatures == :: ``` Therefore, a `$roar` looks like: ``` > *roar:ames [dat=[p=/ q=~] syg=~] ``` In `dat`, for the `(pair path (unit (cask)))`, the `$path` is the remote scry path and the `(unit (cask))` contains the value, or is null if there's no value at this path and will never be one (equivalent to the `[~ ~]` case of a local scry). ## `$purr` ```hoon +$ purr $: peep meow == ``` Response packet payload. ## `$qos` ```hoon +$ qos $~ [%unborn *@da] [?(%live %dead %unborn) last-contact=@da] ``` Quality of service; how is the connection to a peer doing? * `%live` - Peer is ok. * `%dead` - Peer is not responding. * `%unborn` - Peer is sunken. * `last-contact` - Last time Ames heard from the peer, or if `%unborn`, the time when we first started tracking then. ## `$ossuary` ```hoon +$ ossuary $: =next=bone by-duct=(map duct bone) by-bone=(map bone duct) == ``` [`$bone`](#bone) to `$duct` mapping, `$next` is the next `$bone` to map to a `$duct`. ## `$message-pump-state` ```hoon +$ message-pump-state $: current=_`message-num`1 next=_`message-num`1 unsent-messages=(qeu message-blob) unsent-fragments=(list static-fragment) queued-message-acks=(map message-num ack) =packet-pump-state == ``` Persistent state for a `|message-pump`. * `.current`- Sequence number of earliest message sent or being sent. * `.next` - Sequence number of next message to send. * `.unsent-messages` - Messages to be sent after current message. * `.unsent-fragments` - Fragments of current message waiting for sending. * `.queued-message-acks` - Future message acks to be applied after current. * `.packet-pump-state` - State of corresponding `|packet-pump`. ## `$static-fragment` ```hoon +$ static-fragment $: =message-num num-fragments=fragment-num =fragment-num =fragment == ``` A packet; a fragment of a message and metadata. ## `$packet-pump-state` ```hoon +$ packet-pump-state $: next-wake=(unit @da) live=(tree [live-packet-key live-packet-val]) metrics=pump-metrics == ``` Persistent state for a `|packet-pump`. * `next-wake` - Last timer we've set, or null. * `live` - Packets in flight; sent but not yet acked. * `metrics` - Congestion control information. ## `$pump-metrics` ```hoon +$ pump-metrics $: rto=_~s1 rtt=_~s1 rttvar=_~s1 ssthresh=_10.000 cwnd=_1 num-live=@ud counter=@ud == ``` Congestion control state for a `|packet-pump`. * `rto` - Retransmission timeout. * `rtt` - Roundtrip time estimate, low-passed using EWMA. * `rttvar` - Mean deviation of `rtt`, also low-passed with EWMA. * `num-live` - How many packets sent, awaiting ack. * `ssthresh` - Slow-start threshold. * `cwnd` - Congestion window; max unacked packets. ## `$live-packet` ```hoon +$ live-packet $: key=live-packet-key val=live-packet-val == ``` A packet in flight, as tracked in the [$packet-pump-state](#packet-pump-state). ## `$live-packet-key` ```hoon +$ live-packet-key $: =message-num =fragment-num == ``` Identifier of a packet in flight. ## `$live-packet-val` ```hoon +$ live-packet-val $: packet-state num-fragments=fragment-num =fragment == ``` Content and metadata about a packet in flight. ## `$packet-state` ```hoon +$ packet-state $: last-sent=@da retries=@ud skips=@ud == ``` Sending statistics about a packet in flight. ## `$message-sink-state` ```hoon +$ message-sink-state $: last-acked=message-num last-heard=message-num pending-vane-ack=(qeu [=message-num message=*]) live-messages=(map message-num partial-rcv-message) nax=(set message-num) == ``` State of a `|message-sink` to assemble received messages. * `.last-acked` - Highest [`$message-num`](#message-num) Ames has fully acknowledged. * `.last-heard` - Highest `$message-num` Ames has heard all fragments for. * `.pending-vane-ack` - Heard but not processed by local vane. * `.live-messages` - Partially received messages. ## `$partial-rcv-message` ```hoon +$ partial-rcv-message $: num-fragments=fragment-num num-received=fragment-num fragments=(map fragment-num fragment) == ``` A message for which Ames has received some fragments. * `num-fragments` - Total number of fragments in the message. * `num-received` - How many fragments Ames has received so far. * `fragments` - The received fragments themselves. --- # 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/ames/data-types.md?ask= ``` 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.