Skip to content

Commit 3f56b30

Browse files
ReisenReisen
authored
[hermes] Rename from price service and add README. (#705)
* pyth-node: rename from price service and document * pyth_node: Add visual architecture to README.
1 parent a9f5cfc commit 3f56b30

File tree

16 files changed

+233
-33
lines changed

16 files changed

+233
-33
lines changed

‎price_service/server-rust/.gitignore renamed to ‎hermes/.gitignore

File renamed without changes.

‎price_service/server-rust/Cargo.lock renamed to ‎hermes/Cargo.lock

Lines changed: 32 additions & 32 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

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

‎price_service/server-rust/buf.gen.yaml renamed to ‎hermes/buf.gen.yaml

File renamed without changes.

‎price_service/server-rust/build.rs renamed to ‎hermes/build.rs

File renamed without changes.

‎price_service/server-rust/go.mod renamed to ‎hermes/go.mod

File renamed without changes.

‎price_service/server-rust/go.sum renamed to ‎hermes/go.sum

File renamed without changes.

‎price_service/server-rust/shell.nix renamed to ‎hermes/shell.nix

File renamed without changes.

‎price_service/server-rust/src/config.rs renamed to ‎hermes/src/config.rs

File renamed without changes.

0 commit comments

Comments
 (0)