# GridStamp

[![npm version](https://img.shields.io/npm/v/gridstamp.svg)](https://www.npmjs.com/package/gridstamp) [![smithery badge](https://smithery.ai/badge/gridstamp)](https://smithery.ai/server/gridstamp) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)

**Cryptographic dispute evidence for autonomous fleets.**

When a robot causes an incident — a delivery goes missing, an AMR damages inventory, an AV is involved in a collision — the question that decides who pays is always the same: *where was it, exactly, and can you prove it?*

GridStamp is the evidence layer. Every operation produces a tamper-evident spatial receipt: HMAC-signed camera frames, Merkle-rooted memory, cryptographic proof-of-location. The receipts hold up under replay, adversarial patches, depth-injection, and GPS spoofing — tested at fleet scale.

### Proven at scale

In a 92-day simulation with 5,500 agents across 20 fleets and 8 cities, parameterised with publicly disclosed fleet data from Waymo, Tesla, Starship Technologies, Coco Robotics, Serve Robotics, and commercial drone operators (GridStamp is not affiliated with or endorsed by any of them; parameters come from public filings and press releases):

- **14.55M operations** processed (fleet simulation)
- **99,911 operations** in 43 seconds — **2,323 ops/sec** (100K stress test)
- **100%** replay detection, **100%** HMAC tamper detection, **100%** verification pass
- **200 concurrent robots**, 80,000 proof chain links, all chains valid
- **p99 latency: 0.86ms** per spatial proof generation
- Rigorous test suite with 100K production stress bench

Receipts are designed to be **admissible-grade** evidence for insurance disputes, SLA audits, and regulatory investigations. Final admissibility is jurisdiction-dependent and should be confirmed with counsel for your underwriting market.

### Who this is for

| Buyer | Problem GridStamp solves |
|---|---|
| **AV / robotics insurance underwriters** | Reduce loss ratio by resolving location-of-incident disputes with cryptographic evidence instead of he-said/she-said. |
| **Logistics visibility platforms** (freight, last-mile) | Give shippers verifiable proof-of-delivery their customers can't dispute — upgrade ETAs from claims to receipts. |
| **AR gaming & location-based apps** | Stop the ~9% of top players who GPS-spoof. Our stress test catches 91% of spoof attempts. |

If you're evaluating GridStamp for a pilot, contact: **omiagbogold@icloud.com**.

## Architecture

Six layers, each cryptographically isolated:

| Layer | What it does |
|-------|-------------|
| **Perception** | HMAC-signed camera frames, stereo depth fusion, dual-camera support |
| **Memory** | 3-tier spatial memory (short/mid/long-term) with Merkle tree integrity |
| **Navigation** | A* and RRT* pathfinding on 3D occupancy grids, place cells + grid cells |
| **Verification** | SSIM + LPIPS + depth comparison for spatial proof-of-location |
| **Anti-Spoofing** | Replay detection, adversarial patch detection, depth injection, canary honeypots |
| **Gamification** | Trust tiers, capability badges, streak multipliers, zone mastery, fleet leaderboard |

## Install

```bash
npm install gridstamp
```

## Quick Start

```typescript
import { createAgent } from 'gridstamp';

const agent = createAgent({
  robotId: 'DLV-001',
  cameras: [{ type: 'oak-d-pro', role: 'foveal', /* ... */ }],
  hmacSecret: process.env.GRIDSTAMP_SECRET, // min 32 chars
}, cameraDriver);

// Capture and verify
const frame = await agent.see();
const proof = await agent.verifySpatial();

// Settle payment only if spatial proof passes
const settlement = await agent.settle({
  amount: 15.00,
  currency: 'USD',
  payeeId: 'merchant-001',
  spatialProof: true,
});
```

## Trust Tiers

Robots earn trust through verified operations, similar to a credit score:

| Tier | Points | Fee | Max Tx | Verification |
|------|--------|-----|--------|-------------|
| Untrusted | 0 | 2.5x | $10 | Every operation |
| Probation | 100 | 2.0x | $50 | Every operation |
| Verified | 500 | 1.5x | $200 | Every 3rd |
| Trusted | 2,000 | 1.2x | $1,000 | Every 5th |
| Elite | 5,000 | 1.0x | $5,000 | Every 10th |
| Autonomous | 10,000 | 0.8x | $25,000 | Spot checks |

All tier changes are HMAC-signed. Spoofing attempts result in immediate two-tier demotion.

## Proof Chains

Every spatial proof links to the previous via SHA-256 hash chain. A robot's entire operational history becomes a tamper-evident linked list — if any proof is modified, the chain breaks.

```typescript
import { ProofChain } from 'gridstamp';

const chain = new ProofChain();
chain.append(proof1);  // genesis
chain.append(proof2);  // links to proof1
chain.append(proof3);  // links to proof2

const result = chain.verify();
// → { valid: true, chainIntegrity: 1.0, length: 3 }
```

This means a fleet operator or insurance underwriter can verify the complete history of a robot's spatial claims — not just individual proofs, but the unbroken chain between them.

## Security Model

- Every camera frame is HMAC-SHA256 signed at capture time
- Cryptographic key derivation isolates subsystems (`deriveKey(master, 'frame-signing')`)
- Monotonic sequence numbers prevent replay attacks
- Canary landmarks detect memory poisoning
- Constant-time HMAC comparison prevents timing attacks
- Kinematic plausibility gate (`LocationSpoofDetector`) catches GNSS/GPS spoofing and teleport attacks on the pose claim
- Fail-closed: any integrity violation blocks payment

## Modules

```
gridstamp                    # Full SDK
gridstamp/perception         # Camera + depth
gridstamp/memory             # Spatial memory + place/grid cells
gridstamp/navigation         # Pathfinding
gridstamp/verification       # Spatial proofs + settlements
gridstamp/antispoofing       # Threat detection
gridstamp/gamification       # Trust tiers + badges + leaderboard
```

## Use Cases

- **Last-mile delivery** — Robot proves it reached the doorstep before payment settles
- **Warehouse operations** — AMRs earn trust tiers based on verified pick accuracy
- **Drone inspection** — Tamper-proof spatial evidence of site surveys
- **Autonomous trucking** — Spatial proof-of-delivery for freight settlements
- **Roofing/HVAC/Plumbing** — AI agents verify on-site work completion

## Requirements

- Node.js 20+
- TypeScript 5.6+

## License

Apache 2.0 — see [LICENSE](LICENSE).

Copyright 2026 J&B Enterprise LLC.

## Trademark notice

FICO is a registered trademark of Fair Isaac Corporation. GridStamp's trust tier system and MnemoPay's Agent Credit Score (300–850, FICO-style behavioral scoring) are not affiliated with or endorsed by Fair Isaac Corporation.

## Claude Agent SDK

GridStamp ships a first-class Claude-driven agent wrapper that orchestrates the full verification pipeline without any manual glue code.

**Quick start (5 lines):**

```typescript
import { runProofAgent } from 'gridstamp/agent';

const result = await runProofAgent({
  robotId: 'DLV-001',
  hmacSecret: process.env.GRIDSTAMP_SECRET,
  sensorReader: async (sensorId) => myCameraDriver.read(sensorId),
});
// result.status → 'pass' | 'fail' | 'spoofing_detected'
```

The agent (`claude-sonnet-4-6`) runs four tools in sequence — `read_sensor` → `verify_spatial_proof` → `check_antispoofing` → `write_attestation` — and returns a typed `AttestationResult` with confidence score, spoofing signals, and chain length.

**Audit log:** every `write_attestation` call appends an NDJSON record to `./proof-audit.ndjson` (path configurable). This is the file your claims team reads — immutable, timestamped, one record per robot attestation.

See the full runnable example: [`examples/agent-proof-of-presence.ts`](examples/agent-proof-of-presence.ts)

```bash
ANTHROPIC_API_KEY=sk-... npm run example:agent
```

### Remote ID / ASTM F3411 evidence

FAA Part 108 (BVLOS) requires every operator to keep tamper-evident position logs alongside their existing Remote ID broadcast. GridStamp signs each of the five F3411-22a message types (BasicID, Location/Vector, SelfID, System, OperatorID) with an Ed25519 identity key persisted at `${GRIDSTAMP_PERSIST_DIR}/remoteid-ed25519.key`, then batches them into a COSE Merkle Tree Proofs-style receipt (tracking `draft-ietf-cose-merkle-tree-proofs-18`).

```typescript
import { remoteid } from 'gridstamp';

const key = remoteid.loadKey();
const log = remoteid.sign(
  { kind: 'operator_id', operatorIdType: 0, operatorId: 'FA1234567890' },
  key,
);
const ok = remoteid.verify(log, key.publicKey);
const batch = remoteid.batchRoot([log]);
```