@agoric/casting

Agoric Casting

This Agoric Casting package follows ocap broadcasts in a flexible, future-proof way.

TL;DR: You can run yarn demo, or to follow a mailbox castingSpec do:

npx agoric follow -Bhttp://devnet.agoric.net/network-config :mailbox.agoric1foobarbaz -otext

An example of following an on-chain mailbox in code (using this package) is:

// First, obtain a Hardened JS environment via Endo.
import '@endo/init/pre-remoting.js'; // needed only for the next line
import '@endo/init';

import {
  iterateLatest,
  makeFollower,
  makeLeader,
  makeCastingSpec,
} from '@agoric/casting';

// Iterate over a mailbox follower on the devnet.
const leader = makeLeader('https://devnet.agoric.net/network-config');
const castingSpec = makeCastingSpec(':mailbox.agoric1foobarbaz');
const follower = makeFollower(castingSpec, leader);
for await (const { value } of iterateLatest(follower)) {
  console.log(`here's a mailbox value`, value);
}

Follower options

The followerOpts argument in makeFollower(leader, key, followerOpts) provides an optional bag of options:

• the proof option, which has three possibilities:
  • 'strict' - release data only after proving it was validated (may incur waits for one block's data to be validated in the next block),
  • 'optimistic' (default) - release data immediately, but may crash the follower in the future if an already-released value could not be proven,
  • 'none' - release data immediately without validation
• the decode option is a function to translate buf: Uint8Array into data: string
  • (default) - interpret buf as a utf-8 string, then JSON.parse it
• the unserializer option can be
  • (default) - release unserialized objects using @endo/marshal's makeMarshal()
  • null - don't additionally unserialize data before releasing it
  • any unserializer object supporting E(unserializer).fromCapData(data)
• the crasher option can be
  • null (default) follower failures only propagate an exception/rejection
  • any crasher object supporting E(crasher).crash(reason)

Behind the scenes

• the network config contains enough information to obtain Tendermint RPC nodes for a given Agoric network. You can use makeLeaderFromRpcAddresses directly if you want to avoid fetching a network-config.
• each follower uses periodic CosmJS state polling (every X milliseconds) which can be refreshed more expediently via a Tendermint subscription to the corresponding state_change event
• published (string) values are automatically unmarshalled, but without object references. a custom marshaller for your application.
• the iterateRecent adapter transforms a follower into a local async iterator that produces only the last queried value (with no history reconstruction)

Status

This package currently depends on:

• Hardened Javascript
• @agoric/notifier async iterable adapters to implement iterateLatest
• @endo/marshal for default object unserialization
• CosmJS for proof verification, although it does not yet support light client tracking of the validator set
• a bespoke follower of WebSocket Tendermint events

Short-term goals:

• integrate the new SharedSubscription API from the Agoric/agoric-sdk#5418 makePublisherKit PR
• support iterateEach with the lossless forward iteration algorithm via the Agoric/agoric-sdk#5466 x/vstream PR
• upgrade to the Tendermint event log API when Tendermint v0.36 is supported by the Agoric chain