Overview
The Ava SDK for JavaScript/TypeScript (`ava-sdk-js`) is a comprehensive toolkit that enables developers to interact with Ava Protocol AVS.
The Ava SDK for JavaScript/TypeScript (ava-sdk-js) is a comprehensive toolkit that enables developers to interact with Ava Protocol's Actively Validated Services (AVS). This SDK serves as a type-safe wrapper around gRPC communication, simplifying the creation, management, and monitoring of blockchain automation workflows. For information about SDK architecture details, see SDK Architecture.
Purpose and Scope#
The Ava SDK JS provides developers with:
- Workflow Management: Tools to create, submit, monitor, and manage complex automation workflows
- Smart Wallet Integration: Interfaces for interacting with smart contract wallets
- Blockchain Communication: Simplified interaction with blockchain networks
- External Service Integration: Ability to connect with REST APIs, GraphQL endpoints, and custom code
- Secret Management: Secure handling of sensitive information needed by workflows
The SDK bridges the gap between client applications and AVS services, offering a type-safe, developer-friendly experience for both Node.js and browser environments.
Sources:
System Architecture#
Diagram: High-level architecture of the Ava SDK JS system
The SDK functions as a middleware between client applications and the Ava Protocol's AVS service. The Client class serves as the primary entry point, offering methods for authentication, workflow management, and service interaction.
Sources:
Repository Structure#
The ava-sdk-js repository is organized as a monorepo containing multiple packages:
Diagram: Repository structure of ava-sdk-js
The repository contains:
packages/sdk-js: Core SDK implementationpackages/types: TypeScript type definitionsgrpc_codegen: Generated gRPC client code from protocol bufferstests: Test cases and utilities- Configuration files for building, testing, and deployment
Sources:
Core Components#
The SDK consists of several key components:
Client Class#
The Client class serves as the main interface for interacting with the AVS service, providing methods for:
- Authentication (
authWithSignature,authWithAPIKey) - Workflow management (
createWorkflow,submitWorkflow,getWorkflows, etc.) - Execution monitoring (
getExecution,getExecutions) - Smart wallet management (
getWallet,getWallets) - Secret management (
createSecret,updateSecret, etc.)
Sources:
Node System#
The SDK supports various node types that can be used within workflows:
| Node Type | Purpose | Example Usage |
|---|---|---|
| ETHTransfer | Send ETH between accounts | Sending funds to a recipient |
| ContractWrite | Write to a smart contract | Creating an account, swapping tokens |
| ContractRead | Read from a smart contract | Checking balances, fetching data |
| RestAPI | Interact with REST APIs | Fetching price data, notifications |
| GraphQLQuery | Query GraphQL endpoints | Fetching on-chain data |
| Branch | Conditional execution | Implementing if/else logic |
| Filter | Filtering data | Processing array data |
| CustomCode | Running custom code | Complex computation, data transformation |
Sources:
Trigger System#
Triggers initiate workflow executions based on specific events:
| Trigger Type | Description |
|---|---|
| Block | Executes on specified block intervals |
| Cron | Executes on a cron schedule |
| FixedTime | Executes at specific times |
| Event | Executes in response to events |
Sources:
Workflow System#
Diagram: Workflow system class relationships
Workflows are the primary abstraction in the SDK, representing automated processes that execute based on triggers. Each workflow:
- Is associated with a specific smart wallet
- Contains a collection of nodes (tasks to perform)
- Has edges that define the execution flow between nodes
- Is initiated by a trigger
- Has lifecycle parameters like start time, expiry time, and execution limits
Sources:
Integration Technologies#
The SDK employs several technologies for seamless integration:
- gRPC Communication: Used for efficient communication with AVS services
- Ethers.js: Powers blockchain interactions
- TypeScript: Provides type safety throughout the SDK
- REST/GraphQL: Enables integration with external services
The SDK abstracts these technologies with a user-friendly API, allowing developers to focus on business logic rather than implementation details.
Sources:
Authentication Methods#
Diagram: Authentication flow in Ava SDK JS
The SDK supports two authentication methods:
- Signature-based: Securely authenticates using a cryptographic signature from a private key
- API Key: Authenticates using a pre-generated API key from the AVS service
After authentication, the SDK stores the auth key and uses it for all subsequent requests.
Sources:
Version and Release Management#
The SDK follows semantic versioning (major.minor.patch) and uses a structured release process:
- Development versions are published with the
devtag for testing - Release versions are created using changesets to track and document changes
- GitHub Actions automate the release process
The current release version is 1.4.0, as indicated in the CHANGELOG.md file.
Sources:
Summary#
The Ava SDK JS provides a comprehensive solution for building automated blockchain workflows using the Ava Protocol ecosystem. It abstracts the complexities of blockchain interaction, authentication, and service communication behind a type-safe, developer-friendly API. The workflow system enables complex automation tasks through a composable node-based architecture, supporting a wide range of use cases from simple token transfers to complex multi-step blockchain operations with external service integration.
Sources: