Ava SDK for JavaScript/TypeScript

@avaprotocol/sdk-js is the official TypeScript SDK for Ava Protocol's AVS.

3.0.0 is a REST-only rewrite. The 2.x line spoke gRPC; the 3.x line speaks the aggregator gateway's /api/v1/... REST API. The 4.0.0-dev.X versions on npm are pre-release iterations of this rewrite that we ultimately stabilized as 3.0.0 to keep semver continuity from 2.x — see CHANGELOG.md for the full rationale. The README sections below still describe the 2.x gRPC client; an updated quick-start for the 3.x REST client is tracked in a follow-up doc PR.

[2.x — archived] @avaprotocol/sdk-js was a simple, type-safe wrapper around gRPC designed to simplify integration with Ava Protocol's AVS. It enabled developers to interact with Ava Protocol efficiently, whether on the client-side or server-side, and provided full TypeScript support for a seamless development experience.

Archived 2.x documentation

The sections below describe the 2.x gRPC client and are kept for users still on that line. The 3.x REST client documentation is tracked in a follow-up doc PR; in the meantime see the CHANGELOG for what changed between 2.x and 3.x.

Features

• Type-Safe SDK: Automatically generated TypeScript types from gRPC protocol buffers ensure type safety and reduce errors during development.
• Seamless Integration: Works in both Node.js and browser environments, optimized for frameworks like Next.js.
• Easy to Use: Abstracts the complexity of gRPC with a simple JavaScript/TypeScript API.
• Efficient Communication: Leverages gRPC for fast, efficient communication with Ava Protocol’s AVS (Actively Validated Services).

Installation

To install @avaprotocol/sdk-js, run the following command:

npm install @avaprotocol/sdk-js

Or with Yarn:

yarn add @avaprotocol/sdk-js

Getting Started

Here’s a quick example of how to use the SDK to get started with Ava Protocol:

import { Client } from "@avaprotocol/sdk-js";
import { getServerSession } from "next-auth";
import { isAuthKeyValid } from "./utils";
import { authOptions } from "./auth/[...nextauth]/route";

let avaClient: Client | null = null;
const EXPIRED_AT = Math.floor(Date.now() / 1000) + 24 * 60 * 60; // 24 hours from now

async function initializeClient() {
  if (avaClient) return avaClient;

  if (!process.env.AVS_ENDPOINT) {
    throw new Error("AVS_ENDPOINT is not set in environment variables.");
  }

  avaClient = new Client({
    endpoint: process.env.AVS_ENDPOINT,
  });

  return avaClient;
}

/**
 * Get the client instance, lazy initialize it if it's not initialized yet
 * @returns
 */
export async function getClient() {
  if (avaClient) {
    return avaClient;
  }

  return await initializeClient();
}

/**
 * Get the auth key using authWithAPIKey() for a wallet address before user signs in with a wallet signature
 * @param walletAddress
 * @returns
 */
async function getPresignAuthKey(walletAddress: string): Promise<string> {
  const client = await getClient();

  // Since we almost certainly need this env variable, we throw an error if it's not set
  if (!process.env.AVS_API_KEY) {
    throw new Error("AVS_API_KEY is not set in environment variables.");
  }

  const resp = await client.authWithAPIKey(
    walletAddress,
    process.env.AVS_API_KEY,
    EXPIRED_AT
  );
  return resp.authKey;
}

/**
 * Get the auth key for a wallet address
 * First checks if the current session contains a valid auth key
 * If not, it will get the auth key using authWithAPIKey() for the wallet address
 * @param walletAddress
 * @returns
 */
export async function getAuthKey(
  walletAddress: string | undefined
): Promise<string | undefined> {
  const session = await getServerSession(authOptions);

  if (session?.user?.authKey) {
    if (isAuthKeyValid(session?.user?.authKey)) {
      return session?.user?.authKey;
    } else {
      console.warn(
        `AuthKey is found for ${session?.user?.walletAddress} in session, but expired. Atempting to use authWithAPIKey`
      );
    }
  }

  if (walletAddress) {
    return await getPresignAuthKey(walletAddress);
  }

  return undefined;
}

Event trigger output: value vs valueFormatted

When an EventTrigger matches an ERC-20 Transfer, the operator's shared event enrichment publishes both a raw and a formatted amount on the trigger's output data:

| Field | Type | Meaning | Use for | |---|---|---|---| | data.value | string | Raw uint256 base units (e.g. "1500000" for 1.5 USDC) | Math, encoding ERC-20 calldata, BigInt operations | | data.valueFormatted | string | Decimal-applied display string (e.g. "1.5") | Telegram/email messages, UI rendering | | data.tokenSymbol | string | Token symbol from contract metadata | Display | | data.tokenDecimals | number | Token decimals from contract metadata | Reference |

Breaking change in operator output (EigenLayer-AVS PR #509): Prior operator versions populated data.value with the decimal-formatted amount when token metadata was available. After PR #509, data.value is always raw uint256 base units, and data.valueFormatted is the new field for human-readable amounts. SDK consumers that read data.value for display must migrate to data.valueFormatted.

Do not use MethodCallType.applyToFields: ["Transfer.value"] for ERC-20 Transfer events — the enrichment is now automatic and applyToFields would be redundant (and may double-format). applyToFields remains the correct mechanism for every other use case where shared enrichment does not pre-compute a formatted value (Chainlink AnswerUpdated current/answer, ERC-20 totalSupply, generic contract read fields, etc.).

Contributing

We welcome contributions! Feel free to submit pull requests or open issues for any bugs or feature requests.

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for more details.