{ "openapi": "3.1.0", "info": { "title": "Tokenistry Tokenization Engine", "description": "The RWA business layer. It owns the authority key that holds every administrative role, turns requests into validated durable operations, signs them as ERC-2771 forward requests, and hands them to the Transaction Engine. It never pays gas.\n\nEvery mutation requires an `Idempotency-Key` header and returns an operation id immediately, before anything is signed.", "license": { "name": "LicenseRef-Tokenistry-Commercial", "identifier": "LicenseRef-Tokenistry-Commercial" }, "version": "1.0.0" }, "paths": { "/health": { "get": { "tags": [ "system" ], "summary": "Liveness. Answers as long as the process is up.", "operationId": "health", "responses": { "200": { "description": "Running" } } } }, "/ready": { "get": { "tags": [ "system" ], "summary": "Readiness. Fails while the database is unreachable.", "operationId": "ready", "responses": { "200": { "description": "Database reachable" } } } }, "/v1/compliance/lists": { "get": { "tags": [ "compliance" ], "summary": "Compliance lists this deployment knows about.", "operationId": "list_lists", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ComplianceListRecord" } } } } } } }, "post": { "tags": [ "compliance" ], "summary": "Create a compliance list.", "operationId": "create_list", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Required. A repeat returns the original operation.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateListBody" } } }, "required": true }, "responses": { "200": { "description": "The idempotency key already existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "202": { "description": "Operation queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Key reused with different parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "422": { "description": "Rejected against chain state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/v1/compliance/lists/{list_id}/permissions": { "post": { "tags": [ "compliance" ], "summary": "Set send/receive permission for one or many wallets in a list.", "operationId": "set_permissions", "parameters": [ { "name": "list_id", "in": "path", "description": "List id", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Required. A repeat returns the original operation.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionsBody" } } }, "required": true }, "responses": { "200": { "description": "The idempotency key already existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "202": { "description": "Operation queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Key reused with different parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "422": { "description": "Rejected against chain state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/v1/compliance/lists/{list_id}/retire": { "post": { "tags": [ "compliance" ], "summary": "Retire a list. Retired lists cannot be attached or edited.", "operationId": "retire_list", "parameters": [ { "name": "list_id", "in": "path", "description": "List id", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Required. A repeat returns the original operation.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriorityBody" } } }, "required": true }, "responses": { "200": { "description": "The idempotency key already existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "202": { "description": "Operation queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Key reused with different parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "422": { "description": "Rejected against chain state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/v1/compliance/roles": { "post": { "tags": [ "compliance" ], "summary": "Grant or revoke a registry role. Accepts TOKEN_ADMIN_ROLE:
and LIST_ADMIN_ROLE:.", "operationId": "registry_role", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Required. A repeat returns the original operation.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleBody" } } }, "required": true }, "responses": { "200": { "description": "The idempotency key already existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "202": { "description": "Operation queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Key reused with different parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "422": { "description": "Rejected against chain state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/v1/factory/roles": { "post": { "tags": [ "compliance" ], "summary": "Grant or revoke a role on the token factory.", "operationId": "factory_role", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Required. A repeat returns the original operation.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleBody" } } }, "required": true }, "responses": { "200": { "description": "The idempotency key already existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "202": { "description": "Operation queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Key reused with different parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "422": { "description": "Rejected against chain state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/v1/metrics": { "get": { "tags": [ "system" ], "summary": "Operation counts and the authority's nonce position.", "operationId": "metrics", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsDto" } } } } } } }, "/v1/operations": { "get": { "tags": [ "operations" ], "summary": "A page of operations, newest first. Cursor-paged.", "operationId": "list_operations", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/OperationStatus" } }, { "name": "token", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/OperationKind" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous page's `next_cursor`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationPage" } } } }, "400": { "description": "Malformed cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/v1/operations/{id}": { "get": { "tags": [ "operations" ], "summary": "One operation, including the exact parameters the authority signed.", "operationId": "get_operation", "parameters": [ { "name": "id", "in": "path", "description": "Operation id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationView" } } } }, "404": { "description": "Unknown operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/v1/tokens": { "get": { "tags": [ "tokens" ], "summary": "Tokens this deployment knows about, including ones not yet mined.", "operationId": "list_tokens", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TokenRecord" } } } } } } }, "post": { "tags": [ "tokens" ], "summary": "Deploy a token. The CREATE2 address comes back immediately, before it mines.", "operationId": "deploy_token", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Required. A repeat returns the original operation.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeployTokenBody" } } }, "required": true }, "responses": { "200": { "description": "The idempotency key already existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "202": { "description": "Operation queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Key reused with different parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "422": { "description": "Rejected against chain state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/v1/tokens/{token}": { "get": { "tags": [ "tokens" ], "summary": "Live token state, read from the chain rather than the local projection.", "operationId": "token_state", "parameters": [ { "name": "token", "in": "path", "description": "Token address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenState" } } } }, "502": { "description": "Chain unreachable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/v1/tokens/{token}/authority": { "get": { "tags": [ "tokens" ], "summary": "What the authority is permitted to do for this token.", "description": "One key holds every role; the contracts scope them per token, per list, or\nglobally. `can_attach_lists` is the one the factory does not grant on\ndeployment.", "operationId": "authority_access", "parameters": [ { "name": "token", "in": "path", "description": "Token address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorityAccess" } } } } } } }, "/v1/tokens/{token}/burn": { "post": { "tags": [ "tokens" ], "summary": "Destroy tokens held by a wallet, without its consent.", "operationId": "burn", "parameters": [ { "name": "token", "in": "path", "description": "Token address", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Required. A repeat returns the original operation.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmountBody" } } }, "required": true }, "responses": { "200": { "description": "The idempotency key already existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "202": { "description": "Operation queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Key reused with different parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "422": { "description": "Rejected against chain state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/v1/tokens/{token}/forced-transfer": { "post": { "tags": [ "tokens" ], "summary": "Move tokens between wallets without the holder's consent.", "operationId": "forced_transfer", "parameters": [ { "name": "token", "in": "path", "description": "Token address", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Required. A repeat returns the original operation.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForcedTransferBody" } } }, "required": true }, "responses": { "200": { "description": "The idempotency key already existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "202": { "description": "Operation queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Key reused with different parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "422": { "description": "Rejected against chain state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/v1/tokens/{token}/freeze": { "post": { "tags": [ "tokens" ], "summary": "Set the frozen amount. Absolute, as ERC-7943 defines it: zero lifts the freeze.", "operationId": "freeze", "parameters": [ { "name": "token", "in": "path", "description": "Token address", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Required. A repeat returns the original operation.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmountBody" } } }, "required": true }, "responses": { "200": { "description": "The idempotency key already existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "202": { "description": "Operation queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Key reused with different parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "422": { "description": "Rejected against chain state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/v1/tokens/{token}/holders/{wallet}": { "get": { "tags": [ "tokens" ], "summary": "A wallet's balance, frozen amount and compliance verdict.", "operationId": "holder_state", "parameters": [ { "name": "token", "in": "path", "description": "Token address", "required": true, "schema": { "type": "string" } }, { "name": "wallet", "in": "path", "description": "Holder address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HolderState" } } } } } } }, "/v1/tokens/{token}/lists": { "post": { "tags": [ "compliance" ], "summary": "Attach a compliance list to a token.", "operationId": "attach_list", "parameters": [ { "name": "token", "in": "path", "description": "Token address", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Required. A repeat returns the original operation.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachListBody" } } }, "required": true }, "responses": { "200": { "description": "The idempotency key already existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "202": { "description": "Operation queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Key reused with different parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "422": { "description": "Rejected against chain state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/v1/tokens/{token}/lists/{list_id}/detach": { "post": { "tags": [ "compliance" ], "summary": "Detach a list. Detaching every list makes transfers and mints fail closed.", "operationId": "detach_list", "parameters": [ { "name": "token", "in": "path", "description": "Token address", "required": true, "schema": { "type": "string" } }, { "name": "list_id", "in": "path", "description": "List id", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Required. A repeat returns the original operation.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriorityBody" } } }, "required": true }, "responses": { "200": { "description": "The idempotency key already existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "202": { "description": "Operation queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Key reused with different parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "422": { "description": "Rejected against chain state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/v1/tokens/{token}/mint": { "post": { "tags": [ "tokens" ], "summary": "Issue new supply to a wallet.", "operationId": "mint", "parameters": [ { "name": "token", "in": "path", "description": "Token address", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Required. A repeat returns the original operation.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmountBody" } } }, "required": true }, "responses": { "200": { "description": "The idempotency key already existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "202": { "description": "Operation queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Key reused with different parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "422": { "description": "Rejected against chain state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/v1/tokens/{token}/registry": { "post": { "tags": [ "tokens" ], "summary": "Repoint a token at another compliance registry.", "operationId": "set_registry", "parameters": [ { "name": "token", "in": "path", "description": "Token address", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Required. A repeat returns the original operation.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistryBody" } } }, "required": true }, "responses": { "200": { "description": "The idempotency key already existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "202": { "description": "Operation queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Key reused with different parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "422": { "description": "Rejected against chain state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/v1/tokens/{token}/roles": { "post": { "tags": [ "tokens" ], "summary": "Grant or revoke a role on a token.", "operationId": "token_role", "parameters": [ { "name": "token", "in": "path", "description": "Token address", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Required. A repeat returns the original operation.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleBody" } } }, "required": true }, "responses": { "200": { "description": "The idempotency key already existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "202": { "description": "Operation queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Key reused with different parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "422": { "description": "Rejected against chain state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } } }, "components": { "schemas": { "AcceptedResponse": { "allOf": [ { "$ref": "#/components/schemas/OperationView" }, { "type": "object", "required": [ "created" ], "properties": { "created": { "type": "boolean", "description": "False when this call matched an existing idempotency key." } } } ] }, "AmountBody": { "type": "object", "required": [ "account", "amount" ], "properties": { "account": { "type": "string" }, "amount": { "type": "string" }, "priority": { "$ref": "#/components/schemas/Priority" } } }, "ApiErrorBody": { "type": "object", "description": "The body every failed request returns.", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable code, e.g. `validation_error`.", "example": "validation_error" }, "message": { "type": "string" } } }, "AttachListBody": { "type": "object", "required": [ "list_id" ], "properties": { "list_id": { "type": "string" }, "priority": { "$ref": "#/components/schemas/Priority" } } }, "AuthorityAccess": { "type": "object", "description": "Live on-chain state for one wallet's position in one token.\nWhat the single authority key is permitted to do for one token.\n\nThe engine has one key, not one per token. These flags are the *roles* that\nkey holds, and the contracts scope them differently: `can_create_lists` is\nglobal to the registry, everything else is specific to this token.", "required": [ "authority", "token", "can_attach_lists", "can_create_lists", "can_mint", "can_burn", "can_freeze", "can_force_transfer" ], "properties": { "authority": { "type": "string" }, "can_attach_lists": { "type": "boolean", "description": "Registry `tokenAdminRole(token)`. The one role the factory does not\ngrant on deployment, so it starts false for a freshly deployed token." }, "can_burn": { "type": "boolean" }, "can_create_lists": { "type": "boolean", "description": "Registry `LIST_CREATOR_ROLE`, global rather than per token." }, "can_force_transfer": { "type": "boolean" }, "can_freeze": { "type": "boolean" }, "can_mint": { "type": "boolean" }, "token": { "type": "string" } } }, "ComplianceListRecord": { "type": "object", "description": "A compliance list this engine created.", "required": [ "list_id", "name", "registry", "chain_id", "retired", "created_at" ], "properties": { "chain_id": { "type": "integer", "format": "int64", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "list_id": { "type": "string" }, "name": { "type": "string" }, "registry": { "type": "string" }, "retired": { "type": "boolean" } } }, "CreateListBody": { "type": "object", "required": [ "name" ], "properties": { "label": { "type": [ "string", "null" ] }, "list_id": { "type": [ "string", "null" ], "description": "Explicit list id. Omit to derive one from `label`, or from `name`." }, "name": { "type": "string" }, "priority": { "$ref": "#/components/schemas/Priority" } } }, "DeployTokenBody": { "type": "object", "required": [ "name", "symbol", "decimals" ], "properties": { "admin": { "type": [ "string", "null" ], "description": "Receives every role on the new token. Defaults to the authority." }, "decimals": { "type": "integer", "format": "int32", "minimum": 0 }, "name": { "type": "string" }, "priority": { "$ref": "#/components/schemas/Priority" }, "registry": { "type": [ "string", "null" ], "description": "Compliance registry. Omit to use the factory's default." }, "salt": { "type": [ "string", "null" ], "description": "CREATE2 salt. Omit to derive one from the symbol." }, "symbol": { "type": "string" } } }, "ForcedTransferBody": { "type": "object", "required": [ "from", "to", "amount" ], "properties": { "amount": { "type": "string" }, "from": { "type": "string" }, "priority": { "$ref": "#/components/schemas/Priority" }, "to": { "type": "string" } } }, "HolderState": { "type": "object", "required": [ "token", "wallet", "balance", "frozen", "unfrozen", "can_send", "can_receive" ], "properties": { "balance": { "type": "string" }, "can_receive": { "type": "boolean" }, "can_send": { "type": "boolean" }, "frozen": { "type": "string" }, "token": { "type": "string" }, "unfrozen": { "type": "string" }, "wallet": { "type": "string" } } }, "MetricsDto": { "type": "object", "description": "Authority state and operation counts.", "required": [ "pending", "signed", "submitted", "confirmed", "reverted", "failed", "cancelled", "total", "re_signed", "authority", "chain_id", "forwarder", "registry", "factory", "pipeline_depth", "allocated_nonce" ], "properties": { "allocated_nonce": { "type": "integer", "format": "int64", "description": "The next nonce this service will hand out.", "minimum": 0 }, "authority": { "type": "string" }, "cancelled": { "type": "integer", "format": "int64", "minimum": 0 }, "chain_id": { "type": "integer", "format": "int64", "minimum": 0 }, "confirmed": { "type": "integer", "format": "int64", "minimum": 0 }, "factory": { "type": "string" }, "failed": { "type": "integer", "format": "int64", "minimum": 0 }, "forwarder": { "type": "string" }, "oldest_open_secs": { "type": [ "number", "null" ], "format": "double" }, "on_chain_nonce": { "type": [ "integer", "null" ], "format": "int64", "description": "The next nonce the forwarder will accept. Below `allocated_nonce` means\nsigned requests are still in flight; a gap that does not close is a\ncascade waiting to be repaired.", "minimum": 0 }, "pending": { "type": "integer", "format": "int64", "minimum": 0 }, "pipeline_depth": { "type": "integer", "format": "int32", "description": "How many operations may hold an unconfirmed forwarder nonce at once.", "minimum": 0 }, "re_signed": { "type": "integer", "format": "int64", "description": "Operations re-signed after a forwarder-nonce cascade.", "minimum": 0 }, "registry": { "type": "string" }, "reverted": { "type": "integer", "format": "int64", "minimum": 0 }, "signed": { "type": "integer", "format": "int64", "minimum": 0 }, "submitted": { "type": "integer", "format": "int64", "minimum": 0 }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "OperationKind": { "type": "string", "description": "Discriminant stored in the database, kept separate from the payload so the\ncolumn can be indexed and queried.", "enum": [ "DEPLOY_TOKEN", "MINT", "FORCED_BURN", "SET_FROZEN_TOKENS", "FORCED_TRANSFER", "SET_COMPLIANCE_REGISTRY", "GRANT_TOKEN_ROLE", "REVOKE_TOKEN_ROLE", "CREATE_LIST", "RETIRE_LIST", "SET_PERMISSIONS", "SET_PERMISSIONS_BATCH", "ATTACH_LIST", "DETACH_LIST", "GRANT_REGISTRY_ROLE", "REVOKE_REGISTRY_ROLE", "GRANT_FACTORY_ROLE", "REVOKE_FACTORY_ROLE" ] }, "OperationPage": { "type": "object", "required": [ "operations" ], "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Pass back as `cursor` for the next page. Absent when the list is complete." }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/OperationView" } } } }, "OperationParams": { "oneOf": [ { "type": "object", "required": [ "name", "symbol", "decimals", "admin", "registry", "salt", "predicted_address", "kind" ], "properties": { "admin": { "type": "string", "description": "Receives every role on the new token. Defaults to the authority." }, "decimals": { "type": "integer", "format": "int32", "minimum": 0 }, "kind": { "type": "string", "enum": [ "DEPLOY_TOKEN" ] }, "name": { "type": "string" }, "predicted_address": { "type": "string", "description": "Address the deployment is expected to produce, recorded up front." }, "registry": { "type": "string", "description": "Compliance registry for the new token. Zero uses the factory default." }, "salt": { "type": "string", "description": "CREATE2 salt; combined with the deployer to give a stable address." }, "symbol": { "type": "string" } } }, { "type": "object", "required": [ "token", "to", "amount", "kind" ], "properties": { "amount": { "type": "string" }, "kind": { "type": "string", "enum": [ "MINT" ] }, "to": { "type": "string" }, "token": { "type": "string" } } }, { "type": "object", "required": [ "token", "from", "amount", "kind" ], "properties": { "amount": { "type": "string" }, "from": { "type": "string" }, "kind": { "type": "string", "enum": [ "FORCED_BURN" ] }, "token": { "type": "string" } } }, { "type": "object", "required": [ "token", "account", "amount", "kind" ], "properties": { "account": { "type": "string" }, "amount": { "type": "string", "description": "Absolute frozen amount, not a delta. May exceed the balance." }, "kind": { "type": "string", "enum": [ "SET_FROZEN_TOKENS" ] }, "token": { "type": "string" } } }, { "type": "object", "required": [ "token", "from", "to", "amount", "kind" ], "properties": { "amount": { "type": "string" }, "from": { "type": "string" }, "kind": { "type": "string", "enum": [ "FORCED_TRANSFER" ] }, "to": { "type": "string" }, "token": { "type": "string" } } }, { "type": "object", "required": [ "token", "registry", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "SET_COMPLIANCE_REGISTRY" ] }, "registry": { "type": "string" }, "token": { "type": "string" } } }, { "type": "object", "required": [ "token", "role", "account", "kind" ], "properties": { "account": { "type": "string" }, "kind": { "type": "string", "enum": [ "GRANT_TOKEN_ROLE" ] }, "role": { "type": "string" }, "token": { "type": "string" } } }, { "type": "object", "required": [ "token", "role", "account", "kind" ], "properties": { "account": { "type": "string" }, "kind": { "type": "string", "enum": [ "REVOKE_TOKEN_ROLE" ] }, "role": { "type": "string" }, "token": { "type": "string" } } }, { "type": "object", "required": [ "list_id", "name", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "CREATE_LIST" ] }, "list_id": { "type": "string" }, "name": { "type": "string" } } }, { "type": "object", "required": [ "list_id", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "RETIRE_LIST" ] }, "list_id": { "type": "string" } } }, { "type": "object", "required": [ "list_id", "account", "permissions", "kind" ], "properties": { "account": { "type": "string" }, "kind": { "type": "string", "enum": [ "SET_PERMISSIONS" ] }, "list_id": { "type": "string" }, "permissions": { "type": "integer", "format": "int32", "minimum": 0 } } }, { "type": "object", "required": [ "list_id", "entries", "kind" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionEntry" } }, "kind": { "type": "string", "enum": [ "SET_PERMISSIONS_BATCH" ] }, "list_id": { "type": "string" } } }, { "type": "object", "required": [ "token", "list_id", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "ATTACH_LIST" ] }, "list_id": { "type": "string" }, "token": { "type": "string" } } }, { "type": "object", "required": [ "token", "list_id", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "DETACH_LIST" ] }, "list_id": { "type": "string" }, "token": { "type": "string" } } }, { "type": "object", "required": [ "role", "account", "kind" ], "properties": { "account": { "type": "string" }, "kind": { "type": "string", "enum": [ "GRANT_REGISTRY_ROLE" ] }, "role": { "type": "string" } } }, { "type": "object", "required": [ "role", "account", "kind" ], "properties": { "account": { "type": "string" }, "kind": { "type": "string", "enum": [ "REVOKE_REGISTRY_ROLE" ] }, "role": { "type": "string" } } }, { "type": "object", "required": [ "role", "account", "kind" ], "properties": { "account": { "type": "string" }, "kind": { "type": "string", "enum": [ "GRANT_FACTORY_ROLE" ] }, "role": { "type": "string" } } }, { "type": "object", "required": [ "role", "account", "kind" ], "properties": { "account": { "type": "string" }, "kind": { "type": "string", "enum": [ "REVOKE_FACTORY_ROLE" ] }, "role": { "type": "string" } } } ], "description": "The typed parameters of every supported operation.\n\nThis enum is the complete list of what the authority can be asked to sign.\nCalldata is always derived from it through generated bindings, so an\noperation can never carry hand-rolled ABI bytes." }, "OperationStatus": { "type": "string", "description": "Lifecycle of an operation.", "enum": [ "PENDING", "SIGNED", "SUBMITTED", "CONFIRMED", "REVERTED", "FAILED", "CANCELLED" ] }, "OperationView": { "type": "object", "required": [ "id", "idempotency_key", "kind", "status", "priority", "params", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "failure_reason": { "type": [ "string", "null" ] }, "forwarder_nonce": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "id": { "type": "string", "format": "uuid" }, "idempotency_key": { "type": "string" }, "kind": { "$ref": "#/components/schemas/OperationKind" }, "list_id": { "type": [ "string", "null" ] }, "params": { "$ref": "#/components/schemas/OperationParams" }, "priority": { "$ref": "#/components/schemas/Priority" }, "status": { "$ref": "#/components/schemas/OperationStatus" }, "token": { "type": [ "string", "null" ] }, "transaction_hash": { "type": [ "string", "null" ] }, "transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "PermissionEntry": { "type": "object", "description": "One wallet's flags within a batch update.", "required": [ "wallet", "permissions" ], "properties": { "permissions": { "type": "integer", "format": "int32", "minimum": 0 }, "wallet": { "type": "string" } } }, "PermissionsBody": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionEntry" } }, "permissions": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "priority": { "$ref": "#/components/schemas/Priority" }, "wallets": { "type": "array", "items": { "type": "string" }, "description": "Wallets to update. Use `permissions` for a uniform value, or give each\nentry its own via `entries`." } } }, "Priority": { "type": "string", "description": "Execution urgency, passed through to the Transaction Engine.\n\nPriority is applied at *signing* time: a `CRITICAL` operation is picked up\nfirst and therefore receives the lower forwarder nonce, which is the only\npoint where urgency can actually change on-chain ordering for one authority.", "enum": [ "LOW", "NORMAL", "HIGH", "CRITICAL" ] }, "PriorityBody": { "type": "object", "properties": { "priority": { "$ref": "#/components/schemas/Priority" } } }, "RegistryBody": { "type": "object", "required": [ "registry" ], "properties": { "priority": { "$ref": "#/components/schemas/Priority" }, "registry": { "type": "string" } } }, "RoleBody": { "type": "object", "required": [ "role", "account", "grant" ], "properties": { "account": { "type": "string" }, "grant": { "type": "boolean", "description": "`true` grants, `false` revokes." }, "priority": { "$ref": "#/components/schemas/Priority" }, "role": { "type": "string", "description": "A well-known role name such as `MINTER_ROLE`, or a raw `bytes32`." } } }, "TokenRecord": { "type": "object", "description": "A token this engine issued.", "required": [ "address", "chain_id", "name", "symbol", "decimals", "registry", "deployed", "created_at" ], "properties": { "address": { "type": "string" }, "chain_id": { "type": "integer", "format": "int64", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "decimals": { "type": "integer", "format": "int32", "minimum": 0 }, "deployed": { "type": "boolean" }, "factory": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "registry": { "type": "string" }, "symbol": { "type": "string" } } }, "TokenState": { "type": "object", "description": "Live on-chain state for one token.", "required": [ "address", "name", "symbol", "decimals", "total_supply", "compliance_registry", "attached_lists" ], "properties": { "address": { "type": "string" }, "attached_lists": { "type": "array", "items": { "type": "string" } }, "compliance_registry": { "type": "string" }, "decimals": { "type": "integer", "format": "int32", "minimum": 0 }, "name": { "type": "string" }, "symbol": { "type": "string" }, "total_supply": { "type": "string" } } } } }, "tags": [ { "name": "tokens", "description": "Deploying tokens and moving balances" }, { "name": "compliance", "description": "Lists, wallet permissions and registry roles" }, { "name": "operations", "description": "The operation log" }, { "name": "system", "description": "Health and authority metrics" } ] }