Thanks to visit codestin.com
Credit goes to Github.com

Skip to content

Modern JavaScript SDK for Akash Network.

License

Notifications You must be signed in to change notification settings

cryptoandcoffee/akash-jsdk

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

247 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

@cryptoandcoffee/akash-jsdk

npm version npm downloads CI Tests Coverage 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

# 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)

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

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

function App() {
  return (
    <AkashProvider 
      config={{
        rpcEndpoint: 'https://rpc.akashedge.com:443',
        chainId: 'akashnet-2'
      }}
      autoConnect
    >
      <Dashboard />
    </AkashProvider>
  )
}

function Dashboard() {
  const { deployments, loading, createDeployment, closeDeployment } = useDeployments('akash1...')
  const { leases } = useLeases('akash1...')
  const { providers } = useProviders()
  
  if (loading) return <div>Loading deployments...</div>
  
  return (
    <div>
      <h2>Deployments ({deployments.length})</h2>
      {deployments.map(deployment => (
        <div key={deployment.deploymentId.dseq}>
          Deployment {deployment.deploymentId.dseq} - {deployment.state}
          <button onClick={() => closeDeployment(deployment.deploymentId)}>
            Close
          </button>
        </div>
      ))}
      
      <h2>Available Providers ({providers.length})</h2>
      {providers.map(provider => (
        <div key={provider.owner}>
          {provider.hostUri} - {provider.attributes.find(a => a.key === 'region')?.value}
        </div>
      ))}
    </div>
  )
}

πŸ†• 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)

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

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

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

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

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)

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:

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:

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

# 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

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

# Clone repository
git clone <repository-url>
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

# 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

{
  "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 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.