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:

1. Workflow Management: Tools to create, submit, monitor, and manage complex automation workflows
2. Smart Wallet Integration: Interfaces for interacting with smart contract wallets
3. Blockchain Communication: Simplified interaction with blockchain networks
4. External Service Integration: Ability to connect with REST APIs, GraphQL endpoints, and custom code
5. 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:

• README.md5-11
• packages/sdk-js/package.json3-4

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:

• README.md30-32
• tests/templates.ts3-7

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 implementation
• packages/types: TypeScript type definitions
• grpc_codegen: Generated gRPC client code from protocol buffers
• tests: Test cases and utilities
• Configuration files for building, testing, and deployment

Sources:

• package.json11-13
• tsconfig.json10-22

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:

• README.md30-32
• package.json22-33

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:

• tests/templates.ts28-153

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:

• tests/templates.ts190-218
• tests/templates.ts225-230

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:

• tests/templates.ts180-200

Integration Technologies#

The SDK employs several technologies for seamless integration:

1. gRPC Communication: Used for efficient communication with AVS services
2. Ethers.js: Powers blockchain interactions
3. TypeScript: Provides type safety throughout the SDK
4. 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:

• packages/sdk-js/package.json30-39
• README.md2-3

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:

• package.json22-24
• config/aggregator.yaml20-21

Version and Release Management#

The SDK follows semantic versioning (major.minor.patch) and uses a structured release process:

1. Development versions are published with the dev tag for testing
2. Release versions are created using changesets to track and document changes
3. GitHub Actions automate the release process

The current release version is 1.4.0, as indicated in the CHANGELOG.md file.

Sources:

• packages/sdk-js/package.json3
• packages/sdk-js/CHANGELOG.md3-13
• README.md164-173

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:

• README.md1-11
• packages/sdk-js/package.json1-5