diff --git a/learn/infrastructure/.pages b/learn/infrastructure/.pages index b00826b5..e353687b 100644 --- a/learn/infrastructure/.pages +++ b/learn/infrastructure/.pages @@ -3,3 +3,4 @@ nav: - index.md - 'VAAs': 'vaas.md' - 'Guardians': 'guardians.md' + - 'Spies': 'spy.md' diff --git a/learn/infrastructure/spy.md b/learn/infrastructure/spy.md new file mode 100644 index 00000000..51a027d1 --- /dev/null +++ b/learn/infrastructure/spy.md @@ -0,0 +1,70 @@ +--- +title: Spy +description: Discover Wormhole's Spy daemon, which subscribes to gossiped messages in the Guardian Network, including VAAs and Observations, with setup instructions. +--- + +# Spy + +In the Wormhole context, a _Spy_ is a daemon that subscribes to the gossiped messages in the Guardian Network. + +The messages available over gossip are things like: + +- [VAAs](#){target=\_blank} +- [Observations](#){target=\_blank} +- Guardian heartbeats + +The source code for the Spy is available on [GitHub](https://github.com/wormhole-foundation/wormhole/blob/main/node/cmd/spy/spy.go){target=\_blank}. + +!!! note + The Spy has no persistence layer built in, so typically, it is paired with something like Redis or an SQL database to record relevant messages. + +## How to Start a Spy + +To start a Spy locally, run the following Docker command: + +=== "Testnet" + + ```sh + docker run --platform=linux/amd64 \ + -p 7073:7073 \ + --entrypoint /guardiand ghcr.io/wormhole-foundation/guardiand:latest \ + spy \ + --nodeKey /node.key \ + --spyRPC "[::]:7073" \ + --env testnet + ``` + Optionally, add the following flags to skip any VAAs with invalid signatures: + ```sh + --ethRPC https://sepolia.drpc.org/ + --ethContract 0x4a8bc80Ed5a4067f1CCf107057b8270E0cC11A78 + ``` + +=== "Mainnet" + + ```sh + docker run --platform=linux/amd64 \ + -p 7073:7073 \ + --entrypoint /guardiand ghcr.io/wormhole-foundation/guardiand:latest \ + spy \ + --nodeKey /node.key \ + --spyRPC "[::]:7073" \ + --env mainnet + ``` + Optionally, add the following flags to skip any VAAs with invalid signatures: + ```sh + --ethRPC https://eth.drpc.org + --ethContract 0x98f3c9e6E3fAce36bAAd05FE09d375Ef1464288B + ``` + +Once running, a [gRPC](https://grpc.io/){target=\_blank} client (i.e., your program) can subscribe to a filtered stream of messages. + +To generate a client for the gRPC service use [this proto spec file](https://github.com/wormhole-foundation/wormhole/blob/main/proto/spy/v1/spy.proto){target=\_blank}. + +!!! note + If using JavaScript/TypeScript, the [Spydk](https://www.npmjs.com/package/@certusone/wormhole-spydk){target=\_blank} makes setting up a client easier. + +## See Also + +The [Pyth Beacon](https://github.com/pyth-network/beacon){target=\_blank} provides an alternate Spy implementation that is highly available for improved performance and reliability. + +The [relayer engine](https://github.com/wormhole-foundation/relayer-engine){target=\_blank} implements a client and persistence layer for messages received from a Spy subscription. \ No newline at end of file