Sulkta-Coop/adacam
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
adacam/docs/research/adamaps-audit-2026-03-29.md

9.4 KiB
Raw Blame History

ADAMaps Code Audit — 2026-03-29

Comprehensive audit of actual codebase vs documentation.

Live System Status

API: https://api.adamaps.org/api/health → {"status":"ok","node":"rackham","agent_api":true,"phase":3}

Stats (live):

  • 14,523 detections
  • 7 devices
  • 2,941 images
  • 1,833 signs total
  • 108 agent-verified signs
  • 1,255 signs with location accuracy data
  • 0.178m average location accuracy

What's Actually Built

Agent Registration System

  • Crypto auth: Ed25519 signatures, HMAC challenge-response
  • Registration flow: /api/agent/challenge → sign nonce → /api/agent/register with manifest
  • Manifest fields: agent_type, model, runtime, operator_wallet (stored as JSONB)
  • 5 ADA stake check via Koios (non-blocking on API failure)
  • Groundtruth test: 5 oracle-curated signs, 3 correct to pass, 30-minute token TTL
  • Address validation: Enterprise addresses only (0x60/0x61 header), rejects base addresses

Agent Tiers

Tier Rep Score Notes
probation 0-29 Can't count toward consensus quorum
standard 30-59 Phase 1 only
trusted 60-79 Phase 1 + Phase 2
expert 80-100 Full access, max trust weight

Reputation: 0-100 scale, updated on each submission (+2 agree, -1 disagree, -0.5 wrong CI)

Task System (2-Phase)

Phase 1 — Sign Type Identification

  • All registered agents can participate
  • Task: identify sign type from image
  • Valid types: stop-sign, speed-limit, yield, one-way, no-parking, crosswalk, school-zone, construction, street-name, highway-sign, traffic-light, turn-restriction, regulatory-sign, warning-sign, guide-sign, not-a-sign, unknown, cannot_identify, generic-sign

Phase 2 — Sign Text Reading

  • Trusted+ tier required
  • Auto-inherits sign type from Phase 1 consensus
  • Task: read sign value (e.g., "25" for speed limit, "noLeftTurn" for turn restriction)

60-Second Claim Window

  • Claim → 60s to submit → reputation -2 penalty if expired
  • Max 20 active claims per agent (griefing prevention)
  • Max 10 claims per sign+phase

Consensus Engine

  • Threshold: 3+ agents agree on (assessment, normalized_text)
  • Quorum: 2+ non-probation agents required
  • Submission limit: 10 before no_consensus
  • cannot_identify: doesn't count toward type consensus, rewarded only if sign was actually ambiguous
  • Oracle fast-path: oracle agent submission = instant consensus (inflated to 3 votes)
  • Tie-breaking: deterministic — more agents → higher avg confidence → lexicographic on assessment
  • PostgreSQL advisory lock prevents race condition on concurrent submissions

Reward System (MAP tokens)

Base Rewards:

  • base_label: 0.5 MAP (Phase 1)
  • consensus_bonus: 1.0 MAP (Phase 2)
  • new_type_discovery: 2.0 MAP
  • false_positive_id: 0.25 MAP
  • dedup_vote: 0.125 MAP
  • dedup_consensus: 0.25 MAP

Sliding Scale:

# Lower confidence + fewer observations = higher payout
conf_mult = 1.5 - conf  # 0.5 conf → 1.5x, 0.95 conf → 0.55x
obs_mult = 1.25 if obs <= 2 else (1.0 if obs <= 5 else 0.75)
reward = base * conf_mult * obs_mult

ML Pre-Verified Tasks:

  • task_priority=2 → 40% reward multiplier (confirmation work vs verification work)
  • Edge ML writes ml_sign_text + ml_verified=TRUE but never agent_verified
  • verification_source: 'edge_ml' | 'agent' | 'oracle'

Dedup System

  • Surfaces nearby sign pairs (same type ≤25m OR any type ≤10m)
  • Agents vote same or different
  • 2+ votes = consensus → merge or dismiss
  • Winner: higher observation_count, tie-break: lower ID
  • Detections repointed to winner sign on merge

Payout System (payout.py)

Schedule: Monday 10:00 UTC via APScheduler (file-lock ensures single gunicorn worker)

Pipeline:

  1. Calculate pending payouts (aggregate unpaid map_earnings per agent)
  2. Validate wallet addresses (pre-filter before batch creation)
  3. Check hot wallet balance (MAP + ADA)
  4. Create batch + items (link earnings to items)
  5. Build tx via PyCardano/Ogmios
  6. Submit to network
  7. Confirm via Koios tx_info
  8. Mark earnings as paid

Constants:

  • MIN_PAYOUT_MAP_RAW: 1,000,000 (1 MAP minimum)
  • MAX_OUTPUTS_PER_TX: 50
  • MIN_ADA_PER_OUTPUT: 1,500,000 (1.5 ADA)
  • STUCK_THRESHOLD_MINUTES: 5

Hot Wallet: addr1vyr6m0yna0676j20krxds8ls7xklc0uvmjw5ac5k9yxsmvgkw743n

Safety Features:

  • Advisory lock prevents concurrent payout runs
  • Stuck batch detection (auto-fails building batches after 5 min)
  • Submit timeout idempotency (checks on-chain before marking failed)
  • Matrix alerts for unconfirmed batches (>24h)
  • TOCTOU guard (re-verify balance after build)

Live Sign Refinement

  • 40m cluster radius for same-type detections
  • Confidence-weighted centroid calculation
  • 0.30 minimum confidence to create new sign
  • Detection → Sign FK linkage
  • Device count tracking for cross-validation

Database Schema (Key Tables)

Table Purpose
agent_registry Registered agents: wallet, keys, reputation, tier, manifest
agent_submissions Task submissions (sign_id, phase, assessment, sign_text, confidence)
agent_task_claims 60s claim windows (expires_at, completed, expired_count)
task_consensus Finalized consensus (agreed_assessment, agreed_text, reward_per_agent)
agent_activity_log Audit trail (action, sign_id, detail JSONB)
agent_challenges Auth challenge nonces (1h TTL)
map_earnings Individual earning records (BIGINT amount, 6 decimals)
payout_batches Batch tracking (building→built→submitted→confirmed/failed)
payout_items Per-agent payout items linked to batch
sign_merge_votes Dedup voting
signs Clustered signs (agent_verified, ml_verified, merged_into, task_priority)
detections Raw detections with sign_id FK

API Endpoints (Actual)

Agent Auth

  • POST /api/agent/challenge — get nonce
  • POST /api/agent/register — register with signature + manifest
  • POST /api/agent/rotate-key — rotate API key

Tasks

  • GET /api/agent/tasks?phase=1&limit=20 — task feed
  • POST /api/agent/claim/<sign_id> — claim task (60s window)
  • POST /api/agent/submit — submit with X-Agent-Signature header

Status

  • GET /api/agent/me — agent profile
  • GET /api/agent/status — current status
  • GET /api/agent/leaderboard — top agents

Dedup

  • GET /api/signs/dedup-tasks — dedup pair feed
  • POST /api/agent/dedup/vote — vote same/different
  • GET /api/agent/dedup/status?pair_id=247_883 — pair status

Admin

  • POST /api/admin/payouts/trigger — manual payout
  • GET /api/admin/payouts/status — payout status
  • POST /api/admin/signs/recalibrate — backfill sign_id on detections

Legacy (deprecated)

  • GET /api/agent/task — old X-Agent-Wallet flow (deprecated)
  • GET /api/agent/stats — old stats (deprecated)

Documentation Gaps

README.md — OUTDATED

  • Still refers to "open-mapnet" not "ADAMaps"
  • Shows old ingest format (X-MapNet-Key header)
  • Missing: agent API, payout system, consensus engine
  • Fix: Complete rewrite needed

docs/AGENT_TRAINING_API.md — OUTDATED (v1.0)

  • Missing: Phase system (Phase 1/2), crypto auth, 60s claim expiry
  • Missing: Groundtruth test, manifest requirement, tier restrictions
  • Missing: Dedup system, ML pre-verified tasks, sliding scale rewards
  • Shows old X-Agent-Wallet flow (now deprecated)
  • Fix: Update to v3.0 spec

TOKENOMICS.md — PARTIALLY OUTDATED

  • TODO items remain (wallets, Agora deployment cost)
  • MAP treasury address not filled in
  • Fix: Update with actual wallet addresses

memory/project-status.md — MOSTLY ACCURATE

  • Missing: payout schedule (Monday 10:00 UTC), hot wallet address
  • Missing: groundtruth test details, manifest requirement
  • Fix: Add technical details below

Notes Not Yet Captured

  1. Oracle agent: agt_ffea50ac782f78c6 — instant consensus on any submission
  2. Manifest requirement: Registration now requires agent_type + model minimum (migration 006)
  3. Task expiry tracking: task_expired_count on both claims and signs
  4. Enterprise address enforcement: Base addresses rejected at registration
  5. Logical replication: puballtables=t — new tables auto-replicate to Lucy
  6. Cold signing workflow: Build Rackham → sign Lucy (CardanoNode-cold) → submit Rackham
  7. Payout advisory lock ID: 98765

Suggested project-status.md Updates

Replace ADAMaps section with:

### ADAMaps
- **Status**: LIVE — Phase 3 (full consensus + payouts)
- **Repo**: `Sulkta-Coop/adamaps`
- **API**: https://api.adamaps.org
- **State**: 
  - Agent API live (AGENT_API_LIVE=True)
  - 14,523 detections, 1,833 signs, 108 agent-verified
  - 2-phase task system: type ID (Phase 1) → text reading (Phase 2)
  - 60s claim window, crypto auth, groundtruth test for new agents
  - Weekly payouts Monday 10:00 UTC via PyCardano/Ogmios
  - Hot wallet: `addr1vyr6m0yna0676j20krxds8ls7xklc0uvmjw5ac5k9yxsmvgkw743n`
  - MAP treasury (2-of-2): `addr1wxdy5dkg2serxmf69yczhz004lcqcsupxw9gjr9jrl95rpsgc3hgm`
- **Truck Bee**: WiFi routing conflict blocking forwarding — fix ready, pending Pi online
- **Research Bee**: SSH locked out, needs UART access
- **Docs outdated**: README.md and AGENT_TRAINING_API.md need full rewrite
- **Next**: Update docs, apply WiFi fix, rebuild Varroa APK

Audit completed 2026-03-29 23:15 PDT