Client Interface

The Client Interface is the primary entry point for interacting with the Ava Protocol's Actively Validated Services (AVS).

The Client Interface is the primary entry point for interacting with the Ava Protocol's Actively Validated Services (AVS). It provides a comprehensive set of methods for creating, managing, and monitoring workflows, smart wallets, and secrets. This page documents the Client class, its responsibilities, and how it facilitates communication with the AVS service. For information about authentication specifically, see Authentication.

Class Hierarchy#

The Client interface consists of two main classes: BaseClient and Client. The BaseClient class handles low-level functionality such as gRPC communication and authentication, while the Client class extends BaseClient and provides higher-level methods for interacting with the AVS service.

Sources:

Client Initialization#

To interact with the Ava Protocol's AVS service, you must first initialize a Client instance. The constructor accepts a configuration object with options such as the AVS service endpoint and smart wallet factory address.

Sources:

Constructor Options#

The Client constructor accepts a configuration object with the following properties:

PropertyTypeRequiredDescription
endpointstringYesThe gRPC endpoint URL for the AVS service
factoryAddressstringNoThe address of the smart wallet factory contract

Example:

Sources:

Client Functionality#

The Client class provides methods organized into several functional categories:

Sources:

Authentication Methods#

The Client class provides two main authentication methods:

  • authWithSignature: Authenticates using a cryptographic signature from an EOA wallet
  • authWithAPIKey: Authenticates using an API key

After authentication, the returned authKey should be stored for future requests, which can be done using the setAuthKey method.

Sources:

Smart Wallet Management#

The Client class provides methods for retrieving and managing smart wallets:

  • getWallets: Retrieves a list of all smart wallets associated with the authenticated user
  • getWallet: Retrieves a specific smart wallet or creates a new one if it doesn't exist

Sources:

Workflow Management#

The Client class provides methods for creating, retrieving, and managing workflows:

  • createWorkflow: Creates a workflow object (local operation, doesn't persist to AVS)
  • submitWorkflow: Submits a workflow to the AVS service
  • getWorkflows: Retrieves workflows for specified smart wallet addresses
  • getWorkflow: Retrieves a specific workflow by ID
  • cancelWorkflow: Cancels a workflow (stops future executions)
  • deleteWorkflow: Deletes a workflow completely
  • getWorkflowCount: Retrieves the count of workflows for specified addresses

Sources:

Execution Management#

The Client class provides methods for retrieving and managing workflow executions:

  • getExecutions: Retrieves executions for specified workflows
  • getExecution: Retrieves a specific execution by ID
  • getExecutionStatus: Retrieves the status of an execution
  • getExecutionCount: Retrieves the count of executions for specified workflows
  • triggerWorkflow: Manually triggers a workflow execution

Sources:

Secret Management#

The Client class provides methods for managing secrets:

  • createSecret: Creates a new secret
  • updateSecret: Updates an existing secret
  • listSecrets: Lists all secrets accessible to the authenticated user
  • deleteSecret: Deletes a secret

Secrets can be scoped at different levels: user level (default), workflow level, or organization level.

Sources:

Communication with AVS Service#

The Client class communicates with the AVS service using gRPC. This communication is handled internally by the sendGrpcRequest method in the BaseClient class, which sets up the appropriate metadata (including authentication) and sends the request to the AVS service.

Sources:

Request Options#

Most methods in the Client class accept an optional options parameter, which can include:

PropertyTypeDescription
authKeystringAuthentication key to use for the request (overrides the client's authKey)
cursorstringPagination cursor for list operations
limitnumberMaximum number of items to return in a list operation
workflowIdstringWorkflow ID for scoped operations (used in secret management)
orgIdstringOrganization ID for scoped operations (used in secret management)

Sources:

Usage Example#

Here's a complete example of using the Client interface to authenticate, create a smart wallet, create a workflow, and submit it to the AVS service:

Sources: