Protocol Specification v0.1

Your data. Your keys.
Your rules.

Programmable infrastructure for decentralized communication. Identity, encryption, consent-based routing, and encrypted storage — without trusted servers.

identity:platform-controlled account

social graph:fully visible to server

metadata:who, when, where, how often

consent:platform decides

portability:no right to exit

ban =identity erased

identity:self-sovereign DID + your keys

social graph:opaque to mediator

metadata:encrypted tags only

consent:bilateral crypto contracts

portability:switch mediators freely

you ownkeys, data, relationships

E2EE protects content. Decentrl protects everything else.

Read the Protocol Start Building

TypeScript

MIT License

6 RFCs

3 keys

Ed25519 + X25519 + AES-256

Plaintext on mediators

Dual-delivery pattern

DID

W3C decentralized identity

MIT

Open source forever

// architecture

The entire privacy stack.
One protocol.

Tripartite Key Architecture

Each identity generates three independent keys — Ed25519 for signatures, X25519 for key agreement, AES-256 for storage. Key separation limits blast radius: compromising one key cannot compromise the others.

const keys = generateIdentityKeys()
// keys.signing     → Ed25519 keypair
// keys.encryption  → X25519 keypair
// keys.storageKey  → AES-256 (never shared)

const did = createDecentrlDidFromKeys(
  'alice', keys,
  'did:web:mediator.decentrl.io'
)
// → did:decentrl:YWxpY2U:z6Mk...

Dual-Layer Encryption

Transit encryption (root secret from ephemeral X25519 DH) protects data in flight. Storage encryption (local AES-256 key) protects data at rest. Your mediator has neither key.

Communication Contracts

Bilateral cryptographic agreements with dual Ed25519 signatures. No data flows without mutual consent. One primitive handles user-to-user, user-to-mediator, and user-to-group relationships.

// Establish mutual consent
await client.contracts.request(bobDid)

// Bob accepts on his side
await client.contracts.accept(
  request.id,
  request.encryptedPayload,
  request.requestorEphemeralPublicKey,
)

// Root secret derived locally
// No secret ever crosses the network

Encryption-Blind Mediators

Mediators route ciphertext and store opaque blobs. They cannot derive keys, forge signatures, or read metadata. Anyone can run one. Alice on mediator A messages Bob on mediator B — no coordination needed.

Encrypted Event Sourcing

All state is derived from encrypted event streams. Events are signed, encrypted client-side, and queryable through encrypted tags — opaque blobs the mediator can index but never interpret. No backend database needed.

await client.publish('chat.message', {
  id: crypto.randomUUID(),
  chatId: 'abc',
  text: 'Hello Bob',
})

// 1. Validated against Zod schema
// 2. Signed with Ed25519
// 3. Encrypted → sent to Bob's mediator
// 4. Re-encrypted → stored on yours

Declarative SDK

Define event schemas with Zod and state reducers. The SDK handles identity, contracts, encryption, routing, sync, and React hooks — all behind defineDecentrlApp().

// developer experience

Schema in, encrypted app out

Define events and reducers. Get identity, encryption, contracts, and sync for free.

app.ts
import { defineDecentrlApp } from '@decentrl/sdk'
import { z } from 'zod'

const app = defineDecentrlApp({
  events: {
    'chat.message': {
      schema: z.object({
        id: z.string().uuid(),
        chatId: z.string(),
        text: z.string(),
      }),
      tags: ['chat.$${chatId}'],
    },
  },
  state: {
    messages: {
      initial: [],
      reduce: {
        'chat.message': (s, d) =>
          s.some(m => m.id === d.id)
            ? s : [...s, d],
      },
    },
  },
})

chat.tsx
import { useDecentrl, useDecentrlState } 
  from '@decentrl/sdk-react'

function Chat({ chatId }) {
  const { publish } = useDecentrl()
  const messages = useDecentrlState(
    s => s.messages.filter(
      m => m.chatId === chatId
    )
  )

  return (
    <div>
      {messages.map(m => (
        <Message key={m.id} data={m} />
      )))}
      <Composer onSend={text =>
        publish('chat.message', {
          id: crypto.randomUUID(),
          chatId, text,
        })
      } />
    </div>
  )
}

// protocol lifecycle

Three steps to zero-knowledge

Generate Identity

Three keys generated on-device. Your DID embeds public keys and mediator endpoint — anyone can verify you and send you a contract request without a registry lookup.

generateIdentityKeys()

Establish Contract

Both parties exchange ephemeral X25519 keys and sign with Ed25519. A shared root secret is derived locally — no secret ever crosses the network.

client.contracts.request(did)

Communicate

Events are encrypted, signed, and dual-delivered — one copy to the recipient, one to your own mediator. Both parties keep complete records. The mediator sees nothing.

client.publish(type, data)

// get started

One install.
Zero compromises.

$npm install @decentrl/sdk zod