468 lines
18 KiB
HTML
468 lines
18 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>4NK — Tech Overview</title>
|
|
<link rel="icon" type="image/png" href="/favicon.png">
|
|
<link rel="stylesheet" href="/styles.css">
|
|
<style>
|
|
.page { max-width: 960px; margin: 4rem auto; padding: 0 1rem; }
|
|
h1, h2, h3 { margin: 1.5rem 0 .5rem; }
|
|
.section { margin: 1.25rem 0; }
|
|
ul { padding-left: 1.2rem; }
|
|
ol { padding-left: 1.2rem; }
|
|
.header-actions { margin: 1.5rem 0 2rem; display: flex; gap: .75rem; }
|
|
table { width: 100%; border-collapse: collapse; margin: 1rem 0; }
|
|
th, td { border: 1px solid var(--border); padding: 0.5rem; text-align: left; }
|
|
th { background: var(--tint); font-weight: bold; }
|
|
code { background: var(--tint); padding: 0.2rem 0.4rem; border-radius: 4px; font-size: 0.9em; }
|
|
pre { background: var(--tint); padding: 1rem; border-radius: 8px; overflow-x: auto; }
|
|
pre code { background: none; padding: 0; }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<div class="page">
|
|
<h1>4NK Identity and Process System Specification</h1>
|
|
<div class="header-actions">
|
|
<a class="btn btn-secondary" href="/">Back to homepage</a>
|
|
</div>
|
|
|
|
<p><strong>Version:</strong> 1.0<br>
|
|
<strong>Date:</strong> October 1, 2025<br>
|
|
<strong>Source:</strong> Complete analysis of sdk_client, sdk_common, sdk_relay, sdk_storage, ihm_client, rust-silentPayments components</p>
|
|
|
|
<h2>Table of Contents</h2>
|
|
<ol>
|
|
<li><a href="#overview">Overview</a></li>
|
|
<li><a href="#identity">Identity Architecture</a></li>
|
|
<li><a href="#process">Process System</a></li>
|
|
<li><a href="#validation">Validation and Consensus</a></li>
|
|
<li><a href="#network">Network Communication</a></li>
|
|
<li><a href="#storage">Storage and Persistence</a></li>
|
|
<li><a href="#dataflow">Data Flow</a></li>
|
|
<li><a href="#security">Security</a></li>
|
|
</ol>
|
|
|
|
<h2 id="overview">1. Overview</h2>
|
|
|
|
<h3>1.1 System Philosophy</h3>
|
|
<p>4NK is a decentralized system for collaborative process management based on the Bitcoin blockchain, using <strong>Silent Payments (BIP352)</strong> for identity and encryption. The system enables multiple parties to collaborate on processes with verifiable states, defined roles, and cryptographic validation rules.</p>
|
|
|
|
<h3>1.2 Core Principles</h3>
|
|
<ul>
|
|
<li><strong>Decentralized Identity</strong>: Based on Bitcoin Silent Payment addresses</li>
|
|
<li><strong>Device-centric</strong>: Each device has its own cryptographic key</li>
|
|
<li><strong>Multi-device</strong>: A user can manage multiple devices via pairing</li>
|
|
<li><strong>Stateful Processes</strong>: Evolution controlled by Bitcoin commitments</li>
|
|
<li><strong>Distributed Validation</strong>: Multiple cryptographic signatures required</li>
|
|
<li><strong>P2P Communication</strong>: WebSocket relay for real-time synchronization</li>
|
|
</ul>
|
|
|
|
<h3>1.3 Main Components</h3>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Component</th>
|
|
<th>Role</th>
|
|
<th>Technology</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>sdk_common</td>
|
|
<td>Shared types and structures</td>
|
|
<td>Rust (WASM-ready)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>sdk_client</td>
|
|
<td>WASM client library</td>
|
|
<td>Rust → WebAssembly</td>
|
|
</tr>
|
|
<tr>
|
|
<td>sdk_relay</td>
|
|
<td>Message relay and synchronization</td>
|
|
<td>Rust + WebSocket</td>
|
|
</tr>
|
|
<tr>
|
|
<td>sdk_storage</td>
|
|
<td>Distributed key-value storage</td>
|
|
<td>Rust + HTTP</td>
|
|
</tr>
|
|
<tr>
|
|
<td>ihm_client</td>
|
|
<td>Web user interface</td>
|
|
<td>TypeScript + Web Components</td>
|
|
</tr>
|
|
<tr>
|
|
<td>rust-silentPayments</td>
|
|
<td>Silent Payments implementation</td>
|
|
<td>Rust (dependency)</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h2 id="identity">2. Identity Architecture</h2>
|
|
|
|
<h3>2.1 Identity Hierarchy</h3>
|
|
<pre><code>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)</code></pre>
|
|
|
|
<h3>2.2 Device Structure</h3>
|
|
<p>A <code>Device</code> represents a single physical device with its own cryptographic keys:</p>
|
|
<ul>
|
|
<li><strong>sp_wallet</strong>: Silent Payments wallet</li>
|
|
<li><strong>pairing_process_commitment</strong>: Optional link to pairing process</li>
|
|
<li><strong>paired_member</strong>: Group of paired addresses</li>
|
|
</ul>
|
|
|
|
<p><strong>Main operations:</strong></p>
|
|
<ol>
|
|
<li><strong>Creation</strong>: Generates a local Silent Payment address and initializes a Member with this address alone</li>
|
|
<li><strong>Pairing</strong>: Associates the device with a pairing process, linking multiple Silent Payment addresses together</li>
|
|
<li><strong>Unpairing</strong>: Resets to single local state</li>
|
|
</ol>
|
|
|
|
<h3>2.3 Member Structure</h3>
|
|
<p>A <code>Member</code> represents a set of devices belonging to the same entity:</p>
|
|
<ul>
|
|
<li>List of Silent Payment addresses</li>
|
|
<li>Used for multi-signature validations</li>
|
|
<li>Order-independent comparison (internal HashSet)</li>
|
|
<li>Deterministic serialization (automatic sorting)</li>
|
|
</ul>
|
|
|
|
<h3>2.4 Pairing Process</h3>
|
|
<p><strong>Pairing</strong> is the mechanism for associating multiple devices to a single logical identity (member).</p>
|
|
|
|
<p><strong>Pairing steps:</strong></p>
|
|
<ol>
|
|
<li><strong>Creation of pairing process</strong>: A device creates a new Process with a special "pairing" role. The ProcessState contains a public field "pairedAddresses" with the list of addresses.</li>
|
|
<li><strong>Pairing validation</strong>: Members must be empty (no pre-existing members). A single validation rule for the "pairedAddresses" field. Required signatures vary:
|
|
<ul>
|
|
<li><strong>Creation</strong>: Signature from new address only</li>
|
|
<li><strong>Addition</strong>: Signature from already paired addresses</li>
|
|
<li><strong>Removal</strong>: Signatures from all devices (consensus)</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>Post-pairing state</strong>: Device links to process and updates paired member list</li>
|
|
</ol>
|
|
|
|
<h2 id="process">3. Process System</h2>
|
|
|
|
<h3>3.1 Process Definition</h3>
|
|
<p>A <strong>Process</strong> is a state machine with defined roles, validation rules, and Bitcoin commitments. Each state transition creates a new Bitcoin UTXO.</p>
|
|
|
|
<p><strong>Key characteristics:</strong></p>
|
|
<ul>
|
|
<li><strong>Commitment ID</strong>: Bitcoin OutPoint (txid:vout)</li>
|
|
<li><strong>State ID</strong>: Merkle root of all process data</li>
|
|
<li><strong>Immutability</strong>: Each state is immutable once committed on-chain</li>
|
|
<li><strong>Verifiability</strong>: Anyone can verify state transitions via Bitcoin blockchain</li>
|
|
</ul>
|
|
|
|
<h3>3.2 Process Structure</h3>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Description</th>
|
|
<th>Type</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>commitment</td>
|
|
<td>Current Bitcoin commitment (OutPoint)</td>
|
|
<td>OutPoint</td>
|
|
</tr>
|
|
<tr>
|
|
<td>state</td>
|
|
<td>Current state (data + metadata)</td>
|
|
<td>ProcessState</td>
|
|
</tr>
|
|
<tr>
|
|
<td>roles</td>
|
|
<td>Role definitions and permissions</td>
|
|
<td>Roles</td>
|
|
</tr>
|
|
<tr>
|
|
<td>previous</td>
|
|
<td>Previous state (for history)</td>
|
|
<td>Option<ProcessState></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3>3.3 Roles System</h3>
|
|
<p>Each process defines <strong>roles</strong> with specific permissions. A role contains:</p>
|
|
<ul>
|
|
<li><strong>members</strong>: List of Member identifiers (pairing process IDs)</li>
|
|
<li><strong>validation_rules</strong>: Rules for field modifications</li>
|
|
<li><strong>storages</strong>: Authorized storage servers for this role</li>
|
|
</ul>
|
|
|
|
<p><strong>Special role "apophis":</strong></p>
|
|
<ul>
|
|
<li>Can obliterate (destroy) the entire process</li>
|
|
<li>Must be explicitly defined in roles</li>
|
|
<li>Typically restricted to process owner</li>
|
|
</ul>
|
|
|
|
<h3>3.4 Validation Rules</h3>
|
|
<p>A <code>ValidationRule</code> defines who can modify which fields:</p>
|
|
<ul>
|
|
<li><strong>quorum</strong>: Minimum percentage of members required (0.0 to 1.0)</li>
|
|
<li><strong>fields</strong>: List of field names covered by this rule</li>
|
|
<li><strong>min_sig_member</strong>: Minimum percentage of devices per member (0.0 to 1.0)</li>
|
|
</ul>
|
|
|
|
<p><strong>Example:</strong> A rule with quorum=0.67 and min_sig_member=0.5 requires:</p>
|
|
<ul>
|
|
<li>At least 2/3 of members to approve</li>
|
|
<li>Each approving member needs at least 50% of their devices to sign</li>
|
|
</ul>
|
|
|
|
<h2 id="validation">4. Validation and Consensus</h2>
|
|
|
|
<h3>4.1 State Transition Workflow</h3>
|
|
<ol>
|
|
<li><strong>Proposal</strong>: A member proposes a new state via <code>CommitMessage</code></li>
|
|
<li><strong>Distribution</strong>: The relay broadcasts the proposal to all participants</li>
|
|
<li><strong>Validation</strong>: Each member validates the proposal locally</li>
|
|
<li><strong>Signature</strong>: If valid, members sign and send <code>ValidationToken</code></li>
|
|
<li><strong>Aggregation</strong>: Proposer collects signatures until quorum is reached</li>
|
|
<li><strong>Commitment</strong>: Proposer creates Bitcoin transaction with state_id in OP_RETURN</li>
|
|
<li><strong>Broadcast</strong>: New state is distributed with on-chain proof</li>
|
|
</ol>
|
|
|
|
<h3>4.2 Validation Token</h3>
|
|
<p>A <code>ValidationToken</code> is a cryptographic signature proving a member's approval:</p>
|
|
<ul>
|
|
<li><strong>public_key</strong>: Signer's public key (extracted from Silent Payment address)</li>
|
|
<li><strong>signature</strong>: Schnorr signature of state_id</li>
|
|
<li><strong>message</strong>: state_id (32 bytes)</li>
|
|
</ul>
|
|
|
|
<h3>4.3 Multi-signature Validation</h3>
|
|
<p>The system supports complex multi-signature schemes:</p>
|
|
<ul>
|
|
<li><strong>Inter-member quorum</strong>: Percentage of members required</li>
|
|
<li><strong>Intra-member quorum</strong>: Percentage of devices per member</li>
|
|
<li><strong>Field-specific rules</strong>: Different quorums for different fields</li>
|
|
</ul>
|
|
|
|
<p><strong>Example scenario:</strong></p>
|
|
<ul>
|
|
<li>Role "validator" has 3 members: Alice, Bob, Carol</li>
|
|
<li>Alice has 2 devices, Bob has 3 devices, Carol has 1 device</li>
|
|
<li>Rule: quorum=0.67, min_sig_member=0.5, fields=["certifiedDoc"]</li>
|
|
<li>To modify "certifiedDoc": Need 2/3 members (2 of 3) + at least 50% devices per member</li>
|
|
<li>Valid combination: Alice (1/2 devices) + Bob (2/3 devices) = quorum reached</li>
|
|
</ul>
|
|
|
|
<h2 id="network">5. Network Communication</h2>
|
|
|
|
<h3>5.1 WebSocket Protocol</h3>
|
|
<p>The <code>sdk_relay</code> component provides real-time communication via WebSocket. All messages are JSON-encoded.</p>
|
|
|
|
<p><strong>Message types:</strong></p>
|
|
<ul>
|
|
<li><strong>CommitMessage</strong>: Propose a new process state</li>
|
|
<li><strong>ValidationToken</strong>: Sign a proposed state</li>
|
|
<li><strong>CipherMessage</strong>: Send encrypted data to specific recipient</li>
|
|
<li><strong>QueryMessage</strong>: Request process state or history</li>
|
|
</ul>
|
|
|
|
<h3>5.2 Message Flow Example</h3>
|
|
<pre><code>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</code></pre>
|
|
|
|
<h3>5.3 Connection Management</h3>
|
|
<ul>
|
|
<li><strong>Authentication</strong>: Silent Payment address-based</li>
|
|
<li><strong>Reconnection</strong>: Automatic with exponential backoff</li>
|
|
<li><strong>State synchronization</strong>: Query missing states on reconnect</li>
|
|
<li><strong>Heartbeat</strong>: Periodic ping/pong to detect disconnections</li>
|
|
</ul>
|
|
|
|
<h2 id="storage">6. Storage and Persistence</h2>
|
|
|
|
<h3>6.1 Storage Architecture</h3>
|
|
<p>The system uses a distributed key-value storage (<code>sdk_storage</code>) for:</p>
|
|
<ul>
|
|
<li>Process states (historical and current)</li>
|
|
<li>Encrypted field keys</li>
|
|
<li>Large binary data (documents, files)</li>
|
|
<li>Member metadata</li>
|
|
</ul>
|
|
|
|
<h3>6.2 Data Privacy Levels</h3>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Level</th>
|
|
<th>Description</th>
|
|
<th>Example</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>Private (PCD)</td>
|
|
<td>Encrypted data, only commitment on-chain</td>
|
|
<td>Sensitive documents</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Public</td>
|
|
<td>Readable by all network participants</td>
|
|
<td>Paired addresses list</td>
|
|
</tr>
|
|
<tr>
|
|
<td>On-chain</td>
|
|
<td>Only state_id (32 bytes) in OP_RETURN</td>
|
|
<td>State commitments</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3>6.3 Encryption Scheme</h3>
|
|
<p>Private fields use AES-256-GCM encryption:</p>
|
|
<ul>
|
|
<li><strong>Key generation</strong>: Random 32 bytes per field</li>
|
|
<li><strong>Key distribution</strong>: Via CipherMessage or storage (asymmetrically encrypted)</li>
|
|
<li><strong>Key storage</strong>: In ProcessState.keys (field_name → key mapping)</li>
|
|
</ul>
|
|
|
|
<h2 id="dataflow">7. Data Flow</h2>
|
|
|
|
<h3>7.1 Creating a New Process</h3>
|
|
<ol>
|
|
<li>Client calls <code>create_process(roles, initial_state)</code></li>
|
|
<li>SDK generates process structure with empty commitment</li>
|
|
<li>Client proposes first state via <code>CommitMessage</code></li>
|
|
<li>Required members validate and sign</li>
|
|
<li>Client creates Bitcoin transaction with state_id in OP_RETURN</li>
|
|
<li>Process is now live with on-chain commitment</li>
|
|
</ol>
|
|
|
|
<h3>7.2 Updating a Process</h3>
|
|
<ol>
|
|
<li>Client modifies process state fields</li>
|
|
<li>SDK validates modifications against roles and rules</li>
|
|
<li>Client sends <code>CommitMessage</code> with new state</li>
|
|
<li>Other members receive proposal via relay</li>
|
|
<li>Each member validates locally and signs if valid</li>
|
|
<li>Proposer collects signatures until quorum reached</li>
|
|
<li>Proposer spends previous UTXO, creates new one with new state_id</li>
|
|
<li>New state becomes current, previous state moves to history</li>
|
|
</ol>
|
|
|
|
<h3>7.3 Obliterating a Process</h3>
|
|
<ol>
|
|
<li>Member with "apophis" role calls <code>obliterate(process_id)</code></li>
|
|
<li>SDK validates caller has apophis permission</li>
|
|
<li>Final Bitcoin transaction spends UTXO without creating new output</li>
|
|
<li>Process is marked as obliterated (end of lifecycle)</li>
|
|
<li>Historical states remain accessible but process cannot be updated</li>
|
|
</ol>
|
|
|
|
<h2 id="security">8. Security</h2>
|
|
|
|
<h3>8.1 Cryptographic Foundations</h3>
|
|
<ul>
|
|
<li><strong>Identity</strong>: Bitcoin Silent Payments (BIP352), Schnorr signatures</li>
|
|
<li><strong>Encryption</strong>: AES-256-GCM for data, ECDH for key exchange</li>
|
|
<li><strong>Integrity</strong>: Merkle trees for state verification</li>
|
|
<li><strong>Timestamping</strong>: Bitcoin blockchain as immutable clock</li>
|
|
</ul>
|
|
|
|
<h3>8.2 Threat Model</h3>
|
|
<p><strong>Protected against:</strong></p>
|
|
<ul>
|
|
<li>✅ Transaction replay (unique state_id per commitment)</li>
|
|
<li>✅ Double-spending (Bitcoin consensus)</li>
|
|
<li>✅ State manipulation (multi-signature validation + Merkle proofs)</li>
|
|
<li>✅ Sybil attacks (Bitcoin transaction costs for pairing)</li>
|
|
</ul>
|
|
|
|
<p><strong>Residual risks:</strong></p>
|
|
<ul>
|
|
<li>⚠️ Relay censorship (mitigation: multi-relay connections)</li>
|
|
<li>⚠️ Privacy leakage via network analysis (mitigation: Tor support)</li>
|
|
<li>⚠️ Silent Payment scanning complexity (mitigation: Blindbit optimization)</li>
|
|
</ul>
|
|
|
|
<h3>8.3 Best Practices</h3>
|
|
<p><strong>For developers:</strong></p>
|
|
<ul>
|
|
<li>High quorum for critical actions (≥ 0.67 or 2/3)</li>
|
|
<li>Always define "apophis" role for obliteration capability</li>
|
|
<li>Encrypt sensitive data in PCD (private fields)</li>
|
|
<li>Validate client-side before sending CommitMessage</li>
|
|
</ul>
|
|
|
|
<p><strong>For users:</strong></p>
|
|
<ul>
|
|
<li>Pair at least 2 devices for backup</li>
|
|
<li>Regular wallet backups (export keys)</li>
|
|
<li>Verify roles before signing states</li>
|
|
<li>Check fields to validate using <code>get_fields_to_validate_for_member()</code></li>
|
|
</ul>
|
|
|
|
<h2>Conclusion</h2>
|
|
<p>The 4NK identity and process system is built on an innovative decentralized architecture combining:</p>
|
|
<ol>
|
|
<li><strong>Cryptographic Identity</strong>: Bitcoin Silent Payments (BIP352)</li>
|
|
<li><strong>Multi-device</strong>: Flexible pairing without security compromise</li>
|
|
<li><strong>Distributed Consensus</strong>: Multi-signature validation with configurable quorums</li>
|
|
<li><strong>Immutability</strong>: Bitcoin commitments for traceability</li>
|
|
<li><strong>Privacy</strong>: End-to-end encryption of sensitive data</li>
|
|
</ol>
|
|
|
|
<p>This architecture enables various use cases:</p>
|
|
<ul>
|
|
<li>Collaborative contract management</li>
|
|
<li>Multi-party electronic signatures</li>
|
|
<li>Decentralized approval workflows</li>
|
|
<li>Sovereign digital identity</li>
|
|
</ul>
|
|
|
|
<p><strong>Strengths:</strong></p>
|
|
<ul>
|
|
<li>No trusted central server</li>
|
|
<li>Censorship resistance</li>
|
|
<li>Complete auditability</li>
|
|
<li>Native Bitcoin interoperability</li>
|
|
</ul>
|
|
|
|
<p><strong>Areas for improvement:</strong></p>
|
|
<ul>
|
|
<li>Silent Payments scanning performance (Blindbit optimization)</li>
|
|
<li>Network resilience (multi-relays, gossip protocol)</li>
|
|
<li>Key management (social recovery, hardware wallets)</li>
|
|
<li>Pairing UX (NFC, dynamic QR codes)</li>
|
|
</ul>
|
|
|
|
<hr style="margin: 2rem 0; opacity:.2;">
|
|
<p>
|
|
<strong>Document generated on October 1, 2025</strong><br>
|
|
Based on 4NK source code analysis (sdk_client, sdk_common, sdk_relay, sdk_storage, ihm_client)<br>
|
|
<a href="https://git.4nkweb.com/4nk/4NK_env/src/branch/ext/docs/4NK_IDENTITY_AND_PROCESS_SPEC.md" target="_blank" rel="noopener">View original specification (French)</a>
|
|
</p>
|
|
</div>
|
|
<script src="/script.js"></script>
|
|
</body>
|
|
</html>
|