organic-protocol 0.2.0 → 0.3.0

package/PROTOCOL.md

@@ -1,135 +1,168 @@
-# Organic Money — Inter-instance Protocol (v1)
-
-This document is the **standard** every compatible implementation (app or server) must follow. The [`organic-protocol`](https://www.npmjs.com/package/organic-protocol) npm package is its exact TypeScript translation; JS/TS implementations should import it rather than reimplement. Cryptography (signatures, chains, encryption) is defined by [`organic-money`](https://www.npmjs.com/package/organic-money) and is not repeated here.
-
-Protocol version: **1**. QR format version: **1** (independent, see §4).
-
----
-
-## 1. Federated identity
-
-A public key alone is not enough to reach someone in a decentralized network. An **identity** is always the pair:
-
-```json
-{ "pk": "<compressed SECP256K1 public key, hex>", "url": "<root URL of the referent server>" }
-```
-
-The `url` is the server's **root** URL (no `/api`, no trailing slash), normalized: `https` scheme by default (`http` tolerated when explicit — local networks, development), lowercase host. See `normalizeServerUrl`.
-
-## 2. Wire formats
-
-### 2.1 Transaction (`TxWire`)
-
-```json
-{ "v": 1, "d": 20260719, "t": 3, "p": "<target pk>", "s": "<signer pk>",
-  "m": "BLeiCZk=", "i": "", "h": "<DER signature, hex>" }
-```
-
-| Field | Long name | Content |
-|---|---|---|
-| `v` | version | protocol version (1) |
-| `d` | date | `YYYYMMDD` integer |
-| `t` | type | transaction type (§3) |
-| `p` | target | recipient's public key |
-| `s` | signer | sender's public key |
-| `m` | money | packed money unit ids (§2.3) |
-| `i` | invests | packed invest unit ids (§2.3) |
-| `h` | signature | SECP256K1 DER signature, hex |
-
-### 2.2 Block (`BlockWire`)
-
-```json
-{ "v": 1, "d": 20260719, "p": "<previous block signature>", "s": "<pk>",
-  "m": "", "i": "", "t": 42, "r": "<merkle root>", "h": "<signature>", "x": [ …TxWire ] }
-```
-
-Here `t` is the **total** (cumulative economic experience); `p` is the previous block's signature (chain link); `x` is the transaction list. `m`/`i` are the available (unspent) money/invest ids at seal time, packed the same way as in a transaction (§2.3).
-
-### 2.3 Packed unit ids (`m`, `i`)
-
-Money and invest unit ids (`YYYYMMDDXXX` / `YYYYMMDD9XXX`, §2.1 table) are **not** a JSON array of numbers on the wire — a plain decimal array costs 12 bytes per id (11-12 digits plus a separator) for ~5 bytes of actual information, which matters once a paper bill (§4, `PP`) bundles many ids into one QR code. Instead: each id is packed into 5 big-endian bytes (comfortably covers every possible id), all ids are concatenated, and the result is base64-encoded into a single string. An empty array is the empty string `""`. Order and duplicates are preserved. Reference implementation: `packUnitIds`/`unpackUnitIds` in [`organic-money`](https://www.npmjs.com/package/organic-money) (`src/crypto.js`); `organic-protocol` validates the shape (`isTxWire`/`isBlockWire`) but does not implement the packing itself.
-
-## 3. Transaction types
-
-| # | Type | # | Type |
-|---|---|---|---|
-| 1 | INIT | 8 | SETPAYER |
-| 2 | CREATE | 9 | UNSETADMIN |
-| 3 | PAY | 10 | UNSETACTOR |
-| 4 | ENGAGE | 11 | UNSETPAYER |
-| 5 | PAPER | 12 | PAYERORDER |
-| 6 | SETADMIN | 13 | EARN |
-| 7 | SETACTOR | | |
-
-## 4. QR codes
-
-Format: **`OM<version>:<TYPE>:<JSON payload>`** — the prefix lives outside the JSON so any reader can dispatch (or reject an unknown version) without parsing. Current version: `1`.
-
-**Compatibility rule**: a reader encountering a version it does not speak MUST refuse cleanly ("please update the app") and MUST NEVER attempt a best-effort interpretation.
-
-| Type | Shape | Usage |
-|---|---|---|
-| `CT` | `OM1:CT:{"pk","url","n","e"?}` | Contact card. `n` = display name; `e` = true for an ecosystem. |
-| `TX` | `OM1:TX:{"tx":<PAY TxWire>,"url"}` | Offline payment, camera-to-screen. `url` = the PAYER's server, for deferred verification (§5, `tx/verify`). |
-| `BR` | `OM1:BR:{"pk","url","n"}` | Validation request of a new citizen. Blocks are fetched via `GET {url}/api/v1/validations/{pk}` (Phase 2) — the QR is a pointer, not a container. |
-| `PP` | `OM1:PP:{"tx":<PAPER TxWire>}` | Printed paper bill. |
-
-Constraints: the `tx` of a `TX` is of type PAY; the one of a `PP` is of type PAPER.
-
-## 5. REST API `/api/v1`
-
-All routes live under `{url}/api/v1`. JSON bodies. Errors carry `{ "error": "<message>", "code": "<ApiErrorCode>"? }`.
-
-### 5.1 Authentication schemes
-
-**Block-auth** (`PUT /users/save`, `PUT /users/sign`) — `x-signature` header = signature of the submitted block's hash, by the account key:
-`x-signature = signHash(block.hash(), sk)`.
-
-**Timestamp-auth** (`GET /tx/list`, `POST /users/password`, …) — `x-signature` header = `signHash(sha256(publickey + ":" + timestamp), sk)` with `publickey` and `timestamp` (Unix seconds) passed as params/body. Tolerance: ±5 minutes, otherwise 401.
-
-### 5.2 Endpoints (Phase 1)
-
-| Method & route | Auth | Body → Response | Notes |
-|---|---|---|---|
-| `GET /info` | — | → `InfoResponse` | public identity card of the server |
-| `GET /servers` | — | → `ServerListEntry[]` | directory of known servers |
-| `POST /users/register` | — | `RegisterBody` → `RegisterResponse` | the `secretkey` arrives ENCRYPTED (opaque to the server); the password is bcrypted on arrival |
-| `POST /users/login` | — | `LoginBody` → `LoginResponse` | **devicetoken rotation**: the previous device is revoked |
-| `PUT /users/save` | block | `SaveBlockBody` → 200 | `409 DEVICE_REVOKED` when the devicetoken is no longer the active one |
-| `PUT /users/sign` | block | `SignBlockBody` → 200 | the server signs the last block (bills, genesis) |
-| `POST /users/password` | timestamp | `PasswordChangeBody` → 200 | updates bcrypt + re-encrypted sk, without reading anything |
-| `POST /tx/send` | — | `TxSendBody` → 200 | **MANDATORY cross-verification** (§5.3) |
-| `GET /tx/list` | timestamp | → `TxWire[]` | pending payments for the key |
-| `POST /tx/verify` | — | `TxVerifyBody` → `TxVerifyResponse` | read-only; statuses: `confirmed` / `pending` / `invalid` / `unknown-sender` |
-| `POST /papers/cash` | — | `PapersCashBody` → 200 | requires the full PAPER, verifies its crypto; `409 ALREADY_CASHED` |
-| `GET /papers/isCashed?hash=` | — | → `IsCashedResponse` \| 404 | 404 = never cashed |
-
-### 5.3 Cross-verification (server duty)
-
-Before accepting on `tx/send` (and, in Phase 2, any ecosystem input), the server MUST:
-
-1. verify the cryptographic validity of the transaction;
-2. load the SAVED chain of the sender (`tx.s`) and validate it (`assertIsValid`);
-3. verify the transaction exists in that chain's history (by its signature `h`).
-
-Without step 3, an attacker can sign a transaction carrying units they do not own. Client-side consequence: the **`pay → save → send` order is strict**.
-
-### 5.4 One account = one active device
-
-The server issues an opaque `devicetoken` (UUID) at `register` and at every `login`; only the last one issued is valid. A `save` carrying a stale token receives `409 DEVICE_REVOKED` — the app must then switch to read-only and offer the restore flow. This mechanism is not cryptographic (identity is still proven by `x-signature`); it prevents the accidental fork of a chain across two devices.
-
-### 5.5 Error codes
-
-`INVALID_TX` · `INVALID_CHAIN` · `TX_NOT_IN_CHAIN` · `UNKNOWN_SENDER` · `UNKNOWN_USER` · `INVALID_SIGNATURE` · `DEVICE_REVOKED` · `ALREADY_CASHED`
-
-## 6. Versioning
-
-- **Protocol** (`PROTOCOL_VERSION`, `v` field of txs/blocks): bumped only on a wire-format break.
-- **QR** (`QR_VERSION`, `OM<v>` prefix): bumped only on a QR payload break.
-- **API** (`/api/v1`): a REST contract break creates `/api/v2`; `GET /info` announces the spoken versions.
-
-The three evolve independently. Every implementation MUST announce its versions via `GET /info` and refuse cleanly what it does not speak.
-
----
-
-*MIT license — © suipotryot. Phases 2 (ecosystems, validations) and 3 (federation) will extend this document without breaking v1.*
+# Organic Money — Inter-instance Protocol (v1)
+
+This document is the **standard** every compatible implementation (app or server) must follow. The [`organic-protocol`](https://www.npmjs.com/package/organic-protocol) npm package is its exact TypeScript translation; JS/TS implementations should import it rather than reimplement. Cryptography (signatures, chains, encryption) is defined by [`organic-money`](https://www.npmjs.com/package/organic-money) and is not repeated here.
+
+Protocol version: **1**. QR format version: **1** (independent, see §4).
+
+---
+
+## 1. Federated identity
+
+A public key alone is not enough to reach someone in a decentralized network. An **identity** is always the pair:
+
+```json
+{ "pk": "<compressed SECP256K1 public key, hex>", "url": "<root URL of the referent server>" }
+```
+
+The `url` is the server's **root** URL (no `/api`, no trailing slash), normalized: `https` scheme by default (`http` tolerated when explicit — local networks, development), lowercase host. See `normalizeServerUrl`.
+
+## 2. Wire formats
+
+### 2.1 Transaction (`TxWire`)
+
+```json
+{ "v": 1, "d": 20260719, "t": 3, "p": "<target pk>", "s": "<signer pk>",
+  "m": "BLeiCZk=", "i": "", "h": "<DER signature, hex>" }
+```
+
+| Field | Long name | Content |
+|---|---|---|
+| `v` | version | protocol version (1) |
+| `d` | date | `YYYYMMDD` integer |
+| `t` | type | transaction type (§3) |
+| `p` | target | recipient's public key |
+| `s` | signer | sender's public key |
+| `m` | money | packed money unit ids (§2.3) |
+| `i` | invests | packed invest unit ids (§2.3) |
+| `h` | signature | SECP256K1 DER signature, hex |
+| `q`? | quantity | ratio (SETACTOR) or spending cap, `-1` = unlimited (SETPAYER) — required on those two types only |
+| `e`? | ecosystem | target ecosystem's public key — required on SETADMIN/SETACTOR/SETPAYER/UNSETADMIN/UNSETACTOR/UNSETPAYER/PAYERORDER, absent on every other type |
+| `x`? | exercised order | EARN only: signature of the PayerOrder it fulfills, present only when produced by `order()` |
+
+`q`/`e`/`x` are part of the signed preimage on the types where they apply — not cosmetic metadata. They must be absent on every type that doesn't use them (§3 lists which).
+
+### 2.2 Block (`BlockWire`)
+
+```json
+{ "v": 1, "d": 20260719, "p": "<previous block signature>", "s": "<pk>",
+  "m": "", "i": "", "t": 1, "e": 42, "r": "<merkle root>", "h": "<signature>", "x": [ …TxWire ] }
+```
+
+Here `t` is the **block type** (not a total, despite the letter — see the table below); `p` is the previous block's signature (chain link); `x` is the transaction list. `m`/`i` are the available (unspent) money/invest ids at seal time, packed the same way as in a transaction (§2.3). `e` is the cumulative economic experience — present only on citizen block types, absent on ecosystem ones.
+
+| `t` | Block type | Carries `e`? |
+|---|---|---|
+| 1 | CITIZEN | yes |
+| 2 | ECOSYSTEM | no |
+| 3 | CITIZENBIRTH | yes |
+| 4 | CITIZENINIT | yes |
+| 5 | ECOSYSTEMBIRTH | no |
+| 6 | ECOSYSTEMINIT | no |
+
+### 2.3 Packed unit ids (`m`, `i`)
+
+Money and invest unit ids (`YYYYMMDDXXX` / `YYYYMMDD9XXX`, §2.1 table) are **not** a JSON array of numbers on the wire — a plain decimal array costs 12 bytes per id (11-12 digits plus a separator) for ~5 bytes of actual information, which matters once a paper bill (§4, `PP`) bundles many ids into one QR code. Instead: each id is packed into 5 big-endian bytes (comfortably covers every possible id), all ids are concatenated, and the result is base64-encoded into a single string. An empty array is the empty string `""`. Order and duplicates are preserved. Reference implementation: `packUnitIds`/`unpackUnitIds` in [`organic-money`](https://www.npmjs.com/package/organic-money) (`src/crypto.js`); `organic-protocol` validates the shape (`isTxWire`/`isBlockWire`) but does not implement the packing itself.
+
+## 3. Transaction types
+
+| # | Type | # | Type |
+|---|---|---|---|
+| 1 | INIT | 8 | SETPAYER |
+| 2 | CREATE | 9 | UNSETADMIN |
+| 3 | PAY | 10 | UNSETACTOR |
+| 4 | ENGAGE | 11 | UNSETPAYER |
+| 5 | PAPER | 12 | PAYERORDER |
+| 6 | SETADMIN | 13 | EARN |
+| 7 | SETACTOR | | |
+
+## 4. QR codes
+
+Format: **`OM<version>:<TYPE>:<JSON payload>`** — the prefix lives outside the JSON so any reader can dispatch (or reject an unknown version) without parsing. Current version: `1`.
+
+**Compatibility rule**: a reader encountering a version it does not speak MUST refuse cleanly ("please update the app") and MUST NEVER attempt a best-effort interpretation.
+
+| Type | Shape | Usage |
+|---|---|---|
+| `CT` | `OM1:CT:{"pk","url","n","e"?}` | Contact card. `n` = display name; `e` = true for an ecosystem. |
+| `TX` | `OM1:TX:{"tx":<PAY TxWire>,"url"}` | Offline payment, camera-to-screen. `url` = the PAYER's server, for deferred verification (§5, `tx/verify`). |
+| `BR` | `OM1:BR:{"pk","url","n"}` | Validation request of a new citizen. The scanning admin's own device fetches the candidate's blocks via `GET {url}/api/v1/validations/{pk}` (§5.2b) — the QR is a pointer, not a container. |
+| `PP` | `OM1:PP:{"tx":<PAPER TxWire>}` | Printed paper bill. |
+
+Constraints: the `tx` of a `TX` is of type PAY; the one of a `PP` is of type PAPER.
+
+## 5. REST API `/api/v1`
+
+All routes live under `{url}/api/v1`. JSON bodies. Errors carry `{ "error": "<message>", "code": "<ApiErrorCode>"? }`.
+
+### 5.1 Authentication schemes
+
+**Block-auth** (`PUT /users/save`, `PUT /users/sign`) — `x-signature` header = signature of the submitted block's hash, by the account key:
+`x-signature = signHash(block.hash(), sk)`.
+
+**Timestamp-auth** (`GET /tx/list`, `POST /users/password`, …) — `x-signature` header = `signHash(sha256(publickey + ":" + timestamp), sk)` with `publickey` and `timestamp` (Unix seconds) passed as params/body. Tolerance: ±5 minutes, otherwise 401.
+
+### 5.2 Endpoints (Phase 1)
+
+| Method & route | Auth | Body → Response | Notes |
+|---|---|---|---|
+| `GET /info` | — | → `InfoResponse` | public identity card of the server |
+| `GET /servers` | — | → `ServerListEntry[]` | directory of known servers |
+| `POST /users/register` | — | `RegisterBody` → `RegisterResponse` | the `secretkey` arrives ENCRYPTED (opaque to the server); the password is bcrypted on arrival |
+| `POST /users/login` | — | `LoginBody` → `LoginResponse` | **devicetoken rotation**: the previous device is revoked |
+| `PUT /users/save` | block | `SaveBlockBody` → 200 | `409 DEVICE_REVOKED` when the devicetoken is no longer the active one |
+| `PUT /users/sign` | block | `SignBlockBody` → 200 | the server signs the last block (bills, genesis) |
+| `POST /users/password` | timestamp | `PasswordChangeBody` → 200 | updates bcrypt + re-encrypted sk, without reading anything |
+| `POST /tx/send` | — | `TxSendBody` → 200 | **MANDATORY cross-verification** (§5.3) |
+| `GET /tx/list` | timestamp | → `TxWire[]` | pending payments for the key |
+| `POST /tx/verify` | — | `TxVerifyBody` → `TxVerifyResponse` | read-only; statuses: `confirmed` / `pending` / `invalid` / `unknown-sender` |
+| `POST /papers/cash` | — | `PapersCashBody` → 200 | requires the full PAPER, verifies its crypto; `409 ALREADY_CASHED` |
+| `GET /papers/isCashed?hash=` | — | → `IsCashedResponse` \| 404 | 404 = never cashed |
+
+### 5.2b Endpoints (Phase 2 — ecosystems & validations)
+
+Ecosystem creation is free and instant — no admin approval, see the notes column. A citizen's validation is the only thing gated behind the core ecosystem's admins.
+
+| Method & route | Auth | Body → Response | Notes |
+|---|---|---|---|
+| `POST /ecosystems` | timestamp | `EcosystemCreateBody` → `EcosystemCreateResponse` | server generates the ecosystem's own key, self-signs and self-validates it; `founderPk` is recorded as `validatorpk` for attribution only. First ecosystem ever created on a server becomes its core (`iscore: true`) |
+| `GET /ecosystems?lat&lng&radiusKm` | — | → `EcosystemListEntry[]` | public directory; sorted by distance when `lat`/`lng` given |
+| `GET /ecosystems/mine?publickey=` | — | → `MyEcosystemEntry[]` | public — roles are already derivable from each ecosystem's own public chain, this just aggregates across all of them server-side |
+| `GET /ecosystems/:pk` | — | → `EcosystemInfoResponse` | full chain + metadata |
+| `PUT /ecosystems/:pk/meta` | timestamp | `EcosystemMetaUpdateBody` → 200 | caller must be `isAdmin(publickey)` on that ecosystem |
+| `POST /ecosystems/:pk/tx` | — | `EcosystemTxBody` → 200 | generic ingress for PAY/ENGAGE/role/PAYERORDER transactions targeting this ecosystem — same cross-verification duty as `tx/send` (§5.3), against the *signer's* own chain. A `PAYERORDER` executes immediately; the resulting payment is queued for a citizen target or applied directly for an ecosystem target — no separate claim step |
+| `POST /ecosystems/:pk/distribute` | timestamp | `EcosystemDistributeBody` → 200 | caller must be `isAdmin`/`isPayer`; manual only, no scheduling |
+| `GET /validations` | timestamp | → `ValidationListEntry[]` | caller must be a current admin of the server's core ecosystem |
+| `GET /validations/:pk` | timestamp | → `ValidationDetailResponse` | same auth; the admin's device reconstructs the chain locally and calls `validateAccount()` itself |
+| `GET /validations/status/:pk` | — | → `ValidationStatusResponse` | public — for the candidate to poll |
+| `POST /validations/:pk/approve` | block | `ValidationApproveBody` → 200 | `block` is the admin's own already-signed `InitializationBlock`; the server's real check is that its signer is *currently* a core admin (`403 NOT_CORE_ADMIN` otherwise), not just that the signature is valid |
+| `POST /validations/:pk/reject` | timestamp | `ValidationRejectBody` → 200 | caller must be a core admin; the row is kept with `status: 'rejected'`, not deleted |
+
+### 5.3 Cross-verification (server duty)
+
+Before accepting on `tx/send` **or `ecosystems/:pk/tx`**, the server MUST:
+
+1. verify the cryptographic validity of the transaction;
+2. load the SAVED chain of the sender (`tx.s`) and validate it (`assertIsValid`) **and confirm it is validated (`isValidated`)** — a pending account's self-signed chain is well-formed but not yet trustworthy;
+3. verify the transaction exists in that chain's history (by its signature `h`).
+
+Without step 3, an attacker can sign a transaction carrying units they do not own. Without step 2's validation check, an unapproved candidate could act as if already validated. Client-side consequence: the **`pay → save → send` order is strict**.
+
+### 5.4 One account = one active device
+
+The server issues an opaque `devicetoken` (UUID) at `register` and at every `login`; only the last one issued is valid. A `save` carrying a stale token receives `409 DEVICE_REVOKED` — the app must then switch to read-only and offer the restore flow. This mechanism is not cryptographic (identity is still proven by `x-signature`); it prevents the accidental fork of a chain across two devices.
+
+### 5.5 Error codes
+
+`INVALID_TX` · `INVALID_CHAIN` · `TX_NOT_IN_CHAIN` · `UNKNOWN_SENDER` · `UNKNOWN_USER` · `INVALID_SIGNATURE` · `DEVICE_REVOKED` · `ALREADY_CASHED` · `NOT_CORE_ADMIN` · `ALREADY_VALIDATED`
+
+## 6. Versioning
+
+- **Protocol** (`PROTOCOL_VERSION`, `v` field of txs/blocks): bumped only on a wire-format break.
+- **QR** (`QR_VERSION`, `OM<v>` prefix): bumped only on a QR payload break.
+- **API** (`/api/v1`): a REST contract break creates `/api/v2`; `GET /info` announces the spoken versions.
+
+The three evolve independently. Every implementation MUST announce its versions via `GET /info` and refuse cleanly what it does not speak.
+
+---
+
+*MIT license — © suipotryot. Phase 2 (ecosystems, validations) is now specified above (§5.2b) without breaking v1. Phase 3 (federation) will extend this document further.*

package/dist/api.d.ts

@@ -5,7 +5,13 @@
  */
 import type { BlockWire, PublicKeyHex, TxWire } from './wire.js';
 /** Machine-readable error codes carried alongside HTTP status codes. */
-export type ApiErrorCode = 'INVALID_TX' | 'INVALID_CHAIN' | 'TX_NOT_IN_CHAIN' | 'UNKNOWN_SENDER' | 'UNKNOWN_USER' | 'INVALID_SIGNATURE' | 'DEVICE_REVOKED' | 'ALREADY_CASHED';
+export type ApiErrorCode = 'INVALID_TX' | 'INVALID_CHAIN' | 'TX_NOT_IN_CHAIN' | 'UNKNOWN_SENDER' | 'UNKNOWN_USER' | 'INVALID_SIGNATURE' | 'DEVICE_REVOKED' | 'ALREADY_CASHED'
+/** the signer proved their identity but isn't currently a core admin */
+ | 'NOT_CORE_ADMIN'
+/** approve attempted on an account that is already active */
+ | 'ALREADY_VALIDATED';
+/** A citizen or ecosystem account's standing (Phase 2). */
+export type MembershipStatus = 'pending-validation' | 'active' | 'rejected';
 /** Error body returned with any non-2xx response. */
 export interface ApiError {
     error: string;
@@ -44,7 +50,9 @@ export interface RegisterBody {
 }
 export interface RegisterResponse {
     publickey: PublicKeyHex;
-    /** the validated chain (server-signed in genesis mode) */
+    /** 'active' only for the server's very first account (open genesis); 'pending-validation' otherwise */
+    status: MembershipStatus;
+    /** the birth-only chain if pending, or the validated chain if this was the open-genesis account */
     blocks: BlockWire[];
     devicetoken: string;
 }
@@ -59,6 +67,7 @@ export interface LoginResponse {
     mail: string;
     /** the AES-encrypted secret key, exactly as uploaded */
     secretkey: string;
+    status: MembershipStatus;
     blocks: BlockWire[];
     devicetoken: string;
 }
@@ -101,3 +110,114 @@ export interface PapersCashBody {
 export interface IsCashedResponse {
     id: number | string;
 }
+/**
+ * Creation is free and instant (§0.3 of Phase-2.md): the server generates the
+ * ecosystem's own key, self-signs its birth block, and self-validates with
+ * that same key — no separate approval step. founderPk is only the
+ * authenticated requester, recorded as validatorpk for attribution; it is
+ * not the signer of the resulting chain.
+ */
+export interface EcosystemCreateBody {
+    founderPk: PublicKeyHex;
+    timestamp: number;
+    name: string;
+    description?: string;
+    lat?: number;
+    lng?: number;
+}
+export interface EcosystemCreateResponse {
+    publickey: PublicKeyHex;
+    blocks: BlockWire[];
+    /** true only for the very first ecosystem ever created on this server */
+    iscore: boolean;
+}
+/** Directory entry — metadata lives server-side, not on-chain. */
+export interface EcosystemListEntry {
+    publickey: PublicKeyHex;
+    name: string;
+    description: string | null;
+    lat: number | null;
+    lng: number | null;
+    iscore: boolean;
+    /** present only when the request carried lat/lng */
+    distanceKm?: number;
+}
+export type EcosystemListResponse = EcosystemListEntry[];
+/**
+ * Roles are re-carried onto every new block (see organic-money's
+ * EcosystemBlockchain), so the server only ever needs to look at each
+ * ecosystem's current last block to answer this — no full-chain replay.
+ * Public: ecosystem membership is already derivable by anyone from each
+ * ecosystem's own (public) chain — this just saves the client from having
+ * to query every ecosystem on the server one by one to find out.
+ */
+export interface MyEcosystemEntry {
+    publickey: PublicKeyHex;
+    name: string;
+    role: 'admin' | 'actor' | 'payer';
+}
+export type MyEcosystemsResponse = MyEcosystemEntry[];
+export interface EcosystemInfoResponse {
+    publickey: PublicKeyHex;
+    name: string;
+    description: string | null;
+    lat: number | null;
+    lng: number | null;
+    iscore: boolean;
+    blocks: BlockWire[];
+}
+export interface EcosystemMetaUpdateBody {
+    publickey: PublicKeyHex;
+    timestamp: number;
+    name?: string;
+    description?: string;
+    lat?: number;
+    lng?: number;
+}
+/**
+ * Generic ingress for any citizen-signed transaction targeting this
+ * ecosystem: PAY, ENGAGE, the role transactions (SETADMIN/SETACTOR/
+ * SETPAYER/UNSET*), and PAYERORDER. Same cross-verification duty as
+ * POST /tx/send (PROTOCOL.md §5.3), against the *signer's* own chain.
+ * A PAYERORDER is executed immediately: the resulting payment is routed
+ * exactly like a normal payment (queued for a citizen target, applied
+ * directly for an ecosystem target on this same server) — there is no
+ * separate "claim" step.
+ */
+export interface EcosystemTxBody {
+    tx: TxWire;
+}
+/** Manual only (Phase 2) — no scheduled/automatic distribution. */
+export interface EcosystemDistributeBody {
+    publickey: PublicKeyHex;
+    timestamp: number;
+}
+export interface ValidationListEntry {
+    pk: PublicKeyHex;
+    name: string;
+    requestedAt: string;
+}
+export type ValidationListResponse = ValidationListEntry[];
+/** The candidate's not-yet-validated chain, for the admin's device to locally call validateAccount(). */
+export interface ValidationDetailResponse {
+    name: string;
+    blocks: BlockWire[];
+}
+export interface ValidationStatusResponse {
+    status: MembershipStatus;
+}
+/**
+ * block is the InitializationBlock the admin already signed locally with
+ * their own key (requireBlockAuth already proves that signature). The
+ * server's own job is the part signature-proof alone can't give it: check
+ * the signer is *currently* one of the core ecosystem's admins.
+ */
+export interface ValidationApproveBody {
+    publickey: PublicKeyHex;
+    block: BlockWire;
+}
+export interface ValidationRejectBody {
+    publickey: PublicKeyHex;
+    timestamp: number;
+    reason?: string;
+}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { PROTOCOL_VERSION, TxType, isTxWire, isBlockWire, type IntDate, type UnitId, type PackedUnitIds, type PublicKeyHex, type SignatureHex, type TxWire, type BlockWire, } from './wire.js';
+export { PROTOCOL_VERSION, TxType, BlockType, isTxWire, isBlockWire, type IntDate, type UnitId, type PackedUnitIds, type PublicKeyHex, type SignatureHex, type TxWire, type BlockWire, } from './wire.js';
 export { InvalidServerUrlError, normalizeServerUrl, type Identity, type Contact, type ContactType, } from './identity.js';
 export { QR_VERSION, QrError, UnsupportedQrVersionError, InvalidQrError, encodeContactQr, encodeOfflineTxQr, encodeValidationQr, encodePaperQr, decodeQr, type QrType, type DecodedQr, type ContactQrPayload, type OfflineTxQrPayload, type ValidationQrPayload, type PaperQrPayload, } from './qr.js';
-export type { ApiError, ApiErrorCode, InfoResponse, ServerListEntry, ServersResponse, RegisterBody, RegisterResponse, LoginBody, LoginResponse, SaveBlockBody, SignBlockBody, PasswordChangeBody, TxSendBody, TxListResponse, TxVerifyBody, TxVerifyStatus, TxVerifyResponse, PapersCashBody, IsCashedResponse, } from './api.js';
+export type { ApiError, ApiErrorCode, MembershipStatus, InfoResponse, ServerListEntry, ServersResponse, RegisterBody, RegisterResponse, LoginBody, LoginResponse, SaveBlockBody, SignBlockBody, PasswordChangeBody, TxSendBody, TxListResponse, TxVerifyBody, TxVerifyStatus, TxVerifyResponse, PapersCashBody, IsCashedResponse, EcosystemCreateBody, EcosystemCreateResponse, EcosystemListEntry, EcosystemListResponse, MyEcosystemEntry, MyEcosystemsResponse, EcosystemInfoResponse, EcosystemMetaUpdateBody, EcosystemTxBody, EcosystemDistributeBody, ValidationListEntry, ValidationListResponse, ValidationDetailResponse, ValidationStatusResponse, ValidationApproveBody, ValidationRejectBody, } from './api.js';

package/dist/index.js

@@ -1,3 +1,3 @@
-export { PROTOCOL_VERSION, TxType, isTxWire, isBlockWire, } from './wire.js';
+export { PROTOCOL_VERSION, TxType, BlockType, isTxWire, isBlockWire, } from './wire.js';
 export { InvalidServerUrlError, normalizeServerUrl, } from './identity.js';
 export { QR_VERSION, QrError, UnsupportedQrVersionError, InvalidQrError, encodeContactQr, encodeOfflineTxQr, encodeValidationQr, encodePaperQr, decodeQr, } from './qr.js';

package/dist/wire.d.ts

@@ -21,6 +21,20 @@ export declare enum TxType {
     PAYERORDER = 12,
     EARN = 13
 }
+/**
+ * Block types (see PROTOCOL.md §2.2). Mirrors organic-money's BLOCKTYPE —
+ * this is the block's own `t` field, not to be confused with TxType above.
+ * CITIZEN/CITIZENBIRTH/CITIZENINIT carry economic experience (`e` on
+ * BlockWire); the ECOSYSTEM* kinds don't.
+ */
+export declare enum BlockType {
+    CITIZEN = 1,
+    ECOSYSTEM = 2,
+    CITIZENBIRTH = 3,
+    CITIZENINIT = 4,
+    ECOSYSTEMBIRTH = 5,
+    ECOSYSTEMINIT = 6
+}
 /** Date as a YYYYMMDD integer, e.g. 20260719. */
 export type IntDate = number;
 /**
@@ -47,6 +61,14 @@ export type SignatureHex = string;
  * A transaction in wire format (short field names for compactness).
  * Field meanings: v=version, d=date, t=type, p=target, s=signer,
  * m=money ids, i=invest ids, h=signature.
+ *
+ * Ecosystem-related types (see PROTOCOL.md §3) carry extra fields, all part
+ * of the signed preimage (not cosmetic metadata):
+ *   q — ratio (SETACTOR) or spending cap, -1 = unlimited (SETPAYER)
+ *   e — target ecosystem's public key (SETADMIN/SETACTOR/SETPAYER/
+ *       UNSETADMIN/UNSETACTOR/UNSETPAYER/PAYERORDER)
+ *   x — EARN only: signature of the PayerOrder it fulfills, present only
+ *       when produced by order() (absent for distributeSalary()/earn())
  */
 export interface TxWire {
     v: number;
@@ -57,13 +79,20 @@ export interface TxWire {
     m: PackedUnitIds;
     i: PackedUnitIds;
     h: SignatureHex;
+    q?: number;
+    e?: PublicKeyHex;
+    x?: SignatureHex;
 }
 /**
  * A sealed (or open) block in wire format.
  * Field meanings: v=version, d=closedate, p=previous block signature,
  * s=signer, m=available money at seal time, i=available invests,
- * t=total (economic experience), r=merkle root, h=block signature,
- * x=transactions.
+ * t=block type (see BlockType — NOT a total, despite the letter), r=merkle
+ * root, h=block signature, x=transactions.
+ *
+ * e = cumulative economic experience, present only when `t` is a citizen
+ * block type (CITIZEN/CITIZENBIRTH/CITIZENINIT) — ecosystem blocks have no
+ * experience at all.
  */
 export interface BlockWire {
     v: number;
@@ -72,12 +101,13 @@ export interface BlockWire {
     s: PublicKeyHex;
     m: PackedUnitIds;
     i: PackedUnitIds;
-    t: number;
+    t: BlockType;
     r: string;
     h: SignatureHex;
     x: TxWire[];
+    e?: number;
 }
-/** Structural check that an unknown value is a well-formed TxWire. */
+/** Structural check that an unknown value is a well-formed TxWire, including its type-specific fields. */
 export declare function isTxWire(o: unknown): o is TxWire;
 /** Structural check that an unknown value is a well-formed BlockWire. */
 export declare function isBlockWire(o: unknown): o is BlockWire;

package/dist/wire.js

@@ -22,14 +22,35 @@ export var TxType;
     TxType[TxType["PAYERORDER"] = 12] = "PAYERORDER";
     TxType[TxType["EARN"] = 13] = "EARN";
 })(TxType || (TxType = {}));
+/**
+ * Block types (see PROTOCOL.md §2.2). Mirrors organic-money's BLOCKTYPE —
+ * this is the block's own `t` field, not to be confused with TxType above.
+ * CITIZEN/CITIZENBIRTH/CITIZENINIT carry economic experience (`e` on
+ * BlockWire); the ECOSYSTEM* kinds don't.
+ */
+export var BlockType;
+(function (BlockType) {
+    BlockType[BlockType["CITIZEN"] = 1] = "CITIZEN";
+    BlockType[BlockType["ECOSYSTEM"] = 2] = "ECOSYSTEM";
+    BlockType[BlockType["CITIZENBIRTH"] = 3] = "CITIZENBIRTH";
+    BlockType[BlockType["CITIZENINIT"] = 4] = "CITIZENINIT";
+    BlockType[BlockType["ECOSYSTEMBIRTH"] = 5] = "ECOSYSTEMBIRTH";
+    BlockType[BlockType["ECOSYSTEMINIT"] = 6] = "ECOSYSTEMINIT";
+})(BlockType || (BlockType = {}));
 const isHex = (s) => typeof s === 'string' && /^[0-9a-fA-F]*$/.test(s);
 const isPackedUnitIds = (s) => typeof s === 'string' && /^([A-Za-z0-9+/]{4})*([A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(s);
-/** Structural check that an unknown value is a well-formed TxWire. */
+/** Types requiring both q (ratio/cap) and e (target ecosystem). */
+const TX_TYPES_WITH_Q_AND_E = [TxType.SETACTOR, TxType.SETPAYER];
+/** Types requiring e (target ecosystem) alone. */
+const TX_TYPES_WITH_E_ONLY = [
+    TxType.SETADMIN, TxType.UNSETADMIN, TxType.UNSETACTOR, TxType.UNSETPAYER, TxType.PAYERORDER,
+];
+/** Structural check that an unknown value is a well-formed TxWire, including its type-specific fields. */
 export function isTxWire(o) {
     if (typeof o !== 'object' || o === null)
         return false;
     const t = o;
-    return (typeof t.v === 'number' &&
+    if (!(typeof t.v === 'number' &&
         typeof t.d === 'number' &&
         Number.isInteger(t.d) &&
         typeof t.t === 'number' &&
@@ -39,22 +60,42 @@ export function isTxWire(o) {
         isHex(t.s) &&
         isPackedUnitIds(t.m) &&
         isPackedUnitIds(t.i) &&
-        isHex(t.h));
+        isHex(t.h)))
+        return false;
+    const type = t.t;
+    if (TX_TYPES_WITH_Q_AND_E.includes(type)) {
+        return typeof t.q === 'number' && isHex(t.e) && t.x === undefined;
+    }
+    if (TX_TYPES_WITH_E_ONLY.includes(type)) {
+        return t.q === undefined && isHex(t.e) && t.x === undefined;
+    }
+    if (type === TxType.EARN) {
+        return t.q === undefined && t.e === undefined && (t.x === undefined || isHex(t.x));
+    }
+    // INIT/CREATE/PAY/ENGAGE/PAPER: none of q/e/x apply.
+    return t.q === undefined && t.e === undefined && t.x === undefined;
 }
+/** Block types carrying economic experience (`e`) — citizen blocks only. */
+const BLOCK_TYPES_WITH_EXPERIENCE = [BlockType.CITIZEN, BlockType.CITIZENBIRTH, BlockType.CITIZENINIT];
 /** Structural check that an unknown value is a well-formed BlockWire. */
 export function isBlockWire(o) {
     if (typeof o !== 'object' || o === null)
         return false;
     const b = o;
-    return (typeof b.v === 'number' &&
+    if (!(typeof b.v === 'number' &&
         typeof b.d === 'number' &&
         isHex(b.p) &&
         isHex(b.s) &&
         isPackedUnitIds(b.m) &&
         isPackedUnitIds(b.i) &&
         typeof b.t === 'number' &&
+        b.t >= BlockType.CITIZEN &&
+        b.t <= BlockType.ECOSYSTEMINIT &&
         isHex(b.r) &&
         isHex(b.h) &&
         Array.isArray(b.x) &&
-        b.x.every(isTxWire));
+        b.x.every(isTxWire)))
+        return false;
+    const hasExperience = BLOCK_TYPES_WITH_EXPERIENCE.includes(b.t);
+    return hasExperience ? typeof b.e === 'number' : b.e === undefined;
 }

package/package.json

@@ -1,48 +1,48 @@
-{
-  "name": "organic-protocol",
-  "version": "0.2.0",
-  "description": "The shared protocol of the Organic Economy: wire formats, QR codes and API contracts, verified by the TypeScript compiler. Companion of organic-money.",
-  "keywords": [
-    "organic-economy",
-    "organic-money",
-    "protocol",
-    "qr"
-  ],
-  "license": "MIT",
-  "author": "suipotryot",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/OrganicEconomy/organic-protocol.git"
-  },
-  "bugs": {
-    "url": "https://github.com/OrganicEconomy/organic-protocol/issues"
-  },
-  "homepage": "https://github.com/OrganicEconomy/organic-protocol#readme",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "PROTOCOL.md"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "test": "mocha",
-    "prepublishOnly": "npm run build && npm test"
-  },
-  "devDependencies": {
-    "@types/chai": "^5.0.1",
-    "@types/mocha": "^10.0.10",
-    "@types/node": "^24.0.0",
-    "chai": "^5.1.2",
-    "mocha": "^11.0.1",
-    "tsx": "^4.19.2",
-    "typescript": "^5.7.2"
-  }
-}
+{
+  "name": "organic-protocol",
+  "version": "0.3.0",
+  "description": "The shared protocol of the Organic Economy: wire formats, QR codes and API contracts, verified by the TypeScript compiler. Companion of organic-money.",
+  "keywords": [
+    "organic-economy",
+    "organic-money",
+    "protocol",
+    "qr"
+  ],
+  "license": "MIT",
+  "author": "suipotryot",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OrganicEconomy/organic-protocol.git"
+  },
+  "bugs": {
+    "url": "https://github.com/OrganicEconomy/organic-protocol/issues"
+  },
+  "homepage": "https://github.com/OrganicEconomy/organic-protocol#readme",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "PROTOCOL.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "mocha",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/chai": "^5.0.1",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^24.0.0",
+    "chai": "^5.1.2",
+    "mocha": "^11.0.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}