feat(plugin): auctionlog — privacy-preserving audit trails via HCS

[atharvalade]

Summary

New auctionlog plugin that publishes cryptographic commitment hashes to Hedera Consensus Service (HCS) topics, enabling tamper-evident public audit trails for auction and procurement workflows — without revealing any business-sensitive data.

Resolves #1194 (ETHDenver 2026 — Build the Best Hiero CLI Plugin)

---

What it does

At each critical stage of an auction (created → bidding-open → bidding-closed → awarded → settled → disputed), the plugin publishes a commitment hash to an HCS topic:

SHA-256({ auctionId, stage, cantonRef, adiTx, timestamp, nonce })

Anyone can verify the sequence and timing of events. Nobody can reverse-engineer the hash into actual bid values, delivery terms, or party identities.

Commands

Command	Description
hcli auctionlog publish	Publish a commitment hash for an auction stage to HCS
hcli auctionlog verify	Re-compute and validate stored commitment hashes
hcli auctionlog export	Export the full audit timeline as JSON or CSV
hcli auctionlog list	List all tracked auctions with stage counts

Example usage

# Publish commitments at each stage
hcli auctionlog publish --auction-id AUCTION-001 --stage created --canton-ref canton-tx-abc
hcli auctionlog publish --auction-id AUCTION-001 --stage awarded --adi-tx 0xdeadbeef

# Verify integrity
hcli auctionlog verify --auction-id AUCTION-001

# Export for compliance review
hcli auctionlog export --auction-id AUCTION-001 --type csv --file audit-report.csv

# List all tracked auctions
hcli auctionlog list

Why this is useful beyond the hackathon

The publish → verify → export pattern is generic enough for any workflow that needs a tamper-evident public timeline on Hedera:

• Procurement & RFP — prove bid timing and scoring fairness
• Regulatory compliance — exportable JSON/CSV artifacts for audit
• Supply chain — commitment hashes for shipment, customs, delivery milestones
• Corporate governance — voting results, board resolutions, compliance checkpoints
• Multi-party agreements — prove sequence of approvals without exposing terms

Architecture fit

• Follows the exact Hiero CLI plugin architecture (manifest-driven, stateless handlers, CommandHandlerArgs injection)
• Uses api.topic.createTopic() and api.topic.submitMessage() for HCS operations
• State persisted under auctionlog-data namespace via api.state
• Zod input/output schemas + Handlebars human templates — same pattern as topic, account, token plugins
• CommandExecutionResult return type on all handlers

Testing

14 unit tests across all 4 commands, using the same makeArgs/makeLogger test helpers from @/__tests__/mocks/mocks:

auctionlog publish  — 6 tests (success, topic creation, reuse, invalid stage, missing ID, topic failure)
auctionlog verify   — 3 tests (valid hash, tampered hash, missing audit log)
auctionlog export   — 3 tests (JSON export, CSV export, no entries)
auctionlog list     — 2 tests (populated list, empty list)

All pass with npx jest --testPathPatterns="auctionlog" and npx tsc --noEmit is clean.

Files changed

• New: src/plugins/auctionlog/ — 24 files (manifest, types, index, 4 commands with handler/input/output/index each, README, 4 test files)
• Modified: src/core/shared/config/cli-options.ts — 2 lines added (import + array entry)

Documentation

Full plugin README at src/plugins/auctionlog/README.md with:

• Architecture overview
• All commands with flags, examples, and expected output
• Privacy guarantee explanation
• State management details
• Core API integration table
• Test summary