{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "OpenAPI definition",
    "version" : "v0"
  },
  "servers" : [ {
    "url" : "https://api.uverify.io",
    "description" : "Generated server url"
  } ],
  "tags" : [ {
    "name" : "Transaction Management",
    "description" : "Endpoints for building and submitting UVerify certificate transactions to the Cardano blockchain."
  }, {
    "name" : "Connected Goods",
    "description" : "Extension endpoints for managing NFT-based connected physical goods on Cardano."
  }, {
    "name" : "Extensions",
    "description" : "Query which UVerify extensions are enabled on this instance."
  }, {
    "name" : "User State Management",
    "description" : "Endpoints for managing user states and performing user-related actions."
  }, {
    "name" : "Library",
    "description" : "Endpoints for managing on-chain Aiken/Plutus script deployments."
  }, {
    "name" : "Statistics",
    "description" : "Endpoints for retrieving certificate and transaction fee statistics."
  }, {
    "name" : "Certificate Verification",
    "description" : "Endpoints for retrieving and verifying certificates stored on the Cardano blockchain."
  } ],
  "paths" : {
    "/api/v1/user/state/action" : {
      "post" : {
        "tags" : [ "User State Management" ],
        "summary" : "Execute a user state action",
        "description" : "Executes a user state action based on the signed request created in the previous step. The backend prepares an unsigned transaction for the action, which must be signed and submitted by the user. Supported actions include:\n- **USER_INFO**: Execute a request to retrieve user information.\n- **INVALIDATE_STATE**: Execute a request to invalidate a specific user state. This will return an unsigned transaction to burn the state token, collect the UTXO locked in the contract, and send it (including ADA) to the user's wallet.\n- **OPT_OUT**: Execute a request to invalidate all states and claim back all locked UTXOs.\n\nThe unsigned transaction returned by this endpoint must be signed by the user using their wallet or submitted to the `/api/v1/transaction/submit` endpoint.",
        "operationId" : "executeStateAction",
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/ExecuteUserActionRequest"
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "200" : {
            "description" : "Action successfully executed",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ExecuteUserActionResponse"
                }
              }
            }
          },
          "500" : {
            "description" : "Internal server error",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          },
          "400" : {
            "description" : "Invalid request or unknown action type",
            "content" : {
              "application/json" : { }
            }
          }
        }
      }
    },
    "/api/v1/user/request/action" : {
      "post" : {
        "tags" : [ "User State Management" ],
        "summary" : "Create a user state action request",
        "description" : "Creates a request object for a specific user state action. The backend signs the request message, and the user must also sign the message to execute the action in the next step. Supported actions include:\n- **USER_INFO**: Retrieve user information based on the provided address.\n- **INVALIDATE_STATE**: Create a request to invalidate a specific user state. This will prepare an unsigned transaction to burn the state token, collect the UTXO locked in the contract, and send it (including ADA) to the user's wallet.\n- **OPT_OUT**: Create a request to invalidate all states and claim back all locked UTXOs.",
        "operationId" : "requestUserState",
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/UserActionRequest"
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "200" : {
            "description" : "Action request successfully created",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/UserActionResponse"
                }
              }
            }
          },
          "400" : {
            "description" : "Invalid request or unknown action type",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/UserActionResponse"
                }
              }
            }
          },
          "500" : {
            "description" : "Internal server error",
            "content" : {
              "*/*" : {
                "schema" : {
                  "$ref" : "#/components/schemas/UserActionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/transaction/submit" : {
      "post" : {
        "tags" : [ "Transaction Management" ],
        "summary" : "Submit a transaction",
        "description" : "Submits a transaction to the Cardano blockchain using the provided transaction data and witness set. Returns the result of the submission or a 500 status code in case of server errors.",
        "operationId" : "submitTransaction",
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/SubmitTransactionRequest"
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "200" : {
            "description" : "Transaction submitted successfully",
            "content" : {
              "application/json" : { }
            }
          },
          "500" : {
            "description" : "Internal server error",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/transaction/build" : {
      "post" : {
        "tags" : [ "Transaction Management" ],
        "summary" : "Build a transaction",
        "description" : "Builds a transaction for the Cardano blockchain based on the provided request. Supports the following transaction types:\n- **DEFAULT**: Submits UVerify certificates to the blockchain using the cheapest options. If no state is initialized, it forks a new state from the bootstrap datum with the best service fee conditions. If a user state exists with a valid transaction countdown and no service fee is required, it will be reused.\n- **BOOTSTRAP**: Initializes a new bootstrap token and datum for forking states. Requires a whitelisted credential to sign the transaction.\n- **INIT**: Init a new proxy script for UVerify certificate management.\n- **CUSTOM**: Allows the user to specify a bootstrap datum to fork or consume a state related to a specific bootstrap datum. This is useful for use cases requiring a 'partner datum' and may result in a different certificate UI on the client side.",
        "operationId" : "buildTransaction",
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/BuildTransactionRequest"
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "500" : {
            "description" : "Internal server error",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          },
          "200" : {
            "description" : "Transaction built successfully",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/BuildTransactionResponse"
                }
              }
            }
          },
          "400" : {
            "description" : "Invalid transaction type or request data",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/library/upgrade/proxy" : {
      "post" : {
        "tags" : [ "Library" ],
        "summary" : "Upgrade proxy contract",
        "description" : "Builds an unsigned Cardano transaction that upgrades the existing proxy script to a new version. The request body should contain the new script reference transaction hash.",
        "operationId" : "upgradeStateContract",
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "type" : "string"
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "500" : {
            "description" : "Internal server error",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          },
          "400" : {
            "description" : "Transaction build failed",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/BuildTransactionResponse"
                }
              }
            }
          },
          "200" : {
            "description" : "Unsigned upgrade transaction built successfully",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/BuildTransactionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/library/deploy/proxy" : {
      "post" : {
        "tags" : [ "Library" ],
        "summary" : "Deploy proxy contract",
        "description" : "Builds an unsigned Cardano transaction that deploys the UVerify proxy script on-chain. The returned transaction must be signed by the service wallet before submission.",
        "operationId" : "deployContracts",
        "responses" : {
          "200" : {
            "description" : "Unsigned deployment transaction built successfully",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/BuildTransactionResponse"
                }
              }
            }
          },
          "500" : {
            "description" : "Internal server error",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          },
          "400" : {
            "description" : "Transaction build failed",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/BuildTransactionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/extension/connected-goods/update/item" : {
      "post" : {
        "tags" : [ "Connected Goods" ],
        "summary" : "Update a connected good",
        "description" : "Builds and returns an unsigned Cardano transaction that updates the social-hub data of a previously claimed connected good. The transaction must be signed by the owner wallet before submission.",
        "operationId" : "updateItem",
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/ClaimUpdateConnectedGoodsRequest"
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "200" : {
            "description" : "Unsigned update transaction built successfully",
            "content" : {
              "application/json" : {
                "schema" : {
                  "type" : "string",
                  "description" : "Hex-encoded CBOR unsigned transaction"
                }
              }
            }
          },
          "500" : {
            "description" : "Internal server error",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          },
          "400" : {
            "description" : "Invalid request, wrong password, or invalid user address",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/extension/connected-goods/mint/batch" : {
      "post" : {
        "tags" : [ "Connected Goods" ],
        "summary" : "Returns an unsigned transaction to mint a batch of connected goods",
        "description" : "Returns an unsigned transaction to mint a batch of connected goods.\nThe transaction needs to be signed by a user wallet.\nThe request contains a list of connected goods, each with an asset name and a unique claiming password.\n",
        "operationId" : "mintConnectedGoods",
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/MintConnectedGoodsRequest"
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "200" : {
            "description" : "transaction successfully created",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/BuildTransactionResponse"
                }
              }
            }
          },
          "500" : {
            "description" : "Internal server error",
            "content" : {
              "*/*" : {
                "schema" : {
                  "$ref" : "#/components/schemas/MintConnectedGoodsResponse"
                }
              }
            }
          },
          "400" : {
            "description" : "Invalid request or unknown action type",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/BuildTransactionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/extension/connected-goods/claim/item" : {
      "post" : {
        "tags" : [ "Connected Goods" ],
        "summary" : "Claim a connected good",
        "description" : "Builds and returns an unsigned Cardano transaction that claims ownership of a connected good using the item's password. The transaction must be signed by the user wallet before submission.",
        "operationId" : "claimItem",
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/ClaimUpdateConnectedGoodsRequest"
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "200" : {
            "description" : "Unsigned claim transaction built successfully",
            "content" : {
              "application/json" : {
                "schema" : {
                  "type" : "string",
                  "description" : "Hex-encoded CBOR unsigned transaction"
                }
              }
            }
          },
          "500" : {
            "description" : "Internal server error",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          },
          "400" : {
            "description" : "Invalid request, wrong password, or invalid user address",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/verify/{hash}" : {
      "get" : {
        "tags" : [ "Certificate Verification" ],
        "summary" : "Retrieve certificates by data hash",
        "description" : "Retrieves a list of certificates associated with the provided data hash. The `hash` is the data hash (e.g., SHA-256 or SHA-512) of the file or text that was certified.",
        "operationId" : "getCertificateByHash",
        "parameters" : [ {
          "name" : "hash",
          "in" : "path",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "Certificates retrieved successfully",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/CertificateResponse"
                }
              }
            }
          },
          "404" : {
            "description" : "No certificates found for the provided hash",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "array",
                  "items" : {
                    "$ref" : "#/components/schemas/CertificateResponse"
                  }
                }
              }
            }
          },
          "500" : {
            "description" : "Internal server error",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "array",
                  "items" : {
                    "$ref" : "#/components/schemas/CertificateResponse"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/verify/by-transaction-hash/{transactionHash}/{dataHash}" : {
      "get" : {
        "tags" : [ "Certificate Verification" ],
        "summary" : "Retrieve a certificate by transaction hash and data hash",
        "description" : "Retrieves a certificate associated with the provided Cardano blockchain transaction hash and data hash.\nThe `transactionHash` is the hash of the Cardano blockchain transaction where the certificate data has been stored,\nand the `dataHash` is the hash of the certified file or text.",
        "operationId" : "getCertificateByTransactionHash",
        "parameters" : [ {
          "name" : "transactionHash",
          "in" : "path",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "dataHash",
          "in" : "path",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "Certificate retrieved successfully",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/CertificateResponse"
                }
              }
            }
          },
          "500" : {
            "description" : "Internal server error",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          },
          "404" : {
            "description" : "No certificate found for the provided transaction hash and data hash",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/user/bootstrap-access" : {
      "get" : {
        "tags" : [ "User State Management" ],
        "summary" : "Check if a user has access to a specific bootstrap token",
        "description" : "Returns true if the user has an active state derived from the given bootstrap token, false otherwise.",
        "operationId" : "checkBootstrapAccess",
        "parameters" : [ {
          "name" : "address",
          "in" : "query",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "tokenName",
          "in" : "query",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "OK",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "boolean"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/txs/{txHash}/scripts" : {
      "get" : {
        "tags" : [ "Transaction Service" ],
        "operationId" : "getTxContractDetails",
        "parameters" : [ {
          "name" : "txHash",
          "in" : "path",
          "required" : true,
          "schema" : {
            "pattern" : "^[0-9a-fA-F]{64}$",
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "OK",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "array",
                  "items" : {
                    "$ref" : "#/components/schemas/TxContractDetails"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/txs/{txHash}/redeemers" : {
      "get" : {
        "tags" : [ "Transaction Service" ],
        "operationId" : "getTxRedeemers",
        "parameters" : [ {
          "name" : "txHash",
          "in" : "path",
          "required" : true,
          "schema" : {
            "pattern" : "^[0-9a-fA-F]{64}$",
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "OK",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "array",
                  "items" : {
                    "$ref" : "#/components/schemas/TxRedeemerDto"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/transaction/confirm/{hash}" : {
      "get" : {
        "tags" : [ "Transaction Management" ],
        "summary" : "Check if a transaction has been confirmed on-chain",
        "description" : "Returns 200 if the transaction is confirmed on the Cardano blockchain, 404 if it is not yet confirmed.",
        "operationId" : "confirmTransaction",
        "parameters" : [ {
          "name" : "hash",
          "in" : "path",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "Transaction confirmed on-chain",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          },
          "500" : {
            "description" : "Internal server error",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          },
          "404" : {
            "description" : "Transaction not yet confirmed",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/statistic/tx-fees" : {
      "get" : {
        "tags" : [ "Statistics" ],
        "summary" : "Total transaction fees",
        "description" : "Returns the accumulated UVerify transaction fees in lovelace (1 ADA = 1 000 000 lovelace).",
        "operationId" : "getTransactionFees",
        "responses" : {
          "500" : {
            "description" : "Internal server error",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          },
          "200" : {
            "description" : "Fee amount retrieved successfully",
            "content" : {
              "application/json" : {
                "schema" : {
                  "type" : "integer",
                  "description" : "Total fees in lovelace",
                  "format" : "int64"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/statistic/certificate/by-category" : {
      "get" : {
        "tags" : [ "Statistics" ],
        "summary" : "Certificate counts by category",
        "description" : "Returns the total number of UVerify certificates grouped by template/category.",
        "operationId" : "getTransactionStatistics",
        "responses" : {
          "200" : {
            "description" : "Statistics retrieved successfully",
            "content" : {
              "application/json" : {
                "schema" : {
                  "type" : "object",
                  "description" : "Map of category name to certificate count"
                }
              }
            }
          },
          "500" : {
            "description" : "Internal server error",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/scripts/{scriptHash}" : {
      "get" : {
        "tags" : [ "Script Service" ],
        "operationId" : "getScriptByHash",
        "parameters" : [ {
          "name" : "scriptHash",
          "in" : "path",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "OK",
            "content" : {
              "*/*" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ScriptDto"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/scripts/{scriptHash}/json" : {
      "get" : {
        "tags" : [ "Script Service" ],
        "operationId" : "getScriptJsonByHash",
        "parameters" : [ {
          "name" : "scriptHash",
          "in" : "path",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "OK",
            "content" : {
              "*/*" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ScriptJsonDto"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/scripts/{scriptHash}/details" : {
      "get" : {
        "tags" : [ "Script Service" ],
        "operationId" : "getScriptDetailsByHash",
        "parameters" : [ {
          "name" : "scriptHash",
          "in" : "path",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "OK",
            "content" : {
              "*/*" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ScriptDetailDto"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/scripts/{scriptHash}/cbor" : {
      "get" : {
        "tags" : [ "Script Service" ],
        "operationId" : "getScriptCborByHash",
        "parameters" : [ {
          "name" : "scriptHash",
          "in" : "path",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "OK",
            "content" : {
              "*/*" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ScriptCborDto"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/scripts/datum/{datumHash}" : {
      "get" : {
        "tags" : [ "Script Service" ],
        "operationId" : "getDatumJsonByHash",
        "parameters" : [ {
          "name" : "datumHash",
          "in" : "path",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "OK",
            "content" : {
              "*/*" : {
                "schema" : {
                  "$ref" : "#/components/schemas/JsonNode"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/scripts/datum/{datumHash}/cbor" : {
      "get" : {
        "tags" : [ "Script Service" ],
        "operationId" : "getDatumCborByHash",
        "parameters" : [ {
          "name" : "datumHash",
          "in" : "path",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "OK",
            "content" : {
              "*/*" : {
                "schema" : {
                  "$ref" : "#/components/schemas/JsonNode"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/library/undeploy/{transactionHash}/{outputIndex}" : {
      "get" : {
        "tags" : [ "Library" ],
        "summary" : "Undeploy a specific contract",
        "description" : "Builds an unsigned Cardano transaction that removes the script UTxO identified by the given transaction hash and output index.",
        "operationId" : "undeployContract",
        "parameters" : [ {
          "name" : "transactionHash",
          "in" : "path",
          "description" : "Cardano transaction hash of the UTxO containing the deployed script",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "outputIndex",
          "in" : "path",
          "description" : "Output index of the UTxO within the transaction",
          "required" : true,
          "schema" : {
            "type" : "integer",
            "format" : "int32"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "Unsigned undeployment transaction built successfully",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/BuildTransactionResponse"
                }
              }
            }
          },
          "500" : {
            "description" : "Internal server error",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          },
          "400" : {
            "description" : "Transaction build failed",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/BuildTransactionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/library/undeploy/unused" : {
      "get" : {
        "tags" : [ "Library" ],
        "summary" : "Undeploy unused contracts",
        "description" : "Builds an unsigned Cardano transaction that reclaims all on-chain script UTxOs that are no longer referenced by active certificates.",
        "operationId" : "undeployUnusedContracts",
        "responses" : {
          "200" : {
            "description" : "Unsigned undeployment transaction built successfully",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/BuildTransactionResponse"
                }
              }
            }
          },
          "500" : {
            "description" : "Internal server error",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          },
          "400" : {
            "description" : "Transaction build failed",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/BuildTransactionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/library/deployments" : {
      "get" : {
        "tags" : [ "Library" ],
        "summary" : "List script deployments",
        "description" : "Returns the current on-chain deployment state of the UVerify Plutus/Aiken library scripts.",
        "operationId" : "getLibraryDeployments",
        "responses" : {
          "200" : {
            "description" : "Deployments retrieved successfully",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/LibraryDeploymentResponse"
                }
              }
            }
          },
          "400" : {
            "description" : "Failed to retrieve library deployments",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          },
          "500" : {
            "description" : "Internal server error",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/extensions" : {
      "get" : {
        "tags" : [ "Extensions" ],
        "summary" : "List enabled extensions",
        "description" : "Returns a map of extension identifiers to their enabled status.",
        "operationId" : "list",
        "responses" : {
          "200" : {
            "description" : "Extension registry retrieved",
            "content" : {
              "application/json" : {
                "schema" : {
                  "type" : "string",
                  "example" : {
                    "fractionized-certificate" : true,
                    "tokenizable-certificate" : false
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/extension/connected-goods/{batchIds}/{itemId}" : {
      "get" : {
        "tags" : [ "Connected Goods" ],
        "summary" : "Retrieve a connected good",
        "description" : "Decrypts and returns the social-hub data for the connected good identified by its batch ID and item ID.",
        "operationId" : "getConnectedGood",
        "parameters" : [ {
          "name" : "batchIds",
          "in" : "path",
          "description" : "Batch ID of the connected good collection",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "itemId",
          "in" : "path",
          "description" : "Item ID (claiming password hash) used to decrypt the social hub",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "400" : {
            "description" : "Decryption failed for the given item ID",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          },
          "200" : {
            "description" : "Social hub data retrieved and decrypted successfully",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/SocialHub"
                }
              }
            }
          },
          "500" : {
            "description" : "Internal server error",
            "content" : {
              "*/*" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components" : {
    "schemas" : {
      "ExecuteUserActionRequest" : {
        "type" : "object",
        "properties" : {
          "address" : {
            "type" : "string"
          },
          "action" : {
            "type" : "string",
            "enum" : [ "USER_INFO", "INVALIDATE_STATE", "OPT_OUT" ]
          },
          "stateId" : {
            "type" : "string"
          },
          "message" : {
            "type" : "string"
          },
          "signature" : {
            "type" : "string"
          },
          "userSignature" : {
            "type" : "string"
          },
          "userPublicKey" : {
            "type" : "string"
          },
          "timestamp" : {
            "type" : "integer",
            "format" : "int64"
          }
        }
      },
      "BootstrapData" : {
        "type" : "object",
        "properties" : {
          "name" : {
            "type" : "string"
          },
          "whitelistedAddresses" : {
            "type" : "array",
            "items" : {
              "type" : "string"
            }
          },
          "fee" : {
            "type" : "integer",
            "format" : "int32"
          },
          "feeInterval" : {
            "type" : "integer",
            "format" : "int32"
          },
          "feeReceiverAddresses" : {
            "type" : "array",
            "items" : {
              "type" : "string"
            }
          },
          "ttl" : {
            "type" : "integer",
            "format" : "int64"
          },
          "transactionLimit" : {
            "type" : "integer",
            "format" : "int32"
          },
          "batchSize" : {
            "type" : "integer",
            "format" : "int32"
          },
          "version" : {
            "type" : "integer",
            "format" : "int32"
          }
        }
      },
      "ExecuteUserActionResponse" : {
        "type" : "object",
        "properties" : {
          "state" : {
            "$ref" : "#/components/schemas/UserState"
          },
          "status" : {
            "type" : "string",
            "enum" : [ "100 CONTINUE", "101 SWITCHING_PROTOCOLS", "102 PROCESSING", "103 EARLY_HINTS", "103 CHECKPOINT", "200 OK", "201 CREATED", "202 ACCEPTED", "203 NON_AUTHORITATIVE_INFORMATION", "204 NO_CONTENT", "205 RESET_CONTENT", "206 PARTIAL_CONTENT", "207 MULTI_STATUS", "208 ALREADY_REPORTED", "226 IM_USED", "300 MULTIPLE_CHOICES", "301 MOVED_PERMANENTLY", "302 FOUND", "302 MOVED_TEMPORARILY", "303 SEE_OTHER", "304 NOT_MODIFIED", "305 USE_PROXY", "307 TEMPORARY_REDIRECT", "308 PERMANENT_REDIRECT", "400 BAD_REQUEST", "401 UNAUTHORIZED", "402 PAYMENT_REQUIRED", "403 FORBIDDEN", "404 NOT_FOUND", "405 METHOD_NOT_ALLOWED", "406 NOT_ACCEPTABLE", "407 PROXY_AUTHENTICATION_REQUIRED", "408 REQUEST_TIMEOUT", "409 CONFLICT", "410 GONE", "411 LENGTH_REQUIRED", "412 PRECONDITION_FAILED", "413 PAYLOAD_TOO_LARGE", "413 REQUEST_ENTITY_TOO_LARGE", "414 URI_TOO_LONG", "414 REQUEST_URI_TOO_LONG", "415 UNSUPPORTED_MEDIA_TYPE", "416 REQUESTED_RANGE_NOT_SATISFIABLE", "417 EXPECTATION_FAILED", "418 I_AM_A_TEAPOT", "419 INSUFFICIENT_SPACE_ON_RESOURCE", "420 METHOD_FAILURE", "421 DESTINATION_LOCKED", "422 UNPROCESSABLE_ENTITY", "423 LOCKED", "424 FAILED_DEPENDENCY", "425 TOO_EARLY", "426 UPGRADE_REQUIRED", "428 PRECONDITION_REQUIRED", "429 TOO_MANY_REQUESTS", "431 REQUEST_HEADER_FIELDS_TOO_LARGE", "451 UNAVAILABLE_FOR_LEGAL_REASONS", "500 INTERNAL_SERVER_ERROR", "501 NOT_IMPLEMENTED", "502 BAD_GATEWAY", "503 SERVICE_UNAVAILABLE", "504 GATEWAY_TIMEOUT", "505 HTTP_VERSION_NOT_SUPPORTED", "506 VARIANT_ALSO_NEGOTIATES", "507 INSUFFICIENT_STORAGE", "508 LOOP_DETECTED", "509 BANDWIDTH_LIMIT_EXCEEDED", "510 NOT_EXTENDED", "511 NETWORK_AUTHENTICATION_REQUIRED" ]
          },
          "error" : {
            "type" : "string"
          },
          "unsignedTransaction" : {
            "type" : "string"
          }
        }
      },
      "StateData" : {
        "type" : "object",
        "properties" : {
          "id" : {
            "type" : "string"
          },
          "fee" : {
            "type" : "integer",
            "format" : "int32"
          },
          "feeInterval" : {
            "type" : "integer",
            "format" : "int32"
          },
          "feeReceiverAddresses" : {
            "type" : "array",
            "items" : {
              "type" : "string"
            }
          },
          "ttl" : {
            "type" : "integer",
            "format" : "int64"
          },
          "batchSize" : {
            "type" : "integer",
            "format" : "int32"
          },
          "countdown" : {
            "type" : "integer",
            "format" : "int32"
          },
          "bootstrapDatumName" : {
            "type" : "string"
          },
          "version" : {
            "type" : "integer",
            "format" : "int32"
          }
        }
      },
      "UserState" : {
        "type" : "object",
        "properties" : {
          "bootstrapDatums" : {
            "type" : "array",
            "items" : {
              "$ref" : "#/components/schemas/BootstrapData"
            }
          },
          "states" : {
            "type" : "array",
            "items" : {
              "$ref" : "#/components/schemas/StateData"
            }
          }
        }
      },
      "UserActionRequest" : {
        "type" : "object",
        "properties" : {
          "address" : {
            "type" : "string"
          },
          "action" : {
            "type" : "string",
            "enum" : [ "USER_INFO", "INVALIDATE_STATE", "OPT_OUT" ]
          },
          "stateId" : {
            "type" : "string"
          }
        }
      },
      "UserActionResponse" : {
        "type" : "object",
        "properties" : {
          "address" : {
            "type" : "string"
          },
          "action" : {
            "type" : "string",
            "enum" : [ "USER_INFO", "INVALIDATE_STATE", "OPT_OUT" ]
          },
          "signature" : {
            "type" : "string"
          },
          "timestamp" : {
            "type" : "integer",
            "format" : "int64"
          },
          "message" : {
            "type" : "string"
          },
          "status" : {
            "type" : "string",
            "enum" : [ "100 CONTINUE", "101 SWITCHING_PROTOCOLS", "102 PROCESSING", "103 EARLY_HINTS", "103 CHECKPOINT", "200 OK", "201 CREATED", "202 ACCEPTED", "203 NON_AUTHORITATIVE_INFORMATION", "204 NO_CONTENT", "205 RESET_CONTENT", "206 PARTIAL_CONTENT", "207 MULTI_STATUS", "208 ALREADY_REPORTED", "226 IM_USED", "300 MULTIPLE_CHOICES", "301 MOVED_PERMANENTLY", "302 FOUND", "302 MOVED_TEMPORARILY", "303 SEE_OTHER", "304 NOT_MODIFIED", "305 USE_PROXY", "307 TEMPORARY_REDIRECT", "308 PERMANENT_REDIRECT", "400 BAD_REQUEST", "401 UNAUTHORIZED", "402 PAYMENT_REQUIRED", "403 FORBIDDEN", "404 NOT_FOUND", "405 METHOD_NOT_ALLOWED", "406 NOT_ACCEPTABLE", "407 PROXY_AUTHENTICATION_REQUIRED", "408 REQUEST_TIMEOUT", "409 CONFLICT", "410 GONE", "411 LENGTH_REQUIRED", "412 PRECONDITION_FAILED", "413 PAYLOAD_TOO_LARGE", "413 REQUEST_ENTITY_TOO_LARGE", "414 URI_TOO_LONG", "414 REQUEST_URI_TOO_LONG", "415 UNSUPPORTED_MEDIA_TYPE", "416 REQUESTED_RANGE_NOT_SATISFIABLE", "417 EXPECTATION_FAILED", "418 I_AM_A_TEAPOT", "419 INSUFFICIENT_SPACE_ON_RESOURCE", "420 METHOD_FAILURE", "421 DESTINATION_LOCKED", "422 UNPROCESSABLE_ENTITY", "423 LOCKED", "424 FAILED_DEPENDENCY", "425 TOO_EARLY", "426 UPGRADE_REQUIRED", "428 PRECONDITION_REQUIRED", "429 TOO_MANY_REQUESTS", "431 REQUEST_HEADER_FIELDS_TOO_LARGE", "451 UNAVAILABLE_FOR_LEGAL_REASONS", "500 INTERNAL_SERVER_ERROR", "501 NOT_IMPLEMENTED", "502 BAD_GATEWAY", "503 SERVICE_UNAVAILABLE", "504 GATEWAY_TIMEOUT", "505 HTTP_VERSION_NOT_SUPPORTED", "506 VARIANT_ALSO_NEGOTIATES", "507 INSUFFICIENT_STORAGE", "508 LOOP_DETECTED", "509 BANDWIDTH_LIMIT_EXCEEDED", "510 NOT_EXTENDED", "511 NETWORK_AUTHENTICATION_REQUIRED" ]
          },
          "error" : {
            "type" : "string"
          }
        }
      },
      "SubmitTransactionRequest" : {
        "required" : [ "transaction" ],
        "type" : "object",
        "properties" : {
          "transaction" : {
            "type" : "string"
          },
          "witnessSet" : {
            "type" : "string"
          }
        }
      },
      "BuildTransactionRequest" : {
        "type" : "object",
        "properties" : {
          "certificates" : {
            "type" : "array",
            "items" : {
              "$ref" : "#/components/schemas/CertificateData"
            }
          },
          "type" : {
            "type" : "string",
            "enum" : [ "default", "bootstrap", "custom", "burn_state", "burn_bootstrap", "init", "deploy" ]
          },
          "address" : {
            "type" : "string"
          },
          "bootstrapDatum" : {
            "$ref" : "#/components/schemas/BootstrapData"
          },
          "stateId" : {
            "type" : "string"
          }
        }
      },
      "CertificateData" : {
        "type" : "object",
        "properties" : {
          "hash" : {
            "type" : "string"
          },
          "metadata" : {
            "type" : "string"
          },
          "algorithm" : {
            "type" : "string"
          }
        }
      },
      "BuildStatus" : {
        "type" : "object",
        "properties" : {
          "message" : {
            "type" : "string"
          },
          "code" : {
            "type" : "string",
            "enum" : [ "SUCCESS", "ERROR" ]
          }
        }
      },
      "BuildTransactionResponse" : {
        "type" : "object",
        "properties" : {
          "unsignedTransaction" : {
            "type" : "string"
          },
          "type" : {
            "type" : "string",
            "enum" : [ "default", "bootstrap", "custom", "burn_state", "burn_bootstrap", "init", "deploy" ]
          },
          "status" : {
            "$ref" : "#/components/schemas/BuildStatus"
          }
        }
      },
      "ClaimUpdateConnectedGoodsRequest" : {
        "type" : "object",
        "properties" : {
          "password" : {
            "type" : "string"
          },
          "batch_id" : {
            "type" : "string"
          },
          "user_address" : {
            "type" : "string"
          },
          "social_hub" : {
            "$ref" : "#/components/schemas/SocialHub"
          }
        }
      },
      "SocialHub" : {
        "type" : "object",
        "properties" : {
          "owner" : {
            "type" : "string"
          },
          "picture" : {
            "type" : "string"
          },
          "name" : {
            "type" : "string"
          },
          "subtitle" : {
            "type" : "string"
          },
          "x" : {
            "type" : "string"
          },
          "telegram" : {
            "type" : "string"
          },
          "discord" : {
            "type" : "string"
          },
          "youtube" : {
            "type" : "string"
          },
          "website" : {
            "type" : "string"
          },
          "email" : {
            "type" : "string"
          },
          "reddit" : {
            "type" : "string"
          },
          "instagram" : {
            "type" : "string"
          },
          "github" : {
            "type" : "string"
          },
          "linkedin" : {
            "type" : "string"
          },
          "ada_handle" : {
            "type" : "string"
          },
          "item_name" : {
            "type" : "string"
          }
        }
      },
      "Item" : {
        "type" : "object",
        "properties" : {
          "password" : {
            "type" : "string"
          },
          "asset_name" : {
            "type" : "string"
          }
        }
      },
      "MintConnectedGoodsRequest" : {
        "type" : "object",
        "properties" : {
          "items" : {
            "type" : "array",
            "items" : {
              "$ref" : "#/components/schemas/Item"
            }
          },
          "address" : {
            "type" : "string"
          },
          "token_name" : {
            "type" : "string"
          }
        }
      },
      "MintConnectedGoodsResponse" : {
        "type" : "object",
        "properties" : {
          "message" : {
            "type" : "string"
          },
          "status" : {
            "type" : "string",
            "enum" : [ "100 CONTINUE", "101 SWITCHING_PROTOCOLS", "102 PROCESSING", "103 EARLY_HINTS", "103 CHECKPOINT", "200 OK", "201 CREATED", "202 ACCEPTED", "203 NON_AUTHORITATIVE_INFORMATION", "204 NO_CONTENT", "205 RESET_CONTENT", "206 PARTIAL_CONTENT", "207 MULTI_STATUS", "208 ALREADY_REPORTED", "226 IM_USED", "300 MULTIPLE_CHOICES", "301 MOVED_PERMANENTLY", "302 FOUND", "302 MOVED_TEMPORARILY", "303 SEE_OTHER", "304 NOT_MODIFIED", "305 USE_PROXY", "307 TEMPORARY_REDIRECT", "308 PERMANENT_REDIRECT", "400 BAD_REQUEST", "401 UNAUTHORIZED", "402 PAYMENT_REQUIRED", "403 FORBIDDEN", "404 NOT_FOUND", "405 METHOD_NOT_ALLOWED", "406 NOT_ACCEPTABLE", "407 PROXY_AUTHENTICATION_REQUIRED", "408 REQUEST_TIMEOUT", "409 CONFLICT", "410 GONE", "411 LENGTH_REQUIRED", "412 PRECONDITION_FAILED", "413 PAYLOAD_TOO_LARGE", "413 REQUEST_ENTITY_TOO_LARGE", "414 URI_TOO_LONG", "414 REQUEST_URI_TOO_LONG", "415 UNSUPPORTED_MEDIA_TYPE", "416 REQUESTED_RANGE_NOT_SATISFIABLE", "417 EXPECTATION_FAILED", "418 I_AM_A_TEAPOT", "419 INSUFFICIENT_SPACE_ON_RESOURCE", "420 METHOD_FAILURE", "421 DESTINATION_LOCKED", "422 UNPROCESSABLE_ENTITY", "423 LOCKED", "424 FAILED_DEPENDENCY", "425 TOO_EARLY", "426 UPGRADE_REQUIRED", "428 PRECONDITION_REQUIRED", "429 TOO_MANY_REQUESTS", "431 REQUEST_HEADER_FIELDS_TOO_LARGE", "451 UNAVAILABLE_FOR_LEGAL_REASONS", "500 INTERNAL_SERVER_ERROR", "501 NOT_IMPLEMENTED", "502 BAD_GATEWAY", "503 SERVICE_UNAVAILABLE", "504 GATEWAY_TIMEOUT", "505 HTTP_VERSION_NOT_SUPPORTED", "506 VARIANT_ALSO_NEGOTIATES", "507 INSUFFICIENT_STORAGE", "508 LOOP_DETECTED", "509 BANDWIDTH_LIMIT_EXCEEDED", "510 NOT_EXTENDED", "511 NETWORK_AUTHENTICATION_REQUIRED" ]
          },
          "error" : {
            "type" : "string"
          },
          "unsigned_transaction" : {
            "type" : "string"
          },
          "batch_id" : {
            "type" : "string"
          }
        }
      },
      "CertificateResponse" : {
        "type" : "object",
        "properties" : {
          "hash" : {
            "type" : "string"
          },
          "address" : {
            "type" : "string"
          },
          "blockHash" : {
            "type" : "string"
          },
          "blockNumber" : {
            "type" : "integer",
            "format" : "int64"
          },
          "transactionHash" : {
            "type" : "string"
          },
          "slot" : {
            "type" : "integer",
            "format" : "int64"
          },
          "creationTime" : {
            "type" : "integer",
            "format" : "int64"
          },
          "metadata" : {
            "type" : "string"
          },
          "issuer" : {
            "type" : "string"
          },
          "bootstrapTokenName" : {
            "type" : "string"
          }
        }
      },
      "ExUnits" : {
        "type" : "object",
        "properties" : {
          "mem" : {
            "type" : "integer"
          },
          "steps" : {
            "type" : "integer"
          }
        }
      },
      "Redeemer" : {
        "type" : "object",
        "properties" : {
          "tag" : {
            "type" : "string",
            "enum" : [ "spend", "mint", "cert", "reward", "voting", "proposing" ]
          },
          "index" : {
            "type" : "integer",
            "format" : "int32"
          },
          "data" : {
            "type" : "string"
          },
          "ex_units" : {
            "$ref" : "#/components/schemas/ExUnits"
          }
        }
      },
      "TxContractDetails" : {
        "type" : "object",
        "properties" : {
          "tx_hash" : {
            "type" : "string"
          },
          "script_hash" : {
            "type" : "string"
          },
          "script_content" : {
            "type" : "string"
          },
          "type" : {
            "type" : "string",
            "enum" : [ "NATIVE_SCRIPT", "PLUTUS_V1", "PLUTUS_V2", "PLUTUS_V3" ]
          },
          "redeemer" : {
            "$ref" : "#/components/schemas/Redeemer"
          },
          "datum" : {
            "type" : "string"
          },
          "datum_hash" : {
            "type" : "string"
          }
        }
      },
      "TxRedeemerDto" : {
        "type" : "object",
        "properties" : {
          "tx_index" : {
            "type" : "integer",
            "format" : "int32"
          },
          "purpose" : {
            "type" : "string"
          },
          "script_hash" : {
            "type" : "string"
          },
          "datum_hash" : {
            "type" : "string"
          },
          "redeemer_data_hash" : {
            "type" : "string"
          },
          "unit_mem" : {
            "type" : "string"
          },
          "unit_steps" : {
            "type" : "string"
          }
        }
      },
      "ScriptDto" : {
        "type" : "object",
        "properties" : {
          "script_hash" : {
            "type" : "string"
          },
          "type" : {
            "type" : "string",
            "enum" : [ "timelock", "plutusV1", "plutusV2", "plutusV3" ]
          },
          "serialised_size" : {
            "type" : "integer",
            "format" : "int32"
          }
        }
      },
      "JsonNode" : {
        "type" : "object"
      },
      "ScriptJsonDto" : {
        "type" : "object",
        "properties" : {
          "json" : {
            "$ref" : "#/components/schemas/JsonNode"
          }
        }
      },
      "ScriptDetailDto" : {
        "type" : "object",
        "properties" : {
          "script_hash" : {
            "type" : "string"
          },
          "script_type" : {
            "type" : "string",
            "enum" : [ "timelock", "plutusV1", "plutusV2", "plutusV3" ]
          },
          "content" : {
            "$ref" : "#/components/schemas/JsonNode"
          }
        }
      },
      "ScriptCborDto" : {
        "type" : "object",
        "properties" : {
          "cbor" : {
            "type" : "string"
          }
        }
      },
      "LibraryDeploymentResponse" : {
        "type" : "object",
        "properties" : {
          "address" : {
            "type" : "string"
          },
          "entries" : {
            "type" : "array",
            "items" : {
              "$ref" : "#/components/schemas/LibraryEntry"
            }
          }
        }
      },
      "LibraryEntry" : {
        "type" : "object",
        "properties" : {
          "transactionHash" : {
            "type" : "string"
          },
          "outputIndex" : {
            "type" : "integer",
            "format" : "int32"
          },
          "isActiveContract" : {
            "type" : "boolean"
          }
        }
      }
    }
  }
}