feat(argus): internal interfaces and actor model #2659

tejasbadadare · 2025-05-07T05:20:41Z

Summary

Skeleton for Argus. Defines internal interfaces and sets up the actor model using ractor framework.

Note to reviewer: the interesting stuff is in actors and adapters, see the types.rs in each for the big picture.

Actors

In a nutshell, actors have independent responsibilities and can communicate via message-passing. Each actor specifies the messages it can receive and reply to.
- For example, the PythPriceListener actor is responsible for tracking off-chain prices. It can handle a GetLatestPrice(feed_ids) message, which it serves from its internal store of prices that are being polled/streamed from Hermes in the background. It can also handle a UpdateFeedIdSet(feed_ids) message, which can be used to adjust the feeds being tracked.
- Similar actors exist for the other parallel tasks that happen in the keeper: keeping active subscriptions up to date, tracking on-chain prices, etc. The orchestration is handled by the Controller actor.
See actors/types.rs for the message definitions, these enums describe the actors' interfaces.
The actors are currently spawned in keeper.rs, but this will eventually be done using ractor's Factory concept, which provides durability and lifecycle mgmt for actors.

Adapters

Interactions with external services like Hermes and the blockchain are modeled by the traits in adapters/types.rs. These traits are used by the actors, and are implemented by hermes.rs, contract.rs, etc.
- For example, the SubscriptionListener actor expects an implementor of ReadChainSubscriptions. This trait specifies get_active_subscriptions() and subscribe_to_subscription_events(), which are impl'd by PythPulse<M> in contract.rs.

How has this been tested?

Not tested yet. Next up is writing the Controller's main update loop, wiring it up to mock implementations, and ensuring the actor communication works. Then, we will implement individual actor logic, and eventually wire it up to the blockchain instead of mock adapters.

…b/argus/internal-interfaces

vercel · 2025-05-07T05:20:46Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
api-reference	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 7, 2025 9:34pm
component-library	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 7, 2025 9:34pm
entropy-debugger	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 7, 2025 9:34pm
insights	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 7, 2025 9:34pm
proposals	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 7, 2025 9:34pm
staking	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 7, 2025 9:34pm

…b/argus/internal-interfaces

ali-behjati

I like the design. I recommend adding module docs to each of your actors now that you’re establishing the structure and design of the service.

ali-behjati · 2025-05-08T09:17:24Z

apps/argus/src/actors/chain_price_listener.rs

+#[allow(dead_code)]
+pub struct ChainPriceListenerState {
+    chain_id: String,
+    contract: Arc<dyn GetChainPrices + Send + Sync>,


maybe we make a type alias for this?

(and for ChainId also)

We've got one actually, let me use that here

ali-behjati · 2025-05-08T10:08:06Z

apps/argus/src/actors/types.rs

+
+#[derive(Debug)]
+pub enum PythPriceListenerMessage {
+    GetLatestPrice(PriceId, RpcReplyPort<Option<Price>>),


I would advice against using reply between actors because on the sender side it results in an extra async blocker (other than the main message queue) and it defeats the concurrency benefits of the actors (not getting into livelocks and deadlocks). This is mostly useful if an external observer outside the actors wants to get a reply from the system.

I kind of expected to have a good construct for a reply-based mechanism using cast but couldn't find it. probably you need to pass a reference to the requesting actor (and track the request/...)

I think we had a bunch of issues with two-way communication between actors in pyth-agent. I don't know if we had a good solution to that though. maybe you simply use shared memory with a lock for these kinds of read requests?

yeah i think we should either do full actor model or full shared memory model (like hermes/agent/..)

Ah interesting. Do either of you remember why 2-way communication didn't work so well in pyth-agent?

Re @ali-bahjati about the reply-based mechanisms in ractor using cast:

cast supports fully async replies -- you can pass an ActorRef in the message, the receiver can use it to send a reply message to the sender at a later time.

call supports awaitable replies -- the receiver gets an RpcReplyPort that it can use to reply while handling the incoming message. the sender can await this reply. the receiver gets messages serially, so it doesn't need to track requests.

I find call semantics more ergonomic for certain things like fetching the latest price in the Controller, not sure how we would get it to work with cast, since we'd need the latest price in the middle of the Controller's update loop. Lmk if you guys have ideas here.

So the tradeoff of using call with GetLatestPrice operations would be that we're slightly compromising the fully async nature of the actors (but prices would still get polled in an unblocked background thread), but we still get the isolation benefits. I'm inclined to stick with call here for simplicity, but I hear you guys saying this might have been a regret in the past :) Let me know what you think.

Did some thinking, and yeah we are indeed in between paradigms here. By introducing synchronous dependencies between actors (using call,) we trade away the high concurrency of the actor model for simplicity. From what I gather, this became an issue in pyth-agent as the code evolved and added implicit dependencies between actors resulting in dead/livelocks that were hard to diagnose and fix. In Argus, our actor design is a DAG, so it felt okay to introduce these sync dependencies, but ultimately I settled on going the full shared memory model route here: #2682

jayantk

seems generally reasonable to me. I do think that revisiting the pyth-agent experience with actors is worthwhile, as that system got pretty janky over time. Probably some lessons there about how (not) to use Rust actors.

jayantk · 2025-05-08T12:42:38Z

apps/argus/src/actors/chain_price_listener.rs

+    chain_id: String,
+    contract: Arc<dyn GetChainPrices + Send + Sync>,
+    feed_ids: HashSet<PriceId>,
+    latest_prices: Arc<RwLock<HashMap<PriceId, Price>>>,


consider using DashMap as a thread-safe hashmap (instead of RwLock<HashMap<...>>)

Oo very cool, thanks for sharing

jayantk · 2025-05-08T12:50:53Z

apps/argus/src/actors/price_pusher.rs

+    backoff_policy: ExponentialBackoff,
+}
+
+pub struct PricePusher;


I think you're going to get in trouble with this Actor for two reasons: (1) the controller is running on a separate frequency, and so its checks for when to push an update are not synchronized with the actions of PricePusher. That is, the PricePusher can be trying to push an update (possibly stuck in backoff) and meanwhile the Controller is repeatedly detecting that the update needs to occur and is sending more PushPriceUpdate messages. (2) this approach serializes the updates for all subscriptions on a chain, so if we can't update subscription 1 for some reason, that blocks subscription 2 as well.

Yeah good point. We can definitely handle this better in PricePusher. I'm thinking we can spawn a task to attempt the update with backoff and track the handles. If a newer push for a subscription comes in while the last one is stuck in backoff, we can cancel the outstanding task and spawn a new one. This also means the actor's handle function doesn't block, and we can multiple push attempts for different subscriptions active at a time.

jayantk · 2025-05-08T13:00:36Z

apps/argus/src/actors/types.rs

+
+#[derive(Debug)]
+pub enum PythPriceListenerMessage {
+    GetLatestPrice(PriceId, RpcReplyPort<Option<Price>>),


I think we had a bunch of issues with two-way communication between actors in pyth-agent. I don't know if we had a good solution to that though. maybe you simply use shared memory with a lock for these kinds of read requests?

tejasbadadare added 7 commits April 28, 2025 17:54

refactor: remove fortuna/entropy functionality

7f152bb

temp

970b63c

temp2

8a997c6

wip

a767fee

Merge branch 'main' of github.com:pyth-network/pyth-crosschain into t…

5a66d0d

…b/argus/internal-interfaces

actors work now

b7b9706

organize, clean up

61f0030

Merge branch 'main' of github.com:pyth-network/pyth-crosschain into t…

12b5998

…b/argus/internal-interfaces

vercel bot deployed to Preview – entropy-debugger May 7, 2025 18:07 View deployment

vercel bot deployed to Preview – api-reference May 7, 2025 18:08 View deployment

vercel bot deployed to Preview – staking May 7, 2025 18:08 View deployment

vercel bot deployed to Preview – insights May 7, 2025 18:09 View deployment

vercel bot deployed to Preview – component-library May 7, 2025 18:09 View deployment

vercel bot deployed to Preview – proposals May 7, 2025 18:11 View deployment

use types from abigen

11a0dc6

vercel bot deployed to Preview – entropy-debugger May 7, 2025 21:30 View deployment

vercel bot deployed to Preview – api-reference May 7, 2025 21:31 View deployment

vercel bot deployed to Preview – component-library May 7, 2025 21:31 View deployment

vercel bot deployed to Preview – staking May 7, 2025 21:31 View deployment

vercel bot deployed to Preview – insights May 7, 2025 21:32 View deployment

vercel bot deployed to Preview – proposals May 7, 2025 21:34 View deployment

ali-behjati reviewed May 8, 2025

View reviewed changes

jayantk reviewed May 8, 2025

View reviewed changes

tejasbadadare mentioned this pull request May 12, 2025

feat(argus): internal interfaces and shared memory model #2682

Merged

3 tasks

tejasbadadare closed this May 12, 2025

feat(argus): internal interfaces and actor model #2659

feat(argus): internal interfaces and actor model #2659

Uh oh!

Conversation

tejasbadadare commented May 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Actors

Adapters

How has this been tested?

Uh oh!

vercel bot commented May 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ali-behjati left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jayantk left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tejasbadadare commented May 7, 2025 •

edited

Loading

vercel bot commented May 7, 2025 •

edited

Loading