Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

refreshes spy page, updates llms #322

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

refreshes spy page, updates llms #322

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
899776a
refreshes spy page, updates llms
dawnkelly09 Mar 24, 2025
ce9021f
grammarly, llms
dawnkelly09 Mar 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 69 additions & 16 deletions learn/infrastructure/spy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,31 +5,84 @@ description: Discover Wormhole's Spy daemon, which subscribes to gossiped messag

# Spy

## Introduction

In Wormhole’s ecosystem, the _Spy_ is a daemon, a continuously running background process that monitors messages within the Guardian Network. Unlike Guardians, Spies don’t perform validation; instead, they serve as an interface for observing the network’s message traffic, enabling applications and users to access live data transmitted over Wormhole.
In Wormhole's ecosystem, the _Spy_ is a daemon, a continuously running background process that monitors messages within the Guardian Network. Unlike Guardians, Spies don't perform validation; instead, they serve as an interface for observing the network's message traffic, enabling applications and users to access live data transmitted over Wormhole.

The primary purpose of a Spy is to subscribe to the gossiped messages across the Guardian Network, tracking key message types that allow integrators and applications to monitor real-time network activity without directly engaging in consensus operations.

## Key Features of the Spy
This page provides a comprehensive guide to Spies within the Wormhole network, describing their key features and role in facilitating multichain processes.

## Key Features

### Message Categories
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Message Categories as a key feature seems unintuitive to me. When I look at this and put myself in the shoes of someone who doesn't know anything about this stuff yet or someone who is just scanning the page, this doesn't standalone well on it's own.

Like what about message categories is important? It's that the spy can monitor these different categories of messages, so I feel like we should capture that

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah agree, i think we can just keep key features

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Idk. I just kind of shuffled around what was already there. This is the current version:

https://wormhole.com/docs/learn/infrastructure/spy/

So I guess I could use some guidance on:

  • Which headings are preferred. Right now it's like this:

h2 Introduction
h2 Key Features of the Spy
h3 Monitor Spy-Accessible Messages
h2 Integrator Use Case
h2 Resources (now is Additional Resources with the cards)

So, is it preferred to switch back to that (with the exception of the Resources thing), or is there something else that would be better?

To me, it didn't make sense to say "Key Features" and then only one thing under it (Monitor Spy-Accessible Messages) so I tried to move some stuff around. I can definitely see where Integrator Use Case should come back out to it's own h2. Let me know your thoughts.

Copy link
Collaborator

@eshaben eshaben Mar 26, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Which headings are preferred

The only headers I had a problem with are Message Categories and then bumping Integrator Use Cases out to it's own H2, because it's not really a key feature. So IMO everything else you have is fine.

So, is it preferred to switch back to that (with the exception of the Resources thing), or is there something else that would be better?

I don't think there's a need to switch it back. I just think we need to evaluate the Key Features / Message Categories sections.

To me, it didn't make sense to say "Key Features" and then only one thing under it (Monitor Spy-Accessible Messages) so I tried to move some stuff around

That's fair. The point I was trying to make about Message Categories is that, when considering it as a key feature, the value isn't that these categories exist — it's that the Spy can monitor them. So the specific categories it observes feel more like supporting detail than something that belongs in the Key Features section. So perhaps we just get rid of the key feature section. Or maybe we explore what else the key features are. See my answer I got from AI: Spy Key Features Gist - cc: @ilariae @martin0995 to verify

So I'd probably suggest something like this:

h1 Spy - basic introduction, what the spy is
h2 Key Features - why it's useful - insert features list like the one I got from AI
h2 Integrator Use Cases - how can it be used
h2 Observable Message Categories - with base understanding established, what messages can be observed
h2 Additional Resources


Spies can access the following categories of messages shared over the gossip protocol:

- [Verifiable Action Approvals (VAAs)](/docs/learn/infrastructure/vaas/){target=\_blank} - packets of multichain data

- The Spy can detect whether a VAA has been approved by the Guardian Network, making it a valuable tool for applications needing real-time multichain verification

- [Observations](/docs/learn/glossary/#observation){target=\_blank} - emitted by Wormhole's core contracts, observations are picked up by the Guardians and relayed across the network

- Spies allow users to monitor these messages, adding transparency and insight into blockchain events

- [Guardian heartbeats](/docs/learn/glossary/#heartbeat){target=\_blank} - heartbeat messages represent Guardian node status

- By monitoring heartbeats, a Spy can signal the liveness and connectivity of Guardians in the network

### Integrator Use Case
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

use cases doesn't seem like it belongs under key features


The Spy provides a valuable mechanism for integrators to observe real-time network activity in the Guardian Network without directly engaging in validation or consensus. By running a Spy, integrators can track multichain events and message flows — such as VAAs, observations, and Guardian heartbeats — to monitor network activity essential to their applications.

This monitoring capability is especially beneficial for applications that need immediate insights into multichain data events. Integrators can run a Spy to ensure their applications are promptly informed of message approvals, observations, or Guardian liveness signals, supporting timely and responsive app behavior without additional overhead on network resources.

## Additional Resources

<div class="grid cards" markdown>

- :octicons-code-16:{ .lg .middle } **Spy Source Code**

---

To see the source code for the Go implementation of the Spy, visit the `wormhole` repository on GitHub.

[:custom-arrow: View the Source Code](https://github.com/wormhole-foundation/wormhole/blob/main/node/cmd/spy/spy.go){target=\_blank}

- :octicons-code-16:{ .lg .middle } **Alternative Implementation**

---

Visit the `beacon` repository on GitHub to learn more about Beacon, an alternative highly available, reduced-latency version of the Wormhole Spy.

[:custom-arrow: Get Started with Pyth Beacon](https://github.com/pyth-network/beacon)

- :octicons-code-16:{ .lg .middle } **Discover Wormhole Queries**
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe use a book icon here instead to help create more of a distinction between Discover Wormhole Queries and Use Wormhole Queries


---

For an alternative option to on-demand access to Guardian-attested multichain data, see the Wormhole Queries page. Queries provide a simple, REST endpoint style developer experience.

[:custom-arrow: Explore Queries](/docs/build/queries/overview/)

</div>

## Next Steps

<div class="grid cards" markdown>

### Monitor Spy-Accessible Messages
- :octicons-code-16:{ .lg .middle } **Run a Spy**

Spies can access the following categories of messages shared over the gossip protocol::
---

- [Verifiable Action Approvals (VAAs)](/docs/learn/infrastructure/vaas/){target=\_blank} - packets of cross-chain data. The Spy can detect whether a VAA has been approved by the Guardian Network, making it a valuable tool for applications needing real-time cross-chain verification
- [Observations](/docs/learn/glossary/#observation){target=\_blank} - emitted by Wormhole’s core contracts, observations are picked up by the Guardians and relayed across the network. Spies allow users to monitor these messages, adding transparency and insight into blockchain events
- [Guardian heartbeats](/docs/learn/glossary/#heartbeat){target=\_blank} - heartbeat messages represent Guardian node statusn. By monitoring heartbeats, a Spy can signal the liveness and connectivity of Guardians in the network
Learn how to run the needed infrastructure to spin up a Spy daemon locally and subscribe to a stream of Verifiable Action Approvals (VAAs).

## Integrator Use Case
[:custom-arrow: Spin Up a Spy](/docs/infrastructure/spy/run-spy/){target=\_blank}

The Spy provides a valuable mechanism for integrators to observe real-time network activity in the Guardian Network without directly engaging in validation or consensus. By running a Spy, integrators can track cross-chain events, and message flows — such as VAAs, observations, and Guardian heartbeats — to monitor network activity essential to their applications.
- :octicons-code-16:{ .lg .middle } **Use Queries**

This monitoring capability is especially beneficial for applications that need immediate insights into cross-chain data events. Integrators can run a Spy to ensure their applications are promptly informed of message approvals, observations, or Guardian liveness signals, supporting timely and responsive app behavior without additional overhead on network resources.
---

## Resources
For access to real-time network data without infrastructure overhead, follow this guide and use Wormhole Query to construct a query, make a request, and verify the response.

For more information, you can check out the following resources:
[:custom-arrow: Get Started with Queries](/docs/build/queries/use-queries/)

- The source code for the Go implementation of the Spy is available on [GitHub](https://github.com/wormhole-foundation/wormhole/blob/main/node/cmd/spy/spy.go){target=\_blank}
- To find out how to [start and run a Spy](/docs/infrastructure/spy/run-spy/){target=\_blank}, refer to the infrastructure section. This setup enables integrators to create a custom endpoint that applications can use to observe message flows in the Guardian Network, providing greater flexibility and control over cross-chain monitoring
</div>
85 changes: 69 additions & 16 deletions llms.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15668,34 +15668,87 @@ description: Discover Wormhole's Spy daemon, which subscribes to gossiped messag

# Spy

## Introduction

In Wormhole’s ecosystem, the _Spy_ is a daemon, a continuously running background process that monitors messages within the Guardian Network. Unlike Guardians, Spies don’t perform validation; instead, they serve as an interface for observing the network’s message traffic, enabling applications and users to access live data transmitted over Wormhole.
In Wormhole's ecosystem, the _Spy_ is a daemon, a continuously running background process that monitors messages within the Guardian Network. Unlike Guardians, Spies don't perform validation; instead, they serve as an interface for observing the network's message traffic, enabling applications and users to access live data transmitted over Wormhole.

The primary purpose of a Spy is to subscribe to the gossiped messages across the Guardian Network, tracking key message types that allow integrators and applications to monitor real-time network activity without directly engaging in consensus operations.

## Key Features of the Spy
This page provides a comprehensive guide to Spies within the Wormhole network, describing their key features and role in facilitating multichain processes.

## Key Features

### Monitor Spy-Accessible Messages
### Message Categories

Spies can access the following categories of messages shared over the gossip protocol::
Spies can access the following categories of messages shared over the gossip protocol:

- [Verifiable Action Approvals (VAAs)](/docs/learn/infrastructure/vaas/){target=\_blank} - packets of cross-chain data. The Spy can detect whether a VAA has been approved by the Guardian Network, making it a valuable tool for applications needing real-time cross-chain verification
- [Observations](/docs/learn/glossary/#observation){target=\_blank} - emitted by Wormhole’s core contracts, observations are picked up by the Guardians and relayed across the network. Spies allow users to monitor these messages, adding transparency and insight into blockchain events
- [Guardian heartbeats](/docs/learn/glossary/#heartbeat){target=\_blank} - heartbeat messages represent Guardian node statusn. By monitoring heartbeats, a Spy can signal the liveness and connectivity of Guardians in the network
- [Verifiable Action Approvals (VAAs)](/docs/learn/infrastructure/vaas/){target=\_blank} - packets of multichain data

## Integrator Use Case
- The Spy can detect whether a VAA has been approved by the Guardian Network, making it a valuable tool for applications needing real-time multichain verification

The Spy provides a valuable mechanism for integrators to observe real-time network activity in the Guardian Network without directly engaging in validation or consensus. By running a Spy, integrators can track cross-chain events, and message flows — such as VAAs, observations, and Guardian heartbeats — to monitor network activity essential to their applications.
- [Observations](/docs/learn/glossary/#observation){target=\_blank} - emitted by Wormhole's core contracts, observations are picked up by the Guardians and relayed across the network

This monitoring capability is especially beneficial for applications that need immediate insights into cross-chain data events. Integrators can run a Spy to ensure their applications are promptly informed of message approvals, observations, or Guardian liveness signals, supporting timely and responsive app behavior without additional overhead on network resources.
- Spies allow users to monitor these messages, adding transparency and insight into blockchain events

## Resources
- [Guardian heartbeats](/docs/learn/glossary/#heartbeat){target=\_blank} - heartbeat messages represent Guardian node status

- By monitoring heartbeats, a Spy can signal the liveness and connectivity of Guardians in the network

### Integrator Use Case

The Spy provides a valuable mechanism for integrators to observe real-time network activity in the Guardian Network without directly engaging in validation or consensus. By running a Spy, integrators can track multichain events and message flows — such as VAAs, observations, and Guardian heartbeats — to monitor network activity essential to their applications.

This monitoring capability is especially beneficial for applications that need immediate insights into multichain data events. Integrators can run a Spy to ensure their applications are promptly informed of message approvals, observations, or Guardian liveness signals, supporting timely and responsive app behavior without additional overhead on network resources.

## Additional Resources

<div class="grid cards" markdown>

- :octicons-code-16:{ .lg .middle } **Spy Source Code**

---

To see the source code for the Go implementation of the Spy, visit the `wormhole` repository on GitHub.

[:custom-arrow: View the Source Code](https://github.com/wormhole-foundation/wormhole/blob/main/node/cmd/spy/spy.go){target=\_blank}

- :octicons-code-16:{ .lg .middle } **Alternative Implementation**

---

Visit the `beacon` repository on GitHub to learn more about Beacon, an alternative highly available, reduced-latency version of the Wormhole Spy.

[:custom-arrow: Get Started with Pyth Beacon](https://github.com/pyth-network/beacon)

For more information, you can check out the following resources:
- :octicons-code-16:{ .lg .middle } **Discover Wormhole Queries**

- The source code for the Go implementation of the Spy is available on [GitHub](https://github.com/wormhole-foundation/wormhole/blob/main/node/cmd/spy/spy.go){target=\_blank}
- To find out how to [start and run a Spy](/docs/infrastructure/spy/run-spy/){target=\_blank}, refer to the infrastructure section. This setup enables integrators to create a custom endpoint that applications can use to observe message flows in the Guardian Network, providing greater flexibility and control over cross-chain monitoring
---

For an alternative option to on-demand access to Guardian-attested multichain data, see the Wormhole Queries page. Queries provide a simple, REST endpoint style developer experience.

[:custom-arrow: Explore Queries](/docs/build/queries/overview/)

</div>

## Next Steps

<div class="grid cards" markdown>

- :octicons-code-16:{ .lg .middle } **Run a Spy**

---

Learn how to run the needed infrastructure to spin up a Spy daemon locally and subscribe to a stream of Verifiable Action Approvals (VAAs).

[:custom-arrow: Spin Up a Spy](/docs/infrastructure/spy/run-spy/){target=\_blank}

- :octicons-code-16:{ .lg .middle } **Use Queries**

---

For access to real-time network data without infrastructure overhead, follow this guide and use Wormhole Query to construct a query, make a request, and verify the response.

[:custom-arrow: Get Started with Queries](/docs/build/queries/use-queries/)

</div>
--- END CONTENT ---

Doc-Content: https://wormhole.com/docs/learn/infrastructure/vaas/
Expand Down