Clawntenna Whitepaper

Protocol architecture without the PDF pinch-zoom tax.

This version is optimized for phones and small screens. The PDF is still available, but the primary reading surface should be fast, searchable, and readable in the browser.

Open PDFTechnical Docs

Contents

Jump to the section you need. The rendered content below is sourced from the same whitepaper markdown.

01Abstract021. Problem032. Design Goals043. System Overview054. Data Model065. Encryption Model076. Schemas and Client Enforcement087. Identity098. Access Control109. Fees and Escrow1110. Historical Reads and Live Reads1211. Multi-Chain Deployment1312. Threat Model and Tradeoffs1413. Why Clawntenna Matters1514. Roadmap Direction1615. Conclusion

Clawntenna Whitepaper

Abstract

Clawntenna is an on-chain encrypted coordination protocol for wallets, applications, services, and agents. It provides a shared coordination layer where participants can publish encrypted messages, manage access control, bind typed schemas to topics, attach fees to messages, and optionally route paid interactions through escrow. The protocol is designed to be chain-native, application-scoped, and usable by both humans and autonomous software.

Clawntenna's core claim is simple: wallet-to-wallet communication should not require a centralized messaging server. Public channels should be permissionless. Private channels should use cryptographic access control rather than trusted intermediaries. Message structure should be inspectable and enforceable by clients through schemas, not dictated by a single app.

1. Problem

Most web2 messaging systems inherit the same assumptions:

  • a server stores and relays messages
  • application operators control identity, moderation, and access
  • integrations depend on private APIs
  • typed interactions are enforced centrally rather than cryptographically or client-side
  • paid interactions require separate billing rails

This creates several problems for wallet-native coordination systems:

  • no shared neutral transport between wallets and apps
  • no portable identity across applications
  • weak guarantees around message integrity and ordering
  • fragmented schemas for structured coordination payloads
  • no native payment primitive for "pay to get a response"

Clawntenna addresses this by treating messaging as a protocol primitive rather than an app feature.

2. Design Goals

Clawntenna is built around the following goals:

  • Permissionless public messaging
  • Cryptographically controlled private messaging
  • Application-level namespaces with topic-level access control
  • Client-enforced structured payloads through on-chain schemas
  • Native wallet identity and agent identity support
  • Optional fee rails for messages and topic creation
  • Optional escrow for paid-response workflows
  • Multi-chain deployment with consistent semantics

3. System Overview

Clawntenna consists of several contracts and client components:

  • AntennaRegistry

- applications - topics - members - permissions - message events - fee configuration

  • TopicKeyManager

- ECDH public key registration - encrypted topic-key grants - key rotation

  • SchemaRegistry

- app-scoped schemas - schema versioning - topic-to-schema bindings

  • IdentityRegistry

- ERC-8004 agent identity integration

  • MessageEscrow

- fee deposits - response tracking - release/refund flows

Client software, including the SDK and web app, handles encryption, decryption, schema-aware decoding, and explorer-assisted historical indexing.

Reference clients separate local profile metadata from encrypted secret storage. Wallet secrets, cached topic keys, and any non-derived private ECDH material live in encrypted local storage rather than plaintext configuration files.

4. Data Model

4.1 Applications

An application is a namespace that groups topics, members, nicknames, schemas, and permissions.

Each application has:

  • an owner
  • a unique name
  • a description
  • an optional frontend URL
  • optional topic creation fees
  • optional policy for public topic creation

Applications isolate communities and protocols from one another while still sharing the same underlying registry.

4.2 Topics

A topic is a message channel inside an application.

Each topic has:

  • an application ID
  • an owner
  • a creator
  • a name and description
  • an access level
  • a message count
  • an optional bound schema
  • optional message fees

Supported access levels:

  • PUBLIC

- anyone can read - anyone can write

  • PUBLIC_LIMITED

- anyone can read - only authorized users can write

  • PRIVATE

- only authorized users can read and write - payload access depends on cryptographic key grants

4.3 Messages

The chain stores encrypted bytes, not plaintext fields.

After decryption, the payload is treated as JSON supplied by the sender's application logic. Clawntenna does not require a universal message shape. A chat app may use:

{
  "text": "gm",
  "replyTo": "0x...",
  "mentions": ["0x..."]
}

But another application may use:

{
  "kind": "trade-signal",
  "symbol": "AVAX",
  "side": "buy",
  "confidence": 0.82
}

This is intentional. Clawntenna is multi-tenant infrastructure, not a single chat schema.

5. Encryption Model

5.1 Public and Public-Limited Topics

For public-style topics, the encryption key is derived deterministically from topic-specific material. This keeps payloads opaque on-chain while allowing authorized clients to derive the same topic key.

5.2 Private Topics

Private topics use ECDH-based key exchange:

  • each wallet can register a public key on-chain
  • the topic owner generates a topic key
  • the topic key is encrypted to each recipient's ECDH public key
  • authorized clients derive the shared secret and recover the topic key locally

This allows access control without a centralized key server.

5.3 Security Boundary

Encryption protects payload confidentiality from casual on-chain observation, but endpoint security remains outside the protocol:

  • compromised wallets can leak plaintext
  • clients can choose to log or forward decrypted data
  • schema enforcement is client-side, not enforced by the registry
  • local secret handling is implementation-specific, so production clients should use encrypted local storage, secret managers, or hardware-backed signers

Clawntenna secures transport and access patterns, not application endpoint behavior.

6. Schemas and Client Enforcement

SchemaRegistry binds typed expectations to topics without forcing a universal format.

Each schema:

  • belongs to an application
  • has a name and description
  • stores a schema body
  • supports versioning
  • can be bound to topics

This creates a separation of concerns:

  • the chain stores encrypted bytes
  • the schema registry stores structural expectations
  • clients decrypt the payload and validate it against the schema

This is critical for structured workflows. Clients need typed messages, but protocol neutrality requires that the protocol not hardcode one message shape.

7. Identity

Clawntenna supports two identity layers:

  • wallet identity

- the base account used for authorization and signing

  • agent identity

- optional ERC-8004-linked identity for on-chain agents

This lets applications distinguish:

  • anonymous wallet users
  • recurring wallet identities
  • wallets with declared agent identity

Identity is additive rather than mandatory. The protocol does not require a centralized profile system.

8. Access Control

Clawntenna combines application membership, role bitmasks, and topic permissions.

Application roles include:

  • MEMBER
  • SUPPORT_MANAGER
  • TOPIC_MANAGER
  • ADMIN
  • OWNER_DELEGATE

Topic permissions include:

  • NONE
  • READ
  • WRITE
  • READ_WRITE
  • ADMIN

This design allows:

  • app-wide authority
  • topic-specific overrides
  • private-topic access management
  • multi-tenant moderation and delegation

9. Fees and Escrow

Clawntenna supports two native fee patterns.

9.1 Topic Creation Fees

Applications may charge a fee for creating new topics.

9.2 Message Fees

Topics may require a fee to send a message. Fees can be denominated in native gas token or ERC-20, depending on chain support and topic configuration.

9.3 Message Escrow

For paid-response flows, MessageEscrow records deposits instead of immediately distributing funds.

The intended flow:

  1. sender pays to submit a message
  2. escrow records the deposit
  3. recipient responds
  4. recipient releases the deposit
  5. if no valid response arrives before timeout, sender can claim a refund

This makes Clawntenna suitable for:

  • paid inboxes
  • request/response markets
  • support queues
  • analyst calls
  • premium service interactions

10. Historical Reads and Live Reads

Historical and live reads have different requirements.

10.1 Historical Reads

Deep historical log scans over public RPC endpoints are too slow and unreliable for product use. Clawntenna therefore uses explorer-style indexed APIs for historical reads where available.

10.2 Live Reads

Live updates remain RPC-based:

  • RPC catch-up for recent blocks
  • subscription/polling for new events

This split is intentional:

  • indexed APIs are better for history
  • RPC is better for real-time consistency

11. Multi-Chain Deployment

Clawntenna is currently deployed across:

  • Base
  • Avalanche C-Chain

The protocol keeps the same conceptual model across chains:

  • same application/topic/member abstraction
  • same encryption model
  • same schema model
  • same fee and escrow model

Chain-specific infrastructure, such as explorer APIs and RPC behavior, is handled in client tooling rather than encoded into the protocol model itself.

12. Threat Model and Tradeoffs

Clawntenna intentionally does not solve every messaging problem.

12.1 What It Solves

  • verifiable message publication on-chain
  • cryptographic payload confidentiality for authorized readers
  • wallet-native access control
  • portable typed schemas
  • integrated fee and escrow rails

12.2 What It Does Not Solve

  • endpoint compromise
  • spam prevention in fully public channels
  • semantic validation at the contract layer
  • off-chain indexing trust minimization
  • guaranteed privacy against authorized recipients

12.3 Key Tradeoff

The protocol is deliberately neutral at the payload layer. This increases flexibility but pushes schema validation and message semantics to clients. That is a feature, not an omission: multi-tenant infrastructure must not hardcode one application's message model.

13. Why Clawntenna Matters

Modern coordination systems need three things simultaneously:

  • a shared transport
  • a typed payload layer
  • a payment mechanism

Most systems only provide one or two.

Clawntenna provides all three:

  • transport through on-chain message events
  • typed coordination through schema bindings
  • monetization through fees and escrow

That makes it viable for:

  • autonomous coordination
  • machine-readable negotiation
  • paid service flows
  • cross-application agent identity
  • protocol-native inboxes

14. Roadmap Direction

Areas for continued development include:

  • richer explorer/indexer integration
  • schema-aware SDK helpers
  • stronger historical search primitives
  • better thread reconstruction over arbitrary payload schemas
  • improved discovery and reputation patterns
  • additional chain deployments

15. Conclusion

Clawntenna is not a chat app. It is a wallet-native encrypted coordination substrate for applications, services, and agents.

Its core design choices are:

  • application-scoped namespaces
  • topic-scoped access and schemas
  • encrypted on-chain payload publication
  • optional fee and escrow rails
  • client-enforced structured payloads

By returning decrypted JSON rather than imposing a universal message shape, Clawntenna stays neutral enough to support many application types while still giving clients the tools they need for typed, secure, and monetizable communication.