Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(readme): improve documentation and examples #109

Merged
merged 3 commits into from
Dec 10, 2024
Merged

docs(readme): improve documentation and examples #109

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
871f8cb
docs(readme): add packages required to interact with akash
gosuri Dec 10, 2024
ae59c43
docs: remove protobuf-related sections from README
gosuri Dec 10, 2024
ed5f566
docs(readme): update README with detailed setup and contribution guid…
gosuri Dec 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
208 changes: 82 additions & 126 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,170 +4,110 @@

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

## 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
<script
type="text/javascript"
src="https://unpkg.com/@akashnetwork/[email protected]/umd/akashjs.js"
></script>
<script type="text/javascript" src="https://unpkg.com/@akashnetwork/[email protected]/umd/akashjs.js" ></script>
```

## Key Features
## Getting Started

### Certificate Management
The following example demonstrates how to fetch the state of the network.

Generate, broadcast and manage certificates for the Akash Network:
```js
import { getMetadata } from "@akashnetwork/akashjs/build/network/index.js";

```typescript
import { certificate } from "@akashnetwork/akashjs";
console.log(JSON.stringify(await getMetadata("mainnet"), null, 2))
```

// Generate a new certificate
const cert = await certificate.createCertificate("akash1...");
More elborate examples can be found in the [examples](examples) directory.

// Broadcast the certificate
await certificate.broadcastCertificate(cert, "akash1...", client);
## Contributing

// Revoke a certificate
await certificate.revokeCertificate("akash1...", "serial123", client);
### Project Stack

// Query certificates
const certs = await certificate.queryCertificates({
owner: "akash1..."
});
```
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.

### Network Interaction
### Development Setup

Connect to and interact with the Akash Network:
1. **Prerequisites**
- Node.js 18 or higher
- npm or yarn
- Go 1.19 or higher (for akash-api dependency)

```typescript
import { network, rpc } from "@akashnetwork/akashjs";
2. **Installation**
```bash
# Clone the repository
git clone https://github.com/akash-network/akashjs
cd akashjs

// Get sorted RPC endpoints for mainnet
const endpoints = await network.getEndpointsSorted("mainnet", "rpc");
# Install dependencies
npm install

// Get network metadata
const metadata = await network.getMetadata("mainnet");
# Setup git hooks
npm run setup-git-hooks
```

### Wallet Integration

Integrate with Keplr wallet and handle transactions:

```typescript
import { keplr, wallet } from "@akashnetwork/akashjs";
4. **Development Commands**
```bash
# Watch mode for development
npm run dev:watch

// Get chains configuration
const chains = keplr.getChains();
# Run tests
npm run test

// Get signer for a chain
const signer = keplr.getSigner(chains.mainnet);
# Run linting
npm run lint

// Connect to a chain
const client = await keplr.get(chains.mainnet, signer, endpoint);
```
# Fix linting issues
npm run lint:fix

### 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,
}
);
```
# Format code
npm run format

### 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"
);
# Build the project
npm run build
```

## Examples

Additional examples can be found in the [examples directory](https://github.com/ovrclk/akashjs/tree/main/)
### Development Guidelines

## Contributing
1. **TypeScript**
- Use strict TypeScript types
- Avoid using `any` type where possible
- Document complex types with JSDoc comments

### Project Stack
2. **Testing**
- Write unit tests for new features
- Maintain test coverage
- Run `npm test` before submitting PRs

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.
3. **Code Style**
- Follow the existing code style
- Use Prettier for formatting
- Follow ESLint rules

### Automated CI Checks and Releases

Expand All @@ -186,5 +126,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.

13 changes: 13 additions & 0 deletions examples/get_state.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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();
30 changes: 0 additions & 30 deletions script/generate.sh
View file
Open in desktop

This file was deleted.

Loading