ava-sdk-js
is a simple, type-safe wrapper around gRPC designed to simplify integration with Ava Protocol's AVS. It enables developers to interact with Ava Protocol efficiently, whether on the client-side or server-side, and provides full TypeScript support for a seamless development experience.
- 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.
- User-friendly: Simplifies the intricacies of gRPC with an intuitive JavaScript/Typescript interface.
- Efficient Communication: Leverages gRPC for fast, efficient communication with Ava Protocol's AVS (Actively Validated Services).
To install ava-sdk-js
, run the following command:
npm install ava-sdk-js
Or with Yarn:
yarn add ava-sdk-js
Here's a quick example of how to use the SDK to get started with Ava Protocol:
import { AvaSDK } from "ava-sdk-js";
yarn # install grpc-tools, etc. as dev dependencies
Then, run the following command to regenerate the types:
# download the latest .proto file from https://github.com/AvaProtocol/EigenLayer-AVS
yarn run proto-download
# Generate the TypeScript types and gRPC code based on the downloaded .proto file
yarn run protoc-gen
# Build the source files in to ./dist folder
yarn run build
To ensure the SDK is functioning correctly, we have a comprehensive test suite. Follow these steps to run the tests:
-
Make sure all dependencies are installed, and build the project. Tests are run against the files in the
/dist
foldernpm install npm run build
-
Before running the e2e tests, make sure to configure the required environment variables in your
.env.test
file, based on the.env.example
file. -
Bring up a locally environment for aggregator
docker compose up -d --pull always
By default the above command will pull the docker image of the latest commit on the
main
branch of https://github.com/AvaProtocol/EigenLayer-AVS. Alternatively, we could also run tests against a specific commit with the below command.export DOCKER_IMAGE_TAG=image_tag_on_docker_hub docker compose up -d --pull always
-
Generate a test API key for the local tests with the following command. It will automatically save the output to the
TEST_API_KEY
variable in.env.test
.npm run gen-apikey # or if not using docker, run the following command in ./EigenLayer-AVS/out ./out/ap create-api-key --role=admin --subject=apikey
-
Run the test command with env variables set in
.env.test
.# Run all tests npm test # or, run a specific test npm run test:select -- <authWithSignature>
Note: In order to individually test
cancelTask
ordeleteTask
,createTask
test needs to run first.npm run test:select -- "createTask|cancelTask"
This will execute all unit and integration tests. Make sure all tests pass in local dev environment before submitting a pull request or deploying changes.
To run tests with Docker (replicating the GitHub Actions workflow), use the following command:
yarn test:docker
This script will:
- Pull the Docker container defined in docker-compose.yml
- Set up parameters and environment variables
- Run the tests
To run specific tests, you can pass a test name pattern:
yarn test:docker "authWithSignature"
Make sure to set the following environment variables in your .env.test
file:
TEST_PRIVATE_KEY
: A valid Ethereum private key for testingCHAIN_ENDPOINT
: A valid Ethereum RPC endpoint (e.g., Infura, Alchemy)
This guide explains how to properly publish packages from the ava-sdk-js monorepo while handling workspace dependencies correctly.
When publishing npm packages from a monorepo with workspace dependencies, the workspace:*
references don't get resolved to actual version numbers. This causes the published packages to have invalid dependency references that npm cannot resolve.
We've implemented two solutions to handle this issue:
Each package has a prepare
script that automatically resolves workspace dependencies before publishing:
# The prepare script runs automatically when you run npm publish
npm publish
The prepare script:
- Replaces
workspace:*
dependencies with actual version numbers (e.g.,^2.2.9
) - Runs automatically during
npm publish
- Restores the original
workspace:*
references after publishing
For production releases with proper versioning and changelog generation:
# 1. Create a changeset (if you haven't already)
yarn changeset
# 2. Run the release process
yarn release
The release script:
- Checks for changesets
- Builds all packages
- Updates workspace dependencies to actual versions
- Versions packages using changesets
- Publishes to npm
- Restores workspace dependencies
- Generates changelogs
-
Build the packages:
yarn build
-
Publish using the prepare script:
cd packages/sdk-js npm publish
The prepare script will automatically:
- Replace
"@avaprotocol/types": "workspace:*"
with"@avaprotocol/types": "^2.2.9"
- Publish the package with resolved dependencies
- Restore the original workspace references
- Replace
-
Create a changeset:
yarn changeset
Follow the prompts to select packages and describe changes.
-
Run the release process:
yarn release
This will:
- Build all packages
- Update workspace dependencies to actual versions
- Version packages according to changesets
- Publish to npm
- Restore workspace dependencies
- Generates changelogs
Once a package is ready for a new version, we first publish a dev version and test it in local environment.
-
Run
yarn version --prerelease --preid dev
under eitherpackages/sdk-js
orpackages/types
to update the version inpackage.json
. -
Run
npm publish --tag dev
under eitherpackages/sdk-js
orpackages/types
to publish the new dev version to NPM. Most importantly, this bumps up version number inpackage.json
ofpackages/types
. -
If the
types
package has a new version, since it is depended on bysdk-js
, we need to make suresdk-js
can build with the new version.yarn run clean
at the root folder to remove existing node_modules folder and yarn.lock file.- Run
yarn install
under the root folder to re-install the dependencies. You should see a prompt asking the version of@avaprotocol/types
to install. Choose the new version you just created in step 1. - Run
yarn build
under the root folder to build all packages. - Run
yarn run test
under the root folder to run all tests.
Once the dev version is tested and ready to be published to NPM, changeset
can be used to create a new release for NPM.
-
Record changeset workflow
- Go to the "Actions" tab in GitHub, and run the "Record Changeset" workflow
- Select the version bump type:
patch
for backwards-compatible bug fixes (0.0.x)minor
for backwards-compatible features (0.x.0)major
for breaking changes (x.0.0)
- Examine the Pull Request created by the workflow, and merge it if everything looks correct. This will record any commits before it as a major, minor, or patch.
-
Create release workflow There are two ways to create a release:
- Manually create a release in the GitHub UI. This will run
npx changeset version
to bump up version inpackage.json
based on the recorded changeset files. It will also create a new GitHub Release if the new version is higher than the current version inpackage.json
. - Automatically create a release when a PR is merged. This will run
npx changeset version
to bump up version inpackage.json
based on the recorded changeset files. It will also create a new GitHub Release if the new version is higher than the current version inpackage.json
.
- Manually create a release in the GitHub UI. This will run
-
Publish to NPM
- After the last step, the version number in
package.json
is updated and a git tag with the new version number is created. Now you can publish the production version to NPM usingnpm publish
.
- After the last step, the version number in
After publishing, you can verify that the packages were published correctly:
-
Check the published package.json on npm:
npm view @avaprotocol/sdk-js dependencies
-
The dependencies should show actual version numbers, not
workspace:*
:{ '@avaprotocol/types': '^2.2.9', '@grpc/grpc-js': '^1.11.3', // ... other dependencies }
If you see workspace:*
in the published package:
- Make sure you're using one of the provided publishing methods
- Check that the prepare script is running correctly
- Verify that the dependent package versions are correct
If you encounter build errors:
-
Clean and rebuild:
yarn clean yarn build
-
Check that all dependencies are properly installed:
yarn install
If publishing fails:
-
Check that you're logged into npm:
npm whoami
-
Verify package versions are correct
-
Check that the package name and scope are correct
- Use
npm publish
for development - The prepare script handles workspace dependencies automatically - Use
yarn release
for production - Proper versioning and changelog generation - Test the build process before publishing
- Verify published packages after release
- Keep workspace dependencies in sync during development
- Automatically runs during
npm publish
- Replaces
workspace:*
with actual versions - Restores original references after publishing
- Production release script
- Works with changesets for versioning
- Handles the complete release workflow
- Generates changelogs automatically
To generate the key request message for signing, you can run the following command:
npm run build # Make sure to build the project first
export TEST_MNEMONIC=<your_mnemonic> && node scripts/signMessage.js
We welcome contributions! Feel free to submit pull requests or open issues for any bugs or feature requests.
This project is licensed under the Apache 2.0 License. See the LICENSE file for more details.