@lemmaoracle/spec 0.0.1

package/README.md

@@ -0,0 +1,223 @@
+# @lemmaoracle/spec
+
+[![npm version](https://img.shields.io/npm/v/@lemmaoracle/spec)](https://www.npmjs.com/package/@lemmaoracle/spec)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.5-blue)](https://www.typescriptlang.org/)
+
+Authoritative interface types shared by Lemma SDK and Workers. This package contains TypeScript type definitions and OpenAPI specifications for the Lemma oracle system.
+
+## 📦 Installation
+
+```bash
+# Using npm
+npm install @lemmaoracle/spec
+
+# Using pnpm
+pnpm add @lemmaoracle/spec
+
+# Using yarn
+yarn add @lemmaoracle/spec
+```
+
+> **Note**: This package is a required dependency for `@lemmaoracle/sdk`.
+
+## 🎯 Overview
+
+`@lemmaoracle/spec` provides:
+
+- **TypeScript type definitions** for all Lemma API interfaces
+- **OpenAPI specification** (v2) for the Lemma REST API
+- **Shared interfaces** between SDK and backend services
+- **Immutable data types** with strict functional programming constraints
+
+## 📖 API Reference
+
+### Core Types
+
+#### Lemma Client
+
+```typescript
+export type LemmaClientConfig = Readonly<{
+  apiBase: string;
+  apiKey?: string;
+}>;
+
+export type LemmaClient = LemmaClientConfig &
+  Readonly<{
+    readonly fetcher?: typeof fetch;
+  }>;
+```
+
+#### Schema Metadata
+
+```typescript
+export type SchemaMeta = Readonly<{
+  id: string;
+  description?: string;
+  normalize: NormalizeArtifact;
+  [k: string]: unknown;
+}>;
+
+export type NormalizeArtifact = Readonly<{
+  artifact: {
+    readonly type: "ipfs" | "https";
+    readonly wasm: string;
+  };
+  hash: string;
+  abi?: {
+    readonly raw: Record<string, string>;
+    readonly norm: Record<string, string>;
+  };
+}>;
+```
+
+#### Circuit Metadata
+
+```typescript
+export type CircuitMeta = Readonly<{
+  circuitId: string;
+  schema: string;
+  description?: string;
+  inputs?: ReadonlyArray<string>;
+  verifier?: Readonly<{
+    type: "onchain" | "offchain";
+    address?: string;
+    chainId?: number;
+    [k: string]: unknown;
+  }>;
+  artifact?: Readonly<{ location: CircuitArtifactLocation }>;
+  [k: string]: unknown;
+}>;
+```
+
+#### Document Registration
+
+```typescript
+export type RegisterDocumentRequest = Readonly<{
+  schema: string;
+  docHash: string;
+  cid: string;
+  issuerId: string;
+  subjectId: string;
+  commitments: DocumentCommitments;
+  revocation: Revocation;
+  signature?: IssuerSignature;
+  hooks?: ReadonlyArray<OnchainHook>;
+}>;
+
+export type RegisterDocumentResponse = Readonly<{
+  status: "registered";
+  docHash: string;
+  [k: string]: unknown;
+}>;
+```
+
+#### Proof Submission
+
+```typescript
+export type SubmitProofRequest = Readonly<{
+  docHash: string;
+  circuitId: string;
+  proof: string;
+  inputs: ReadonlyArray<string>;
+  disclosure?: SelectiveDisclosure;
+  onchain?: boolean;
+}>;
+
+export type SubmitProofResponse = Readonly<{
+  status: "received" | "verified" | "onchain-verified" | "rejected";
+  verificationId: string;
+  [k: string]: unknown;
+}>;
+```
+
+#### Verified Attributes Query
+
+```typescript
+export type VerifiedAttributesQueryRequest = Readonly<{
+  query: string;
+  mode: "natural" | "structured";
+  attributes?: ReadonlyArray<Readonly<{ name: string; value: unknown }>>;
+  proof?: Readonly<{ required: boolean; type?: "zk-snark" | "opaque" }>;
+  targets?: Readonly<{ schemas?: ReadonlyArray<string> } & Record<string, unknown>>;
+}>;
+
+export type VerifiedAttributesQueryResponse = Readonly<{
+  results: ReadonlyArray<VerifiedAttributesQueryResponseItem>;
+}>;
+```
+
+### Commitment Schemes
+
+```typescript
+export type CommitmentScheme = "poseidon" | "poseidon2" | "rescue-prime" | "sha256-placeholder";
+
+export type DocumentCommitments = Readonly<{
+  scheme: CommitmentScheme;
+  root: string;
+  leaves: ReadonlyArray<string>;
+  randomness: string; // bytes32 hex - blinding factor for hiding property
+}>;
+```
+
+### Selective Disclosure
+
+```typescript
+export type SelectiveDisclosure = Readonly<{
+  format: "bbs+" | "opaque";
+  attributes: Readonly<Record<string, unknown>>;
+  proof: string;
+}>;
+```
+
+## 🔧 Development
+
+### Building from Source
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd lemma
+
+# Install dependencies
+pnpm install
+
+# Build the spec package
+cd packages/spec
+pnpm build
+```
+
+### OpenAPI Specification
+
+The package includes an OpenAPI v2 specification at `openapi.lemma.v2.json`. This file is automatically included in the npm package and can be used for:
+
+- API documentation generation
+- Client SDK generation in other languages
+- API validation and testing
+
+### TypeScript Strict Mode
+
+All types use `Readonly<>` and `ReadonlyArray<>` to enforce immutability, following Lemma's functional programming guidelines.
+
+## 📦 Publishing
+
+### Prerequisites
+1. npm account with access to `@lemmaoracle` organization
+2. Authentication configured (`npm login`)
+
+### Publishing Process
+
+```bash
+# Build the package
+pnpm build
+
+# Publish to npm
+npm publish --access public
+```
+
+### Version Management
+
+This package uses semantic versioning. When making breaking changes to types, increment the major version. The SDK depends on specific versions of this package, so coordinate updates accordingly.
+
+## 📄 License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,158 @@
+/**
+ * @lemmaoracle/spec — Authoritative interface types shared by SDK and Workers.
+ * MUST remain identical (or semver-compatible) across both repositories.
+ *
+ * Whitepaper reference: §2, §3, §4.
+ */
+export type LemmaClientConfig = Readonly<{
+    apiBase: string;
+    apiKey?: string;
+}>;
+export type LemmaClient = LemmaClientConfig & Readonly<{
+    readonly fetcher?: typeof fetch;
+}>;
+export type SchemaMeta = Readonly<{
+    id: string;
+    description?: string;
+    normalize: NormalizeArtifact;
+    [k: string]: unknown;
+}>;
+export type NormalizeArtifact = Readonly<{
+    artifact: {
+        readonly type: "ipfs" | "https";
+        readonly wasm: string;
+    };
+    hash: string;
+    abi?: {
+        readonly raw: Record<string, string>;
+        readonly norm: Record<string, string>;
+    };
+}>;
+export type CircuitArtifactLocation = Readonly<{
+    type: "ipfs" | "https";
+    wasm: string;
+    zkey: string;
+}>;
+export type CircuitMeta = Readonly<{
+    circuitId: string;
+    schema: string;
+    description?: string;
+    inputs?: ReadonlyArray<string>;
+    verifier?: Readonly<{
+        type: "onchain" | "offchain";
+        address?: string;
+        chainId?: number;
+        [k: string]: unknown;
+    }>;
+    artifact?: Readonly<{
+        location: CircuitArtifactLocation;
+    }>;
+    [k: string]: unknown;
+}>;
+export type GeneratorMeta = Readonly<{
+    generatorId: string;
+    schema: string;
+    description?: string;
+    language?: string;
+    source?: Readonly<{
+        type: "url";
+        uri: string;
+    }>;
+    inputsSpec?: Readonly<Record<string, unknown>>;
+    outputsSpec?: Readonly<Record<string, unknown>>;
+    [k: string]: unknown;
+}>;
+export type CommitmentScheme = "poseidon" | "poseidon2" | "rescue-prime" | "sha256-placeholder";
+export type DocumentCommitments = Readonly<{
+    scheme: CommitmentScheme;
+    root: string;
+    leaves: ReadonlyArray<string>;
+    randomness: string;
+}>;
+export type Revocation = Readonly<{
+    scheme?: string;
+    root: string;
+    [k: string]: unknown;
+}>;
+export type IssuerSignature = Readonly<{
+    format: "bbs+" | "opaque";
+    payload: string;
+    issuerId: string;
+}>;
+export type OnchainHook = Readonly<{
+    chainId: number;
+    address: string;
+    method: string;
+    mode?: "after-registry";
+    payload?: "registry-public-inputs";
+    [k: string]: unknown;
+}>;
+export type RegisterDocumentRequest = Readonly<{
+    schema: string;
+    docHash: string;
+    cid: string;
+    issuerId: string;
+    subjectId: string;
+    attributes?: Readonly<Record<string, unknown>>;
+    commitments: DocumentCommitments;
+    revocation: Revocation;
+    signature?: IssuerSignature;
+    hooks?: ReadonlyArray<OnchainHook>;
+}>;
+export type RegisterDocumentResponse = Readonly<{
+    status: "registered";
+    docHash: string;
+    [k: string]: unknown;
+}>;
+export type SelectiveDisclosure = Readonly<{
+    format: "bbs+" | "opaque";
+    attributes: Readonly<Record<string, unknown>>;
+    proof: string;
+}>;
+export type SubmitProofRequest = Readonly<{
+    docHash: string;
+    circuitId: string;
+    proof: string;
+    inputs: ReadonlyArray<string>;
+    disclosure?: SelectiveDisclosure;
+    onchain?: boolean;
+}>;
+export type SubmitProofResponse = Readonly<{
+    status: "received" | "verified" | "onchain-verified" | "rejected";
+    verificationId: string;
+    [k: string]: unknown;
+}>;
+export type VerifiedAttributesQueryRequest = Readonly<{
+    query: string;
+    mode: "natural" | "structured";
+    attributes?: ReadonlyArray<Readonly<{
+        name: string;
+        value: unknown;
+    }>>;
+    proof?: Readonly<{
+        required: boolean;
+        type?: "zk-snark" | "opaque";
+    }>;
+    targets?: Readonly<{
+        schemas?: ReadonlyArray<string>;
+    } & Record<string, unknown>>;
+}>;
+export type VerifiedAttributesQueryResponseItem = Readonly<{
+    docHash: string;
+    schema: string;
+    issuerId: string;
+    subjectId: string;
+    attributes: Readonly<Record<string, unknown>>;
+    proof?: Readonly<{
+        status?: string;
+        circuitId?: string;
+    } & Record<string, unknown>>;
+    disclosure?: SelectiveDisclosure;
+}>;
+export type VerifiedAttributesQueryResponse = Readonly<{
+    results: ReadonlyArray<VerifiedAttributesQueryResponseItem>;
+}>;
+export type ErrorResponse = Readonly<{
+    error: string;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * @lemmaoracle/spec — Authoritative interface types shared by SDK and Workers.
+ * MUST remain identical (or semver-compatible) across both repositories.
+ *
+ * Whitepaper reference: §2, §3, §4.
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/openapi.lemma.v2.json

@@ -0,0 +1,502 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Lemma v2 API",
+    "version": "0.1.0",
+    "description": "REST surface derived from the Lemma v2 whitepaper SDK interface (§3, §4)."
+  },
+  "servers": [{ "url": "http://localhost:8787" }],
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" }
+    },
+    "schemas": {
+      "ErrorResponse": {
+        "type": "object",
+        "properties": { "error": { "type": "string" } },
+        "required": ["error"],
+        "additionalProperties": false
+      },
+      "SchemaMeta": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string" },
+          "description": { "type": "string" }
+        },
+        "required": ["id"],
+        "additionalProperties": true
+      },
+      "CircuitArtifactLocation": {
+        "type": "object",
+        "properties": {
+          "type": { "type": "string", "enum": ["ipfs", "https"] },
+          "wasm": { "type": "string" },
+          "zkey": { "type": "string" }
+        },
+        "required": ["type", "wasm", "zkey"],
+        "additionalProperties": false
+      },
+      "CircuitMeta": {
+        "type": "object",
+        "properties": {
+          "circuitId": { "type": "string" },
+          "schema": { "type": "string" },
+          "description": { "type": "string" },
+          "inputs": { "type": "array", "items": { "type": "string" } },
+          "verifier": {
+            "type": "object",
+            "properties": {
+              "type": { "type": "string", "enum": ["onchain", "offchain"] },
+          "address": { "type": "string" },
+          "chainId": { "type": "integer" }
+        },
+        "required": ["type"],
+            "additionalProperties": true
+          },
+          "artifact": {
+            "type": "object",
+            "properties": {
+              "location": { "$ref": "#/components/schemas/CircuitArtifactLocation" }
+            },
+            "required": ["location"],
+            "additionalProperties": false
+          }
+        },
+        "required": ["circuitId", "schema"],
+        "additionalProperties": true
+      },
+      "GeneratorMeta": {
+        "type": "object",
+        "properties": {
+          "generatorId": { "type": "string" },
+          "schema": { "type": "string" },
+          "description": { "type": "string" },
+          "language": { "type": "string" },
+          "source": {
+            "type": "object",
+            "properties": {
+              "type": { "type": "string", "enum": ["url"] },
+              "uri": { "type": "string" }
+            },
+            "required": ["type", "uri"],
+            "additionalProperties": false
+          },
+          "inputsSpec": { "type": "object", "additionalProperties": true },
+          "outputsSpec": { "type": "object", "additionalProperties": true }
+        },
+        "required": ["generatorId", "schema"],
+        "additionalProperties": true
+      },
+      "DocumentCommitments": {
+        "type": "object",
+        "properties": {
+          "scheme": {
+            "type": "string",
+            "enum": ["poseidon", "poseidon2", "rescue-prime", "sha256-placeholder"]
+          },
+          "root": { "type": "string" },
+          "leaves": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "randomness": { "type": "string" }
+        },
+        "required": ["scheme", "root", "leaves", "randomness"],
+        "additionalProperties": false
+      },
+      "Revocation": {
+        "type": "object",
+        "properties": {
+          "scheme": { "type": "string" },
+          "root": { "type": "string" }
+        },
+        "required": ["root"],
+        "additionalProperties": true
+      },
+      "IssuerSignature": {
+        "type": "object",
+        "properties": {
+          "format": { "type": "string", "enum": ["bbs+", "opaque"] },
+          "payload": { "type": "string" },
+          "issuerId": { "type": "string" }
+        },
+        "required": ["format", "payload", "issuerId"],
+        "additionalProperties": false
+      },
+      "OnchainHook": {
+        "type": "object",
+        "properties": {
+          "chainId": { "type": "integer" },
+          "address": { "type": "string" },
+          "method": { "type": "string" },
+          "mode": { "type": "string", "enum": ["after-registry"] },
+          "payload": { "type": "string", "enum": ["registry-public-inputs"] }
+        },
+        "required": ["chainId", "address", "method"],
+        "additionalProperties": true
+      },
+      "RegisterDocumentRequest": {
+        "type": "object",
+        "properties": {
+          "schema": { "type": "string" },
+          "docHash": { "type": "string" },
+          "cid": { "type": "string" },
+          "issuerId": { "type": "string" },
+          "subjectId": { "type": "string" },
+          "commitments": { "$ref": "#/components/schemas/DocumentCommitments" },
+          "revocation": { "$ref": "#/components/schemas/Revocation" },
+          "signature": { "$ref": "#/components/schemas/IssuerSignature" },
+          "hooks": {
+            "type": "array",
+            "items": { "$ref": "#/components/schemas/OnchainHook" }
+          }
+        },
+        "required": [
+          "schema",
+          "docHash",
+          "cid",
+          "issuerId",
+          "subjectId",
+          "commitments",
+          "revocation"
+        ],
+        "additionalProperties": false
+      },
+      "RegisterDocumentResponse": {
+        "type": "object",
+        "properties": {
+          "status": { "type": "string", "enum": ["registered"] },
+          "docHash": { "type": "string" }
+        },
+        "required": ["status", "docHash"],
+        "additionalProperties": true
+      },
+      "SelectiveDisclosure": {
+        "type": "object",
+        "properties": {
+          "format": { "type": "string", "enum": ["bbs+", "opaque"] },
+          "attributes": { "type": "object", "additionalProperties": true },
+          "proof": { "type": "string" }
+        },
+        "required": ["format", "attributes", "proof"],
+        "additionalProperties": false
+      },
+      "SubmitProofRequest": {
+        "type": "object",
+        "properties": {
+          "docHash": { "type": "string" },
+          "circuitId": { "type": "string" },
+          "proof": { "type": "string" },
+          "inputs": { "type": "array", "items": { "type": "string" } },
+          "disclosure": { "$ref": "#/components/schemas/SelectiveDisclosure" },
+          "onchain": { "type": "boolean" }
+        },
+        "required": ["docHash", "circuitId", "proof", "inputs"],
+        "additionalProperties": false
+      },
+      "SubmitProofResponse": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": ["received", "verified", "onchain-verified", "rejected"]
+          },
+          "verificationId": { "type": "string" }
+        },
+        "required": ["status", "verificationId"],
+        "additionalProperties": true
+      },
+      "VerifiedAttributesQueryRequest": {
+        "type": "object",
+        "properties": {
+          "query": { "type": "string" },
+          "mode": { "type": "string", "enum": ["natural", "structured"] },
+          "proof": {
+            "type": "object",
+            "properties": {
+              "required": { "type": "boolean" },
+              "type": { "type": "string", "enum": ["zk-snark", "opaque"] }
+            },
+            "required": ["required"],
+            "additionalProperties": true
+          },
+          "targets": {
+            "type": "object",
+            "properties": { "schemas": { "type": "array", "items": { "type": "string" } } },
+            "additionalProperties": true
+          }
+        },
+        "required": ["query", "mode"],
+        "additionalProperties": false
+      },
+      "VerifiedAttributesQueryResponseItem": {
+        "type": "object",
+        "properties": {
+          "docHash": { "type": "string" },
+          "schema": { "type": "string" },
+          "issuerId": { "type": "string" },
+          "subjectId": { "type": "string" },
+          "attributes": { "type": "object", "additionalProperties": true },
+          "proof": {
+            "type": "object",
+            "properties": { "status": { "type": "string" }, "circuitId": { "type": "string" } },
+            "additionalProperties": true
+          },
+          "disclosure": { "$ref": "#/components/schemas/SelectiveDisclosure" }
+        },
+        "required": ["docHash", "schema", "issuerId", "subjectId", "attributes"],
+        "additionalProperties": true
+      },
+      "VerifiedAttributesQueryResponse": {
+        "type": "object",
+        "properties": {
+          "results": {
+            "type": "array",
+            "items": { "$ref": "#/components/schemas/VerifiedAttributesQueryResponseItem" }
+          }
+        },
+        "required": ["results"],
+        "additionalProperties": false
+      }
+    }
+  },
+  "security": [{ "ApiKeyAuth": [] }],
+  "paths": {
+    "/v1/health": {
+      "get": {
+        "security": [],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": { "ok": { "type": "boolean" } },
+                  "required": ["ok"]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/schemas": {
+      "post": {
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": { "schema": { "$ref": "#/components/schemas/SchemaMeta" } }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Registered",
+            "content": {
+              "application/json": { "schema": { "$ref": "#/components/schemas/SchemaMeta" } }
+            }
+          },
+          "400": {
+            "description": "Bad Request",
+            "content": {
+              "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
+            }
+          }
+        }
+      }
+    },
+    "/v1/schemas/{id}": {
+      "get": {
+        "parameters": [
+          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
+        ],
+        "responses": {
+          "200": {
+            "description": "Found",
+            "content": {
+              "application/json": { "schema": { "$ref": "#/components/schemas/SchemaMeta" } }
+            }
+          },
+          "404": {
+            "description": "Not Found",
+            "content": {
+              "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
+            }
+          }
+        }
+      }
+    },
+    "/v1/circuits": {
+      "post": {
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": { "schema": { "$ref": "#/components/schemas/CircuitMeta" } }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Registered",
+            "content": {
+              "application/json": { "schema": { "$ref": "#/components/schemas/CircuitMeta" } }
+            }
+          },
+          "400": {
+            "description": "Bad Request",
+            "content": {
+              "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
+            }
+          }
+        }
+      }
+    },
+    "/v1/circuits/{circuitId}": {
+      "get": {
+        "parameters": [
+          { "name": "circuitId", "in": "path", "required": true, "schema": { "type": "string" } }
+        ],
+        "responses": {
+          "200": {
+            "description": "Found",
+            "content": {
+              "application/json": { "schema": { "$ref": "#/components/schemas/CircuitMeta" } }
+            }
+          },
+          "404": {
+            "description": "Not Found",
+            "content": {
+              "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
+            }
+          }
+        }
+      }
+    },
+    "/v1/doc-generators": {
+      "post": {
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": { "schema": { "$ref": "#/components/schemas/GeneratorMeta" } }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Registered",
+            "content": {
+              "application/json": { "schema": { "$ref": "#/components/schemas/GeneratorMeta" } }
+            }
+          },
+          "400": {
+            "description": "Bad Request",
+            "content": {
+              "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
+            }
+          }
+        }
+      }
+    },
+    "/v1/doc-generators/{generatorId}": {
+      "get": {
+        "parameters": [
+          { "name": "generatorId", "in": "path", "required": true, "schema": { "type": "string" } }
+        ],
+        "responses": {
+          "200": {
+            "description": "Found",
+            "content": {
+              "application/json": { "schema": { "$ref": "#/components/schemas/GeneratorMeta" } }
+            }
+          },
+          "404": {
+            "description": "Not Found",
+            "content": {
+              "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
+            }
+          }
+        }
+      }
+    },
+    "/v1/documents": {
+      "post": {
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/RegisterDocumentRequest" }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Registered",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/RegisterDocumentResponse" }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request",
+            "content": {
+              "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
+            }
+          }
+        }
+      }
+    },
+    "/v1/proofs": {
+      "post": {
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": { "schema": { "$ref": "#/components/schemas/SubmitProofRequest" } }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Submitted",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/SubmitProofResponse" }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request",
+            "content": {
+              "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
+            }
+          }
+        }
+      }
+    },
+    "/v1/verified-attributes/query": {
+      "post": {
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/VerifiedAttributesQueryRequest" }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Results",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/VerifiedAttributesQueryResponse" }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request",
+            "content": {
+              "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@lemmaoracle/spec",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "openapi.lemma.v2.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint 'src/**/*.ts'",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
+    "eslint": "^9.39.3",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-functional": "^9.0.4",
+    "typescript": "^5.5.0",
+    "vitest": "^2.1.0"
+  }
+}