confidentialledger.json

{
  "swagger": "2.0",
  "info": {
    "version": "0.1-preview",
    "title": "ConfidentialLedgerClient",
    "description": "The ConfidentialLedgerClient writes and retrieves ledger entries against the Confidential Ledger service."
  },
  "x-ms-parameterized-host": {
    "hostTemplate": "{ledgerUri}",
    "useSchemePrefix": false,
    "positionInOperation": "first",
    "parameters": [
      {
        "name": "ledgerUri",
        "description": "The Confidential Ledger URL, for example https://contoso.confidentialledger.azure.com",
        "required": true,
        "type": "string",
        "in": "path",
        "format": "url",
        "x-ms-skip-url-encoding": true,
        "x-ms-parameter-location": "client"
      }
    ]
  },
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/app/governance/constitution": {
      "get": {
        "operationId": "ConfidentialLedger_GetConstitution",
        "x-ms-examples": {
          "GetConstitution": {
            "$ref": "./examples/ledger/GetConstitution.json"
          }
        },
        "summary": "Gets the constitution used for governance.",
        "description": "The constitution is a script that assesses and applies proposals from consortium members.",
        "parameters": [
          {
            "$ref": "common.json#/parameters/ApiVersionParameter"
          }
        ],
        "responses": {
          "200": {
            "description": "The constitution.",
            "schema": {
              "$ref": "#/definitions/Constitution"
            }
          },
          "default": {
            "description": "Error response describing why the operation failed.",
            "schema": {
              "$ref": "common.json#/definitions/ConfidentialLedgerError"
            }
          }
        }
      }
    },
    "/app/governance/members": {
      "get": {
        "operationId": "ConfidentialLedger_GetConsortiumMembers",
        "x-ms-examples": {
          "GetConsortiumMembers": {
            "$ref": "./examples/ledger/GetConsortiumMembers.json"
          }
        },
        "summary": "Gets the consortium members.",
        "description": "Consortium members can manage the Confidential Ledger.",
        "parameters": [
          {
            "$ref": "common.json#/parameters/ApiVersionParameter"
          }
        ],
        "responses": {
          "200": {
            "description": "List of consortium members.",
            "schema": {
              "$ref": "#/definitions/Consortium"
            }
          },
          "default": {
            "description": "Error response describing why the operation failed.",
            "schema": {
              "$ref": "common.json#/definitions/ConfidentialLedgerError"
            }
          }
        }
      }
    },
    "/app/enclaveQuotes": {
      "get": {
        "operationId": "ConfidentialLedger_GetEnclaveQuotes",
        "x-ms-examples": {
          "GetEnclaveQuotes": {
            "$ref": "./examples/ledger/GetEnclaveQuotes.json"
          }
        },
        "summary": "Gets quotes for all nodes of the Confidential Ledger.",
        "description": "A quote is an SGX enclave measurement that can be used to verify the validity of a node and its enclave.",
        "parameters": [
          {
            "$ref": "common.json#/parameters/ApiVersionParameter"
          }
        ],
        "responses": {
          "200": {
            "description": "Response containing enclave quotes.",
            "schema": {
              "$ref": "#/definitions/ConfidentialLedgerEnclaves"
            }
          },
          "default": {
            "description": "Error response describing why the operation failed",
            "schema": {
              "$ref": "common.json#/definitions/ConfidentialLedgerError"
            }
          }
        }
      }
    },
    "/app/transactions": {
      "get": {
        "operationId": "ConfidentialLedger_GetLedgerEntries",
        "x-ms-examples": {
          "GetLedgerEntries": {
            "$ref": "./examples/ledger/GetLedgerEntries.json"
          }
        },
        "x-ms-pageable": {
          "itemName": "entries",
          "nextLinkName": "@nextLink"
        },
        "summary": "Gets ledger entries from a sub-ledger corresponding to a range.",
        "description": "A sub-ledger id may optionally be specified. Only entries in the specified (or default) sub-ledger will be returned.",
        "parameters": [
          {
            "$ref": "common.json#/parameters/ApiVersionParameter"
          },
          {
            "$ref": "#/parameters/SubLedgerIdParameter"
          },
          {
            "$ref": "#/parameters/TransactionIdFromParameter"
          },
          {
            "$ref": "#/parameters/TransactionIdToParameter"
          }
        ],
        "responses": {
          "200": {
            "description": "Ledger entries in the specified range.",
            "schema": {
              "$ref": "#/definitions/PagedLedgerEntries"
            }
          },
          "default": {
            "description": "Error response describing why the operation failed",
            "schema": {
              "$ref": "common.json#/definitions/ConfidentialLedgerError"
            }
          }
        }
      },
      "post": {
        "operationId": "ConfidentialLedger_PostLedgerEntry",
        "x-ms-examples": {
          "PostLedgerEntry": {
            "$ref": "./examples/ledger/PostLedgerEntry.json"
          }
        },
        "summary": "Writes a ledger entry.",
        "description": "A sub-ledger id may optionally be specified.",
        "parameters": [
          {
            "$ref": "common.json#/parameters/ApiVersionParameter"
          },
          {
            "$ref": "#/parameters/SubLedgerIdParameter"
          },
          {
            "in": "body",
            "name": "entry",
            "description": "Ledger entry.",
            "schema": {
              "$ref": "#/definitions/LedgerEntry"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns the transaction id at which the write will be durably stored.",
            "headers": {
              "x-ms-ccf-transaction-id": {
                "type": "string",
                "description": "The transaction id at which this write will become durable."
              }
            },
            "schema": {
              "$ref": "#/definitions/LedgerWriteResult"
            }
          },
          "default": {
            "description": "Error response describing why the operation failed",
            "schema": {
              "$ref": "common.json#/definitions/ConfidentialLedgerError"
            }
          }
        }
      }
    },
    "/app/transactions/{transactionId}": {
      "get": {
        "operationId": "ConfidentialLedger_GetLedgerEntry",
        "x-ms-examples": {
          "GetLedgerEntry": {
            "$ref": "./examples/ledger/GetLedgerEntry.json"
          }
        },
        "summary": "Gets the ledger entry at the specified transaction id. A sub-ledger id may optionally be specified to indicate the sub-ledger from which to fetch the value.",
        "description": "To return older ledger entries, the relevant sections of the ledger must be read from disk and validated. To prevent blocking within the enclave, the response will indicate whether the entry is ready and part of the response, or if the loading is still ongoing.",
        "parameters": [
          {
            "$ref": "common.json#/parameters/ApiVersionParameter"
          },
          {
            "$ref": "#/parameters/SubLedgerIdParameter"
          },
          {
            "$ref": "#/parameters/TransactionIdParameter"
          }
        ],
        "responses": {
          "200": {
            "description": "The result of querying the Confidential Ledger.",
            "schema": {
              "$ref": "#/definitions/LedgerQueryResult"
            }
          },
          "default": {
            "description": "Error response describing why the operation failed.",
            "schema": {
              "$ref": "common.json#/definitions/ConfidentialLedgerError"
            }
          }
        }
      }
    },
    "/app/transactions/{transactionId}/receipt": {
      "get": {
        "operationId": "ConfidentialLedger_GetReceipt",
        "x-ms-examples": {
          "GetReceipt": {
            "$ref": "./examples/ledger/GetReceipt.json"
          }
        },
        "summary": "Gets a receipt certifying ledger contents at a particular transaction id.",
        "parameters": [
          {
            "$ref": "common.json#/parameters/ApiVersionParameter"
          },
          {
            "$ref": "#/parameters/TransactionIdParameter"
          }
        ],
        "responses": {
          "200": {
            "description": "The receipt for the write occurring at the transaction id.",
            "schema": {
              "$ref": "#/definitions/TransactionReceipt"
            }
          },
          "default": {
            "description": "Error response describing why the operation failed",
            "schema": {
              "$ref": "common.json#/definitions/ConfidentialLedgerError"
            }
          }
        }
      }
    },
    "/app/transactions/{transactionId}/status": {
      "get": {
        "operationId": "ConfidentialLedger_GetTransactionStatus",
        "x-ms-examples": {
          "GetTransactionStatus": {
            "$ref": "./examples/ledger/GetTransactionStatus.json"
          }
        },
        "summary": "Gets the status of an entry identified by a transaction id.",
        "parameters": [
          {
            "$ref": "common.json#/parameters/ApiVersionParameter"
          },
          {
            "$ref": "#/parameters/TransactionIdParameter"
          }
        ],
        "responses": {
          "200": {
            "description": "The status of the entry recorded at the specified transaction id.",
            "schema": {
              "$ref": "#/definitions/TransactionStatus"
            }
          },
          "default": {
            "description": "Error response describing why the operation failed",
            "schema": {
              "$ref": "common.json#/definitions/ConfidentialLedgerError"
            }
          }
        }
      }
    },
    "/app/transactions/current": {
      "get": {
        "operationId": "ConfidentialLedger_GetCurrentLedgerEntry",
        "x-ms-examples": {
          "GetCurrentLedgerEntry": {
            "$ref": "./examples/ledger/GetCurrentLedgerEntry.json"
          }
        },
        "summary": "Gets the current value available in the ledger.",
        "description": "A sub-ledger id may optionally be specified.",
        "parameters": [
          {
            "$ref": "common.json#/parameters/ApiVersionParameter"
          },
          {
            "$ref": "#/parameters/SubLedgerIdParameter"
          }
        ],
        "responses": {
          "200": {
            "description": "The current ledger entry available on the receiving node. Non-primary nodes may return older values.",
            "schema": {
              "$ref": "#/definitions/LedgerEntry"
            }
          },
          "default": {
            "description": "Error response describing why the operation failed",
            "schema": {
              "$ref": "common.json#/definitions/ConfidentialLedgerError"
            }
          }
        }
      }
    },
    "/app/users/{userId}": {
      "delete": {
        "operationId": "ConfidentialLedger_DeleteUser",
        "x-ms-examples": {
          "DeleteUser": {
            "$ref": "./examples/ledger/DeleteUser.json"
          }
        },
        "summary": "Deletes a user from the Confidential Ledger.",
        "parameters": [
          {
            "$ref": "common.json#/parameters/ApiVersionParameter"
          },
          {
            "$ref": "#/parameters/UserIdParameter"
          }
        ],
        "responses": {
          "204": {
            "description": "The specified user is deleted."
          },
          "default": {
            "description": "Error response describing why the operation failed",
            "schema": {
              "$ref": "common.json#/definitions/ConfidentialLedgerError"
            }
          }
        }
      },
      "get": {
        "operationId": "ConfidentialLedger_GetUser",
        "x-ms-examples": {
          "GetUser": {
            "$ref": "./examples/ledger/GetUser.json"
          }
        },
        "summary": "Gets a user.",
        "parameters": [
          {
            "$ref": "common.json#/parameters/ApiVersionParameter"
          },
          {
            "$ref": "#/parameters/UserIdParameter"
          }
        ],
        "responses": {
          "200": {
            "description": "Details about the specified user.",
            "schema": {
              "$ref": "#/definitions/LedgerUser"
            }
          },
          "default": {
            "description": "Error response describing why the operation failed",
            "schema": {
              "$ref": "common.json#/definitions/ConfidentialLedgerError"
            }
          }
        }
      },
      "patch": {
        "operationId": "ConfidentialLedger_CreateOrUpdateUser",
        "x-ms-examples": {
          "CreateOrUpdateUser": {
            "$ref": "./examples/ledger/CreateOrUpdateUser.json"
          }
        },
        "summary": "Adds a user or updates a user's fields.",
        "description": "A JSON merge patch is applied for existing users",
        "parameters": [
          {
            "$ref": "common.json#/parameters/ApiVersionParameter"
          },
          {
            "$ref": "#/parameters/UserIdParameter"
          },
          {
            "$ref": "#/parameters/UserDetailsParameter"
          }
        ],
        "responses": {
          "200": {
            "description": "User created or updated successfully.",
            "schema": {
              "$ref": "#/definitions/LedgerUser"
            }
          },
          "default": {
            "description": "Error response describing why the operation failed",
            "schema": {
              "$ref": "common.json#/definitions/ConfidentialLedgerError"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "ConfidentialLedgerEnclaves": {
      "description": "Information about the enclaves running the Confidential Ledger.",
      "required": [
        "currentNodeId",
        "enclaveQuotes"
      ],
      "properties": {
        "currentNodeId": {
          "description": "Id of the Confidential Ledger node responding to the request.",
          "$ref": "#/definitions/EntityId"
        },
        "enclaveQuotes": {
          "$ref": "#/definitions/EnclaveQuotes"
        }
      },
      "type": "object"
    },
    "Consortium": {
      "description": "List of members in the consortium.",
      "required": [
        "members"
      ],
      "properties": {
        "members": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ConsortiumMember"
          }
        }
      },
      "type": "object"
    },
    "ConsortiumMember": {
      "description": "Describes a member of the consortium.",
      "required": [
        "certificate",
        "id"
      ],
      "properties": {
        "certificate": {
          "type": "string",
          "description": "PEM-encoded certificate associated with the member."
        },
        "id": {
          "description": "Identifier assigned to the member.",
          "$ref": "#/definitions/EntityId"
        }
      },
      "type": "object"
    },
    "Constitution": {
      "description": "The governance script for the application.",
      "required": [
        "digest",
        "script"
      ],
      "properties": {
        "digest": {
          "description": "SHA256 digest of the constitution script.",
          "type": "string"
        },
        "script": {
          "description": "Contents of the constitution.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "EnclaveQuote": {
      "description": "Contains the enclave quote.",
      "required": [
        "nodeId",
        "quoteVersion",
        "raw"
      ],
      "properties": {
        "nodeId": {
          "description": "ID assigned to this node.",
          "$ref": "#/definitions/EntityId"
        },
        "mrenclave": {
          "description": "MRENCLAVE value of the code running in the enclave.",
          "type": "string"
        },
        "quoteVersion": {
          "description": "Version of the quote presented.",
          "type": "string"
        },
        "raw": {
          "description": "Raw SGX quote, parsable by tools like Open Enclave's oeverify.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "EnclaveQuotes": {
      "description": "Dictionary of enclave quotes, indexed by node id.",
      "additionalProperties": {
        "$ref": "#/definitions/EnclaveQuote"
      },
      "type": "object"
    },
    "EntityId": {
      "description": "Identifier for an entity.",
      "type": "string"
    },
    "LedgerEntries": {
      "description": "Array of ledger entries.",
      "type": "array",
      "items": {
        "$ref": "#/definitions/LedgerEntry"
      }
    },
    "LedgerEntry": {
      "description": "An entry in the ledger.",
      "required": [
        "contents"
      ],
      "properties": {
        "contents": {
          "type": "string",
          "description": "Contents of the ledger entry."
        },
        "subLedgerId": {
          "$ref": "#/definitions/SubLedgerId",
          "readOnly": true
        },
        "transactionId": {
          "$ref": "#/definitions/TransactionId",
          "readOnly": true
        }
      },
      "type": "object"
    },
    "LedgerQueryResult": {
      "description": "The result of querying for a ledger entry from an older transaction id. The ledger entry is available in the response only if the returned state is Ready.",
      "required": [
        "state"
      ],
      "properties": {
        "state": {
          "$ref": "#/definitions/LedgerQueryState"
        },
        "entry": {
          "description": "The ledger entry found as a result of the query. This is only available if the query is in Ready state.",
          "$ref": "#/definitions/LedgerEntry"
        }
      },
      "type": "object"
    },
    "LedgerQueryState": {
      "description": "State of a ledger query.",
      "type": "string",
      "enum": [
        "Loading",
        "Ready"
      ],
      "x-ms-enum": {
        "name": "ConfidentialLedgerQueryState",
        "modelAsString": true
      }
    },
    "LedgerUser": {
      "description": "Details about a Confidential Ledger user.",
      "required": [
        "assignedRole"
      ],
      "properties": {
        "assignedRole": {
          "$ref": "#/definitions/LedgerUserRole"
        },
        "userId": {
          "$ref": "#/definitions/UserId",
          "readOnly": true
        }
      },
      "type": "object"
    },
    "LedgerUserRole": {
      "type": "string",
      "description": "Represents an assignable role.",
      "enum": [
        "Administrator",
        "Contributor",
        "Reader"
      ],
      "x-ms-enum": {
        "name": "ConfidentialLedgerUserRoleName",
        "modelAsString": true
      }
    },
    "LedgerWriteResult": {
      "description": "Returned as a result of a write to the Confidential Ledger, the transaction id in the response indicates when the write will become durable.",
      "required": [
        "subLedgerId"
      ],
      "properties": {
        "subLedgerId": {
          "$ref": "#/definitions/SubLedgerId"
        }
      },
      "type": "object"
    },
    "MerkleProof": {
      "description": "The Merkle proof verifying a transaction.",
      "type": "array",
      "items": {
        "$ref": "#/definitions/MerkleProofElement"
      }
    },
    "MerkleProofElement": {
      "description": "An item in the Merkle proof.",
      "type": "object",
      "properties": {
        "left": {
          "type": "string"
        },
        "right": {
          "type": "string"
        }
      }
    },
    "PagedLedgerEntries": {
      "description": "Paginated ledger entries returned in response to a query.",
      "type": "object",
      "required": [
        "state",
        "entries"
      ],
      "properties": {
        "state": {
          "$ref": "#/definitions/LedgerQueryState"
        },
        "@nextLink": {
          "description": "Path from which to retrieve the next page of results.",
          "type": "string"
        },
        "entries": {
          "$ref": "#/definitions/LedgerEntries"
        }
      }
    },
    "ReceiptContents": {
      "description": "A receipt certifying the transaction at the specified id.",
      "required": [
        "leaf",
        "nodeId",
        "proof",
        "root",
        "signature"
      ],
      "type": "object",
      "properties": {
        "leaf": {
          "description": "Merkle tree leaf for this transaction.",
          "type": "string"
        },
        "nodeId": {
          "description": "Id of the node returning the receipt.",
          "$ref": "#/definitions/EntityId"
        },
        "proof": {
          "description": "Merkle proof.",
          "$ref": "#/definitions/MerkleProof"
        },
        "root": {
          "description": "Root of the Merkle tree at the time the transaction was recorded.",
          "type": "string"
        },
        "signature": {
          "description": "Signature by the node, with its certificate, over the Merkle root.",
          "type": "string"
        }
      }
    },
    "RoleAssignment": {
      "description": "Object for assigning a role to a user.",
      "required": [
        "roleName"
      ],
      "properties": {
        "roleName": {
          "$ref": "#/definitions/LedgerUserRole"
        },
        "description": {
          "description": "Description of the role.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "SubLedgerId": {
      "description": "Identifier for sub-ledgers.",
      "type": "string"
    },
    "TransactionId": {
      "description": "A unique identifier for the state of the ledger. If returned as part of a LedgerEntry, it indicates the state from which the entry was read.",
      "type": "string"
    },
    "TransactionReceipt": {
      "description": "A receipt certifying the transaction at the specified id.",
      "required": [
        "state",
        "transactionId"
      ],
      "properties": {
        "receipt": {
          "$ref": "#/definitions/ReceiptContents"
        },
        "state": {
          "$ref": "#/definitions/LedgerQueryState"
        },
        "transactionId": {
          "$ref": "#/definitions/TransactionId"
        }
      },
      "type": "object"
    },
    "TransactionState": {
      "type": "string",
      "description": "Represents the state of the transaction.",
      "enum": [
        "Committed",
        "Pending"
      ],
      "x-ms-enum": {
        "name": "TransactionState",
        "modelAsString": true
      }
    },
    "TransactionStatus": {
      "description": "Response returned to a query for the transaction status",
      "required": [
        "state",
        "transactionId"
      ],
      "properties": {
        "state": {
          "$ref": "#/definitions/TransactionState"
        },
        "transactionId": {
          "$ref": "#/definitions/TransactionId"
        }
      },
      "type": "object"
    },
    "UserId": {
      "description": "Identifier for the user. This must either be an AAD object id or a certificate fingerprint.",
      "type": "string"
    }
  },
  "parameters": {
    "CommitParameter": {
      "name": "commit",
      "in": "query",
      "required": true,
      "x-ms-parameter-location": "method",
      "maximum": 9223372036854775807,
      "minimum": -9223372036854775808,
      "type": "integer",
      "description": "The commit in the consensus protocol."
    },
    "SubLedgerIdParameter": {
      "name": "subLedgerId",
      "in": "query",
      "required": false,
      "x-ms-parameter-location": "method",
      "description": "The sub-ledger id.",
      "type": "string"
    },
    "TransactionIdParameter": {
      "name": "transactionId",
      "in": "path",
      "required": true,
      "x-ms-parameter-location": "method",
      "description": "Identifies a write transaction.",
      "type": "string"
    },
    "TransactionIdFromParameter": {
      "name": "fromTransactionId",
      "in": "query",
      "required": false,
      "x-ms-parameter-location": "method",
      "description": "Specify the first transaction ID in a range.",
      "type": "string"
    },
    "TransactionIdToParameter": {
      "name": "toTransactionId",
      "in": "query",
      "required": false,
      "x-ms-parameter-location": "method",
      "description": "Specify the last transaction ID in a range.",
      "type": "string"
    },
    "UserDetailsParameter": {
      "name": "userDetails",
      "description": "Details about a Confidential Ledger user.",
      "in": "body",
      "required": true,
      "x-ms-parameter-location": "method",
      "schema": {
        "$ref": "#/definitions/LedgerUser"
      }
    },
    "UserIdParameter": {
      "name": "userId",
      "in": "path",
      "required": true,
      "description": "The user id, either an AAD object ID or certificate fingerprint.",
      "type": "string",
      "x-ms-parameter-location": "method"
    }
  }
}