{"id":18665250,"url":"https://github.com/avaprotocol/ava-sdk-js","last_synced_at":"2025-08-30T18:31:46.498Z","repository":{"id":259147983,"uuid":"876430975","full_name":"AvaProtocol/ava-sdk-js","owner":"AvaProtocol","description":"A JavaScript/TypeScript SDK designed to simplify integration with Ava Protocol’s AVS","archived":false,"fork":false,"pushed_at":"2024-10-23T05:42:27.000Z","size":170,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-24T08:47:47.341Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AvaProtocol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-22T00:38:11.000Z","updated_at":"2024-10-23T05:41:43.000Z","dependencies_parsed_at":"2024-10-26T00:26:57.910Z","dependency_job_id":"19d25960-6990-4667-bc01-962047e679b3","html_url":"https://github.com/AvaProtocol/ava-sdk-js","commit_stats":null,"previous_names":["avaprotocol/ava-sdk-js"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AvaProtocol%2Fava-sdk-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AvaProtocol%2Fava-sdk-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AvaProtocol%2Fava-sdk-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AvaProtocol%2Fava-sdk-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AvaProtocol","download_url":"https://codeload.github.com/AvaProtocol/ava-sdk-js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231517707,"owners_count":18388807,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T08:26:56.730Z","updated_at":"2025-08-30T18:31:46.482Z","avatar_url":"https://github.com/AvaProtocol.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ava SDK for JavaScript/TypeScript\n\n`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.\n\n## Features\n\n- Type-Safe SDK: Automatically generated TypeScript types from gRPC protocol buffers ensure type safety and reduce errors during development.\n- Seamless Integration: Works in both Node.js and browser environments, optimized for frameworks like Next.js.\n- User-friendly: Simplifies the intricacies of gRPC with an intuitive JavaScript/Typescript interface.\n- Efficient Communication: Leverages gRPC for fast, efficient communication with Ava Protocol's AVS (Actively Validated Services).\n\n## Installation\n\nTo install `ava-sdk-js`, run the following command:\n\n```bash\nnpm install ava-sdk-js\n```\n\nOr with Yarn:\n\n```bash\nyarn add ava-sdk-js\n```\n\n## Getting Started\n\nHere's a quick example of how to use the SDK to get started with Ava Protocol:\n\n```typescript\nimport { AvaSDK } from \"ava-sdk-js\";\n```\n\n## Development\n\n### Install Dependencies and Download Protobuf Files\n\n```bash\nyarn # install grpc-tools, etc. as dev dependencies\n```\n\nThen, run the following command to regenerate the types:\n\n```bash\n# download the latest .proto file from https://github.com/AvaProtocol/EigenLayer-AVS\nyarn run proto-download\n\n# Generate the TypeScript types and gRPC code based on the downloaded .proto file\nyarn run protoc-gen\n\n# Build the source files in to ./dist folder\nyarn run build\n```\n\n### Running Tests\n\nTo ensure the SDK is functioning correctly, we have a comprehensive test suite. Follow these steps to run the tests:\n\n1. Make sure all dependencies are installed, and build the project. Tests are run against the files in the `/dist` folder\n   ```bash\n   npm install\n   npm run build\n   ```\n2. Before running the e2e tests, make sure to configure the required environment variables in your `.env.test` file, based on the `.env.example` file.\n\n3. Bring up a locally environment for aggregator\n\n   ```bash\n   docker compose up -d --pull always\n   ```\n\n   \u003e 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.\n   \u003e\n   \u003e ```\n   \u003e export DOCKER_IMAGE_TAG=image_tag_on_docker_hub\n   \u003e docker compose up -d --pull always\n   \u003e ```\n\n4. 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`.\n\n   ```bash\n   npm run gen-apikey\n\n   # or if not using docker, run the following command in ./EigenLayer-AVS/out\n   ./out/ap create-api-key --role=admin --subject=apikey\n   ```\n\n5. Run the test command with env variables set in `.env.test`.\n\n   ```bash\n   # Run all tests\n   npm test\n\n   # or, run a specific test\n   npm run test:select -- \u003cauthWithSignature\u003e\n   ```\n\n   \u003e Note: In order to individually test `cancelTask` or `deleteTask`, `createTask` test needs to run first.\n\n   \u003e ```bash\n   \u003e npm run test:select -- \"createTask|cancelTask\"\n   \u003e ```\n\n   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.\n\n### Running Tests with Docker\n\nTo run tests with Docker (replicating the GitHub Actions workflow), use the following command:\n\n```bash\nyarn test:docker\n```\n\nThis script will:\n1. Pull the Docker container defined in docker-compose.yml\n2. Set up parameters and environment variables\n3. Run the tests\n\nTo run specific tests, you can pass a test name pattern:\n\n```bash\nyarn test:docker \"authWithSignature\"\n```\n\nMake sure to set the following environment variables in your `.env.test` file:\n- `TEST_PRIVATE_KEY`: A valid Ethereum private key for testing\n- `CHAIN_ENDPOINT`: A valid Ethereum RPC endpoint (e.g., Infura, Alchemy)\n\n## Release Process\n\nThis guide explains how to properly publish packages from the ava-sdk-js monorepo while handling workspace dependencies correctly.\n\n### The Problem\n\nWhen 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.\n\n### Solutions\n\nWe've implemented two solutions to handle this issue:\n\n#### 1. Automatic Prepare Script (For Development/Quick Publishing)\n\nEach package has a `prepare` script that automatically resolves workspace dependencies before publishing:\n\n```bash\n# The prepare script runs automatically when you run npm publish\nnpm publish\n```\n\nThe prepare script:\n- Replaces `workspace:*` dependencies with actual version numbers (e.g., `^2.2.9`)\n- Runs automatically during `npm publish`\n- Restores the original `workspace:*` references after publishing\n\n#### 2. Changesets Release (For Production Releases)\n\nFor production releases with proper versioning and changelog generation:\n\n```bash\n# 1. Create a changeset (if you haven't already)\nyarn changeset\n\n# 2. Run the release process\nyarn release\n```\n\nThe release script:\n- Checks for changesets\n- Builds all packages\n- Updates workspace dependencies to actual versions\n- Versions packages using changesets\n- Publishes to npm\n- Restores workspace dependencies\n- Generates changelogs\n\n### Publishing Workflow\n\n#### For Development/Quick Publishing\n\n1. **Build the packages:**\n   ```bash\n   yarn build\n   ```\n\n2. **Publish using the prepare script:**\n   ```bash\n   cd packages/sdk-js\n   npm publish\n   ```\n\n   The prepare script will automatically:\n   - Replace `\"@avaprotocol/types\": \"workspace:*\"` with `\"@avaprotocol/types\": \"^2.2.9\"`\n   - Publish the package with resolved dependencies\n   - Restore the original workspace references\n\n#### For Production Releases\n\n1. **Create a changeset:**\n   ```bash\n   yarn changeset\n   ```\n   Follow the prompts to select packages and describe changes.\n\n2. **Run the release process:**\n   ```bash\n   yarn release\n   ```\n\n   This will:\n   - Build all packages\n   - Update workspace dependencies to actual versions\n   - Version packages according to changesets\n   - Publish to npm\n   - Restore workspace dependencies\n   - Generates changelogs\n\n### Releasing a new version for development\n\nOnce a package is ready for a new version, we first publish a dev version and test it in local environment.\n\n1. Run `yarn version --prerelease --preid dev` under either `packages/sdk-js` or `packages/types` to update the version in `package.json`.\n2. Run `npm publish --tag dev` under either `packages/sdk-js` or `packages/types` to publish the new dev version to NPM. Most importantly, this **bumps up version number** in `package.json` of `packages/types`.\n3. If the `types` package has a new version, since it is depended on by `sdk-js`, we need to make sure `sdk-js` can build with the new version.\n\n   1. `yarn run clean` **at the root folder** to remove existing node_modules folder and yarn.lock file.\n   2. 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.\n   3. Run `yarn build` under the root folder to build all packages.\n   4. Run `yarn run test` under the root folder to run all tests.\n\n### Publishing to NPM\n\nOnce the dev version is tested and ready to be published to NPM, `changeset` can be used to create a new release for NPM.\n\n1. **Record changeset workflow**\n\n   - Go to the \"Actions\" tab in GitHub, and run the \"Record Changeset\" workflow\n   - Select the version bump type:\n     - `patch` for backwards-compatible bug fixes (0.0.x)\n     - `minor` for backwards-compatible features (0.x.0)\n     - `major` for breaking changes (x.0.0)\n   - 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.\n\n2. **Create release workflow**\n   There are two ways to create a release:\n   - Manually create a release in the GitHub UI. This will run `npx changeset version` to bump up version in `package.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 in `package.json`.\n   - Automatically create a release when a PR is merged. This will run `npx changeset version` to bump up version in `package.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 in `package.json`.\n3. **Publish to NPM**\n   - 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 using `npm publish`.\n\n### Verification\n\nAfter publishing, you can verify that the packages were published correctly:\n\n1. Check the published package.json on npm:\n   ```bash\n   npm view @avaprotocol/sdk-js dependencies\n   ```\n\n2. The dependencies should show actual version numbers, not `workspace:*`:\n   ```json\n   {\n     '@avaprotocol/types': '^2.2.9',\n     '@grpc/grpc-js': '^1.11.3',\n     // ... other dependencies\n   }\n   ```\n\n### Troubleshooting\n\n#### Workspace Dependencies Not Resolved\n\nIf you see `workspace:*` in the published package:\n\n1. Make sure you're using one of the provided publishing methods\n2. Check that the prepare script is running correctly\n3. Verify that the dependent package versions are correct\n\n#### Build Errors\n\nIf you encounter build errors:\n\n1. Clean and rebuild:\n   ```bash\n   yarn clean\n   yarn build\n   ```\n\n2. Check that all dependencies are properly installed:\n   ```bash\n   yarn install\n   ```\n\n#### Publishing Errors\n\nIf publishing fails:\n\n1. Check that you're logged into npm:\n   ```bash\n   npm whoami\n   ```\n\n2. Verify package versions are correct\n3. Check that the package name and scope are correct\n\n### Best Practices\n\n1. **Use `npm publish` for development** - The prepare script handles workspace dependencies automatically\n2. **Use `yarn release` for production** - Proper versioning and changelog generation\n3. **Test the build process** before publishing\n4. **Verify published packages** after release\n5. **Keep workspace dependencies in sync** during development\n\n### Script Details\n\n#### prepare-package.js\n- Automatically runs during `npm publish`\n- Replaces `workspace:*` with actual versions\n- Restores original references after publishing\n\n#### release.js\n- Production release script\n- Works with changesets for versioning\n- Handles the complete release workflow\n- Generates changelogs automatically\n\n### Utility Scripts\n\nTo generate the key request message for signing, you can run the following command:\n\n```bash\nnpm run build # Make sure to build the project first\n\nexport TEST_MNEMONIC=\u003cyour_mnemonic\u003e \u0026\u0026 node scripts/signMessage.js\n```\n\n## Contributing\n\nWe welcome contributions! Feel free to submit pull requests or open issues for any bugs or feature requests.\n\n## License\n\nThis project is licensed under the Apache 2.0 License. See the LICENSE file for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favaprotocol%2Fava-sdk-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Favaprotocol%2Fava-sdk-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favaprotocol%2Fava-sdk-js/lists"}