gRPC Communication

This page documents how the AVA SDK uses gRPC (Google Remote Procedure Call) to communicate with the Actively Validated Services (AVS). It covers the Protocol Buffer definitions, message types, service interfaces, and how these elements enable the SDK to interact with the AVS backend.

For information about the client interface that abstracts these gRPC communications, see Client Interface.

Overview of gRPC in AVA SDK#

The AVA SDK uses gRPC as its primary communication mechanism with the AVS backend. gRPC is a high-performance, language-agnostic RPC framework that uses Protocol Buffers (protobuf) for serializing structured data. This approach provides several advantages:

1. Strongly typed interfaces - The service interface is defined in .proto files, ensuring consistent communication between client and server
2. Efficient serialization - Protocol Buffers provide compact binary serialization
3. Code generation - Automatically generated client code reduces development effort and errors
4. Multiple language support - Allows for consistent communication between components written in different languages

The AVA SDK's gRPC implementation enables all the core functionality, including authentication, workflow management, smart wallet operations, and secret management.

Sources:

• grpc_codegen/avs.proto1-777

Protocol Buffer Schema#

The Protocol Buffer schema defines both the data structures and service interfaces used for communication between the SDK and AVS service. The schema is defined in avs.proto and is used to generate the TypeScript/JavaScript client code.

Message Types#

The schema defines several key message types that form the foundation of the communication:

Task-Related Messages#

• Task - Represents a workflow with nodes, edges, and triggers
• TaskNode - Represents a node in a workflow with different task types like ETH transfers, contract interactions, etc.
• TaskEdge - Defines connections between nodes in a workflow
• TaskTrigger - Specifies conditions for workflow activation (time-based, event-based, etc.)
• Execution - Records execution details of a workflow, including steps, status, and outputs

Sources:

• grpc_codegen/avs.proto400-424
• grpc_codegen/avs.proto276-299
• grpc_codegen/avs.proto269-274
• grpc_codegen/avs.proto61-78
• grpc_codegen/avs.proto302-397

Node Type Messages#

The protocol defines various node types that can be used in workflows:

• ETHTransferNode - For transferring ETH
• ContractWriteNode - For writing to smart contracts
• ContractReadNode - For reading from smart contracts
• GraphQLQueryNode - For querying GraphQL endpoints
• RestAPINode - For interacting with REST APIs
• CustomCodeNode - For executing custom JavaScript code
• BranchNode - For conditional branching in workflows
• FilterNode - For filtering data in workflows
• LoopNode - For iterating over data in workflows

Sources:

• grpc_codegen/avs.proto121-267

Trigger-Related Messages#

The schema defines several trigger types that determine when workflows are executed:

• FixedTimeCondition - Triggers at specific epochs
• CronCondition - Triggers based on cron schedules
• BlockCondition - Triggers at specific block intervals
• EventCondition - Triggers based on blockchain events

Sources:

• grpc_codegen/avs.proto15-58

Service Definition#

The protocol defines a service called Aggregator which provides methods for interacting with the AVS backend:

The service methods are organized into several functional categories:

Authentication#

• GetKey - Exchanges credentials for an authentication key

Smart Wallet Operations#

• GetNonce - Retrieves the current nonce for a wallet
• GetWallet - Gets wallet information
• ListWallets - Lists all wallets for the authenticated user

Task/Workflow Management#

• CreateTask - Creates a new workflow
• ListTasks - Lists workflows with pagination
• GetTask - Gets detailed information about a specific workflow
• CancelTask - Cancels a workflow
• DeleteTask - Deletes a workflow
• TriggerTask - Manually triggers a workflow execution

Execution Management#

• ListExecutions - Lists executions for workflows with pagination
• GetExecution - Gets detailed information about a specific execution
• GetExecutionStatus - Gets the status of an execution

Secret Management#

• CreateSecret - Creates a new secret
• ListSecrets - Lists all secrets
• DeleteSecret - Deletes a secret
• UpdateSecret - Updates an existing secret

Metrics#

• GetWorkflowCount - Gets the count of workflows
• GetExecutionCount - Gets the count of executions

Sources:

• grpc_codegen/avs.proto653-703

gRPC Client Usage#

The AVA SDK uses the generated gRPC client to communicate with the AVS backend. The generated client code is in the grpc_codegen directory and includes TypeScript type definitions.

Client Initialization#

The gRPC client is initialized with the endpoint of the AVS service. The initialization typically happens in the Client class, which abstracts the gRPC communication from the application code.

Sources:

• grpc_codegen/avs_grpc_pb.js3-14
• grpc_codegen/avs_grpc_pb.js574

Authentication Flow#

Authentication is a prerequisite for most operations. The SDK supports authentication using either signature-based authentication or API key authentication.

Sources:

• grpc_codegen/avs.proto532-542
• grpc_codegen/avs_grpc_pb.js343-354

Task/Workflow Management#

The SDK provides methods for creating, listing, and managing workflows through the gRPC client.

Sources:

• grpc_codegen/avs.proto390-466
• grpc_codegen/avs_grpc_pb.js389-422

Execution Management#

The SDK provides methods for listing and retrieving execution details through the gRPC client.

Sources:

• grpc_codegen/avs.proto511-530
• grpc_codegen/avs_grpc_pb.js423-454

Secret Management#

The SDK provides methods for creating, listing, updating, and deleting secrets through the gRPC client.

Sources:

• grpc_codegen/avs.proto610-640
• grpc_codegen/avs_grpc_pb.js492-539

Error Handling#

The SDK handles various errors that may occur during gRPC communication. The protocol defines an Error enum with specific error codes:

enum Error {
  UnknowError              = 0;
  RpcNodeError             = 1000;
  StorageUnavailable       = 2000;
  StorageWriteError        = 2001;
  SmartWalletRpcError      = 6000;
  SmartWalletNotFoundError = 6001;
  TaskDataCorrupted        = 7000;
  TaskDataMissingError     = 7001;
  TaskTriggerError         = 7003;
}

Common error scenarios and handling strategies include:

Sources:

• grpc_codegen/avs.proto81-101

Code Generation#

The Protocol Buffer compiler (protoc) generates JavaScript and TypeScript code from the .proto files. The generated code includes:

1. Message classes - Classes for each message type defined in the proto file
2. Service interfaces - Interfaces for the service methods
3. Client implementation - Implementation of the gRPC client

The JavaScript code is in avs_pb.js and avs_grpc_pb.js, and the TypeScript definitions are in avs_pb.d.ts and avs_grpc_pb.d.ts.

Sources:

• grpc_codegen/avs_pb.js1-13
• grpc_codegen/avs_pb.d.ts1-11
• grpc_codegen/avs_grpc_pb.js1-9
• grpc_codegen/avs_grpc_pb.d.ts1-12

Local Development with gRPC#

For local development, you can run the AVS service in a Docker container. The repository includes a docker-compose.yml file for setting up a local development environment:

This sets up a local AVS service that the SDK can connect to during development and testing.

Sources:

• docker-compose.yml1-12

Conclusion#

The AVA SDK uses gRPC to provide a robust, efficient, and type-safe communication layer with the AVS backend. The Protocol Buffer schema defines the message types and service interfaces, and the generated client code makes it easy to interact with the AVS service.

Understanding the gRPC communication layer is essential for working with the AVA SDK, as it underpins all the functionality provided by the SDK. The generated client code abstracts much of the complexity, but knowing the underlying message types and service methods can be helpful for debugging and extending the SDK.