Skip to content

coordinator.md

Latest commit

 

History

History
101 lines (68 loc) · 5.23 KB

coordinator.md

File metadata and controls

101 lines (68 loc) · 5.23 KB

Coordinator

The coordinator is a service that orchestrates the runtime of the Valence co-processor app. It is responsible for submitting ZK storage proof requests to the co-processor and submitting them to the configured authorizations contract on Neutron.

This document provides a developer-focused overview of the coordinator, explaining its architecture and how to customize it.

Architecture

The coordinator's code is organized into three main files:

  • main.rs: The entry point of the application.
  • strategy.rs: Defines the Strategy struct, which holds the coordinator's configuration and state.
  • engine.rs: Implements the core logic of the coordinator.

main.rs

The main.rs file is responsible for:

  1. Initializing the env-based configuration: loads environment variables from .env file configured during the setup
  2. Loading configuration: reads the neutron_strategy_config.toml file generated by the provisioner, and deserializes it into a NeutronStrategyConfig struct used to initialize the strategy
  3. Creating a Strategy instance: initializes the Strategy struct with the loaded configuration
  4. Starting the coordinator: calls the start method on the Strategy instance, which spawns a new thread for the coordinator's main loop

strategy.rs

The strategy.rs file defines the Strategy struct, which outlines the coordinator's scope of operation. This struct holds the configuration and state needed for the coordinator to run and execute the business logic, including:

  • Clients for interacting with the Neutron domain and the co-processor
  • Configuration parameters loaded from neutron_strategy_config.toml and env variables

engine.rs

The engine.rs file contains the core logic of the coordinator.

All flavors of Valence Coordinators should implement the ValenceCoordinator trait provided by the valence-coordinator-sdk. See the section below for more information about it.

The key function of a coordinator, cycle, should define a single iteration that will be executed in a continuous loop of coordinator operations. In the case of this template, it does the following:

  1. Sleep: pauses for the duration specified by the STRATEGY_TIMEOUT environment variable to prevent firing excessive number of requests with no state changes
  2. Generate Proof Request: constructs a ControllerInputs struct with the necessary parameters for the ZK proof request and serializes it as json
  3. Submit Proof Request: sends the json-encoded proof request to the co-processor using the coprocessor_client.prove function
  4. Process Proof: decodes the program and domain proofs received from the co-processor
  5. Submit Proof to Neutron for verification: calls the post_zkp_on_chain function to send the ZK proof results to the authorizations contract on the Neutron network for verification
  6. Tick Processor: ticks the processor contract on Neutron in order to process the message obtained from proof verification

Valence Coordinator SDK

The coordinator is built on top of the Valence Coordinator SDK. This SDK provides a set of utilities and abstractions to simplify the development of coordinators, including:

  • A ValenceCoordinator trait that defines the main loop of the coordinator
  • Default implementations for spawning the coordinator and handling basic lifecycle events
  • Helper functions for interacting with the Neutron network and the co-processor
  • Telemetry and logging utilities

Utilizing valence-coordinator-sdk allows developers to focus on implementing the core logic of their coordinator without having to worry about the boilerplate code required for a robust and reliable service.

Configuration

The coordinator is configured through a combination of a configuration file and environment variables.

Configuration File

The main configuration file for the coordinator is neutron_strategy_config.toml, which is generated by the provisioner. These configuration files will be committed to VCS, and should therefore not contain any sensitive information.

Currently, this file contains the following information:

  • grpc_url: The URL of the Neutron gRPC server.
  • grpc_port: The port of the Neutron gRPC server.
  • chain_id: The chain ID of the Neutron network.
  • coprocessor_app_id: The ID of the co-processor application.
  • authorizations: The address of the authorization contract.
  • processor: The address of the processor contract.
  • cw20: The address of the CW20 token contract.

Environment Variables

The following environment variables are used to configure the coordinator:

  • MNEMONIC: The mnemonic seed phrase for the on-chain signing account.
  • LABEL: A label for the strategy.
  • ERC20_ADDR: The address of the ERC20 token contract on Ethereum.
  • STRATEGY_TIMEOUT: The timeout in seconds between each cycle of the coordinator.
  • ERC20_BALANCES_STORAGE_INDEX: The storage index of the ERC20 token balances map.
  • ETH_SRC_ADDR: The Ethereum address to prove the balance of.

How to Run

To run the coordinator, execute the following command:

RUST_LOG=info cargo run --bin coordinator

It will start the coordinator, which will then run in a continuous loop until manually stopped.