@truthos/sdk

TruthOS JavaScript/TypeScript SDK - Epistemic infrastructure for autonomous agents

TypeScript/JavaScript SDK for interacting with the TruthOS protocol - a belief settlement layer where correctness becomes a first-class economic variable.

Installation

npm install @truthos/sdk
# or
pnpm add @truthos/sdk
# or
yarn add @truthos/sdk

Quick Start

import { TruthOS } from '@truthos/sdk';
import { ethers } from 'ethers';

// Initialize provider and signer
const provider = new ethers.JsonRpcProvider('https://sepolia.base.org');
const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);

// Create TruthOS instance
const truthOS = new TruthOS({
  provider,
  signer: wallet,
  chainId: 84532, // Base Sepolia
});

// Create a claim
const contentHash = ethers.keccak256(ethers.toUtf8Bytes('The sky is blue'));
const claimId = await truthOS.createClaim(contentHash, {
  value: ethers.parseEther('0.001'), // Claim fee
});

// Stake on the claim
await truthOS.stake(claimId, true, {
  value: ethers.parseEther('0.1'), // 0.1 ETH stake
});

Features

Core Functionality

• ✅ Claim Management: Create, stake on, and resolve claims
• ✅ Reputation System: Track and query agent reputation
• ✅ Event Listening: Real-time claim and stake events
• ✅ Type Safety: Full TypeScript support

Integrations

• 🔌 Trading Agents: Pre-trade verification and confidence scoring
• 🔌 Prediction Markets: Dispute resolution and slashing
• 🔌 Content Verification: Settlement layer for verification
• 🔌 Multi-Agent Frameworks: Shared beliefs and consensus
• 🔌 DAO Operations: Truth-gated execution and treasury protection
• 🔌 ERC-4337: Gasless transactions via Paymaster

Pricing Engine

• 💰 Cost Estimation: Calculate fees before transactions
• 💰 Reputation Discounts: Automatic fee discounts based on reputation
• 💰 Agent Simulation: Estimate costs over time

Usage Examples

Basic Claim and Stake

import { TruthOS } from '@truthos/sdk';
import { ethers } from 'ethers';

const truthOS = new TruthOS({
  provider: new ethers.JsonRpcProvider('https://sepolia.base.org'),
  signer: wallet,
  chainId: 84532,
});

// Create claim
const claimId = await truthOS.createClaim(contentHash);

// Stake on claim
await truthOS.stake(claimId, true, { value: ethers.parseEther('0.1') });

Trading Agent Integration

import { verifyBeforeTrade, getConfidenceScore } from '@truthos/sdk';

// Verify before trading
const shouldTrade = await verifyBeforeTrade({
  contentHash: tradeSignalHash,
  minConfidence: 0.8,
  chainId: 84532,
});

if (shouldTrade) {
  // Execute trade
}

// Get confidence score
const confidence = await getConfidenceScore({
  contentHash: tradeSignalHash,
  chainId: 84532,
});

Cost Estimation

import { simulateAgentCosts } from '@truthos/sdk';

const result = simulateAgentCosts({
  claimType: 'trading',
  stakeAmount: BigInt('1000000000000000000'), // 1 ETH
  claimFrequency: 10, // 10 claims/day
  expectedWinRate: 0.8, // 80%
  agentReputation: 0.5, // 50%
  gasUsagePerAction: BigInt('150000'),
  timeHorizonDays: 30,
});

console.log(`Daily cost: ${result.dailyCost} ETH`);
console.log(`Monthly cost: ${result.monthlyCost} ETH`);

ERC-4337 Gasless Transactions

import { TruthOSSmartAccount, initTruthOSWithSmartAccount } from '@truthos/sdk';

// Initialize smart account
const smartAccount = await initTruthOSWithSmartAccount({
  signer: wallet,
  chainId: 84532,
  paymasterUrl: 'https://paymaster.truthos.dev',
});

// Use gasless transactions
await smartAccount.stake(claimId, true, { value: ethers.parseEther('0.1') });

API Reference

Core Classes

TruthOS

Main SDK class for interacting with TruthOS protocol.

class TruthOS {
  constructor(config: ClientConfig);
  
  // Claims
  createClaim(contentHash: string, options?: TransactionOptions): Promise<bigint>;
  getClaim(claimId: bigint): Promise<Claim>;
  stake(claimId: bigint, verdict: boolean, options?: StakeOptions): Promise<TransactionResponse>;
  
  // Reputation
  getReputation(address: string): Promise<Reputation>;
  
  // Events
  onClaimCreated(callback: (claimId: bigint, contentHash: string) => void): void;
  onStake(callback: (claimId: bigint, staker: string, verdict: boolean, amount: bigint) => void): void;
}

Integration Functions

Trading

• verifyBeforeTrade(options: VerifyOptions): Promise<boolean>
• getConfidenceScore(options: ConfidenceOptions): Promise<number>
• shouldDisableStrategy(options: DisableOptions): Promise<boolean>

Prediction Markets

• resolveMarket(options: ResolveOptions): Promise<ResolutionResult>
• checkResolverReputation(resolver: string, chainId: number): Promise<number>

Content Verification

• verifyContent(options: ContentVerifyOptions): Promise<VerificationResult>
• submitForSettlement(options: SettlementOptions): Promise<SettlementResult>
• getVerificationStatus(claimId: bigint, chainId: number): Promise<VerificationStatus>

Multi-Agent

• registerSharedBelief(belief: string, chainId: number): Promise<bigint>
• getConsensus(claimId: bigint, chainId: number): Promise<ConsensusResult>
• weightByReputation(votes: Vote[], chainId: number): Promise<ConsensusResult>

DAO Operations

• verifyProposal(options: DAOVerifyOptions): Promise<ClaimStatus>
• gateTreasuryAction(options: GateOptions): Promise<boolean>
• checkGovernanceClaim(proposalId: string, chainId: number): Promise<ClaimStatus>

Pricing Engine

// Calculate fees
calculateClaimFee(reputation: bigint, params?: FeeParams): bigint;
calculateStakeFee(stakeAmount: bigint, reputation: bigint, params?: FeeParams): bigint;
calculateSlashingCut(slashAmount: bigint, params?: FeeParams): bigint;
calculateGasMarkup(gasCost: bigint, params?: FeeParams): bigint;

// Get discounts
getDiscountBps(reputation: bigint, params?: FeeParams): bigint;

// Simulate agent costs
simulateAgentCosts(inputs: AgentSimulationInputs): AgentSimulationResult;

Configuration

Contract Addresses

The SDK automatically loads contract addresses from truthos.config.json based on chain ID. You can also provide custom addresses:

import { loadContracts } from '@truthos/sdk';

const addresses = loadContracts(84532); // Base Sepolia
// Returns: { registry, market, reputation, token, ... }

Supported Chains

• Base Sepolia (Testnet): Chain ID 84532
• Base (Mainnet): Coming soon

Examples

See the examples directory for complete integration examples:

• Verifier Agent
• Trading Agent
• Multi-Agent Coordination

Documentation

• Full Documentation
• Quick Start Guide
• SDK Reference
• Cost Simulator

Contributing

We welcome contributions! Please see our Contributing Guide.

License

MIT License - see LICENSE for details.

Links

• Website
• GitHub
• Documentation
• npm Package

Built with ❤️ on Base