From 871f8cb7cab593dcfbbe304d15b244bff474d73f Mon Sep 17 00:00:00 2001 From: Greg Osuri Date: Mon, 9 Dec 2024 18:42:18 -0600 Subject: [PATCH 1/3] docs(readme): add packages required to interact with akash Signed-off-by: Greg Osuri --- README.md | 148 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 147 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d993569..b393f08 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,18 @@ Or use the UMD bundle (the object returned is `Window.akjs`): > ``` +## Packages + +This repository is the home of `akashjs`, a library designed to facilitate interaction with the Akash Network. However, for full functionality, users will need to integrate several additional libraries. The Akash Network is built using the Cosmos SDK and utilizes the Stargate client for transaction signing and broadcasting. These packages are specifically tailored to enhance interaction with the Akash Network. + +| Package | Description | +| ------- | ----------- | +| [@akashnetwork/akashjs](src) | Main library for interacting with the Akash Network | +| [@akashnetwork/akash-api](https://github.com/akash-network/akash-api/tree/main/ts) | Akash API generated from [Akash API](https://github.com/akash-network/akash-api) for interacting with the Akash Network. Documentation is available for [node](https://github.com/akash-network/akash-api/blob/main/docs/proto/node.md) and [provider](https://github.com/akash-network/akash-api/blob/main/docs/proto/provider.md) | +| [@cosmjs/stargate](https://github.com/cosmos/cosmjs/tree/main/packages/stargate) | A client library for the Cosmos SDK 0.40+ (Stargate) | +| [@cosmjs/proto-signing](https://github.com/cosmos/cosmjs/tree/main/packages/proto-signing) | A library for signing and broadcasting transactions using the Cosmos SDK | + + ## Key Features ### Certificate Management @@ -161,7 +173,7 @@ const result = await client.signAndBroadcast( ## Examples -Additional examples can be found in the [examples directory](https://github.com/ovrclk/akashjs/tree/main/) +Additional examples can be found in the [examples directory](examples) ## Contributing @@ -169,6 +181,124 @@ Additional examples can be found in the [examples directory](https://github.com/ This repository is primarily written in TypeScript and uses Node.js version 18. We use Webpack 5 for UMD bundling. These tools ensure that our development environment is consistent and our builds are stable. +### Development Setup + +1. **Prerequisites** + - Node.js 18 or higher + - npm or yarn + - Protocol Buffers Compiler (protoc) v3.15.0 or higher + - **Installation Instructions:** + - **macOS**: Use Homebrew to install protoc: + ```bash + brew install protobuf + ``` + - **Linux**: Use your package manager, for example, on Ubuntu: + ```bash + sudo apt update + sudo apt install -y protobuf-compiler + ``` + - **Windows**: Download the precompiled binaries from the [official releases page](https://github.com/protocolbuffers/protobuf/releases) and add the `bin` directory to your system's PATH. + - Go 1.19 or higher (for akash-api dependency) + +2. **Installation** +```bash +# Clone the repository +git clone https://github.com/akash-network/akashjs +cd akashjs + +# Install dependencies +npm install + +# Setup git hooks +npm run setup-git-hooks +``` + +## Protobuf Generation (Optional) + +Protobuf generation is only necessary when the protobuf definitions have changed. If you need to regenerate the protobuf files, follow these steps: + +1. **Clone the akash-api repository** (required for proto files): + ```bash + git clone https://github.com/akash-network/akash-api.git ../akash-api + ``` + +2. **Install gogoproto**: Ensure that the `gogoproto` library is available in your environment. + ```bash + # Clone the gogoproto repository + git clone https://github.com/gogo/protobuf.git + + # Ensure the path to gogo.proto is included in your proto path + export PROTO_PATH=./protobuf/protobuf + ``` + +3. **Generate protobuf files**: + ```bash + # Use the following command to generate TypeScript definitions + protoc -I=$PROTO_PATH -I=./path/to/akash-api --ts_out=./src/protobuf akash/discovery/v1/client_info.proto + ``` + +The protobuf generation script will: +- Look for .proto files in the akash-api repository +- Generate TypeScript definitions in `src/protobuf` +- Use ts-proto for TypeScript code generation +- Include necessary Cosmos SDK proto definitions + +If you encounter protobuf-related errors: +- Ensure `protoc` is installed correctly +- Verify the `akash-api` repository is at the correct path +- Check `protoc` version compatibility +- Look for detailed errors in `generate.log` + +### Troubleshooting + +If you encounter the error `Import "gogoproto/gogo.proto" was not found or had errors`, follow these steps: + +1. **Ensure `gogoproto` is cloned**: Make sure the `gogoproto` repository is cloned and accessible. +2. **Update the Protobuf Generation Script**: Modify your script to include the path to `gogoproto` using the `-I` flag. +3. **Verify Paths**: Double-check that the paths to `gogo.proto` and other proto files are correct. +4. **Check Dependencies**: Ensure all dependencies are installed and up-to-date. +5. **Protoc Version**: Verify that your `protoc` version is compatible with the proto files. + +By following these instructions, you should be able to resolve the `gogoproto/gogo.proto` error and successfully generate your protobuf files when necessary. + +4. **Development Commands** +```bash +# Watch mode for development +npm run dev:watch + +# Run tests +npm run test + +# Run linting +npm run lint + +# Fix linting issues +npm run lint:fix + +# Format code +npm run format + +# Build the project +npm run build +``` + +### Development Guidelines + +1. **TypeScript** + - Use strict TypeScript types + - Avoid using `any` type where possible + - Document complex types with JSDoc comments + +2. **Testing** + - Write unit tests for new features + - Maintain test coverage + - Run `npm test` before submitting PRs + +3. **Code Style** + - Follow the existing code style + - Use Prettier for formatting + - Follow ESLint rules + ### Automated CI Checks and Releases Our project enforces high standards of code quality and consistency through: @@ -186,5 +316,21 @@ To enable git hooks for local development: npm run setup-git-hooks ``` +### Pull Request Process + +1. Create a feature branch from `main` +2. Make your changes following our guidelines +3. Ensure all tests pass +4. Update documentation as needed +5. Submit a PR with a clear description of changes +6. Wait for review and address any feedback + +### Debugging Tips + +- Use the `dev:watch` command for live reloading during development +- Check the `examples` directory for implementation references +- Use Jest's debugging capabilities with `--inspect` flag +- Set `DEBUG=akashjs:*` environment variable for detailed logs + PRs are welcome! By adhering to these guidelines and leveraging our automated systems, we can maintain a high-quality codebase and streamline our development processes. From ae59c433c7a1d951b0965e565eaed42b2b5c51da Mon Sep 17 00:00:00 2001 From: Greg Osuri Date: Mon, 9 Dec 2024 20:27:31 -0600 Subject: [PATCH 2/3] docs: remove protobuf-related sections from README - Removed all references and instructions related to Protobuf from the README.md - Updated documentation to reflect the current state of the project without Protobuf dependencies Signed-off-by: Greg Osuri --- README.md | 83 ++++++---------------------------------------- script/generate.sh | 30 ----------------- 2 files changed, 11 insertions(+), 102 deletions(-) delete mode 100755 script/generate.sh diff --git a/README.md b/README.md index b393f08..3f93fe2 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,17 @@ Connect and communicate with the Akash Network. Pure JS library can be used in browser for unsigned transactions, and with node.js for full compatibility. +## Packages + +This repository is the home of `akashjs`, a library designed to facilitate interaction with the Akash Network. However, for full functionality, users will need to integrate several additional libraries. The Akash Network is built using the Cosmos SDK and utilizes the Stargate client for transaction signing and broadcasting. These packages are specifically tailored to enhance interaction with the Akash Network. + +| Package | Description | +| ------- | ----------- | +| [@akashnetwork/akashjs](src) | Main library for interacting with the Akash Network | +| [@akashnetwork/akash-api](https://github.com/akash-network/akash-api/tree/main/ts) | Akash API generated from [Akash API](https://github.com/akash-network/akash-api) for interacting with the Akash Network. Documentation is available for [node](https://github.com/akash-network/akash-api/blob/main/docs/proto/node.md) and [provider](https://github.com/akash-network/akash-api/blob/main/docs/proto/provider.md) | +| [@cosmjs/stargate](https://github.com/cosmos/cosmjs/tree/main/packages/stargate) | A client library for the Cosmos SDK 0.40+ (Stargate) | +| [@cosmjs/proto-signing](https://github.com/cosmos/cosmjs/tree/main/packages/proto-signing) | A library for signing and broadcasting transactions using the Cosmos SDK | + ## Compatibility Compatible with modern browsers, nodejs 14+ and Webpack 5 @@ -26,18 +37,6 @@ Or use the UMD bundle (the object returned is `Window.akjs`): > ``` -## Packages - -This repository is the home of `akashjs`, a library designed to facilitate interaction with the Akash Network. However, for full functionality, users will need to integrate several additional libraries. The Akash Network is built using the Cosmos SDK and utilizes the Stargate client for transaction signing and broadcasting. These packages are specifically tailored to enhance interaction with the Akash Network. - -| Package | Description | -| ------- | ----------- | -| [@akashnetwork/akashjs](src) | Main library for interacting with the Akash Network | -| [@akashnetwork/akash-api](https://github.com/akash-network/akash-api/tree/main/ts) | Akash API generated from [Akash API](https://github.com/akash-network/akash-api) for interacting with the Akash Network. Documentation is available for [node](https://github.com/akash-network/akash-api/blob/main/docs/proto/node.md) and [provider](https://github.com/akash-network/akash-api/blob/main/docs/proto/provider.md) | -| [@cosmjs/stargate](https://github.com/cosmos/cosmjs/tree/main/packages/stargate) | A client library for the Cosmos SDK 0.40+ (Stargate) | -| [@cosmjs/proto-signing](https://github.com/cosmos/cosmjs/tree/main/packages/proto-signing) | A library for signing and broadcasting transactions using the Cosmos SDK | - - ## Key Features ### Certificate Management @@ -186,18 +185,6 @@ This repository is primarily written in TypeScript and uses Node.js version 18. 1. **Prerequisites** - Node.js 18 or higher - npm or yarn - - Protocol Buffers Compiler (protoc) v3.15.0 or higher - - **Installation Instructions:** - - **macOS**: Use Homebrew to install protoc: - ```bash - brew install protobuf - ``` - - **Linux**: Use your package manager, for example, on Ubuntu: - ```bash - sudo apt update - sudo apt install -y protobuf-compiler - ``` - - **Windows**: Download the precompiled binaries from the [official releases page](https://github.com/protocolbuffers/protobuf/releases) and add the `bin` directory to your system's PATH. - Go 1.19 or higher (for akash-api dependency) 2. **Installation** @@ -213,54 +200,6 @@ npm install npm run setup-git-hooks ``` -## Protobuf Generation (Optional) - -Protobuf generation is only necessary when the protobuf definitions have changed. If you need to regenerate the protobuf files, follow these steps: - -1. **Clone the akash-api repository** (required for proto files): - ```bash - git clone https://github.com/akash-network/akash-api.git ../akash-api - ``` - -2. **Install gogoproto**: Ensure that the `gogoproto` library is available in your environment. - ```bash - # Clone the gogoproto repository - git clone https://github.com/gogo/protobuf.git - - # Ensure the path to gogo.proto is included in your proto path - export PROTO_PATH=./protobuf/protobuf - ``` - -3. **Generate protobuf files**: - ```bash - # Use the following command to generate TypeScript definitions - protoc -I=$PROTO_PATH -I=./path/to/akash-api --ts_out=./src/protobuf akash/discovery/v1/client_info.proto - ``` - -The protobuf generation script will: -- Look for .proto files in the akash-api repository -- Generate TypeScript definitions in `src/protobuf` -- Use ts-proto for TypeScript code generation -- Include necessary Cosmos SDK proto definitions - -If you encounter protobuf-related errors: -- Ensure `protoc` is installed correctly -- Verify the `akash-api` repository is at the correct path -- Check `protoc` version compatibility -- Look for detailed errors in `generate.log` - -### Troubleshooting - -If you encounter the error `Import "gogoproto/gogo.proto" was not found or had errors`, follow these steps: - -1. **Ensure `gogoproto` is cloned**: Make sure the `gogoproto` repository is cloned and accessible. -2. **Update the Protobuf Generation Script**: Modify your script to include the path to `gogoproto` using the `-I` flag. -3. **Verify Paths**: Double-check that the paths to `gogo.proto` and other proto files are correct. -4. **Check Dependencies**: Ensure all dependencies are installed and up-to-date. -5. **Protoc Version**: Verify that your `protoc` version is compatible with the proto files. - -By following these instructions, you should be able to resolve the `gogoproto/gogo.proto` error and successfully generate your protobuf files when necessary. - 4. **Development Commands** ```bash # Watch mode for development diff --git a/script/generate.sh b/script/generate.sh deleted file mode 100755 index d1fb45e..0000000 --- a/script/generate.sh +++ /dev/null @@ -1,30 +0,0 @@ -API_DIR=$1 -PROTO_PATH="$1/proto/node" - -echo "Generating protobuf files for ${PROTO_PATH}" - -SRC_PATHS=$(find ${PROTO_PATH} -name "*.proto") -OUTPUT_DIR="./src/protobuf" -LOG_FILE="./generate.log" - -if [ ! -d ${PROTO_PATH} ]; then - echo "Unable to locate definitions directory: ${PROTO_PATH}" - exit 1 -fi - -echo "Generating new definitions in ${OUTPUT_DIR}" -if protoc \ - --plugin="./node_modules/.bin/protoc-gen-ts_proto" \ - -I="${API_DIR}/vendor/github.com/gogo/protobuf" \ - -I="${API_DIR}/vendor/github.com/cosmos/cosmos-sdk/third_party/proto" \ - -I="${API_DIR}/vendor/github.com/cosmos/cosmos-sdk/proto" \ - --proto_path=${PROTO_PATH} \ - --ts_proto_out=${OUTPUT_DIR} \ - --ts_proto_opt=esModuleInterop=true,forceLong=long,outputTypeRegistry=true \ - ${SRC_PATHS}; then - echo "ok"; -else - echo "Unable to regenerate protobuf files: error below" - cat ${LOG_FILE} - rm ${LOG_FILE} -fi \ No newline at end of file From ed5f566515e798591a470f05d90ce06fcb617ddb Mon Sep 17 00:00:00 2001 From: Greg Osuri Date: Mon, 9 Dec 2024 20:53:33 -0800 Subject: [PATCH 3/3] docs(readme): update README with detailed setup and contribution guidelines Enhanced the README with comprehensive instructions for development setup, including prerequisites and installation steps. Added detailed guidelines for contributing, covering TypeScript usage, testing, and code style. Included information on automated CI checks and the pull request process to ensure high code quality and consistency. --- README.md | 155 ++++-------------------------------------- examples/get_state.ts | 13 ++++ 2 files changed, 26 insertions(+), 142 deletions(-) create mode 100644 examples/get_state.ts diff --git a/README.md b/README.md index 3f93fe2..6b78ffe 100644 --- a/README.md +++ b/README.md @@ -11,9 +11,9 @@ This repository is the home of `akashjs`, a library designed to facilitate inter | Package | Description | | ------- | ----------- | | [@akashnetwork/akashjs](src) | Main library for interacting with the Akash Network | -| [@akashnetwork/akash-api](https://github.com/akash-network/akash-api/tree/main/ts) | Akash API generated from [Akash API](https://github.com/akash-network/akash-api) for interacting with the Akash Network. Documentation is available for [node](https://github.com/akash-network/akash-api/blob/main/docs/proto/node.md) and [provider](https://github.com/akash-network/akash-api/blob/main/docs/proto/provider.md) | -| [@cosmjs/stargate](https://github.com/cosmos/cosmjs/tree/main/packages/stargate) | A client library for the Cosmos SDK 0.40+ (Stargate) | -| [@cosmjs/proto-signing](https://github.com/cosmos/cosmjs/tree/main/packages/proto-signing) | A library for signing and broadcasting transactions using the Cosmos SDK | +| [@akashnetwork/akash-api](https://github.com/akash-network/akash-api/tree/main/ts) | Akash API generated from [Akash API](https://github.com/akash-network/akash-api) for interacting with the Akash Network. Documentation is available for [node](https://github.com/akash-network/akash-api/blob/main/docs/proto/node.md) and [provider](https://github.com/akash-network/akash-api/blob/main/docs/proto/provider.md). | +| [@cosmjs/stargate](https://github.com/cosmos/cosmjs/tree/main/packages/stargate) | A client library for the Cosmos SDK 0.40+ (Stargate). | +| [@cosmjs/proto-signing](https://github.com/cosmos/cosmjs/tree/main/packages/proto-signing) | A library for signing and broadcasting transactions using the Cosmos SDK. | ## Compatibility @@ -21,158 +21,29 @@ Compatible with modern browsers, nodejs 14+ and Webpack 5 ## Installation -Install from `npm` or `yarn`: +To install the library, run the following command: -```bash -npm i @akashnetwork/akashjs -yarn add @akashnetwork/akashjs +```sh +npm install @akashnetwork/akashjs ``` Or use the UMD bundle (the object returned is `Window.akjs`): ```html - -``` - -## Key Features - -### Certificate Management - -Generate, broadcast and manage certificates for the Akash Network: - -```typescript -import { certificate } from "@akashnetwork/akashjs"; - -// Generate a new certificate -const cert = await certificate.createCertificate("akash1..."); - -// Broadcast the certificate -await certificate.broadcastCertificate(cert, "akash1...", client); - -// Revoke a certificate -await certificate.revokeCertificate("akash1...", "serial123", client); - -// Query certificates -const certs = await certificate.queryCertificates({ - owner: "akash1..." -}); + ``` -### Network Interaction - -Connect to and interact with the Akash Network: +## Getting Started -```typescript -import { network, rpc } from "@akashnetwork/akashjs"; +The following example demonstrates how to fetch the state of the network. -// Get sorted RPC endpoints for mainnet -const endpoints = await network.getEndpointsSorted("mainnet", "rpc"); +```js +import { getMetadata } from "@akashnetwork/akashjs/build/network/index.js"; -// Get network metadata -const metadata = await network.getMetadata("mainnet"); +console.log(JSON.stringify(await getMetadata("mainnet"), null, 2)) ``` -### Wallet Integration - -Integrate with Keplr wallet and handle transactions: - -```typescript -import { keplr, wallet } from "@akashnetwork/akashjs"; - -// Get chains configuration -const chains = keplr.getChains(); - -// Get signer for a chain -const signer = keplr.getSigner(chains.mainnet); - -// Connect to a chain -const client = await keplr.get(chains.mainnet, signer, endpoint); -``` - -### Stargate Client - -For more control over transactions, use the Stargate client integration: - -```typescript -import { stargate as akashStargate } from "@akashnetwork/akashjs"; -import { Registry, DirectSecp256k1HdWallet } from "@cosmjs/proto-signing"; -import { SigningStargateClient } from "@cosmjs/stargate"; - -// Setup registry -const myRegistry = new Registry([ - ...defaultRegistryTypes, - ...akashStargate.registry, -]); - -// Create client -const client = await SigningStargateClient.connectWithSigner( - `http://rpcUrl/`, - offlineSigner, - { - registry: myRegistry, - } -); -``` - -### Transaction Example - -Here's an example of sending a deployment take-down message: - -```typescript -const mnemonic = "your wallet mnemonic"; -const wallet = await DirectSecp256k1HdWallet.fromMnemonic(mnemonic, { prefix: "akash" }); - -// Get first account -const [account] = await wallet.getAccounts(); - -// Create the message -const message = MsgCloseDeployment.fromPartial({ - id: { - dseq: "555555", - owner: account.address, - } -}); - -// Set the message type and value -const msgAny = { - typeUrl: getTypeUrl(MsgCloseDeployment), - value: message -}; - -// Setup client with registry -const myRegistry = new Registry(getAkashTypeRegistry()); -const client = await SigningStargateClient.connectWithSigner( - rpcEndpoint, - wallet, - { registry: myRegistry } -); - -// Define transaction fee -const fee = { - amount: [ - { - denom: "uakt", - amount: "5000", - }, - ], - gas: "800000", -}; - -// Sign and broadcast -const result = await client.signAndBroadcast( - account.address, - [msgAny], - fee, - "take down deployment" -); -``` - -## Examples - -Additional examples can be found in the [examples directory](examples) +More elborate examples can be found in the [examples](examples) directory. ## Contributing diff --git a/examples/get_state.ts b/examples/get_state.ts new file mode 100644 index 0000000..7e7a4d1 --- /dev/null +++ b/examples/get_state.ts @@ -0,0 +1,13 @@ +import { getMetadata } from "@akashnetwork/akashjs/build/network"; + +async function fetchMetadata() { + try { + console.log("Fetching metadata..."); + const metadata = await getMetadata("mainnet"); + console.log(JSON.stringify(metadata, null, 2)); + } catch (error) { + console.error("Error fetching metadata:", error); + } +} + +fetchMetadata(); \ No newline at end of file