@ottochain/sdk 2.4.0 → 2.5.0

package/dist/types/apps/privacy/index.d.ts

@@ -0,0 +1,328 @@
+/**
+ * Privacy Application — note-layer privacy primitives.
+ *
+ * Σ-protocol / ZK-backed fibers that carry real privacy on the OttoChain note
+ * layer. The flagship is `sigma-mixer`, a CDS OR-of-`dhtuple` ring mixer whose
+ * anonymity comes from a `sigma_verify` ring proof and whose double-spend safety
+ * comes from a witness-bound nullifier (`Nf = x_j·H`, `H` a NUMS base of unknown
+ * dlog w.r.t. `G`).
+ *
+ * The std-lib UTXO primitive is `shielded-note-pool` ({@link notePoolDef}): a
+ * fixed-denomination Tornado-style private asset pool over the `zk-shielded`
+ * Groth16 circuit. ⚠ UNAUDITED / TEST-ASSETS-ONLY (BN254 ~100-bit, single trusted
+ * relayer for root advancement) — see note-pool.ts.
+ *
+ * @example
+ * ```typescript
+ * import { getPrivacyDefinition, PRIVACY_DEFINITIONS, sigmaDdhRingOf, notePoolDef } from '@ottochain/sdk/apps/privacy';
+ *
+ * const mixerDef = getPrivacyDefinition('sigma-mixer');
+ * // Build a custom n-member OR-of-dhtuple proposition for an audited H:
+ * const prop = sigmaDdhRingOf('state.points', 'event.nullifier', G_HEX, H_HEX, 8);
+ * // Instantiate a shielded note-pool (pin the circuit vkey + denomination + relayer):
+ * const pool = notePoolDef({ vkey, depth: 8, denom: 100, poolPolicyRef, feeAsset, relayer });
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { mixerDdhRingDef, sigmaDdhRingOf, notePoolDef, NOTE_POOL_STATE, PV_LAYOUT, ZERO_WORD, pvField, pmtMembership, type NotePoolOptions, type ShieldedSpendPayload, type TransferPayload, type UnshieldPayload, type NoteMintedPayload } from './state-machines/index.js';
+import type { FiberAppDefinition } from '../../schema/fiber-app.js';
+export { mixerDdhRingDef, sigmaDdhRingOf, notePoolDef, NOTE_POOL_STATE, PV_LAYOUT, ZERO_WORD, pvField, pmtMembership, type NotePoolOptions, type ShieldedSpendPayload, type TransferPayload, type UnshieldPayload, type NoteMintedPayload, };
+/**
+ * A documented DEFAULT shielded-note-pool instance for the registry/lint surface, with PLACEHOLDER
+ * pin values (the real vkey comes from the SP1 `zk-shielded` toolchain; relayer/policy are
+ * deployment-specific). Downstream callers should build their own via {@link notePoolDef}; this
+ * instance exists so the privacy app group exposes a concrete `shielded-note-pool` definition.
+ * ⚠ UNAUDITED / TEST-ASSETS-ONLY.
+ */
+export declare const shieldedNotePoolDef: FiberAppDefinition<string, string>;
+/** All privacy (note-layer) state machine definitions. */
+export declare const PRIVACY_DEFINITIONS: {
+    readonly 'sigma-mixer': {
+        metadata: {
+            name: string;
+            app: string;
+            type: string;
+            version: string;
+            description: string;
+        };
+        createSchema: {
+            required: readonly ["mixerId", "denomination", "anonymityTarget"];
+            properties: {
+                mixerId: {
+                    type: "string";
+                    immutable: true;
+                    description: string;
+                };
+                denomination: {
+                    type: "integer";
+                    immutable: true;
+                    description: string;
+                };
+                nullifierBaseH: {
+                    type: "string";
+                    immutable: true;
+                    description: string;
+                };
+                anonymityTarget: {
+                    type: "integer";
+                    immutable: true;
+                    description: string;
+                };
+                points: {
+                    type: "array";
+                    items: {
+                        type: "string";
+                    };
+                    default: never[];
+                    description: string;
+                };
+                spentNullifiers: {
+                    type: "object";
+                    default: {};
+                    description: string;
+                };
+                depositCount: {
+                    type: "integer";
+                    default: number;
+                };
+                withdrawCount: {
+                    type: "integer";
+                    default: number;
+                };
+                status: {
+                    type: "string";
+                    default: string;
+                    description: string;
+                };
+            };
+        };
+        stateSchema: {
+            properties: {
+                mixerId: {
+                    type: "string";
+                    immutable: true;
+                };
+                denomination: {
+                    type: "integer";
+                    immutable: true;
+                };
+                nullifierBaseH: {
+                    type: "string";
+                    immutable: true;
+                };
+                anonymityTarget: {
+                    type: "integer";
+                    immutable: true;
+                };
+                points: {
+                    type: "array";
+                    items: {
+                        type: "string";
+                    };
+                    computed: true;
+                };
+                spentNullifiers: {
+                    type: "object";
+                    computed: true;
+                };
+                depositCount: {
+                    type: "integer";
+                    computed: true;
+                };
+                withdrawCount: {
+                    type: "integer";
+                    computed: true;
+                };
+                status: {
+                    type: "string";
+                    computed: true;
+                };
+            };
+        };
+        eventSchemas: {
+            deposit: {
+                description: string;
+            };
+            withdraw: {
+                description: string;
+            };
+        };
+        states: {
+            filling: {
+                id: string;
+                isFinal: false;
+                metadata: {
+                    label: string;
+                    description: string;
+                    category: "active";
+                };
+            };
+            open: {
+                id: string;
+                isFinal: false;
+                metadata: {
+                    label: string;
+                    description: string;
+                    category: "active";
+                };
+            };
+            drained: {
+                id: string;
+                isFinal: true;
+                metadata: {
+                    label: string;
+                    description: string;
+                    category: "terminal";
+                };
+            };
+        };
+        initialState: "filling";
+        transitions: ({
+            from: "filling";
+            to: "open";
+            eventName: "deposit";
+            guard: {
+                and: ({
+                    '===': ({
+                        '+': (number | {
+                            var: string;
+                        })[];
+                        var?: undefined;
+                    } | {
+                        var: string;
+                        '+'?: undefined;
+                    })[];
+                    '!!'?: undefined;
+                    none?: undefined;
+                } | {
+                    '!!': {
+                        var: string;
+                    }[];
+                    '==='?: undefined;
+                    none?: undefined;
+                } | {
+                    none: ({
+                        var: string;
+                        '==='?: undefined;
+                    } | {
+                        '===': {
+                            var: string;
+                        }[];
+                        var?: undefined;
+                    })[];
+                    '==='?: undefined;
+                    '!!'?: undefined;
+                })[];
+            };
+            effect: {
+                merge: ({
+                    var: string;
+                    points?: undefined;
+                    depositCount?: undefined;
+                    status?: undefined;
+                } | {
+                    points: {
+                        merge: ({
+                            var: string;
+                        } | {
+                            var: string;
+                        }[])[];
+                    };
+                    depositCount: {
+                        '+': (number | {
+                            var: string;
+                        })[];
+                    };
+                    status: string;
+                    var?: undefined;
+                })[];
+            };
+            dependencies: never[];
+        } | {
+            from: "filling";
+            to: "filling";
+            eventName: "deposit";
+            guard: {
+                and: ({
+                    '<': ({
+                        '+': (number | {
+                            var: string;
+                        })[];
+                        var?: undefined;
+                    } | {
+                        var: string;
+                        '+'?: undefined;
+                    })[];
+                    '!!'?: undefined;
+                    none?: undefined;
+                } | {
+                    '!!': {
+                        var: string;
+                    }[];
+                    '<'?: undefined;
+                    none?: undefined;
+                } | {
+                    none: ({
+                        var: string;
+                        '==='?: undefined;
+                    } | {
+                        '===': {
+                            var: string;
+                        }[];
+                        var?: undefined;
+                    })[];
+                    '<'?: undefined;
+                    '!!'?: undefined;
+                })[];
+            };
+            effect: {
+                merge: ({
+                    var: string;
+                    points?: undefined;
+                    depositCount?: undefined;
+                } | {
+                    points: {
+                        merge: ({
+                            var: string;
+                        } | {
+                            var: string;
+                        }[])[];
+                    };
+                    depositCount: {
+                        '+': (number | {
+                            var: string;
+                        })[];
+                    };
+                    var?: undefined;
+                })[];
+            };
+            dependencies: never[];
+        } | {
+            from: "open";
+            to: "drained";
+            eventName: "withdraw";
+            guard: {
+                and: import("../../schema/fiber-app.js").JsonLogicRule[];
+            };
+            effect: import("../../schema/fiber-app.js").JsonLogicRule;
+            dependencies: never[];
+        } | {
+            from: "open";
+            to: "open";
+            eventName: "withdraw";
+            guard: {
+                and: import("../../schema/fiber-app.js").JsonLogicRule[];
+            };
+            effect: import("../../schema/fiber-app.js").JsonLogicRule;
+            dependencies: never[];
+        })[];
+    };
+    readonly 'shielded-note-pool': FiberAppDefinition<string, string>;
+};
+export type PrivacyDefType = keyof typeof PRIVACY_DEFINITIONS;
+/**
+ * Get a privacy state machine definition by type.
+ * @param type - 'sigma-mixer' (default) | 'shielded-note-pool'.
+ */
+export declare function getPrivacyDefinition(type?: PrivacyDefType): FiberAppDefinition;

package/dist/types/apps/privacy/state-machines/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Privacy (note-layer) state machine definitions.
+ * Re-exports from TypeScript definition files.
+ */
+export { mixerDdhRingDef, sigmaDdhRingOf } from './mixer-ddhRing.js';
+export { notePoolDef, NOTE_POOL_STATE, PV_LAYOUT, ZERO_WORD, pvField, pmtMembership, type NotePoolOptions, type ShieldedSpendPayload, type TransferPayload, type UnshieldPayload, type NoteMintedPayload, } from './note-pool.js';

package/dist/types/apps/privacy/state-machines/mixer-ddhRing.d.ts

@@ -0,0 +1,337 @@
+import type { JsonLogicRule } from '../../../schema/fiber-app.js';
+/**
+ * sigma-mixer — a CDS OR-of-`dhtuple` Σ-protocol ring mixer.
+ *
+ * Anonymity comes from a Cramer–Damgård–Schoenmakers OR-proof over the deposited
+ * ring, verified by the `sigma_verify` JLVM opcode; double-spend safety comes
+ * from a WITNESS-BOUND nullifier carried as the shared DDH point of an
+ * OR-of-`dhtuple` proposition.
+ *
+ * Each ring branch is a DDH tuple `dhtuple(G, H, P_i, Nf)`. A satisfied dhtuple
+ * proves knowledge of one `x` with `P_i = x·G` AND `Nf = x·H` (the verifier uses
+ * a SINGLE shared response `z` for both coordinate reconstructions
+ * `a1 = z·G − e·P_i`, `a2 = z·H − e·Nf`). The OR uses the SAME
+ * `v = event.nullifier` in every branch, so it hides which branch while forcing
+ * `event.nullifier = x_j·H` for the one real branch `j`. With `H` a NUMS base of
+ * unknown dlog w.r.t. `G`, the map `x ↦ x·H` is injective, so the nullifier is
+ * cryptographically bound to the proven secret — closing the
+ * witness-unbound-nullifier double-spend hole an OR-of-`dlog` ring leaves open.
+ *
+ * Verified against `@constellation-network/metagraph-sdk-jlvm@1.8.0-rc.5`: the
+ * `sigma_verify` dhtuple operands are exactly `["type","g","h","u","v"]` (each a
+ * 64-byte G1 hex), the OR child challenges XOR to the node challenge, and the
+ * strong-FS root challenge folds the bound message. Array append uses `merge`
+ * (`merge([arr,[item]])` flattens one level == append). All operators used
+ * (`sigma_verify`, `has`, `set`, `none`, `cat`, `substr`, `merge`) are in
+ * KNOWN_OPERATORS.
+ *
+ * SCOPE: this base definition is CRYPTO + LIFECYCLE. Production custody
+ * (`_transferAsset` in on deposit / out on withdraw), a signer-bound deposit-auth
+ * clause, and a `mixerId`-prefixed bound message are layered on by a downstream
+ * specialization (see the §8 production-hardening note in the design doc).
+ */
+/**
+ * Emit the `or`-of-`dhtuple` proposition for an `n`-member ring, unrolling
+ * `{"var":"<pointsVar>.k"}` for `k in 0..n-1` as the `u` (commitment) of each
+ * branch, with `g = gHex`, `h = hHex` (literal 64-byte G1 hex) and a shared
+ * `v = {"var":"<nullifierVar>"}` across ALL branches.
+ *
+ * `n` is FIXED at definition time (the proposition shape is closed). `u` and `v`
+ * are `{"var":...}` map-node values that the evaluator resolves element-wise.
+ *
+ * @param pointsVar    state var holding the ordered ring points, e.g. `"state.points"`.
+ * @param nullifierVar event var holding the revealed nullifier, e.g. `"event.nullifier"`.
+ * @param gHex         the verifier generator `G=(1,2)` as 64-byte `0x` hex.
+ * @param hHex         the NUMS second base `H` as 64-byte `0x` hex (unknown dlog wrt G).
+ * @param n            ring size (number of unrolled branches).
+ */
+export declare function sigmaDdhRingOf(pointsVar: string, nullifierVar: string, gHex: string, hHex: string, n: number): JsonLogicRule;
+/**
+ * sigma-mixer fiber definition (pinned-ring v1, n=4).
+ *
+ * Trust model: PUBLIC. Anyone may deposit a ring point or submit a withdrawal.
+ * Privacy = a CDS OR-proof hides which of the n branches is being spent;
+ * anonymity set = exactly n (the ring size is public). Double-spend safety =
+ * the witness-bound nullifier + spent-set. Replay/front-run safety = the
+ * message-bound recipient.
+ */
+export declare const mixerDdhRingDef: {
+    metadata: {
+        name: string;
+        app: string;
+        type: string;
+        version: string;
+        description: string;
+    };
+    createSchema: {
+        required: readonly ["mixerId", "denomination", "anonymityTarget"];
+        properties: {
+            mixerId: {
+                type: "string";
+                immutable: true;
+                description: string;
+            };
+            denomination: {
+                type: "integer";
+                immutable: true;
+                description: string;
+            };
+            nullifierBaseH: {
+                type: "string";
+                immutable: true;
+                description: string;
+            };
+            anonymityTarget: {
+                type: "integer";
+                immutable: true;
+                description: string;
+            };
+            points: {
+                type: "array";
+                items: {
+                    type: "string";
+                };
+                default: never[];
+                description: string;
+            };
+            spentNullifiers: {
+                type: "object";
+                default: {};
+                description: string;
+            };
+            depositCount: {
+                type: "integer";
+                default: number;
+            };
+            withdrawCount: {
+                type: "integer";
+                default: number;
+            };
+            status: {
+                type: "string";
+                default: string;
+                description: string;
+            };
+        };
+    };
+    stateSchema: {
+        properties: {
+            mixerId: {
+                type: "string";
+                immutable: true;
+            };
+            denomination: {
+                type: "integer";
+                immutable: true;
+            };
+            nullifierBaseH: {
+                type: "string";
+                immutable: true;
+            };
+            anonymityTarget: {
+                type: "integer";
+                immutable: true;
+            };
+            points: {
+                type: "array";
+                items: {
+                    type: "string";
+                };
+                computed: true;
+            };
+            spentNullifiers: {
+                type: "object";
+                computed: true;
+            };
+            depositCount: {
+                type: "integer";
+                computed: true;
+            };
+            withdrawCount: {
+                type: "integer";
+                computed: true;
+            };
+            status: {
+                type: "string";
+                computed: true;
+            };
+        };
+    };
+    eventSchemas: {
+        deposit: {
+            description: string;
+        };
+        withdraw: {
+            description: string;
+        };
+    };
+    states: {
+        filling: {
+            id: string;
+            isFinal: false;
+            metadata: {
+                label: string;
+                description: string;
+                category: "active";
+            };
+        };
+        open: {
+            id: string;
+            isFinal: false;
+            metadata: {
+                label: string;
+                description: string;
+                category: "active";
+            };
+        };
+        drained: {
+            id: string;
+            isFinal: true;
+            metadata: {
+                label: string;
+                description: string;
+                category: "terminal";
+            };
+        };
+    };
+    initialState: "filling";
+    transitions: ({
+        from: "filling";
+        to: "open";
+        eventName: "deposit";
+        guard: {
+            and: ({
+                '===': ({
+                    '+': (number | {
+                        var: string;
+                    })[];
+                    var?: undefined;
+                } | {
+                    var: string;
+                    '+'?: undefined;
+                })[];
+                '!!'?: undefined;
+                none?: undefined;
+            } | {
+                '!!': {
+                    var: string;
+                }[];
+                '==='?: undefined;
+                none?: undefined;
+            } | {
+                none: ({
+                    var: string;
+                    '==='?: undefined;
+                } | {
+                    '===': {
+                        var: string;
+                    }[];
+                    var?: undefined;
+                })[];
+                '==='?: undefined;
+                '!!'?: undefined;
+            })[];
+        };
+        effect: {
+            merge: ({
+                var: string;
+                points?: undefined;
+                depositCount?: undefined;
+                status?: undefined;
+            } | {
+                points: {
+                    merge: ({
+                        var: string;
+                    } | {
+                        var: string;
+                    }[])[];
+                };
+                depositCount: {
+                    '+': (number | {
+                        var: string;
+                    })[];
+                };
+                status: string;
+                var?: undefined;
+            })[];
+        };
+        dependencies: never[];
+    } | {
+        from: "filling";
+        to: "filling";
+        eventName: "deposit";
+        guard: {
+            and: ({
+                '<': ({
+                    '+': (number | {
+                        var: string;
+                    })[];
+                    var?: undefined;
+                } | {
+                    var: string;
+                    '+'?: undefined;
+                })[];
+                '!!'?: undefined;
+                none?: undefined;
+            } | {
+                '!!': {
+                    var: string;
+                }[];
+                '<'?: undefined;
+                none?: undefined;
+            } | {
+                none: ({
+                    var: string;
+                    '==='?: undefined;
+                } | {
+                    '===': {
+                        var: string;
+                    }[];
+                    var?: undefined;
+                })[];
+                '<'?: undefined;
+                '!!'?: undefined;
+            })[];
+        };
+        effect: {
+            merge: ({
+                var: string;
+                points?: undefined;
+                depositCount?: undefined;
+            } | {
+                points: {
+                    merge: ({
+                        var: string;
+                    } | {
+                        var: string;
+                    }[])[];
+                };
+                depositCount: {
+                    '+': (number | {
+                        var: string;
+                    })[];
+                };
+                var?: undefined;
+            })[];
+        };
+        dependencies: never[];
+    } | {
+        from: "open";
+        to: "drained";
+        eventName: "withdraw";
+        guard: {
+            and: JsonLogicRule[];
+        };
+        effect: JsonLogicRule;
+        dependencies: never[];
+    } | {
+        from: "open";
+        to: "open";
+        eventName: "withdraw";
+        guard: {
+            and: JsonLogicRule[];
+        };
+        effect: JsonLogicRule;
+        dependencies: never[];
+    })[];
+};