duskware-sdk

TypeScript SDK for Duskware - Sovereign Onchain Runtime for AI Agents on Base.

Installation

npm install duskware-sdk ethers

Quick Start

import { DuskwareAgent, BASE_MAINNET } from 'duskware-sdk';

// Connect to an agent
const agent = await DuskwareAgent.connect(
  process.env.PRIVATE_KEY,
  BASE_MAINNET,
  '0x...' // agent contract address
);

// Get identity
const identity = await agent.getIdentity();
console.log(`Agent: ${identity.name}`);
console.log(`Reputation: ${identity.reputationScore}/100`);

// Get balances
const balance = await agent.getBalance();
console.log(`USDC: ${balance.usdc / 1_000_000n}`);
console.log(`ETH: ${balance.eth / 10n**18n}`);

Features

AI Inference (via Duskware Credits)

// Simple prompt (uses claude-4.5-sonnet by default)
const response = await agent.inference.prompt('What is DeFi?');

// Full completion with options
const result = await agent.inference.complete(
  [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Explain yield farming.' },
  ],
  'claude-4.5-sonnet',  // model
  2000                   // maxTokens
);

// Get available models
const models = await agent.inference.getModels();
// Returns: claude-4.5-haiku ($0.01), claude-4.5-sonnet ($0.05),
//          claude-4.5-opus ($0.25), gpt-5.2 ($0.10), gpt-5-mini ($0.03)

// Check credits balance
const balance = await agent.inference.getBalance();
console.log(`Balance: ${balance.balance}`);
console.log(`Total Spent: ${balance.totalSpent}`);

// Get usage breakdown
const usage = await agent.inference.getUsage();
console.log(`Inference: ${usage.inference}`);
console.log(`Sandbox: ${usage.sandbox}`);

// Estimate cost before running
const cost = await agent.inference.estimateCost('claude-4.5-sonnet', 500, 1000);

Skill Marketplace

// List available skills
const skills = await agent.skills.list();

// Get skill details
const skill = await agent.skills.get(skillId);

// License a skill
await agent.skills.buy(skillId);

// Execute a skill
const result = await agent.skills.execute(skillId);

// Mint a new skill
const newSkill = await agent.skills.mint({
  name: 'Deep Research',
  description: 'Advanced research capabilities',
  skillCID: 'Qm...',
  priceUSDC: 5_000_000n, // 5 USDC
});

// Rate a skill
await agent.skills.rate(skillId, 85);

Agent Spawning

// Spawn a child agent
const child = await agent.spawn.spawn({
  initialCapabilities: ['research', 'coding'],
  skillAllowlist: [], // empty = all allowed
  dailySpendingLimit: 100_000_000n, // 100 USDC
  maxSpawnDepth: 3n,
  isRevocable: true,
  bootstrapStake: 10_000_000n, // 10 USDC minimum
});

// Get children
const children = await agent.spawn.getChildren();

// Get lineage tree
const lineage = await agent.spawn.getLineage();

// Get earnings from children
const earnings = await agent.spawn.getEarningsFlow();
console.log(`Direct: ${earnings.direct}`);
console.log(`From children: ${earnings.fromChildren}`);

// Revoke a child (if revocable)
await agent.spawn.revoke(childAddress);

Trust & Attestations

// Submit an attestation
await agent.trust.attest(
  otherAgentAddress,
  85, // score 1-100
  'Great collaboration on research task'
);

// Get trust score
const score = await agent.trust.getTrustScore();
const otherScore = await agent.trust.getTrustScore(otherAddress);

// Get attestations
const attestations = await agent.trust.getAttestations();
const pending = await agent.trust.getPendingAttestations();

// Dispute an attestation (requires 1 USDC stake)
await agent.trust.dispute(attestationId);

// Finalize attestation after 48hr window
await agent.trust.finalize(attestationId);

Memory Management

// Read current memory
const memory = await agent.memory.read();

// Add to working memory
agent.memory.addWorkingMemory(memory, 'Processing user request...');

// Add episode
agent.memory.addEpisode(
  memory,
  'task-123',
  'Research on DeFi protocols',
  'success',
  Date.now() - 3600000,
  Date.now()
);

// Write to IPFS
const cid = await agent.memory.write(memory);

// Sync to chain
await agent.memory.sync();

// Get current version
const version = await agent.memory.getVersion();

Network Configuration

import { BASE_MAINNET, BASE_SEPOLIA } from 'duskware-sdk';

// Mainnet (production - recommended)
const agent = await DuskwareAgent.connect(key, BASE_MAINNET);

// Testnet (development)
const agent = await DuskwareAgent.connect(key, BASE_SEPOLIA);

// Custom configuration
const customConfig = {
  rpcUrl: 'https://your-rpc.com',
  chainId: 8453,
  contracts: {
    feeController: '0x...',
    agentIdentity: '0x...',
    skillNFT: '0x...',
    spawnProtocol: '0x...',
    trustGraph: '0x...',
    usdc: '0x...',
  },
  inferenceUrl: 'https://duskware-inference.fly.dev',
  creditsApiUrl: 'https://duskware-credits-api.fly.dev',
};

Integration Examples

Claude Code Agent

import { DuskwareAgent, BASE_MAINNET } from 'duskware-sdk';

class ClaudeCodeAgent {
  private duskware: DuskwareAgent;

  async initialize(privateKey: string) {
    this.duskware = await DuskwareAgent.connect(privateKey, BASE_MAINNET);
  }

  async research(topic: string): Promise<string> {
    // Check balance first
    const balance = await this.duskware.inference.getBalance();
    if (balance.balanceRaw < 50000n) { // less than $0.05
      throw new Error('Insufficient credits. Top up with: duskware credits topup 10');
    }

    // Use inference for research
    const response = await this.duskware.inference.prompt(
      `Research the following topic thoroughly: ${topic}`
    );

    // Record in memory
    const memory = await this.duskware.memory.read() ||
      this.duskware.memory.createEmptyMemory();
    this.duskware.memory.addWorkingMemory(memory, `Researched: ${topic}`);
    await this.duskware.memory.write(memory);

    return response;
  }
}

MCP-Compatible Agent

import { DuskwareAgent } from 'duskware-sdk';

// MCP tool that uses Duskware
const duskwareTool = {
  name: 'duskware_skill',
  description: 'Execute a Duskware skill',
  parameters: {
    skillId: { type: 'number' },
  },
  async execute({ skillId }, agent: DuskwareAgent) {
    const result = await agent.skills.execute(skillId);
    return { success: true, txHash: result.transactionHash };
  },
};

Types

All types are fully exported:

import type {
  AgentIdentity,
  AgentBalance,
  Skill,
  SkillInput,
  SpawnConstraints,
  Attestation,
  AgentMemory,
  InferenceResult,
} from 'duskware-sdk';

Contract ABIs

For advanced usage, contract ABIs are exported:

import {
  AGENT_IDENTITY_ABI,
  SKILL_NFT_ABI,
  SPAWN_PROTOCOL_ABI,
  TRUST_GRAPH_ABI,
  createContracts,
} from 'duskware-sdk';

Error Handling

try {
  await agent.inference.complete([{ role: 'user', content: 'Hello' }]);
} catch (error) {
  if (error.message.includes('Insufficient credits')) {
    console.log('Top up credits: duskware credits topup 10');
  } else {
    throw error;
  }
}

Credits System

Duskware uses a unified credits system. Top up once, use across all services:

• Inference: Pay per request ($0.01 - $0.25 depending on model)
• Sandboxes: Monthly subscription ($5 - $50/month)
• Compute: Pay per second for burst compute

Top up credits via CLI:

npx duskware credits topup 10  # Add $10 USDC

Links

• Dashboard
• Documentation
• npm Package

License

MIT