organic-protocol 0.1.1 → 0.2.0

package/PROTOCOL.md

@@ -22,7 +22,7 @@ The `url` is the server's **root** URL (no `/api`, no trailing slash), normalize
 
 ```json
 { "v": 1, "d": 20260719, "t": 3, "p": "<target pk>", "s": "<signer pk>",
-  "m": [20260719001], "i": [], "h": "<DER signature, hex>" }
+  "m": "BLeiCZk=", "i": "", "h": "<DER signature, hex>" }
 ```
 
 | Field | Long name | Content |
@@ -32,18 +32,22 @@ The `url` is the server's **root** URL (no `/api`, no trailing slash), normalize
 | `t` | type | transaction type (§3) |
 | `p` | target | recipient's public key |
 | `s` | signer | sender's public key |
-| `m` | money | money unit ids (`YYYYMMDDXXX`) |
-| `i` | invests | invest unit ids (`YYYYMMDD9XXX`) |
+| `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 ] }
+  "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.
+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
 

package/README.md

@@ -4,7 +4,7 @@
 
 This package carries the **shapes** that travel between Organic Economy instances: transaction and block wire formats, the versioned QR standard (`OM1:CT/TX/BR/PP`) with its encode/decode functions, and the DTOs of the `/api/v1` REST contract. It contains **no cryptography** — that lives in [`organic-money`](https://www.npmjs.com/package/organic-money).
 
-The [organic-webapp](https://github.com/GuziEconomy/organic-webapp) client and the [organic-webserver](https://github.com/GuziEconomy/organic-webserver) server both import this package, so any drift between what one sends and the other expects becomes a compile error instead of a silent bug. Third-party implementations should either import it or implement [PROTOCOL.md](PROTOCOL.md), which is the same standard in prose.
+The [organic-webapp](https://github.com/OrganicEconomy/organic-webapp) client and the [organic-webserver](https://github.com/OrganicEconomy/organic-webserver) server both import this package, so any drift between what one sends and the other expects becomes a compile error instead of a silent bug. Third-party implementations should either import it or implement [PROTOCOL.md](PROTOCOL.md), which is the same standard in prose.
 
 ```bash
 npm install organic-protocol

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { PROTOCOL_VERSION, TxType, isTxWire, isBlockWire, type IntDate, type UnitId, type PublicKeyHex, type SignatureHex, type TxWire, type BlockWire, } from './wire.js';
+export { PROTOCOL_VERSION, TxType, 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';

package/dist/wire.d.ts

@@ -29,6 +29,16 @@ export type IntDate = number;
  * The creation date is embedded in the id.
  */
 export type UnitId = number;
+/**
+ * Wire representation of a `UnitId[]`: each id packed into 5 big-endian
+ * bytes (comfortably covers every possible money/invest id), concatenated,
+ * then base64-encoded. An empty array is the empty string. A plain JSON
+ * number array costs 12 bytes per id (11-12 decimal digits + a separator)
+ * for ~5 bytes of actual information — this roughly halves the size of a
+ * transaction or block on the wire, which matters most for QR-encoded
+ * paper bills. Mirrors `packUnitIds`/`unpackUnitIds` in organic-money.
+ */
+export type PackedUnitIds = string;
 /** Compressed SECP256K1 public key, hex-encoded (33 bytes → 66 chars). */
 export type PublicKeyHex = string;
 /** DER-encoded SECP256K1 signature, hex-encoded. */
@@ -44,8 +54,8 @@ export interface TxWire {
     t: TxType;
     p: PublicKeyHex;
     s: PublicKeyHex;
-    m: UnitId[];
-    i: UnitId[];
+    m: PackedUnitIds;
+    i: PackedUnitIds;
     h: SignatureHex;
 }
 /**
@@ -60,8 +70,8 @@ export interface BlockWire {
     d: IntDate;
     p: string;
     s: PublicKeyHex;
-    m: UnitId[];
-    i: UnitId[];
+    m: PackedUnitIds;
+    i: PackedUnitIds;
     t: number;
     r: string;
     h: SignatureHex;

package/dist/wire.js

@@ -23,7 +23,7 @@ export var TxType;
     TxType[TxType["EARN"] = 13] = "EARN";
 })(TxType || (TxType = {}));
 const isHex = (s) => typeof s === 'string' && /^[0-9a-fA-F]*$/.test(s);
-const isUnitIdArray = (a) => Array.isArray(a) && a.every((n) => typeof n === 'number' && Number.isInteger(n));
+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. */
 export function isTxWire(o) {
     if (typeof o !== 'object' || o === null)
@@ -37,8 +37,8 @@ export function isTxWire(o) {
         t.t <= TxType.EARN &&
         isHex(t.p) &&
         isHex(t.s) &&
-        isUnitIdArray(t.m) &&
-        isUnitIdArray(t.i) &&
+        isPackedUnitIds(t.m) &&
+        isPackedUnitIds(t.i) &&
         isHex(t.h));
 }
 /** Structural check that an unknown value is a well-formed BlockWire. */
@@ -50,8 +50,8 @@ export function isBlockWire(o) {
         typeof b.d === 'number' &&
         isHex(b.p) &&
         isHex(b.s) &&
-        isUnitIdArray(b.m) &&
-        isUnitIdArray(b.i) &&
+        isPackedUnitIds(b.m) &&
+        isPackedUnitIds(b.i) &&
         typeof b.t === 'number' &&
         isHex(b.r) &&
         isHex(b.h) &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "organic-protocol",
-  "version": "0.1.1",
+  "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",
@@ -10,6 +10,14 @@
   ],
   "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",