42 lines
2.3 KiB
Markdown
42 lines
2.3 KiB
Markdown
# ChronoSeal Third-Party Wrapper & Integration Guide (WRAPPER_GUIDE)
|
|
|
|
This document provides stable guidance for developers building third-party integration wrappers, clients, or SDKs around the `chronoseald` daemon.
|
|
|
|
---
|
|
|
|
## 1. Public Contract & Stability Guarantees
|
|
|
|
As a protocol-first Unix daemon, `chronoseald` guarantees stability on the public network interface.
|
|
|
|
### Guaranteed Stable
|
|
* **Endpoints:** `POST /init` and `POST /hb`.
|
|
* **JSON Fields:** The structure and naming of request and response keys.
|
|
* **VM Instruction Set:** The behavior and encoding of the 10 core VM opcodes (`0x00`..=`0x09`).
|
|
* **Signature Serialization:** Alphabetical key-sorting rules using `BTreeMap` serialization.
|
|
* **Hash Progression:** Blake3 chain folding rules.
|
|
|
|
### Private (Unstable / Subject to Change)
|
|
* **Database Engines & Schemas:** SQLite table structure, Valkey key formatting, and indexes.
|
|
* **Daemon CLI Flags:** Internal metrics query formats.
|
|
* **Memory Structures:** Thread boundaries, session caches, and synchronization locks.
|
|
|
|
---
|
|
|
|
## 2. API Versioning & Deprecation Policy
|
|
|
|
* **Version Format:** API endpoints do not contain version prefixes (e.g., `/v1/hb`). Instead, protocol versioning is coupled to the daemon release version.
|
|
* **Breaking Protocol Changes:** Any change to the core hash function (Blake3) or the VM instruction set will trigger a major release (e.g., `v2.0.0`).
|
|
* **Deprecation Cycle:** Deprecated features will be supported for at least one minor release cycle, documented in `docs/PROTOCOL_STABILITY.md`.
|
|
|
|
---
|
|
|
|
## 3. Reference Implementation Steps for Wrappers
|
|
|
|
To build a client-side wrapper or application adapter for `chronoseald`:
|
|
|
|
1. **Handshake:** Send `POST /init` with the hex-encoded Ed25519 public key. Save the returned `session_id`, `salt`, `opcodes_b64`, and `mutation_order_b64`.
|
|
2. **VM Execution:** Run the math VM program (decoded from `opcodes_b64`) using the client wasm runtime to get the target `stack_state`.
|
|
3. **Gene Mutation:** Decode `mutation_order_b64`, apply the mutation steps to the local gene buffer, and compute the new commitment hash.
|
|
4. **Signing:** Build the canonical alphabetical JSON message, sign it, and send `POST /hb`.
|
|
5. **Chain Advancement:** On success, extract `next_salt` and `next_mutation_order_b64` to prepare the next heartbeat request.
|