4NK Identity and Process System Specification

Back to homepage

Version: 1.0
Date: October 1, 2025
Source: Complete analysis of sdk_client, sdk_common, sdk_relay, sdk_storage, ihm_client, rust-silentPayments components

Table of Contents

  1. Overview
  2. Identity Architecture
  3. Process System
  4. Validation and Consensus
  5. Network Communication
  6. Storage and Persistence
  7. Data Flow
  8. Security

1. Overview

1.1 System Philosophy

4NK is a decentralized system for collaborative process management based on the Bitcoin blockchain, using Silent Payments (BIP352) for identity and encryption. The system enables multiple parties to collaborate on processes with verifiable states, defined roles, and cryptographic validation rules.

1.2 Core Principles

1.3 Main Components

Component Role Technology
sdk_common Shared types and structures Rust (WASM-ready)
sdk_client WASM client library Rust → WebAssembly
sdk_relay Message relay and synchronization Rust + WebSocket
sdk_storage Distributed key-value storage Rust + HTTP
ihm_client Web user interface TypeScript + Web Components
rust-silentPayments Silent Payments implementation Rust (dependency)

2. Identity Architecture

2.1 Identity Hierarchy

Device
  ├─ SpClient (Silent Payment Client)
  │   ├─ Scan Key (private)
  │   ├─ Spend Key (private)
  │   └─ Silent Payment Address (public)
  ├─ SpWallet (UTXO outputs)
  ├─ Pairing Process (OutPoint)
  └─ Member (list of paired addresses)

2.2 Device Structure

A Device represents a single physical device with its own cryptographic keys:

Main operations:

  1. Creation: Generates a local Silent Payment address and initializes a Member with this address alone
  2. Pairing: Associates the device with a pairing process, linking multiple Silent Payment addresses together
  3. Unpairing: Resets to single local state

2.3 Member Structure

A Member represents a set of devices belonging to the same entity:

2.4 Pairing Process

Pairing is the mechanism for associating multiple devices to a single logical identity (member).

Pairing steps:

  1. Creation of pairing process: A device creates a new Process with a special "pairing" role. The ProcessState contains a public field "pairedAddresses" with the list of addresses.
  2. Pairing validation: Members must be empty (no pre-existing members). A single validation rule for the "pairedAddresses" field. Required signatures vary:
    • Creation: Signature from new address only
    • Addition: Signature from already paired addresses
    • Removal: Signatures from all devices (consensus)
  3. Post-pairing state: Device links to process and updates paired member list

3. Process System

3.1 Process Definition

A Process is a state machine with defined roles, validation rules, and Bitcoin commitments. Each state transition creates a new Bitcoin UTXO.

Key characteristics:

3.2 Process Structure

Field Description Type
commitment Current Bitcoin commitment (OutPoint) OutPoint
state Current state (data + metadata) ProcessState
roles Role definitions and permissions Roles
previous Previous state (for history) Option<ProcessState>

3.3 Roles System

Each process defines roles with specific permissions. A role contains:

Special role "apophis":

3.4 Validation Rules

A ValidationRule defines who can modify which fields:

Example: A rule with quorum=0.67 and min_sig_member=0.5 requires:

4. Validation and Consensus

4.1 State Transition Workflow

  1. Proposal: A member proposes a new state via CommitMessage
  2. Distribution: The relay broadcasts the proposal to all participants
  3. Validation: Each member validates the proposal locally
  4. Signature: If valid, members sign and send ValidationToken
  5. Aggregation: Proposer collects signatures until quorum is reached
  6. Commitment: Proposer creates Bitcoin transaction with state_id in OP_RETURN
  7. Broadcast: New state is distributed with on-chain proof

4.2 Validation Token

A ValidationToken is a cryptographic signature proving a member's approval:

4.3 Multi-signature Validation

The system supports complex multi-signature schemes:

Example scenario:

5. Network Communication

5.1 WebSocket Protocol

The sdk_relay component provides real-time communication via WebSocket. All messages are JSON-encoded.

Message types:

5.2 Message Flow Example

Client A → Relay: CommitMessage (new state proposal)
Relay → All participants: Broadcast CommitMessage
Client B → Relay: ValidationToken (signature)
Client C → Relay: ValidationToken (signature)
Relay → Client A: Forward ValidationTokens
Client A: Aggregates signatures, creates Bitcoin tx
Client A → Relay: CommitMessage (with on-chain proof)
Relay → All: Broadcast committed state

5.3 Connection Management

6. Storage and Persistence

6.1 Storage Architecture

The system uses a distributed key-value storage (sdk_storage) for:

6.2 Data Privacy Levels

Level Description Example
Private (PCD) Encrypted data, only commitment on-chain Sensitive documents
Public Readable by all network participants Paired addresses list
On-chain Only state_id (32 bytes) in OP_RETURN State commitments

6.3 Encryption Scheme

Private fields use AES-256-GCM encryption:

7. Data Flow

7.1 Creating a New Process

  1. Client calls create_process(roles, initial_state)
  2. SDK generates process structure with empty commitment
  3. Client proposes first state via CommitMessage
  4. Required members validate and sign
  5. Client creates Bitcoin transaction with state_id in OP_RETURN
  6. Process is now live with on-chain commitment

7.2 Updating a Process

  1. Client modifies process state fields
  2. SDK validates modifications against roles and rules
  3. Client sends CommitMessage with new state
  4. Other members receive proposal via relay
  5. Each member validates locally and signs if valid
  6. Proposer collects signatures until quorum reached
  7. Proposer spends previous UTXO, creates new one with new state_id
  8. New state becomes current, previous state moves to history

7.3 Obliterating a Process

  1. Member with "apophis" role calls obliterate(process_id)
  2. SDK validates caller has apophis permission
  3. Final Bitcoin transaction spends UTXO without creating new output
  4. Process is marked as obliterated (end of lifecycle)
  5. Historical states remain accessible but process cannot be updated

8. Security

8.1 Cryptographic Foundations

8.2 Threat Model

Protected against:

Residual risks:

8.3 Best Practices

For developers:

For users:

Conclusion

The 4NK identity and process system is built on an innovative decentralized architecture combining:

  1. Cryptographic Identity: Bitcoin Silent Payments (BIP352)
  2. Multi-device: Flexible pairing without security compromise
  3. Distributed Consensus: Multi-signature validation with configurable quorums
  4. Immutability: Bitcoin commitments for traceability
  5. Privacy: End-to-end encryption of sensitive data

This architecture enables various use cases:

Strengths:

Areas for improvement:

Document generated on October 1, 2025
Based on 4NK source code analysis (sdk_client, sdk_common, sdk_relay, sdk_storage, ihm_client)
View original specification (French)