A Spy, in the wormhole context, is a daemon that subscribes to the gossiped messages in the Guardian Network.

The messages available on over gossip are things like

The source for the Spy is available on Github

The Spy has no persistence layer built in, so typically its paired with something like Redis or a SQL database to record relevant messages


To start a Spy locally, run the following docker command.

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 flags to skip any VAAs with invalid signatures

--ethRPC https://sepolia.drpc.org/
--ethContract 0x4a8bc80Ed5a4067f1CCf107057b8270E0cC11A78

Once running, a gRPC 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.

If using JavaScript/TypeScript, the Spydk makes setting up a client easier.

See Also

The Pyth Beacon provides an alternate Spy implementation that is highly available for improved performance and reliability.

The relayer engine implements a client and persistence layer for messages received from a Spy subscription.

Last updated