Dubhe Client SDK for Initia

Before getting started with Dubhe Client SDK, please install the required dependencies:

pnpm install @0xobelisk/initia-client @0xobelisk/initia-common

Note: @0xobelisk/initia-common contains essential configuration type definitions like DubheConfig, which are necessary for contract development.

Dubhe provides a client SDK for interacting with Initia Move contracts across various platforms including browsers, Node.js, and COCOS game engine.

Getting Started

Prerequisites

Before using the SDK, ensure you have:

Created and deployed your contract using the Dubhe CLI
Obtained the packageId after deployment

Data Model Setup

First, define your contract’s configuration using DubheConfig:

import { DubheConfig } from "@0xobelisk/initia-common";
 
export const dubheConfig = {
  name: "counter",
  description: "counter",
  systems: ["counter"],
  schemas: {
    counter: {
      structure: {
        value: "StorageValue<u32>",
      },
    },
  },
} as DubheConfig;

Generate the contract code using CLI:

pnpm dubhe schemagen

Initializing the Client

The Dubhe client can be initialized in several ways:

import { Dubhe, NetworkType } from "@0xobelisk/initia-client";
 
// Using mnemonics
const dubhe = new Dubhe({
  mnemonics: "your mnemonic words...",
  networkType: "mainnet",
  packageId: "YOUR_PACKAGE_ID",
  metadata: metadata,
});
 
// Using secret key
const dubhe = new Dubhe({
  secretKey: "your-secret-key",
  networkType: "mainnet",
  packageId: "YOUR_PACKAGE_ID",
  metadata: metadata,
});

Account Management

The SDK provides comprehensive account management features:

// Get current address
const address = dubhe.currentAddress();
 
// Get address in hex format
const hexAddress = dubhe.getHexAddress();
 
// Switch account using derive path
dubhe.switchAccount({
  accountIndex: 2,
  isExternal: false,
  addressIndex: 10,
});
 
// Get balance
const balance = await dubhe.getBalance(address);
const balances = await dubhe.getBalances(address);
 
// Request faucet tokens (testnet/localnet only)
await dubhe.requestFaucet(address, 10000000, "testnet");

Executing Transactions

To interact with contract methods:

// Execute transaction
const response = await dubhe.tx.counter_system.increase({
  params: ["param1", "param2"],
  typeArguments: ["type1", "type2"],
});
 
// For wallet integration (raw transaction)
const rawTx = await dubhe.tx.counter_system.increase({
  params: ["param1", "param2"],
  typeArguments: ["type1", "type2"],
  isRaw: true,
});
const response = await dubhe.signAndSendTxnWithPayload([rawTx]);

Querying Data

To query contract state:

// Simple query
const result = await dubhe.query.counter_system.get({
  params: ["param1", "param2"],
  typeArguments: ["type1", "type2"],
});

Transaction Building

The SDK provides methods to build and send transactions:

// Generate Move call payload
const payload = dubhe.generateMoveCallPayload(
  sender,
  moduleAddress,
  moduleName,
  funcName,
  typeArguments,
  params
);
 
// Sign and send transaction
const response = await dubhe.signAndSendTxnWithPayload([payload], sender);

Chain Interaction

The SDK provides methods to interact with the chain:

// Get chain ID
const chainId = await dubhe.getChainId();
 
// Get package ID
const packageId = dubhe.getPackageId();
 
// Get metadata
const metadata = dubhe.getMetadata();

Transaction Structure

Both query and transaction methods accept a parameter structure with the following fields:

{
  sender?: AccAddress | string;  // Optional: Transaction sender
  params?: string[];            // Optional: Array of parameters
  typeArguments?: string[];     // Optional: Generic type arguments
  isRaw?: boolean;             // Optional: Return raw transaction instead of executing
}

Best Practices

Always handle transaction responses properly
Implement proper error handling
Use appropriate network types for different environments
Manage account derivation paths carefully
Consider using raw transactions for wallet integrations

Known Limitations

⚠️ Important Notes:

Faucet requests are limited to testnet and localnet environments
Some complex transaction types might require additional handling

Support

For more information or support, please visit our GitHub repository or join our community channels.

CLI Schemas