-
Notifications
You must be signed in to change notification settings - Fork 206
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs(streams): add aspirational documentation
- Loading branch information
1 parent
75ad08b
commit 8352d4c
Showing
1 changed file
with
24 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,24 @@ | ||
# Agoric Streams | ||
|
||
The Agoric Streams package uses CosmJS and a homegrown WebSocket event querier to consume the Agoric chain's data publication sources in a flexible, future-proof way. | ||
|
||
The MVP of this package is to provide the following API to off-chain clients: | ||
|
||
```js | ||
const src = makeStreamSourceFromURL('https://devnet.agoric.net/network-config'); | ||
const stream = E(src).streamFromStoragePath('mailbox.agoric1...'); | ||
for await (const mailbox of iterateLatest(stream)) { | ||
console.log(`here's a mailbox object`, mailbox); | ||
} | ||
``` | ||
|
||
## Behind the scenes | ||
|
||
- the network config contains enough information to obtain Tendermint RPC nodes for a given Agoric network | ||
- each stream uses periodic state polling which can be triggered expediently with a Tendermint `state_change` event produced by the included `x/swingset` `SetStorageAndNotify` implementation. | ||
- There is an initial option to choose the level of integrity: | ||
a. release data immediately without validation, | ||
b. release data only after proving it was validated, | ||
c. release data optimistically, but crash the stream in the future if a provably wrong value was ever released | ||
- published (string) values are automatically unmarshalled. Options allow specifying your own unserializer | ||
- the `iterateRecent` adapter transforms a "stream" (converging on the [SharableSubscription](https://github.com/Agoric/agoric-sdk/pull/5418#discussion_r886253328) representation) into a local async iterator that produces only the last queried value (with no history reconstruction) |