{
  "swagger": "2.0",
  "info": {
    "title": "google/api/http.proto",
    "version": "version not set"
  },
  "tags": [
    {
      "name": "MpcWalletService"
    }
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/v1/dkg/initiate": {
      "post": {
        "summary": "Initiates a new Distributed Key Generation (DKG) session across threshold nodes.",
        "operationId": "MpcWalletService_InitiateDkg",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/v1InitiateDkgResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/v1InitiateDkgRequest"
            }
          }
        ],
        "tags": [
          "MpcWalletService"
        ]
      }
    },
    "/v1/dkg/shares": {
      "post": {
        "summary": "Executes a round of polynomial commitment / share exchange during DKG.",
        "operationId": "MpcWalletService_ExchangeDkgShares",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/v1DkgShareExchangeResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/v1DkgShareExchangeRequest"
            }
          }
        ],
        "tags": [
          "MpcWalletService"
        ]
      }
    },
    "/v1/key-material/provision": {
      "post": {
        "summary": "Provisions or attests Mesh-owned provider-backed key material for a\nVaultCore-governed key allocation.",
        "operationId": "MpcWalletService_ProvisionKeyMaterial",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/v1ProvisionKeyMaterialResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/v1ProvisionKeyMaterialRequest"
            }
          }
        ],
        "tags": [
          "MpcWalletService"
        ]
      }
    },
    "/v1/sessions/resume": {
      "post": {
        "summary": "Resumes a previously paused or escalated session using a checkpoint token.",
        "operationId": "MpcWalletService_ResumeSession",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/v1ResumeSessionResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/v1ResumeSessionRequest"
            }
          }
        ],
        "tags": [
          "MpcWalletService"
        ]
      }
    },
    "/v1/signing/initiate": {
      "post": {
        "summary": "Initiates a threshold signature ceremony for a transaction intent.",
        "operationId": "MpcWalletService_InitiateSigning",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/v1InitiateSigningResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/v1InitiateSigningRequest"
            }
          }
        ],
        "tags": [
          "MpcWalletService"
        ]
      }
    },
    "/v1/signing/share": {
      "post": {
        "summary": "Submits partial signature shares to reconstruct the final signature.",
        "operationId": "MpcWalletService_SubmitSignatureShare",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/v1SignatureShareResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/v1SignatureShareRequest"
            }
          }
        ],
        "tags": [
          "MpcWalletService"
        ]
      }
    }
  },
  "definitions": {
    "protobufAny": {
      "type": "object",
      "properties": {
        "@type": {
          "type": "string"
        }
      },
      "additionalProperties": {}
    },
    "rpcStatus": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        },
        "details": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/protobufAny"
          }
        }
      }
    },
    "v1ApprovalMode": {
      "type": "string",
      "enum": [
        "APPROVAL_MODE_UNSPECIFIED",
        "DIRECT_ALLOWED",
        "HUMAN_REQUIRED"
      ],
      "default": "APPROVAL_MODE_UNSPECIFIED"
    },
    "v1ClientVersionInfo": {
      "type": "object",
      "properties": {
        "client_name": {
          "type": "string"
        },
        "client_version": {
          "type": "string"
        },
        "contract_version": {
          "type": "string"
        }
      }
    },
    "v1DiagnosticReceipt": {
      "type": "object",
      "properties": {
        "receipt_id": {
          "type": "string"
        },
        "state": {
          "$ref": "#/definitions/v1ReceiptState"
        },
        "approval_mode": {
          "$ref": "#/definitions/v1ApprovalMode"
        },
        "reason_code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "correlation_id": {
          "type": "string"
        },
        "session_id": {
          "type": "string"
        },
        "contract_version": {
          "type": "string"
        },
        "client_name": {
          "type": "string"
        },
        "client_version": {
          "type": "string"
        },
        "epoch": {
          "type": "string",
          "format": "int64"
        },
        "checkpoint_id": {
          "type": "string"
        },
        "resumable": {
          "type": "boolean"
        },
        "keystore_type": {
          "$ref": "#/definitions/v1KeystoreType"
        },
        "backend_route": {
          "type": "string"
        },
        "request_id": {
          "type": "string"
        }
      }
    },
    "v1DkgShareExchangeRequest": {
      "type": "object",
      "properties": {
        "session_id": {
          "type": "string"
        },
        "sender_node_id": {
          "type": "integer",
          "format": "int32"
        },
        "recipient_node_id": {
          "type": "integer",
          "format": "int32"
        },
        "encrypted_share": {
          "type": "string",
          "format": "byte",
          "description": "In M0 local simulation mode this can carry raw share bytes."
        },
        "commitments": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "byte"
          },
          "description": "Feldman VSS commitments for the threshold ceremony."
        },
        "context": {
          "$ref": "#/definitions/v1OrchestrationContext"
        }
      }
    },
    "v1DkgShareExchangeResponse": {
      "type": "object",
      "properties": {
        "session_id": {
          "type": "string"
        },
        "verified": {
          "type": "boolean"
        },
        "error_message": {
          "type": "string"
        },
        "receipt": {
          "$ref": "#/definitions/v1DiagnosticReceipt"
        },
        "checkpoint": {
          "$ref": "#/definitions/v1SessionCheckpoint"
        }
      }
    },
    "v1InitiateDkgRequest": {
      "type": "object",
      "properties": {
        "session_id": {
          "type": "string"
        },
        "threshold": {
          "type": "integer",
          "format": "int32"
        },
        "total_nodes": {
          "type": "integer",
          "format": "int32"
        },
        "derivation": {
          "$ref": "#/definitions/v1ThresholdDerivation"
        },
        "context": {
          "$ref": "#/definitions/v1OrchestrationContext"
        }
      }
    },
    "v1InitiateDkgResponse": {
      "type": "object",
      "properties": {
        "session_id": {
          "type": "string"
        },
        "state": {
          "$ref": "#/definitions/v1ReceiptState"
        },
        "epoch": {
          "type": "string",
          "format": "int64"
        },
        "receipt": {
          "$ref": "#/definitions/v1DiagnosticReceipt"
        },
        "checkpoint": {
          "$ref": "#/definitions/v1SessionCheckpoint"
        }
      }
    },
    "v1InitiateSigningRequest": {
      "type": "object",
      "properties": {
        "transaction_intent_id": {
          "type": "string",
          "description": "Upstream signing intent reference owned by VaultCore/WalletKit. Mesh uses\nit for idempotency, audit linkage, and signing_session_id derivation; it is\nnot a blockchain transaction hash and is not generated by Mesh."
        },
        "wallet_id": {
          "type": "string"
        },
        "derivation": {
          "$ref": "#/definitions/v1ThresholdDerivation"
        },
        "message_hash": {
          "type": "string",
          "format": "byte"
        },
        "policy_approval_token": {
          "type": "string",
          "format": "byte",
          "description": "Opaque upstream approval evidence. Mesh treats this as execution evidence\nwhen approval_mode says governance has already been applied; Mesh does not\nevaluate business-policy semantics from this payload."
        },
        "human_approval_witness": {
          "type": "string",
          "format": "byte"
        },
        "approval_mode": {
          "$ref": "#/definitions/v1ApprovalMode",
          "description": "Upstream execution constraint decided by VaultCore/PolicyKit/WalletKit.\nMesh enforces pause/resume behavior and receipt state from this value but\ndoes not decide whether a customer transaction needs approval."
        },
        "context": {
          "$ref": "#/definitions/v1OrchestrationContext"
        },
        "keystore_type": {
          "$ref": "#/definitions/v1KeystoreType"
        },
        "test_directive": {
          "$ref": "#/definitions/v1TestDirective",
          "description": "Explicit M0-only override for deterministic local testing. Must not carry business-policy semantics."
        },
        "vaultcore_signer_authorization": {
          "$ref": "#/definitions/v1VaultCoreSignerAuthorization",
          "description": "VaultCore-issued signer authorization for HSM-backed keystore signing.\nVaultCore authorizes signer/key use; Mesh resolves provider execution\ndetails from governed signer bindings. Required when keystore_type is\nKEYSTORE_TYPE_HSM_PKCS11."
        }
      }
    },
    "v1InitiateSigningResponse": {
      "type": "object",
      "properties": {
        "signing_session_id": {
          "type": "string"
        },
        "state": {
          "$ref": "#/definitions/v1ReceiptState"
        },
        "epoch": {
          "type": "string",
          "format": "int64"
        },
        "receipt": {
          "$ref": "#/definitions/v1DiagnosticReceipt"
        },
        "checkpoint": {
          "$ref": "#/definitions/v1SessionCheckpoint"
        },
        "keystore_signature": {
          "type": "string",
          "format": "byte",
          "description": "Provider-backed signature bytes when a keystore signing request completes\nsynchronously, for example KEYSTORE_TYPE_HSM_PKCS11. Empty for denials,\npending MPC ceremonies, and flows that complete via SubmitSignatureShare."
        }
      }
    },
    "v1KeystoreType": {
      "type": "string",
      "enum": [
        "KEYSTORE_TYPE_UNSPECIFIED",
        "KEYSTORE_TYPE_MPC_THRESHOLD",
        "KEYSTORE_TYPE_MULTISIG_EVM_SAFE",
        "KEYSTORE_TYPE_MPC_SEPIOR",
        "KEYSTORE_TYPE_MPC_FROST",
        "KEYSTORE_TYPE_HSM_PKCS11"
      ],
      "default": "KEYSTORE_TYPE_UNSPECIFIED",
      "description": " - KEYSTORE_TYPE_MPC_THRESHOLD: Generic threshold MPC signing. Deployment chooses whether this routes to a\nlocal simulator, Sepior, FROST, or another MPC implementation; callers do\nnot select a test backend through this enum.\n - KEYSTORE_TYPE_HSM_PKCS11: HSM signing through a PKCS#11 profile selected by a Mesh-governed signer\nbinding. Concrete HSM devices and local test surfaces are deployment\ndetails, not public keystore types."
    },
    "v1OrchestrationContext": {
      "type": "object",
      "properties": {
        "payload": {
          "type": "string",
          "format": "byte",
          "description": "Opaque payload from the upstream orchestrator. HSM signing authorization is\ncarried by InitiateSigningRequest.vaultcore_signer_authorization instead of\nthis field. MPC signing can leave this empty or carry future execution\nevidence. Transport adapters do not parse it."
        },
        "traceparent": {
          "type": "string",
          "description": "W3C traceparent header string for WORM audit traceability."
        },
        "correlation_id": {
          "type": "string",
          "description": "Correlation ID across the entire transaction lifecycle."
        },
        "client": {
          "$ref": "#/definitions/v1ClientVersionInfo",
          "description": "Client/runtime identity used for contract version traceability."
        },
        "request_id": {
          "type": "string",
          "description": "Customer-visible per-request support handle. Clients and servers must generate one when absent."
        }
      }
    },
    "v1ProvisionKeyMaterialRequest": {
      "type": "object",
      "properties": {
        "contract_version": {
          "type": "string"
        },
        "org_id": {
          "type": "string"
        },
        "service_identity": {
          "type": "string"
        },
        "key_reference_id": {
          "type": "string"
        },
        "signer_binding_intent_ref": {
          "type": "string"
        },
        "key_profile_id": {
          "type": "string"
        },
        "capability_family": {
          "type": "string"
        },
        "mechanism": {
          "type": "string"
        },
        "key_algorithm": {
          "type": "string"
        },
        "key_purpose": {
          "type": "string"
        },
        "backend_profile_id": {
          "type": "string"
        },
        "backend_profile_class": {
          "type": "string"
        },
        "environment": {
          "type": "string"
        },
        "idempotency_key": {
          "type": "string"
        },
        "correlation_id": {
          "type": "string"
        },
        "provisioning_intent_hash": {
          "type": "string"
        },
        "evidence_source": {
          "type": "string"
        },
        "requested_key_label": {
          "type": "string",
          "description": "Abstract governance label only. Mesh derives concrete provider selectors\nfrom governed backend profiles."
        },
        "context": {
          "$ref": "#/definitions/v1OrchestrationContext"
        }
      }
    },
    "v1ProvisionKeyMaterialResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "reason_code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "receipt_id": {
          "type": "string"
        },
        "public_key_pem": {
          "type": "string"
        },
        "public_key_fingerprint": {
          "type": "string"
        },
        "mechanism": {
          "type": "string"
        },
        "key_algorithm": {
          "type": "string"
        },
        "key_selector_evidence_ref": {
          "type": "string"
        },
        "backend_profile_id": {
          "type": "string"
        },
        "backend_profile_class": {
          "type": "string"
        },
        "environment": {
          "type": "string"
        },
        "provisioning_evidence_hash": {
          "type": "string"
        },
        "conflicting_fields": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "receipt": {
          "$ref": "#/definitions/v1DiagnosticReceipt"
        }
      }
    },
    "v1ReceiptState": {
      "type": "string",
      "enum": [
        "RECEIPT_STATE_UNSPECIFIED",
        "RECEIPT_STATE_ACCEPTED",
        "RECEIPT_STATE_DENIED",
        "RECEIPT_STATE_PENDING_HUMAN_APPROVAL",
        "RECEIPT_STATE_RESUMED",
        "RECEIPT_STATE_EXPIRED",
        "RECEIPT_STATE_REPLAY_REJECTED",
        "RECEIPT_STATE_REVOKED",
        "RECEIPT_STATE_BACKEND_COMPLETED",
        "RECEIPT_STATE_BACKEND_FAILED",
        "RECEIPT_STATE_UNSUPPORTED_CLIENT_CONTRACT_VERSION"
      ],
      "default": "RECEIPT_STATE_UNSPECIFIED"
    },
    "v1ResumeSessionRequest": {
      "type": "object",
      "properties": {
        "session_id": {
          "type": "string"
        },
        "resume_token": {
          "type": "string"
        },
        "context": {
          "$ref": "#/definitions/v1OrchestrationContext"
        },
        "human_approval_witness": {
          "type": "string",
          "format": "byte"
        }
      }
    },
    "v1ResumeSessionResponse": {
      "type": "object",
      "properties": {
        "session_id": {
          "type": "string"
        },
        "state": {
          "$ref": "#/definitions/v1ReceiptState"
        },
        "epoch": {
          "type": "string",
          "format": "int64"
        },
        "receipt": {
          "$ref": "#/definitions/v1DiagnosticReceipt"
        },
        "checkpoint": {
          "$ref": "#/definitions/v1SessionCheckpoint"
        }
      }
    },
    "v1SessionCheckpoint": {
      "type": "object",
      "properties": {
        "checkpoint_id": {
          "type": "string"
        },
        "epoch": {
          "type": "string",
          "format": "int64"
        },
        "created_at_epoch_ms": {
          "type": "string",
          "format": "int64"
        },
        "state": {
          "$ref": "#/definitions/v1ReceiptState"
        },
        "resume_token": {
          "type": "string"
        }
      }
    },
    "v1SignatureShareRequest": {
      "type": "object",
      "properties": {
        "signing_session_id": {
          "type": "string"
        },
        "node_id": {
          "type": "integer",
          "format": "int32"
        },
        "partial_signature": {
          "type": "string",
          "format": "byte"
        },
        "ephemeral_public_key": {
          "type": "string",
          "format": "byte"
        },
        "context": {
          "$ref": "#/definitions/v1OrchestrationContext"
        }
      }
    },
    "v1SignatureShareResponse": {
      "type": "object",
      "properties": {
        "signing_session_id": {
          "type": "string"
        },
        "is_complete": {
          "type": "boolean"
        },
        "full_signature": {
          "type": "string",
          "format": "byte"
        },
        "recovery_id": {
          "type": "string",
          "format": "byte"
        },
        "receipt": {
          "$ref": "#/definitions/v1DiagnosticReceipt"
        },
        "checkpoint": {
          "$ref": "#/definitions/v1SessionCheckpoint"
        }
      }
    },
    "v1TestDirective": {
      "type": "string",
      "enum": [
        "TEST_DIRECTIVE_UNSPECIFIED",
        "TEST_DIRECTIVE_FORCE_DENIED",
        "TEST_DIRECTIVE_FORCE_REVOKED",
        "TEST_DIRECTIVE_FORCE_EXPIRED",
        "TEST_DIRECTIVE_FORCE_BACKEND_FAILED"
      ],
      "default": "TEST_DIRECTIVE_UNSPECIFIED"
    },
    "v1ThresholdDerivation": {
      "type": "object",
      "properties": {
        "derivation_path": {
          "type": "string",
          "description": "BIP-32/44 derivation path (e.g., \"m/44'/60'/0'/0/0\")."
        },
        "curve": {
          "type": "string",
          "description": "Curve type (\"secp256k1\" or \"ed25519\")."
        },
        "network_id": {
          "type": "string",
          "description": "Optional chain ID or network identifier."
        }
      }
    },
    "v1VaultCoreSignerAuthorization": {
      "type": "object",
      "properties": {
        "schema_version": {
          "type": "string",
          "description": "Authorization envelope version. Current value:\n\"keystore-signing-reference.v1\"."
        },
        "key_reference_id": {
          "type": "string",
          "description": "VaultCore's stable key identity. Mesh uses this with\nvaultcore_signer_binding_id to resolve a governed signer binding."
        },
        "vaultcore_signer_binding_id": {
          "type": "string",
          "description": "VaultCore/Mesh signer-binding identity. Mesh resolves backend profile,\ntoken selector, and PKCS#11 key selector from this binding."
        },
        "issuer": {
          "type": "string",
          "description": "Expected issuer: \"vaultcore-signer-router\"."
        },
        "audience": {
          "type": "string",
          "description": "Expected audience: \"alloy-mesh-service\"."
        },
        "mechanism": {
          "type": "string",
          "description": "Requested PKCS#11 mechanism, e.g. \"CKM_ECDSA\"."
        },
        "key_control_evidence_hash": {
          "type": "string",
          "description": "Reference/hash for upstream key-control evidence. Mesh validates presence\nand format, carries it into audit context, and leaves business-policy\nsemantics to VaultCore/PolicyKit."
        },
        "approval_expires_at_epoch_ms": {
          "type": "string",
          "format": "int64",
          "description": "Epoch milliseconds after which Mesh must reject the authorization."
        }
      }
    }
  }
}