Akashjs refactor to client-js

[baktun14]

Akash client-js Specification

Overview

The Akash client-js library aims to provide a simplified, high-level interface for interacting with the Akash Network. This specification outlines the transition from the current akashjs implementation to a more streamlined client library.

Goals

1. Simplified API Surface

   • Create intuitive, promise-based APIs
   • Abstract complex blockchain interactions
   • Provide strong TypeScript types
   • Implement comprehensive error handling

2. Move Low-Level Logic

   • Transfer protocol buffers to akash-api (chain-sdk)
     • https://github.com/akash-network/akashjs/tree/main/src/protobuf
   • Relocate network configuration
     • https://github.com/akash-network/akashjs/blob/main/src/config/network.ts
     • https://github.com/akash-network/akashjs/blob/main/src/network/index.ts
     • https://github.com/akash-network/akashjs/blob/main/src/types/network.ts
   • Move certificate management
     • https://github.com/akash-network/akashjs/blob/main/src/certificates/certificate-manager/CertificateManager.ts
     • https://github.com/akash-network/akashjs/blob/main/src/pbclient/pbclient.ts
   • Move SDL parsing and generating
     • https://github.com/akash-network/akashjs/blob/main/src/sdl/SDL/SDL.ts
     • A class to generate an SDL with simple js object param API
   • Transfer RPC implementations
     • https://github.com/akash-network/akashjs/blob/main/src/rpc/index.ts
   • Miscellaneous
     • Amino https://github.com/akash-network/akashjs/blob/main/src/keplr/index.ts
     • Wallet https://github.com/akash-network/akashjs/blob/main/src/wallet/index.ts

New client-js project structure

Core library package (@akashnetwork/client-js)

This package will contain the high level interactions with the Akash Network.

For example when creating a deployment, we need:

• We need an account, either from the browser wallet extension or manual imported one from a mnemonic in a nodejs environment
• The signer client with the akash types registry
• An SDL and validate it
• Create a certificate
• Sign and broadcast the transaction
• Get the list of bids for the deployment
• Create a lease
• Send manifest

Post creation:

• Get lease status
• Get lease logs
• Close deployment
• Update deployment
• Deposit deployment
• List deployments

An example of how it will look like to use the new client-js API

Core Package Architecture

Client Configuration

interface AkashClientConfig {
  network: "mainnet" | "testnet" | "sandbox";
  rpcEndpoint?: string;
  
  // Optional configurations
  defaultGas?: number;
  defaultFees?: {
    amount: string;
    denom: string;
  };
}

Main Client Interface

interface AkashClient {
  // Deployment Operations
  deployments: {
    create(params: CreateDeploymentParams): Promise<DeploymentResult>;
    update(params: UpdateDeploymentParams): Promise<void>;
    close(id: DeploymentId): Promise<void>;
    get(id: DeploymentId): Promise<DeploymentInfo>;
    list(params?: ListDeploymentParams): Promise<DeploymentInfo[]>;
  };

  // Lease Operations
  leases: {
    create(params: CreateLeaseParams): Promise<LeaseResult>;
    close(id: LeaseId): Promise<void>;
    get(id: LeaseId): Promise<LeaseInfo>;
    list(params?: ListLeaseParams): Promise<LeaseInfo[]>;
  };

  // Provider Operations
  providers: {
    list(): Promise<Provider[]>;
    get(address: string): Promise<ProviderInfo>;
  };

  // Certificate Operations
  certificates: {
    create(): Promise<CertificateResult>;
    revoke(serial: string): Promise<void>;
    list(): Promise<Certificate[]>;
  };
}

Type Definitions

interface DeploymentParams {
  sdl: string;
  deposit: {
    amount: string;
    denom: string;
  };
}

interface LeaseParams {
  deploymentId: string;
  provider: string;
  price: {
    amount: string;
    denom: string;
  };
}

interface DeploymentInfo {
  id: string;
  owner: string;
  state: DeploymentState;
  version: string;
  createdAt: Date;
  deposit: {
    amount: string;
    denom: string;
  };
}

Usage Examples

Browser Environment

import { createClient } from "@akashnetwork/client";

const client = createClient({
  network: "mainnet",
  wallet: await getKeplrWallet()
});

// Create a deployment
const deployment = await client.deployments.create({
  sdl: sdlContent,
  autoSelectBid: false, // this could be set to true to select the cheapest bid
  provider: "akash1824w2vqx57n8zr8707dnyh85kjrkfkrrs94pk9", // this would force to select a bid for a specific provider
});

// Get lease information
const lease = await client.leases.get(deployment.leaseId);

Node.js Environment

import { createClient } from "@akashnetwork/client";

const client = createClient({
  network: "mainnet",
  mnemonic: "your mnemonic phrase"
});

// List active leases
const leases = await client.leases.list({
  state: "active"
});

// Close a deployment
await client.deployments.close(deploymentId);

Error Handling

export class AkashError extends Error {
  constructor(
    message: string,
    public code: string,
    public details?: any
  ) {
    super(message);
  }
}

// Error codes
export const ErrorCodes = {
  INVALID_SDL: "INVALID_SDL",
  INSUFFICIENT_FUNDS: "INSUFFICIENT_FUNDS",
  PROVIDER_NOT_FOUND: "PROVIDER_NOT_FOUND",
  DEPLOYMENT_NOT_FOUND: "DEPLOYMENT_NOT_FOUND",
  NETWORK_ERROR: "NETWORK_ERROR"
} as const;

Migration Strategy

This library refactor will be BREAKING and previous applications that used it will have to refactor their code to the latest version. A new package entirely will be generated so the old package will remain and work for old applications.

1. Phase 1: Core Implementation

   • Create new repository structure
   • Implement core interfaces
   • Write comprehensive tests
   • Document API surface

2. Phase 2: Migration Support

   • Create migration guides
   • Provide compatibility layer
   • Support transition period

3. Phase 3: Legacy Deprecation

   • Mark old akashjs as deprecated
   • Communicate timeline
   • Complete documentation

Documentation Requirements

1. Getting Started Guide

   • Installation instructions
   • Basic configuration
   • Simple examples
   • Environment setup

2. API Documentation

   • Method descriptions
   • Type definitions
   • Error handling
   • Best practices

3. Migration Guide

   • Comparison with old API
   • Step-by-step migration
   • Breaking changes
   • Common pitfalls

4. Examples

   • Basic deployment workflow
   • Provider selection
   • Error handling
   • Advanced scenarios

Installation

npm install @akashnetwork/client

Basic Usage

import { createClient } from "@akashnetwork/client";

// Create client instance
const client = createClient({
  network: "mainnet",
  // Wallet configuration (Cosmos-kit or mnemonic)
});

// Create deployment
const deployment = await client.deployments.create({
  sdl: sdlContent,
  autoSelectBid: false, // this could be set to true to select the cheapest bid
  provider: "akash1824w2vqx57n8zr8707dnyh85kjrkfkrrs94pk9", // this would force to select a bid for a specific provider
});

// Get deployment info
const info = await client.deployments.get(deployment.dseq);