Run a Spy

Introduction

The Spy is a lightweight component in the Wormhole infrastructure designed to listen for and forward messages (Verifiable Action Approvals (VAAs)) published on the Wormhole network. Running a Spy locally allows developers to subscribe to a filtered stream of these messages, facilitating the development of custom relayers or other integrations with Wormhole.

For a more comprehensive understanding of the Spy and its role within the Wormhole ecosystem, refer to the Spy Documentation.

How to Start a Spy

To start a Spy locally, run the following Docker command:

MainnetTestnet

docker run --pull=always --platform=linux/amd64 \
    -p 7073:7073 \
    --entrypoint /guardiand ghcr.io/wormhole-foundation/guardiand:latest \
    spy \
    --nodeKey /node.key \
    --spyRPC "[::]:7073" \
    --env mainnet

docker run --pull=always --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:

MainnetTestnet

--ethRPC https://eth.drpc.org
--ethContract 0x98f3c9e6E3fAce36bAAd05FE09d375Ef1464288B

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

Subscribe to Filtered VAAs

Once running, a gRPC client (i.e., your program) can subscribe to a filtered stream of messages (VAAs).

Use this proto-spec file to generate a client for the gRPC service.

Note

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

Data Persistence

The Spy does not have a built-in persistence layer, so it is typically paired with something like Redis or an SQL database to record relevant messages.

The persistence layer needs to implement the appropriate interface. For example, you can check out the Redis interface used by the Relayer Engine, a package that implements a client and persistence layer for messages received from a Spy subscription.