Skip to content

Commit 016a22f

Browse files
ReisenReisen
committed
pyth_node: Add visual architecture to README.
1 parent 8536c7f commit 016a22f

File tree

17 files changed

+201
-86
lines changed

17 files changed

+201
-86
lines changed

‎pyth_node/.gitignore‎ renamed to ‎hermes/.gitignore‎

File renamed without changes.

‎pyth_node/Cargo.lock‎ renamed to ‎hermes/Cargo.lock‎

File renamed without changes.

‎pyth_node/Cargo.toml‎ renamed to ‎hermes/Cargo.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
[package]
2-
name = "pyth-node"
2+
name = "hermes"
33
version = "0.1.0"
44
edition = "2021"
55

‎hermes/README.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
Hermes
2+
================================================================================
3+
4+
Hermes is a highly available and versatile software that defines the Pyth P2P
5+
network. It also provides the public Pyth API and connects with the Pyth Geyser
6+
node software to listen for PythNet events. Hermes offers both REST and
7+
WebSocket APIs for seamless integration and interaction with the Pyth network
8+
stack. Anyone can run the Node to:
9+
10+
1. Provide their own Pyth API for interacting with the Pyth Network stack.
11+
2. Observe Pyth price updates in real-time.
12+
3. Operate alongside their PythNet validator for fully decentralized access to Pyth.
13+
14+
15+
## Architecture Overview
16+
17+
For users who simply want to run the software, this section can be skipped.
18+
However, for those interested in understanding Pyth's architecture, this
19+
section explains the old and new architecture, as well as our motivation for
20+
the design.
21+
22+
### Background
23+
24+
The Pyth project offers a cross-chain price oracle service for real-time access
25+
to current prices of real-world assets. These prices are aggregated on PythNet,
26+
where core Pyth contracts are hosted, and pricing information is generated. The
27+
Wormhole project currently sends these prices to other chains.
28+
29+
To share these prices, the Pyth project provides a standalone application
30+
called the Price Service, which queries the message API provided by Wormhole to
31+
look for Pyth prices.
32+
33+
The original communication flow can be visualized in the following graph:
34+
35+
```
36+
+--------+ +--------+ +--------+
37+
| User 3 | | User 2 | | User 1 |
38+
+--------+ +--------+ +--------+
39+
| | |
40+
| | |
41+
+--------------+--------------+
42+
|
43+
v
44+
+---------------------+
45+
| Price Service | (Weakly Decentralised)
46+
+----------+----------+
47+
|
48+
v
49+
+---------------------+
50+
| Wormhole | (Decentralised)
51+
+---------------------+
52+
^
53+
|
54+
v
55+
+ - - - - - - - - - + - - - - - - - - - - - +
56+
' PythNet '
57+
' '
58+
' +----------------+ '
59+
' | PythNet Node 1 | ------+ '
60+
' +----------------+ | '
61+
' | | '
62+
' | | '
63+
' +----------------+ | ' (Decentralised)
64+
' | PythNet Node 2 | | '
65+
' +----------------+ | '
66+
' | | '
67+
' | | '
68+
' +----------------+ +----------------+ '
69+
' | PythNet Node 3 | --- | PythNet Node 4 | '
70+
' +----------------+ +----------------+ '
71+
+ - - - - - - - - - - - - - - - - - - - - - +
72+
```
73+
74+
This design has issues due to latency and API complexity introduced by the
75+
Price Service, which acts as a middleman between the user, Wormhole, and
76+
PythNet. Additionally, it does not represent a particularly decentralized
77+
design, which was a weak point for Pyth.
78+
79+
### New Model
80+
81+
In the new model, we designed a single node-style service, Hermes, intended for
82+
direct integration into PythNet nodes. This aligns with other blockchain
83+
projects where running standard node software allows users to act as observers
84+
of the network:
85+
86+
```
87+
+--------+ +--------+ +--------+
88+
| User 3 | | User 2 | | User 1 |
89+
+--------+ +--------+ +--------+
90+
| | |
91+
| | |
92+
+--------------+--------------+
93+
|
94+
v
95+
+ - - - - - - - - - + - - - - - - - - - - - +
96+
' PythNet '
97+
' '
98+
' +----------------+ '
99+
' | PythNet Node 1 | ------+ '
100+
' +----------------+ | '
101+
' | |Hermes| | '
102+
' | +------+ | '
103+
' | | '
104+
' +----------------+ | '
105+
' | PythNet Node 2 | | '
106+
' +----------------+ | '
107+
' | |Hermes| | '
108+
' | +------+ | '
109+
' | | '
110+
' +----------------+ +----------------+ '
111+
' | PythNet Node 3 | --- | PythNet Node 4 | '
112+
' +----------------+ +----------------+ '
113+
' |Hermes| |Hermes| '
114+
' +------+ +------+ '
115+
+ - - - - - - - - - - - - - - - - - - - - - +
116+
^
117+
|
118+
v
119+
+---------------------+
120+
| Wormhole |
121+
+---------------------+
122+
```
123+
124+
125+
In this new design, the Price Service is integrated into the Hermes node
126+
service, decentralizing the API. Hermes is now also responsible for direct
127+
communication with Wormhole over P2P, which reduces latency and simplifies
128+
responsibilities.
129+
130+
The new design offers several benefits:
131+
132+
1. Hermes can participate as a P2P node in the Wormhole network directly.
133+
2. Hermes nodes form a Pyth-specific P2P network with fast communication.
134+
3. Hermes can directly observe on-chain state for faster operation.
135+
4. Hermes can have its identity tied to a PythNet node for authenticated operation.
136+
5. Data ownership is clearer with the removal of the middleman.
137+
138+
With tighter communication flow, we can define new behaviors such as
139+
Pyth-specific threshold signing, fast price accumulation with proving (due to
140+
direct node access), improved metrics and observations, and the ability for
141+
users to run observe-only Hermes nodes to watch the Pyth network directly
142+
instead of relying on a Price Service host.
143+
144+
The Hermes node architecture is as follows:
145+
146+
---
147+
148+
![image](https://user-images.githubusercontent.com/158967/225939587-f19cfe77-0393-4798-ad72-0022420d3e51.png)
149+
150+
---
151+
152+
This is more in line with other well-known projects in the blockchain and P2P
153+
space, such as Solana, Bitcoin, and Cosmos chains, where users who run the node
154+
can also act as observers with specific features disabled.
155+
156+
In our case, the node software can be run with or without a PythNet validator
157+
running due to it being designed to fetch updates from either Pyth or Geyser
158+
networks for high availability.
159+
160+
## Components
161+
162+
The Hermes Node software consists of the following components:
163+
164+
- **Wormhole P2P Connector**: Connects to the Wormhole P2P network and listens for VAAs.
165+
- **Pyth P2P Connector**: Connects to the Pyth P2P network and listens for Account Updates.
166+
- **Geyser Connector**: Connects to the Geyser node software and listens for Account Updates.
167+
- **REST API**: Provides an interface for external applications to interact with PythNet.
168+
- **Websocket API**: Offers real-time data streaming for interacting with PythNet.
169+
170+
While Hermes will always participate in the Wormhole and Pyth P2P networks, the
171+
Pyth network shares network updates on the Pyth layer and so can be run without
172+
a PythNet node running along-side it for a spy-only mode. This can be done by
173+
running without specifying `--geyser-socket`.
174+
175+
## Getting Started
176+
177+
To set up and run a Hermes node, follow the steps below:
178+
179+
1. **Install Rust**: If you haven't already, you'll need to install Rust. You can
180+
do so by following the official instructions.
181+
2. **Install Go**: If you haven't already, you'll also need to install Go. You can
182+
do so by following the official instructions.
183+
3. **Clone the repository**: Clone the Pyth Crosschain repository to your local
184+
machine using the following command:
185+
```bash
186+
git clone https://github.com/pyth-network/pyth-crosschain.git
187+
```
188+
4. **Build the project**: Navigate to the project directory and run the following command to build the project:
189+
```bash
190+
cd hermes
191+
cargo build --release
192+
```
193+
This will create a binary in the target/release directory.
194+
5. **Run the node**: To run Hermes, use the following command, replacing
195+
```bash
196+
./target/release/hermes run
197+
```
198+
Your Hermes node will now start and connect to the specified networks. You
199+
can interact with the node using the REST and Websocket APIs as described
200+
in the [API Documentation]().

‎pyth_node/buf.gen.yaml‎ renamed to ‎hermes/buf.gen.yaml‎

File renamed without changes.

‎pyth_node/build.rs‎ renamed to ‎hermes/build.rs‎

File renamed without changes.

‎pyth_node/go.mod‎ renamed to ‎hermes/go.mod‎

File renamed without changes.

‎pyth_node/go.sum‎ renamed to ‎hermes/go.sum‎

File renamed without changes.

‎pyth_node/shell.nix‎ renamed to ‎hermes/shell.nix‎

File renamed without changes.

‎pyth_node/src/config.rs‎ renamed to ‎hermes/src/config.rs‎

File renamed without changes.

0 commit comments

Comments
 (0)