Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/cryptoandcoffee/akash-jsdk

Modern JavaScript SDK for Akash Network.
https://github.com/cryptoandcoffee/akash-jsdk

akash akash-network blockchain cloud-computing cosmos cosmos-sdk decentralized-cloud deployment docker ibc javascript jwt-auth kubernetes monorepo pnpm sdk staking typescript web3

Last synced: 4 months ago
JSON representation

Modern JavaScript SDK for Akash Network.

Awesome Lists containing this project

README 

          
# @cryptoandcoffee/akash-jsdk



[![npm version](https://img.shields.io/npm/v/@cryptoandcoffee/akash-jsdk-core.svg)](https://www.npmjs.com/package/@cryptoandcoffee/akash-jsdk-core)

[![npm downloads](https://img.shields.io/npm/dm/@cryptoandcoffee/akash-jsdk-core.svg)](https://www.npmjs.com/package/@cryptoandcoffee/akash-jsdk-core)

[![CI](https://img.shields.io/github/actions/workflow/status/cryptoandcoffee/akash-jsdk/ci.yml?branch=main&label=CI)](https://github.com/cryptoandcoffee/akash-jsdk/actions/workflows/ci.yml)

[![Tests](https://img.shields.io/badge/tests-1,280%20passing-brightgreen.svg)](#-comprehensive-test-results)

[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](#-comprehensive-test-results)

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)



A modern, fully-featured JavaScript SDK for Akash Network built from scratch with cutting-edge frameworks and enterprise-grade quality.



## 🚀 Features



- **Modern TypeScript**: Full type safety with strict TypeScript 5.9+ configuration

- **Monorepo Architecture**: pnpm workspaces with modular, tree-shakeable packages

- **React Integration**: Custom hooks and provider for seamless React development  

- **CLI Tools**: Command-line interface for deployment and management operations

- **Custom Protobuf**: Optimized protobuf implementation using @bufbuild/protobuf

- **Comprehensive Testing**: Enterprise-grade testing with 1,280 tests passing across all packages

- **Performance First**: ES2022 target, ESM modules, incremental builds



## What's New in v3.11.1



Version 3.11.1 brings comprehensive Protobuf message type registration and production-ready blockchain integration:



### Protobuf Message Type Registration (v3.7.0)

- **New `createAkashRegistry()` Utility**: Centralized registry creation with all 14 Akash message types pre-registered

- **Full CosmJS Compatibility**: Eliminates "Unregistered type url" errors when broadcasting transactions

- **Message Types Registered**:

  - Deployment: MsgCreateDeployment, MsgUpdateDeployment, MsgCloseDeployment, MsgDepositDeployment

  - Market: MsgCreateBid, MsgCloseBid, MsgCreateLease, MsgCloseLease, MsgWithdrawLease

  - Provider: MsgCreateProvider, MsgUpdateProvider, MsgDeleteProvider

  - Certificate: MsgCreateCertificate, MsgRevokeCertificate



### Previous Release: GitHub Packages Integration (v3.6.1)

- Published to both npm and GitHub Packages registries

- Repository field integration for GitHub

- Dual registry publishing support



### All Mainnet 14 Features Available

Full support for Akash Network Mainnet 14 features:

- **JWT Authentication (AEP-63)**: Modern JWT tokens with ES256K signatures

- **Multi-Depositor Escrow (AEP-75)**: Flexible funding sources for deployments

- **Lease Termination Tracking (AEP-39)**: Detailed lease close reasons

- **Cosmos SDK v0.53 Compatibility**: Latest SDK features and improvements



## ✅ Production Ready



**All modules are now production-ready with real blockchain implementations:**



| Module | Status | Capabilities |

|--------|--------|--------------|

| **Batch Operations** | ✅ Production Ready | Real transaction broadcasting, gas simulation, confirmation polling |

| **IBC Module** | ✅ Production Ready | Real IBC transfers, channel queries, packet acknowledgement tracking |

| **Staking Module** | ✅ Production Ready | Real staking operations, validator queries, reward distribution |

| **Deployment Module** | ✅ Production Ready | Full deployment lifecycle management |

| **Market Module** | ✅ Production Ready | Orders, bids, leases, multi-source deposits |

| **Provider Module** | ✅ Production Ready | Provider registration, capacity queries, manifest deployment |

| **Wallet Module** | ✅ Production Ready | Multi-wallet support (Keplr, Leap, Cosmostation) |



**All modules use SigningStargateClient for real blockchain interactions and REST API queries for state retrieval.**



---



## 📦 Packages



| Package | Description | Version |

|---------|-------------|---------|

| `@cryptoandcoffee/akash-jsdk-core` | Core SDK with deployment, market, provider, and wallet management | 3.11.1 |

| `@cryptoandcoffee/akash-jsdk-react` | React hooks and context provider for seamless integration | 3.11.1 |

| `@cryptoandcoffee/akash-jsdk-cli` | Command-line tools for project initialization and deployment | 3.11.1 |

| `@cryptoandcoffee/akash-jsdk-protobuf` | Custom protobuf definitions with TypeScript support | 3.11.1 |



## 🔧 Installation



```bash

# Core SDK only

npm install @cryptoandcoffee/akash-jsdk-core



# With React hooks

npm install @cryptoandcoffee/akash-jsdk-core @cryptoandcoffee/akash-jsdk-react



# CLI tools globally

npm install -g @cryptoandcoffee/akash-jsdk-cli



# All packages for development

pnpm install @cryptoandcoffee/akash-jsdk-core @cryptoandcoffee/akash-jsdk-react @cryptoandcoffee/akash-jsdk-cli

```



## 💻 Quick Start



### Core SDK (Vanilla JavaScript/TypeScript)



```typescript

import { AkashSDK } from '@cryptoandcoffee/akash-jsdk-core'



const sdk = new AkashSDK({

  rpcEndpoint: 'https://rpc.akashedge.com:443',

  apiEndpoint: 'https://api.akashedge.com:443',

  chainId: 'akashnet-2',

  gasPrice: '0.025uakt'

})



await sdk.connect()



// Deployment operations

const deployments = await sdk.deployments.list('akash1...')

const deploymentId = await sdk.deployments.create(sdlConfig)

await sdk.deployments.close(deploymentId)



// Market operations

const orders = await sdk.market.listOrders()

const leases = await sdk.market.listLeases('akash1...')



// Provider operations

const providers = await sdk.providers.list()

const capacity = await sdk.providers.getCapacity('akash1provider...')



// Wallet operations

await sdk.wallet.connect('keplr')

const balance = await sdk.wallet.getBalance()

```



### React Integration



```tsx

import { AkashProvider, useDeployments, useLeases, useProviders } from '@cryptoandcoffee/akash-jsdk-react'



function App() {

  return (

    

      

    

  )

}



function Dashboard() {

  const { deployments, loading, createDeployment, closeDeployment } = useDeployments('akash1...')

  const { leases } = useLeases('akash1...')

  const { providers } = useProviders()

  

  if (loading) return 
Loading deployments...


  

  return (

    


      
Deployments ({deployments.length})


      {deployments.map(deployment => (

        


          Deployment {deployment.deploymentId.dseq} - {deployment.state}

           closeDeployment(deployment.deploymentId)}>

            Close

          

        


      ))}

      

      
Available Providers ({providers.length})


      {providers.map(provider => (

        


          {provider.hostUri} - {provider.attributes.find(a => a.key === 'region')?.value}

        


      ))}

    


  )

}

```



## 🆕 Mainnet 14 Features - Code Examples



### JWT Authentication (AEP-63)



Replace traditional certificate-based authentication with JWT tokens:



#### 🌐 Using Cosmos Wallets for JWT Authentication



The SDK supports multiple Cosmos wallets through a universal adapter. All wallets use ADR-36 signing, so your private key never leaves the wallet extension.



**Keplr Wallet** (Recommended for Web Apps)



```typescript

import { AkashSDK, WalletAdapter } from '@cryptoandcoffee/akash-jsdk-core'



const sdk = new AkashSDK({

  rpcEndpoint: 'https://rpc.akashedge.com:443',

  chainId: 'akashnet-2'

})



const walletAdapter = new WalletAdapter()



// Connect to Keplr

await window.keplr.enable('akashnet-2')

const offlineSigner = window.keplr.getOfflineSigner('akashnet-2')

const accounts = await offlineSigner.getAccounts()



// Generate JWT using Keplr's ADR-36 signing (no private key needed!)

const token = await walletAdapter.generateJWTWithKeplr(

  'akashnet-2',

  accounts[0].address,

  {

    expiresIn: 900, // 15 minutes

    accessType: 'full'

  }

)



// Set authentication and use!

sdk.setAuthConfig({ method: 'jwt', jwtToken: token })

```



**Leap Wallet**



```typescript

import { WalletAdapter } from '@cryptoandcoffee/akash-jsdk-core'



const walletAdapter = new WalletAdapter()



// Connect to Leap

await window.leap.enable('akashnet-2')

const accounts = await window.leap.getAccounts('akashnet-2')



// Generate JWT using Leap

const token = await walletAdapter.generateJWTWithLeap(

  'akashnet-2',

  accounts[0].address,

  { expiresIn: 900, accessType: 'full' }

)

```



**Cosmostation Wallet**



```typescript

import { WalletAdapter } from '@cryptoandcoffee/akash-jsdk-core'



const walletAdapter = new WalletAdapter()



// Connect to Cosmostation

const account = await window.cosmostation.cosmos.request({

  method: 'cos_requestAccount',

  params: { chainName: 'akashnet-2' }

})



// Generate JWT using Cosmostation

const token = await walletAdapter.generateJWTWithCosmostation(

  'akashnet-2',

  account.address,

  { expiresIn: 900, accessType: 'full' }

)

```



**MetaMask with Leap Cosmos Snap**



```typescript

import { WalletAdapter } from '@cryptoandcoffee/akash-jsdk-core'



const walletAdapter = new WalletAdapter()



// Generate JWT using MetaMask Snap (auto-installs snap if needed)

const token = await walletAdapter.generateJWTWithMetaMaskSnap(

  'akashnet-2',

  'akash1youraddress...',

  { expiresIn: 900, accessType: 'full' }

)

```



**Auto-Detect Available Wallet**



```typescript

import { WalletAdapter, SupportedWallet } from '@cryptoandcoffee/akash-jsdk-core'



const walletAdapter = new WalletAdapter()



// Detect available wallets

const available = walletAdapter.detectAvailableWallets()

console.log('Available wallets:', available) // [SupportedWallet.Keplr, SupportedWallet.Leap, ...]



// Auto-select and use first available wallet

const { token, wallet } = await walletAdapter.generateJWTAuto(

  'akashnet-2',

  'akash1youraddress...',

  { expiresIn: 900, accessType: 'full' }

)



console.log(`Generated JWT using ${wallet}`) // "Generated JWT using keplr"

sdk.setAuthConfig({ method: 'jwt', jwtToken: token })

```



#### 🔑 Using Private Key (For Node.js/CLI)



```typescript

import { JWTAuthManager, JWTAccessType, JWTPermissionScope } from '@cryptoandcoffee/akash-jsdk-core'



const jwtAuth = new JWTAuthManager()



// Generate JWT with private key

const token = await jwtAuth.generateToken({

  address: 'akash1...',

  privateKey: process.env.AKASH_PRIVATE_KEY,

  expiresIn: 900,

  accessType: JWTAccessType.Full,

  leasePermissions: [{

    owner: 'akash1...',

    dseq: '12345',

    scopes: [

      JWTPermissionScope.SendManifest,

      JWTPermissionScope.Status,

      JWTPermissionScope.Logs

    ]

  }]

})



// Use token in HTTP requests

const authHeader = jwtAuth.createAuthHeader(token)

// Authorization: Bearer eyJhbGciOiJFUzI1NksiLCJ0eXAiOiJKV1QifQ...



// Validate and check expiration

const validation = await jwtAuth.validateToken(token, publicKey)

if (jwtAuth.isTokenExpired(token)) {

  // Regenerate token

}

```



### Multi-Depositor Escrow (AEP-75)



Create deployments with multiple funding sources:



```typescript

import { MarketManager, DepositSource } from '@cryptoandcoffee/akash-jsdk-core'



const market = new MarketManager(provider)



// Create a deposit configuration with multiple sources

const depositConfig = market.createDepositConfig(

  '5000000', // 5 AKT

  'uakt',

  [

    DepositSource.Balance,    // From account balance

    DepositSource.Grant,      // From external grant

    DepositSource.Delegated   // From delegated account

  ],

  [

    'akash1depositor1...',  // Primary depositor

    'akash1depositor2...',  // Secondary depositor

    'akash1depositor3...'   // Tertiary depositor

  ]

)



// Use the deposit config when creating a bid

const bid = await market.createBid({

  orderId: {

    owner: 'akash1...',

    dseq: '12345',

    gseq: 1,

    oseq: 1

  },

  provider: 'akash1provider...',

  price: { denom: 'uakt', amount: '100' },

  depositConfig // Use multi-source deposit instead of single deposit

})



// Deposit funds from a specific depositor

import { EscrowManager } from '@cryptoandcoffee/akash-jsdk-core'



const escrow = new EscrowManager(provider)



await escrow.depositFunds({

  accountId: { scope: 'deployment', xid: '12345' },

  amount: { denom: 'uakt', amount: '1000000' },

  depositor: 'akash1depositor2...' // Specify which depositor

})



// List escrow accounts with depositor information

const accounts = await escrow.listAccounts({

  owner: 'akash1...'

})



accounts.forEach(account => {

  console.log(`Account ${account.id.xid}:`)

  console.log(`  Depositor: ${account.depositor}`)

  console.log(`  Balance: ${account.balance.amount} ${account.balance.denom}`)

  console.log(`  Funds: ${account.funds.amount} ${account.funds.denom}`)

})

```



### Lease Termination Tracking (AEP-39)



Track why leases are terminated:



```typescript

import { MarketManager, LeaseCloseReason } from '@cryptoandcoffee/akash-jsdk-core'



const market = new MarketManager(provider)



// Close a lease with a specific reason

await market.closeLease(

  {

    owner: 'akash1...',

    dseq: '12345',

    gseq: 1,

    oseq: 1,

    provider: 'akash1provider...'

  },

  LeaseCloseReason.InsufficientFunds

)



// Available close reasons:

// - LeaseCloseReason.Unspecified

// - LeaseCloseReason.ManifestTimeout

// - LeaseCloseReason.Unstable

// - LeaseCloseReason.InsufficientFunds

// - LeaseCloseReason.UserRequested



// Query lease details to see close reason

const lease = await market.getLease({

  owner: 'akash1...',

  dseq: '12345',

  gseq: 1,

  oseq: 1,

  provider: 'akash1provider...'

})



if (lease && lease.state === 'closed' && lease.closeReason) {

  console.log(`Lease closed due to: ${lease.closeReason}`)



  // Handle different close reasons

  switch (lease.closeReason) {

    case LeaseCloseReason.InsufficientFunds:

      console.log('Please deposit more funds to continue')

      break

    case LeaseCloseReason.ManifestTimeout:

      console.log('Provider did not receive manifest in time')

      break

    case LeaseCloseReason.Unstable:

      console.log('Workload was unstable')

      break

    case LeaseCloseReason.UserRequested:

      console.log('User requested termination')

      break

  }

}

```



### CLI Usage



```bash

# Initialize new Akash project

akash-cli init

# ✓ Choose framework (vanilla, react, next)

# ✓ Configure network settings

# ✓ Generate project files



# Deploy application

akash-cli deploy app.yml --config ~/.akash/config.json



# Check deployment status

akash-cli status --owner akash1...



# Close deployment

akash-cli close --deployment 12345 --owner akash1... --yes

```



## 📚 SDK Modules



### Core Package Features



| Module | Description | Key Features |

|--------|-------------|--------------|

| **DeploymentManager** | Deployment lifecycle management | Create, update, close, list deployments |

| **MarketManager** | Marketplace operations | Orders, bids, leases, market statistics, multi-source deposits |

| **ProviderManager** | Provider interactions | Registration, capacity, manifest deployment |

| **WalletManager** | Wallet integration | Keplr, Cosmostation, transaction signing |

| **SDLManager** | SDL processing | Parse, validate, convert, optimize SDL files |

| **CertificateManager** | Certificate management | Client certificates, secure communication (legacy) |

| **JWTAuthManager** | JWT authentication | Token generation, validation, ES256K signatures (Mainnet 14+) |

| **EscrowManager** | Escrow operations | Deposit, withdrawal, multi-depositor support, account management |

| **GovernanceManager** | Governance participation | Proposals, voting, delegation |



### SDL Template Generation



```typescript

import { SDLManager } from '@cryptoandcoffee/akash-jsdk-core'



const sdlManager = new SDLManager(provider)



// Generate common templates

const webApp = sdlManager.generateTemplate('web-app')

const apiServer = sdlManager.generateTemplate('api-server')

const database = sdlManager.generateTemplate('database')

const worker = sdlManager.generateTemplate('worker')



// Parse and validate custom SDL

const sdl = sdlManager.parseSDL(yamlContent)

const validation = sdlManager.validateSDL(sdl)



// Convert to manifest and estimate costs

const manifest = sdlManager.generateManifest(sdl)

const costs = sdlManager.estimateResourceCosts(sdl)

```



## 🏗️ Development



### System Requirements



- **Node.js**: 18+ (ESM modules required)

- **TypeScript**: 5.9+ for development

- **Package Manager**: pnpm (recommended) or npm



### Monorepo Setup



```bash

# Clone repository

git clone 

cd akash-jsdk



# Install dependencies (uses pnpm workspaces)

pnpm install



# Build all packages

pnpm run build



# Run tests with coverage

pnpm test -- --coverage



# Development mode (watch)

pnpm run dev

```



### Package Development Scripts



```bash

# Build individual packages

cd packages/core && pnpm build

cd packages/react && pnpm build

cd packages/cli && pnpm build



# Test individual packages

pnpm test packages/core

pnpm test packages/react -- --coverage



# Type checking

pnpm run typecheck

```



## 📊 Comprehensive Test Results



### Overall Statistics

- **Total Tests**: 1,280 tests passing

- **Test Files**: 53 comprehensive test suites

- **Coverage**: 100% statements, functions, and lines across all packages

- **Branch Coverage**: 100% (3 packages), 98.15% (core package)

- **Test Duration**: ~6 seconds total

- **Source Lines**: 25,000+ lines of production code



### Package-Level Coverage



| Package | Tests | Coverage | Features Tested |

|---------|-------|----------|----------------|

| **Core** | 888 tests | 100% statements/functions/lines, 98.15% branches | SDK modules, JWT auth, multi-depositor escrow, lease tracking, providers, batch operations, IBC, staking, error handling |

| **CLI** | 148 tests | 100% all metrics | Commands, config management, CLI execution, subprocess testing |

| **React** | 141 tests | 100% all metrics | Hooks, context, component lifecycle, error boundaries |

| **Protobuf** | 103 tests | 100% all metrics | Type generation, serialization, Mainnet 14 types, error conditions |



### Testing Infrastructure



- **Framework**: Vitest with V8 coverage provider

- **Environments**: Node.js (core/CLI/protobuf), jsdom (React)

- **Features**: Async/await patterns, comprehensive mocking, error path testing

- **Quality**: Zero flaky tests, deterministic results, enterprise-grade reliability



## 🏛️ Architecture Highlights



### Modern TypeScript Configuration

- **Target**: ES2022 with bundler module resolution

- **Strict Mode**: Full type safety with comprehensive rules

- **Project References**: Incremental compilation support

- **Path Mapping**: Workspace package aliases



### Performance Optimizations

- **Tree-Shaking**: Modular exports for minimal bundle size

- **Code Splitting**: Package-level separation of concerns

- **Incremental Builds**: TypeScript composite projects

- **Memory Efficiency**: Optimized protobuf serialization



### Developer Experience

- **IntelliSense**: Rich TypeScript support

- **Error Handling**: Comprehensive error types with context

- **Documentation**: Extensive inline documentation

- **Examples**: Working examples in `examples/` directory



## 🛠️ Build Configuration



### TypeScript Project Structure

```json

{

  "references": [

    { "path": "./packages/protobuf" },

    { "path": "./packages/core" },

    { "path": "./packages/react" },

    { "path": "./packages/cli" }

  ]

}

```



### Output Formats

- **ES Modules**: Primary format for modern bundlers

- **CommonJS**: Compatibility layer for Node.js

- **Type Definitions**: Complete `.d.ts` files

- **Source Maps**: Full debugging support



## 📄 License



Apache License 2.0 - see [LICENSE](LICENSE) file for details.



## 🛡️ Quality Assurance



This SDK represents exceptional quality standards:



- **100% Statement Coverage**: Every executable line tested

- **100% Function Coverage**: Every function validated

- **100% Line Coverage**: Complete code execution validation

- **Near-Perfect Branch Coverage**: 98.15%+ on complex modules

- **Zero Test Failures**: Robust, reliable test suite

- **Production Ready**: Enterprise-grade quality assurance



## 🙏 Acknowledgments



Built from scratch as a modern replacement for existing Akash Network JavaScript tooling, focusing on developer experience, type safety, and comprehensive testing coverage.



---



*This SDK represents a complete, production-ready implementation built with modern web standards and world-class quality assurance.*