TypeScript SDK¶

The ACDC TypeScript SDK (@acdc/sdk) provides a comprehensive interface for interacting with the Alpha and Delta chains from JavaScript and TypeScript applications.

Installation¶

npm install @acdc/sdk

Requirements: - Node.js 18+ or modern browser - TypeScript 5.0+ (for TypeScript users)

Client Setup¶

Basic Setup¶

import { AcdcClient } from '@acdc/sdk';

const client = new AcdcClient({
  chain: 'delta',
  network: 'mainnet'
});

Advanced Configuration¶

import { AcdcClient, LogLevel } from '@acdc/sdk';

const client = new AcdcClient({
  chain: 'delta',
  network: 'mainnet',

  // Custom endpoints
  rpcUrl: 'https://my-rpc.example.com',
  wsUrl: 'wss://my-ws.example.com',

  // Authentication
  apiKey: process.env.ACDC_API_KEY,

  // Timeouts and retries
  timeout: 30000,
  retries: 3,
  retryDelay: 1000,

  // Logging
  logLevel: LogLevel.Debug,

  // Custom fetch (for server-side)
  fetch: customFetch,
});

Wallet Management¶

Creating Wallets¶

import { Wallet } from '@acdc/sdk';

// Generate new wallet
const wallet = Wallet.create();
console.log('Address:', wallet.address);
console.log('Mnemonic:', wallet.mnemonic);

// From mnemonic
const restored = Wallet.fromMnemonic(
  'abandon abandon abandon ...',
  { path: "m/44'/60'/0'/0/0" }
);

// From private key
const imported = Wallet.fromPrivateKey('0xprivatekey...');

Connecting Wallet to Client¶

// Connect wallet to client for signing
const connectedWallet = wallet.connect(client);

// Now you can send transactions
const tx = await connectedWallet.sendTransaction({
  to: 'dx1recipient...',
  value: parseUnits('1.0', 18)
});

HD Wallet Derivation¶

import { HDWallet } from '@acdc/sdk';

const hdWallet = HDWallet.fromMnemonic('abandon abandon ...');

// Derive accounts
const account0 = hdWallet.derive(0);
const account1 = hdWallet.derive(1);

// Custom derivation path
const custom = hdWallet.derivePath("m/44'/60'/0'/0/5");

Querying Data¶

Account Information¶

// Get balance
const balance = await client.getBalance('dx1abc...');
console.log(`Balance: ${balance.formatted} ACDC`);

// Get nonce
const nonce = await client.getNonce('dx1abc...');

// Get account details
const account = await client.getAccount('dx1abc...');
console.log(`Nonce: ${account.nonce}`);
console.log(`Balance: ${account.balance}`);
console.log(`Code Hash: ${account.codeHash}`);

Block Information¶

// Get latest block
const latest = await client.getBlock('latest');
console.log(`Block ${latest.number}: ${latest.hash}`);

// Get specific block
const block = await client.getBlock(1234567);

// Get block with transactions
const blockWithTx = await client.getBlock(1234567, true);
for (const tx of blockWithTx.transactions) {
  console.log(`  TX: ${tx.hash}`);
}

Transaction Information¶

// Get transaction by hash
const tx = await client.getTransaction('0xtxhash...');
console.log(`From: ${tx.from}`);
console.log(`To: ${tx.to}`);
console.log(`Value: ${formatUnits(tx.value, 18)} ACDC`);

// Get transaction receipt
const receipt = await client.getTransactionReceipt('0xtxhash...');
console.log(`Status: ${receipt.status === 1 ? 'Success' : 'Failed'}`);
console.log(`Gas Used: ${receipt.gasUsed}`);

Sending Transactions¶

Simple Transfer¶

const tx = await connectedWallet.sendTransaction({
  to: 'dx1recipient...',
  value: parseUnits('1.0', 18)
});

// Wait for 1 confirmation
const receipt = await tx.wait(1);
console.log(`Confirmed in block ${receipt.blockNumber}`);

Advanced Transaction Options¶

const tx = await connectedWallet.sendTransaction({
  to: 'dx1recipient...',
  value: parseUnits('1.0', 18),

  // Gas settings
  gasLimit: 21000n,
  gasPrice: parseUnits('10', 9),  // 10 gwei

  // Or use EIP-1559 gas
  maxFeePerGas: parseUnits('20', 9),
  maxPriorityFeePerGas: parseUnits('2', 9),

  // Nonce (optional, auto-fetched if omitted)
  nonce: 42,

  // Data for contract calls
  data: '0x...',
});

Estimating Gas¶

const gasEstimate = await client.estimateGas({
  from: 'dx1sender...',
  to: 'dx1recipient...',
  value: parseUnits('1.0', 18)
});

console.log(`Estimated gas: ${gasEstimate}`);

Contract Interaction¶

Reading Contract State¶

import { Contract } from '@acdc/sdk';

const tokenAbi = [
  'function balanceOf(address owner) view returns (uint256)',
  'function symbol() view returns (string)',
  'function decimals() view returns (uint8)',
];

const token = new Contract('dx1tokencontract...', tokenAbi, client);

const balance = await token.balanceOf('dx1holder...');
const symbol = await token.symbol();
const decimals = await token.decimals();

console.log(`${formatUnits(balance, decimals)} ${symbol}`);

Writing to Contracts¶

const tokenAbi = [
  'function transfer(address to, uint256 amount) returns (bool)',
  'function approve(address spender, uint256 amount) returns (bool)',
];

const token = new Contract('dx1tokencontract...', tokenAbi, connectedWallet);

// Transfer tokens
const tx = await token.transfer(
  'dx1recipient...',
  parseUnits('100', 18)
);
await tx.wait();

// Approve spending
const approveTx = await token.approve(
  'dx1spender...',
  parseUnits('1000', 18)
);
await approveTx.wait();

Listening to Contract Events¶

const tokenAbi = [
  'event Transfer(address indexed from, address indexed to, uint256 value)',
];

const token = new Contract('dx1tokencontract...', tokenAbi, client);

// Listen to all Transfer events
token.on('Transfer', (from, to, value, event) => {
  console.log(`Transfer: ${from} -> ${to}: ${formatUnits(value, 18)}`);
});

// Filter events
const filter = token.filters.Transfer(null, 'dx1myaddress...');
token.on(filter, (from, to, value) => {
  console.log(`Received ${formatUnits(value, 18)} from ${from}`);
});

// Query past events
const events = await token.queryFilter(
  token.filters.Transfer(),
  1234567,  // fromBlock
  1234667   // toBlock
);

WebSocket Subscriptions¶

Subscribing to Events¶

// Subscribe to new blocks
const unsubBlocks = client.subscribe('newBlocks', (block) => {
  console.log(`Block ${block.number}`);
});

// Subscribe to pending transactions
const unsubTx = client.subscribe('pendingTransactions', (tx) => {
  console.log(`Pending: ${tx.hash}`);
});

// Subscribe to address activity
const unsubAddr = client.subscribe('address', {
  address: 'dx1myaddress...',
  includeTokenTransfers: true
}, (event) => {
  console.log(`Activity: ${event.hash}`);
});

// Unsubscribe
unsubBlocks();
unsubTx();
unsubAddr();

Connection Management¶

// Check WebSocket status
console.log(`WS Connected: ${client.ws.isConnected}`);

// Reconnect
await client.ws.reconnect();

// Close connection
client.ws.close();

Staking (Delta Chain)¶

import { Staking } from '@acdc/sdk';

const staking = new Staking(connectedWallet);

// Delegate stake
const delegateTx = await staking.delegate(
  'dx1validator...',
  parseUnits('1000', 18)
);
await delegateTx.wait();

// Get stake info
const stakeInfo = await staking.getStake('dx1myaddress...');
console.log(`Staked: ${formatUnits(stakeInfo.amount, 18)} ACDC`);
console.log(`Rewards: ${formatUnits(stakeInfo.rewards, 18)} ACDC`);

// Claim rewards
const claimTx = await staking.claimRewards();
await claimTx.wait();

// Unstake
const unstakeTx = await staking.unstake(parseUnits('500', 18));
await unstakeTx.wait();

Governance (Delta Chain)¶

import { Governance } from '@acdc/sdk';

const governance = new Governance(connectedWallet);

// Get active proposals
const proposals = await governance.getProposals({ status: 'active' });

for (const proposal of proposals) {
  console.log(`#${proposal.id}: ${proposal.title}`);
  console.log(`  For: ${proposal.votesFor}`);
  console.log(`  Against: ${proposal.votesAgainst}`);
}

// Vote on proposal
const voteTx = await governance.vote(42, 'yes');
await voteTx.wait();

// Create proposal
const proposeTx = await governance.propose({
  title: 'Increase Block Gas Limit',
  description: 'Proposal to increase...',
  actions: [
    {
      target: 'dx1paramcontract...',
      data: '0x...'
    }
  ]
});
await proposeTx.wait();

Alpha Chain (Privacy)¶

import { AlphaClient } from '@acdc/sdk';

const alphaClient = new AlphaClient({
  network: 'mainnet'
});

// Generate a view key
const viewKey = alphaClient.generateViewKey(wallet.privateKey);

// Scan for records
const records = await alphaClient.scanRecords(viewKey);
for (const record of records) {
  console.log(`Record: ${record.commitment}`);
  console.log(`  Value: ${formatUnits(record.value, 18)}`);
}

// Create private transfer
const privateTx = await alphaClient.createPrivateTransfer({
  wallet: connectedWallet,
  to: 'ax1recipient...',
  value: parseUnits('10', 18),
  records: records.slice(0, 2)  // Input records
});

// Submit transaction
const submitted = await alphaClient.submitTransaction(privateTx);
console.log(`TX Hash: ${submitted.hash}`);

Utilities¶

Unit Conversion¶

import { parseUnits, formatUnits, parseAcdc, formatAcdc } from '@acdc/sdk';

// Generic conversion
const wei = parseUnits('1.5', 18);     // 1500000000000000000n
const eth = formatUnits(wei, 18);      // "1.5"

// ACDC-specific helpers
const acdcWei = parseAcdc('1.5');      // 1500000000000000000n
const acdc = formatAcdc(acdcWei);      // "1.5"

Address Utilities¶

import { isValidAddress, getAddressChain, checksumAddress } from '@acdc/sdk';

// Validate address
isValidAddress('dx1abc...');           // true
isValidAddress('invalid');             // false

// Get chain from address
getAddressChain('dx1abc...');          // 'delta'
getAddressChain('ax1xyz...');          // 'alpha'

// Checksum address
checksumAddress('dx1abc...');          // 'dx1Abc...'

Hashing¶

import { keccak256, sha256, hashMessage } from '@acdc/sdk';

const hash = keccak256('0xdata...');
const msgHash = hashMessage('Sign this message');

TypeScript Types¶

import type {
  Block,
  Transaction,
  TransactionReceipt,
  Log,
  Balance,
  Account,
  Validator,
  Proposal,
  StakeInfo
} from '@acdc/sdk';

// Type-safe contract interaction
interface ERC20 {
  balanceOf(owner: string): Promise<bigint>;
  transfer(to: string, amount: bigint): Promise<Transaction>;
}

const token = new Contract('dx1token...', abi, client) as unknown as ERC20;
const balance: bigint = await token.balanceOf('dx1holder...');

Browser Usage¶

<script type="module">
  import { AcdcClient, Wallet } from 'https://cdn.jsdelivr.net/npm/@acdc/sdk/dist/esm/index.js';

  const client = new AcdcClient({
    chain: 'delta',
    network: 'mainnet'
  });

  const balance = await client.getBalance('dx1abc...');
  console.log(balance.formatted);
</script>

Error Reference¶

Error Class	Description
`RpcError`	JSON-RPC error from node
`NetworkError`	Connection/timeout error
`InvalidAddressError`	Invalid address format
`InsufficientFundsError`	Not enough balance
`NonceError`	Nonce mismatch
`SignatureError`	Invalid signature