Canary Technical Roadshow — Canary Technical Library

Six Nodes. One Truth.

The complete webhook-to-inscription pipeline that powers real-time detection and permanent proof.

SOURCE

Square POS Webhooks

GATEWAY

HMAC · SHA-256 ULID

QUEUE

Valkey Streams 3 Consumer Groups

SUB 1: SEAL

Evidence Store Chain Hash

SUB 2: PARSE

CRDM Writer Detection Trigger

SUB 3: INSCRIBE

Merkle Batch Bitcoin Ordinal

T+0ms

Received

T+5ms

Queued

T+15ms

Sealed+Parsed

T+~10min

Inscribed

Performance Guarantee: Receipt (T+0) through gateway validation (T+5ms) is synchronous. Queue fan-out to three subscribers completes in <15ms. Merkle batch inscribes to Bitcoin approximately every 10 minutes or after 100 events, whichever comes first.

Three Paths. Zero Dependencies.

Each subscriber has its own consumer group, independent failure handling, and distinct purpose in the detection chain.

Sub 1: Hash & Seal

Purpose: INSERT-only evidence store with chain hash linking. Every record cryptographically proves the previous one was untouched.

canary_sales.evidence_records

The forensic foundation

Sub 2: Parse & Route

Purpose: Structured CRDM writer. Routes 10+ event types to relational tables. Emits detection notifications in real time.

Mutable, replayable from Sub 1

The operational intelligence layer

Sub 3: Merkle & Inscribe

Purpose: Batches events by count (100) or time (10 min). Builds Merkle tree. Inscribes root to Bitcoin Ordinal.

Two-phase: Sealed + Inscribed

The permanence layer

Fault Tolerance: If Sub 2 (Parse) fails, Sub 1 (Seal) still captures the raw event. Sub 3 (Inscribe) batches independently. Dead letter queue retries failed messages up to 5 times. At-least-once delivery guaranteed. Each subscriber fails independently.

Write Once. Prove Forever.

The evidence_records table is the permanent, tamper-evident ledger of every transaction.

Record 1 → Record 2 → Record 3 → Record 4 → Record 5

Each record's chain_hash proves the integrity of the entire chain up to that point.

evidence_records
├── event_id        ULID (time-sortable)
├── merchant_id     TEXT
├── event_hash      SHA-256(raw payload)
├── chain_hash      SHA-256(prev_chain + current_hash)
├── raw_payload     Verbatim JSON (never transformed)
├── sealed_at       TIMESTAMPTZ
└── CONSTRAINT      INSERT only — NO UPDATE, NO DELETE

"The record cannot be changed because the next record proves what the previous one contained."

Schema Guarantee: PostgreSQL enforces INSERT-only via role-level permissions. No UPDATE or DELETE allowed at the database level. Audit triggers log every access attempt. Hash chain verification runs hourly to detect tampering within minutes.

37 Rules. 10 Categories. Real-Time.

All Chirp detection rules organized by risk domain. Each rule is independently configurable by the merchant.

Category	Rule	Severity
Payment Alerts	C-001: Quick refund after sale	HIGH
	C-002: Excessive refund rate	HIGH
	C-003: Round-dollar pattern	MEDIUM
	C-004: After-hours transaction	MEDIUM
	C-005: Card velocity spike	HIGH
	C-006: Split tender pattern	MEDIUM
	C-007: High-value refund	HIGH
	C-008: Manual entry spike	MEDIUM
Cash Drawer	C-101: No-sale drawer opens	HIGH
	C-102: Drawer came up short	HIGH
	C-103: Unusual paid-out	MEDIUM
	C-104: After-hours drawer open	CRITICAL
Order & Line-Item	C-201: Heavy discounting	HIGH
	C-202: Voided line items	HIGH
	C-203: Discount without approval	HIGH
Timecard	C-301: Sale while off the clock	CRITICAL
	C-302: Sale during break	HIGH
	C-303: Wrong location	HIGH
Void & Refund	C-501: High void rate	HIGH
Void & Refund	C-502: Post-void detected	CRITICAL
Gift Card	C-601: Load velocity spike	HIGH
Gift Card	C-602: Load-and-drain pattern	CRITICAL
Loyalty	C-801: Rapid point accumulation	MEDIUM
	C-802: Bulk redemption	HIGH
	C-803: Cross-location velocity	HIGH
	C-804: Enrollment fraud	MEDIUM

Real-Time Pipeline: Sub 2 writes parsed events → Valkey pub/sub emits canary:detection → Detection engine evaluates all active rules → Alert generated → WebSocket push to dashboard. Detection latency p95: <500ms.

From Bytes to Bitcoin.

Every sealed transaction batch is cryptographically committed to the Bitcoin blockchain via Ordinals protocol.

Leaf Nodes

Layer 2 Hashes

Layer 3 Hashes

Root (₿)

T+15ms — Sealed

Evidence stored, chain linked, batch queued. Forensic-grade guarantee. The event is cryptographically bound to all previous events in the chain.

T+~10min — Inscribed

Merkle root committed to Bitcoin. Inscription_id assigned. Immutable forever. The batch is now part of the global ledger.

Batch Triggers: COUNT ≥ 100 events OR TIME ≥ 10 minutes — whichever comes first. Every event can be independently verified via its Merkle proof path without trusting GrowDirect.

Perpetual Revenue. Every Verification Pays.

Status: Roadmap — architecture designed, implementation planned for Sprint 7+. See the elJeffe Protocol for the full design specification.

L402 creates a micropayment gate for every verification request. The merchant never pays twice for the same proof.

REQUEST /validate/{event_hash}

402 Payment Required + Lightning Invoice

PAY 50 sats via Lightning Network

PROOF Full verification + Merkle proof

Revenue Model: Every event ever notarized generates validation revenue on every future verification request. Not a one-time fee — a perpetual royalty on the Bitcoin time chain. 50 sats per validation. 99.9% availability. <500ms proof delivery. 100% revenue tracking via on-chain settlement.

Invoice Generation

<100ms

Payment Verification

<200ms

Proof Generation

<300ms

Total Latency (p95)

<500ms

Trust Nothing. Verify Everything.

A five-step verification procedure that proves event integrity across all layers without requiring trust in Canary.

✓ Evidence Retrieval

Locate record in evidence_records. Verify ULID, merchant_id, sealed_at timestamp.

✓ Hash Recomputation

SHA-256(stored raw_payload) must match stored event_hash. No field substitution.

✓ Source Comparison

Stored event_hash must match original from Square network via HMAC signature verification.

✓ Chain Integrity

Chain_hash must equal SHA-256(previous_chain_hash + current_event_hash). Verify unbroken back to genesis.

✓ Bitcoin Inscription

Merkle proof validated against on-chain inscription_root on Bitcoin blockheight B+N.

VERIFIED

Event integrity confirmed across all layers. SHA-256 chain holds. Merkle proof validates on Bitcoin. This transaction happened, exactly as recorded, at exactly this time.

TAMPER DETECTED

Event integrity compromised. Either the payload was modified, the chain link is broken, or the on-chain inscription doesn't match. This transaction has been altered.

"The merchant doesn't have to trust us. The math is the proof."

What Powers It.

Modern, battle-tested technologies serving millions of retail transactions annually.

Runtime

Node.js + Python (Flask)

Database

PostgreSQL (ACID, RLS, partitioned)

Queue

Valkey Streams (Redis-compatible, AOF persistent)

Cache

Valkey (in-memory, <100μs latency)

Bitcoin

Ordinals + Lightning (L402)

Orchestration

Kubernetes-ready (stateless)

Monitoring

Prometheus metrics (every component)

Frontend

React + HTMX (hybrid)

Auth

Square OAuth 2.0 + LNURL

Webhook Receipt

<5ms

Queue Fan-out

<10ms

Detection Latency

<500ms

Inscription Batch

~10 min

Throughput

10K evt/s

Availability

99.9%

Architecture Philosophy: Local-first for everything that can run locally. Cloud APIs behind explicit spend-cap approval. No unmetered connections. Every component emits Prometheus metrics. Stateless design allows infinite horizontal scaling.

One Page. Full Control.

Merchants configure which Chirps they want to monitor. Simple toggles, real-time feedback, zero technical jargon.

Turn on the things you want Canary to watch for. (3 of 37 active)

Rule	Status
Drawer came up short	HIGH — ACTIVE
Quick refund after sale	HIGH — ACTIVE
Sale while off the clock	CRITICAL — ACTIVE

Connect (30 sec)

Square OAuth

Backfill (1–5 min)

7 days of history

Configure (3 min)

Choose your Chirps

Monitor (Instant)

First real alert

Total Onboarding Time: Under 10 minutes from handshake to first insight.