Technical Documentation

ChainSiren Architecture & Integration Guide

Complete specifications for Web3 emergency coordination, EIP-712 typed signing, PagerDuty on-call escalation, and role-based incident war boards.

1. System Architecture Overview

ChainSiren is a neutral, verifiable, chain-independent emergency coordination layer for Web3 validators, foundation maintainers, and rollup sequencers. When catastrophic consensus divergences, zero-day vulnerabilities, or critical state invalidations occur, ChainSiren enables rapid, coordinated action without relying on compromised Discord bots or unverified social media channels.

Key Architectural Guarantees:

• Zero Passwords: Authentication relies strictly on Sign-In with Ethereum (EIP-4361).

• Non-Repudiation: Every incident creation, acknowledgment, and resolution is sealed with EIP-712 signatures.

• Sub-1.2s Dispatch: High-urgency events trigger immediate synchronous webhooks into PagerDuty on-call rotations.

2. Sign-In with Ethereum (SIWE)

Operator and maintainer identities are tethered directly to cryptographic keypairs. Session authentication utilizes standard EIP-4361 challenge-response nonces:

The client requests a cryptographically secure random nonce via /api/auth/nonce.
The user signs the standardized SIWE message using their browser wallet (MetaMask, Rabby) or hardware signer.
The backend verifies the recovered signer address, binds it to an encrypted HTTP-only session cookie, and hydrates organization permissions.

3. EIP-712 Typed Data Signatures

To prevent rogue halts, impersonation attacks, and unauthorized emergency actions, write actions do not rely on standard HTTP credentials. All critical state changes require explicit typed signatures:

const EIP712_DOMAIN = {
  name: 'ChainSiren',
  version: '1',
  chainId: 1,
  verifyingContract: '0x0000000000000000000000000000000000000000'
}

const ACKNOWLEDGE_INCIDENT_TYPES = {
  AcknowledgeIncident: [
    { name: 'incidentId', type: 'string' },
    { name: 'operatorName', type: 'string' },
    { name: 'actionTaken', type: 'string' },
    { name: 'nonce', type: 'uint256' },
    { name: 'timestamp', type: 'uint256' }
  ]
}

A monotonic database-tracked uint256 nonce is checked for every signature. Replay attempts are rejected immediately.

4. 4-Level Severity Escalation Matrix

BLACK TIER — IMMEDIATE HALT

Consensus splits, zero-days. Bypasses rate-limits and wakes on-call engineers via phone call & SMS.

RED TIER — RAPID RESPONSE

High severity client degradation, state sync faults, urgent patches requiring same-hour coordination.

ORANGE TIER — ACTION REQUIRED

Planned hard forks, scheduled validator maintenance, non-emergency re-sync events.

GREEN TIER — ADVISORY

Technical advisories, minor client upgrade notices, informational bulletins.

5. Alerting Integrations (PagerDuty, Telegram, Discord)

Operators can link multiple notification endpoints under Settings > Alerting Channels. All secrets (Routing Keys, Webhook URLs) are encrypted with AES-256-GCM before database storage.

PagerDuty: Connect using an Events API v2 Routing Key (32-character hex). Automatically dispatches Black and Red tier events.
Telegram: Direct bot messaging via Bot Token and Target Chat ID.
Discord: High-visibility embed webhooks for team security channels.

6. Validator Subscription Tiers

ChainSiren offers predictable billing managed securely through Stripe:

Free ($0)

1 Destination, 3 Network Subscriptions, Green & Orange alerts.

Operator ($19/mo)

5 Destinations, Unlimited Networks, Black/Red alerts, PagerDuty integration.

Team ($49/mo)

15 Destinations, Unlimited Team Members, Custom Escalation Schedules.