Skip to content

alexchenai/hedera-apex-agent-trust

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

2 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

PACT Protocol: Programmable Agent Commitment Tracking on Hedera

Hedera Hello Future: Apex Hackathon 2026 — AI & Agents Track

Hedera Solidity TypeScript License

Built by: Alex Chen (AI agent builder) & Jhon MagdalenaChita Cloud


Overview

As autonomous AI agents become economic participants — transacting, delegating, and collaborating — a critical infrastructure gap has emerged: there is no standardized mechanism for agents to form binding service commitments with verifiable performance guarantees and automated economic consequences.

PACT Protocol solves this. It is a Programmable Agent Commitment Tracking layer built on Hedera, providing:

  • Trustless SLA enforcement between AI agents without human intermediation
  • Graduated escrow that releases proportionally as performance checkpoints are verified on-chain
  • HCS performance oracle — tamper-proof, ordered performance attestations at $0.0001 per log
  • Automated dispute resolution with two-tier arbitration (automated + panel)
  • Reputation-adjusted collateral — agents with higher track records post less collateral

"Agent A contracts Agent B to scrape 500 sites in 2 hours for 50 USDC. PACT locks collateral, verifies each checkpoint via HCS, releases payment on completion, and slashes on failure — no human required."


Architecture

Agent A (Client)              Agent B (Provider)
      |                              |
      |--- createCommitment() ------>|
      |                              |--- acceptCommitment()
      |                              |
      |         PACTRegistry (on-chain)
      |         - Agent registration & reputation
      |         - Collateral requirements (reputation-adjusted)
      |
      |         PACTEscrow (on-chain)
      |         - Lock collateral at commitment formation
      |         - Graduated release per verified checkpoint
      |         - Slash distribution: 70% harmed / 20% treasury / 10% arbiter
      |
      |         Hedera Consensus Service (HCS)
      |         - Performance checkpoints (tamper-proof, 3-5s finality)
      |         - $0.0001 per attestation
      |         - 10,000+ TPS — scales to millions of agent interactions
      |
      |         PACTResolver (on-chain)
      |         - Tier 1: Automated (missed checkpoints, timeouts)
      |         - Tier 2: Arbiter panel (5 arbiters, 3/5 majority)

Why Hedera

Property Hedera Advantage PACT Use
Hedera Consensus Service (HCS) Ordered, immutable message log, 3-5s finality Performance checkpoint attestations
Hedera Token Service (HTS) Native tokens with KYC/freeze/supply controls Escrow tokens, PACT staking
Low fees ~$0.0001 per HCS message Economically viable for thousands of checkpoints per commitment
High throughput 10,000+ TPS Scales to ecosystem-wide agent commerce
EVM compatibility Solidity smart contracts on Hedera EVM Complex escrow and dispute logic
Fair ordering Hashgraph consensus prevents front-running Commitment market integrity

Smart Contracts

All contracts are in contracts/. Compiled for Hedera EVM (Solidity ^0.8.20).

PACTEscrow.sol

Manages graduated escrow for commitments. Funds lock when a commitment forms and release proportionally as HCS-verified checkpoints are submitted.

Key mechanics:

  • Collateral locked at acceptCommitment()
  • Each releaseCheckpoint() call releases totalEscrow * checkpointWeight / totalWeight
  • Slashing distributes as: 70% to harmed party, 20% to treasury, 10% to arbiter panel
  • Integrates with Hedera Token Service via the 0x167 HTS precompile for native token operations
function lockFunds(bytes32 commitmentId, uint256 amount, address token) external;
function releaseCheckpoint(bytes32 commitmentId, uint256 checkpointIndex) external;
function slash(bytes32 commitmentId, uint256 severityBps) external;

PACTRegistry.sol

Agent registration and reputation management. Tracks performance history and computes collateral requirements based on reputation score.

Key mechanics:

  • Initial reputation: 0 (new agents post maximum collateral, base rate 20%)
  • Reputation gain: +5 per successful completion (scaled by value)
  • High-reputation agents unlock lower collateral requirements
  • Agents must be registered before forming commitments
function registerAgent(address agent, string calldata metadataURI) external;
function getCollateralRequirement(address agent, uint256 commitmentValue) external view returns (uint256);
function updateReputation(address agent, bool success, uint256 value) external;

PACTResolver.sol

Two-tier dispute resolution engine. Evaluates commitment breaches using HCS evidence logs and produces binding rulings.

  • Tier 1 (Automated): Clear breaches — missed checkpoints, timeout, unreachable agent. Resolved on-chain instantly.
  • Tier 2 (Arbiter Panel): Ambiguous cases. 5 arbiters selected from staked PACT holders (minimum 1,000 PACT stake). 3/5 majority required for ruling.
function fileDispute(bytes32 commitmentId, string calldata evidenceTopicId) external;
function resolveAutomated(bytes32 commitmentId) external returns (bool resolved);
function submitArbiterVote(uint256 disputeId, bool inFavorOfClient) external;

Interfaces


SDK

TypeScript plugin for Hedera Agent Kit. Drop PACT into any Hedera agent in minutes.

Files in sdk/:

  • plugin.tsPACTPlugin class implementing full commitment lifecycle
  • types.ts — All TypeScript types: PACTCommitment, PACTCheckpoint, AgentReputation, HCSMessage, etc.

Quick Integration

import { PACTPlugin } from '@pact-protocol/hedera-agent-plugin';

const agent = new HederaAgentKit({
  accountId: '0.0.12345',
  privateKey: process.env.HEDERA_PRIVATE_KEY,
  network: 'testnet',
  plugins: [new PACTPlugin({
    registryTopicId: '0.0.999999',
    escrowContractId: '0.0.888888',
    resolverContractId: '0.0.777777',
    registryContractId: '0.0.666666',
  })],
});

// Agent A creates a commitment
const commitment = await agent.pact.createCommitment({
  provider: '0.0.67890',
  value: 50_000_000,        // 50 USDC (8 decimals)
  token: '0.0.456789',      // HTS USDC token
  deadline: Date.now() + 2 * 60 * 60 * 1000,  // 2 hours
  checkpoints: [
    { description: '250 sites scraped', weight: 50 },
    { description: '500 sites scraped', weight: 50 },
  ],
  slaSpec: {
    successRate: 0.95,
    latencyMs: 7_200_000,
  },
});

// Agent B submits a checkpoint via HCS
await agent.pact.submitCheckpoint({
  commitmentId: commitment.id,
  checkpointIndex: 0,
  evidence: { sitesScraped: 250, errorRate: 0.02 },
});

Whitepaper

The full technical whitepaper is at WHITEPAPER.md (974 lines).

Sections include:

  1. Introduction & Why Hedera
  2. Problem Statement — the trust vacuum in agentic commerce
  3. Related Work — HTLC, SUAVE, IC3, OpenClaw, LangChain
  4. System Architecture
  5. PACT Lifecycle — form, monitor, complete, dispute
  6. Hedera Service Integration (HCS, HTS, EVM)
  7. Commitment Specification Language (PSL)
  8. Escrow and Staking Mechanics
  9. Performance Monitoring via HCS
  10. Dispute Resolution Engine
  11. Economic Model
  12. Security Analysis
  13. Implementation
  14. Use Cases
  15. Roadmap
  16. Conclusion

How to Run

Prerequisites

  • Node.js 20+
  • Hedera testnet account — get one free at portal.hedera.com
  • TypeScript (for SDK development)

Setup

git clone https://github.com/alexchenai/hedera-apex-agent-trust.git
cd hedera-apex-agent-trust
npm install

Configure

cp .env.example .env
# Edit .env with your Hedera testnet credentials:
# HEDERA_ACCOUNT_ID=0.0.XXXXX
# HEDERA_PRIVATE_KEY=302e...
# HEDERA_NETWORK=testnet

Run

# Start the agent trust server
npm start

# Run tests (mock mode, no credentials needed)
npm test

# Deploy contracts to Hedera testnet
npx hardhat deploy --network hedera-testnet

Deploy Contracts

# Set contract addresses after deployment in .env:
# PACT_REGISTRY_CONTRACT=0.0.XXXXX
# PACT_ESCROW_CONTRACT=0.0.XXXXX
# PACT_RESOLVER_CONTRACT=0.0.XXXXX
# PACT_REGISTRY_TOPIC=0.0.XXXXX

Verify on HashScan

All HCS messages and contract interactions are publicly verifiable: https://hashscan.io/testnet/topic/{topicId}


Unique Value Propositions

1. Graduated Escrow Unlike all-or-nothing escrow, PACT releases payment incrementally as each checkpoint is verified on HCS. Providers earn as they deliver; clients don't wait until the end to see if an agent performed.

2. HCS as Performance Oracle Hedera Consensus Service provides the tamper-proof, fairly-ordered, low-cost event stream that makes a trustless performance oracle possible for the first time. At $0.0001/message, an agent can log 1,000 checkpoints for $0.10.

3. Automated Dispute Resolution Most disputes in agent commerce are clear-cut: a deadline was missed, checkpoints weren't submitted, or an agent went offline. PACTResolver handles these automatically on-chain. Only genuinely ambiguous cases escalate to a 5-arbiter panel — keeping the system efficient.

4. Reputation-Adjusted Collateral New agents post 20% collateral. Agents with long successful track records post less. This mirrors real-world contractor bonding and creates a natural incentive for sustained good behavior.

5. Native HTS Integration PACT works with any HTS token as collateral, not just HBAR. This allows commitments denominated in stablecoins (USDC, USDT) for predictable pricing between agents.


Hedera Apex Hackathon 2026

This project is submitted to the Hedera Hello Future: Apex Hackathon 2026, AI & Agents Track.

Track relevance: PACT Protocol directly addresses the trust infrastructure gap in AI agent ecosystems. As agents transact autonomously at scale, the ability to form verifiable commitments on a high-throughput, low-cost ledger like Hedera becomes foundational infrastructure — not a nice-to-have.

Hedera services used:

  • Hedera Consensus Service (HCS) — performance oracle backbone
  • Hedera Token Service (HTS) — escrow and staking tokens
  • Hedera EVM — smart contracts (PACTEscrow, PACTRegistry, PACTResolver)

Docs: docs/pitch-deck.html | docs/VIDEO_SCRIPT_JHON.md


Repository Structure

hedera-apex-agent-trust/
├── WHITEPAPER.md              # Full PACT Protocol technical paper (974 lines)
├── contracts/
│   ├── PACTEscrow.sol         # Graduated escrow with HTS precompile integration
│   ├── PACTRegistry.sol       # Agent registration and reputation management
│   ├── PACTResolver.sol       # Two-tier automated + arbiter dispute resolution
│   └── interfaces/
│       ├── IPACTEscrow.sol
│       └── IPACTRegistry.sol
├── sdk/
│   ├── plugin.ts              # PACTPlugin for Hedera Agent Kit
│   └── types.ts               # TypeScript types for the full PACT lifecycle
├── docs/
│   ├── pitch-deck.html        # Visual pitch deck
│   └── VIDEO_SCRIPT_JHON.md   # Video walkthrough script
└── src/                       # Node.js reference server

Team

  • Alex Chen (AI agent builder) — alexchen.chitacloud.dev
  • Jhon Magdalena (co-author, human supervisor) — Chita Cloud

Authors of WHITEPAPER.md: Jhon, Alex Chen


License

MIT

About

Agent Commerce Trust Protocol - Hedera Hello Future Apex Hackathon 2026 AI & Agents Track

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors