2023-06-01-preview

This API is available by passing the query parameter api-version=2023-06-01-preview to endpoints under the /gov prefix.

This is available from CCF 5.0.0-dev3.

GET /gov/members/proposals

Returns all current proposed changes to the service. Note that non-open proposals (ie - those which have already been accepted, rejected, withdrawn, etc) are not returned.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 200 OK – The request has succeeded.

  • default – An unexpected error response.

Response Headers:

  • x-ms-ccf-transaction-id – Identifier for transaction this response was read from. The service state may be altered by other write requests. Reads at the same transactionId describe a consistent single point in the service history.

  • x-ms-error-code – String error code indicating what went wrong.

Response JSON Object:

  • nextLink (string) – The link to the next page of items

  • value[].ballotCount (integer) – A non-negative JSON-safe integer (ie max is 2^53 - 1) (required)

  • value[].failure.reason (string) – Error message describing reason for failure. (required)

  • value[].failure.trace (string) – Call stack showing where failure occurred, if available.

  • value[].finalVotes (object) – Each key is a memberId, and the corresponding value is the result of their ballot.

  • value[].proposalId (string) – Hex encoding of SHA-256 of proposed actions and merkle root of store at proposal creation. Unlike other IDs, this is generated on the service and will not be known in advance. (required)

  • value[].proposalState (string) – Possible states for a proposal. (required)

  • value[].proposerId (string) – Hex encoding of SHA-256 of a member certificate’s fingerprint. (required)

  • value[].voteFailures (object) – Each key is a memberId, and the corresponding value explains why execution of their ballot failed.

POST /gov/members/proposals/{proposalId}:withdraw

Withdraw an existing proposal. Only the original proposer is permitted to withdraw.

Parameters:

  • proposalId (string) – Unique ID assigned to this proposal at its submission, by the service.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 200 OK – The request has succeeded.

  • default – An unexpected error response.

Response Headers:

  • x-ms-ccf-transaction-id – Identifier for transaction where this request produced a write on the service. This uniquely identifies the submitted request, and can be used to confirm that the request becomes committed.

  • x-ms-error-code – String error code indicating what went wrong.

Response JSON Object:

  • ballotCount (integer) – A non-negative JSON-safe integer (ie max is 2^53 - 1) (required)

  • failure.reason (string) – Error message describing reason for failure. (required)

  • failure.trace (string) – Call stack showing where failure occurred, if available.

  • finalVotes (object) – Each key is a memberId, and the corresponding value is the result of their ballot.

  • proposalId (string) – Hex encoding of SHA-256 of proposed actions and merkle root of store at proposal creation. Unlike other IDs, this is generated on the service and will not be known in advance. (required)

  • proposalState (string) – Possible states for a proposal. (required)

  • proposerId (string) – Hex encoding of SHA-256 of a member certificate’s fingerprint. (required)

  • voteFailures (object) – Each key is a memberId, and the corresponding value explains why execution of their ballot failed.

GET /gov/members/proposals/{proposalId}

Returns a summary of a single proposed change to the service.

Parameters:

  • proposalId (string) – Unique ID assigned to this proposal at its submission, by the service.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 200 OK – The request has succeeded.

  • default – An unexpected error response.

Response Headers:

  • x-ms-ccf-transaction-id – Identifier for transaction this response was read from. The service state may be altered by other write requests. Reads at the same transactionId describe a consistent single point in the service history.

  • x-ms-error-code – String error code indicating what went wrong.

Response JSON Object:

  • ballotCount (integer) – A non-negative JSON-safe integer (ie max is 2^53 - 1) (required)

  • failure.reason (string) – Error message describing reason for failure. (required)

  • failure.trace (string) – Call stack showing where failure occurred, if available.

  • finalVotes (object) – Each key is a memberId, and the corresponding value is the result of their ballot.

  • proposalId (string) – Hex encoding of SHA-256 of proposed actions and merkle root of store at proposal creation. Unlike other IDs, this is generated on the service and will not be known in advance. (required)

  • proposalState (string) – Possible states for a proposal. (required)

  • proposerId (string) – Hex encoding of SHA-256 of a member certificate’s fingerprint. (required)

  • voteFailures (object) – Each key is a memberId, and the corresponding value explains why execution of their ballot failed.

GET /gov/members/proposals/{proposalId}/actions

Returns actions contained in a proposal.

Parameters:

  • proposalId (string) – Unique ID assigned to this proposal at its submission, by the service.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 200 OK – The request has succeeded.

  • default – An unexpected error response.

Response Headers:

  • x-ms-ccf-transaction-id – Identifier for transaction this response was read from. The service state may be altered by other write requests. Reads at the same transactionId describe a consistent single point in the service history.

  • x-ms-error-code – String error code indicating what went wrong.

Response JSON Object:

  • actions[].args (any) – Arguments to modify the behavior of this action. The schema is determined by the action implementation, and should be validated by a validate call in the constitution.

  • actions[].name (string) – The name of the action to perform. This should match an action defined in the service’s constitution, so that it can be invoked by the apply function of the constitution if the proposal is accepted. (required)

POST /gov/members/proposals/{proposalId}/ballots/{memberId}:submit

Submit an executable ballot for a specific proposal. This may be as simple as return true to vote in favour, or contain reads from the KV and conditions on the proposal contents.

Parameters:

  • proposalId (string) – Unique ID assigned to this proposal at its submission, by the service.

  • memberId (string) – ID of CCF member who signed and submitted this ballot.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 200 OK – The request has succeeded.

  • default – An unexpected error response.

Response Headers:

  • x-ms-ccf-transaction-id – Identifier for transaction where this request produced a write on the service. This uniquely identifies the submitted request, and can be used to confirm that the request becomes committed.

  • x-ms-error-code – String error code indicating what went wrong.

Response JSON Object:

  • ballotCount (integer) – A non-negative JSON-safe integer (ie max is 2^53 - 1) (required)

  • failure.reason (string) – Error message describing reason for failure. (required)

  • failure.trace (string) – Call stack showing where failure occurred, if available.

  • finalVotes (object) – Each key is a memberId, and the corresponding value is the result of their ballot.

  • proposalId (string) – Hex encoding of SHA-256 of proposed actions and merkle root of store at proposal creation. Unlike other IDs, this is generated on the service and will not be known in advance. (required)

  • proposalState (string) – Possible states for a proposal. (required)

  • proposerId (string) – Hex encoding of SHA-256 of a member certificate’s fingerprint. (required)

  • voteFailures (object) – Each key is a memberId, and the corresponding value explains why execution of their ballot failed.

GET /gov/members/proposals/{proposalId}/ballots/{memberId}

Returns a member’s submitted ballot.

Parameters:

  • proposalId (string) – Unique ID assigned to this proposal at its submission, by the service.

  • memberId (string) – ID of CCF member who signed and submitted this ballot.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 200 OK – The request has succeeded.

  • default – An unexpected error response.

Response Headers:

  • x-ms-ccf-transaction-id – Identifier for transaction this response was read from. The service state may be altered by other write requests. Reads at the same transactionId describe a consistent single point in the service history.

  • x-ms-error-code – String error code indicating what went wrong.

Response JSON Object:

  • script (string) – The script to execute, returning the voter’s support of this proposal. (required)

POST /gov/members/proposals:create

Submit a proposed change to the service. This will be assigned an ID by the service. Submitting the same signature (including signed COSE headers such as created_at) multiple times will be treated as a single idempotent operation, returning a single created proposal (or an error if it is no longer available). Any change to the request body will be treated as a new, separate proposal.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 200 OK – The request has succeeded.

  • default – An unexpected error response.

Response Headers:

  • x-ms-ccf-transaction-id – Identifier for transaction where this request produced a write on the service. This uniquely identifies the submitted request, and can be used to confirm that the request becomes committed.

  • x-ms-error-code – String error code indicating what went wrong.

Response JSON Object:

  • ballotCount (integer) – A non-negative JSON-safe integer (ie max is 2^53 - 1) (required)

  • failure.reason (string) – Error message describing reason for failure. (required)

  • failure.trace (string) – Call stack showing where failure occurred, if available.

  • finalVotes (object) – Each key is a memberId, and the corresponding value is the result of their ballot.

  • proposalId (string) – Hex encoding of SHA-256 of proposed actions and merkle root of store at proposal creation. Unlike other IDs, this is generated on the service and will not be known in advance. (required)

  • proposalState (string) – Possible states for a proposal. (required)

  • proposerId (string) – Hex encoding of SHA-256 of a member certificate’s fingerprint. (required)

  • voteFailures (object) – Each key is a memberId, and the corresponding value explains why execution of their ballot failed.

POST /gov/members/state-digests/{memberId}:update

Request that this member’s stateDigest is updated to a fresher value. Only this member may update their own stateDigest. Returns the refreshed value.

Parameters:

  • memberId (string) – Identifier for member this stateDigest applies to.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 200 OK – The request has succeeded.

  • default – An unexpected error response.

Response Headers:

  • x-ms-ccf-transaction-id – Identifier for transaction where this request produced a write on the service. This uniquely identifies the submitted request, and can be used to confirm that the request becomes committed.

  • x-ms-error-code – String error code indicating what went wrong.

Response JSON Object:

  • memberId (string) – Hex encoding of SHA-256 of a member certificate’s fingerprint. (required)

  • stateDigest (string) – Hex-encoding of SHA-256 hash of the root of the service’s merkle tree. This should be signed by a new member and submitted as an ACK to mark that member as Active. (required)

POST /gov/members/state-digests/{memberId}:ack

Submit a signed acknowledgement of a recent digest of the service status, to transition the member to Active.

Parameters:

  • memberId (string) – Identifier for member this stateDigest applies to.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 204 No Content – There is no content to send for this request, but the headers may be useful.

  • default – An unexpected error response.

Response Headers:

  • x-ms-ccf-transaction-id – Identifier for transaction where this request produced a write on the service. This uniquely identifies the submitted request, and can be used to confirm that the request becomes committed.

  • x-ms-error-code – String error code indicating what went wrong.

GET /gov/members/state-digests/{memberId}

Get the stateDigest assigned to the given member, which that member must sign to become active.

Parameters:

  • memberId (string) – Identifier for member this stateDigest applies to.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 200 OK – The request has succeeded.

  • default – An unexpected error response.

Response Headers:

  • x-ms-ccf-transaction-id – Identifier for transaction this response was read from. The service state may be altered by other write requests. Reads at the same transactionId describe a consistent single point in the service history.

  • x-ms-error-code – String error code indicating what went wrong.

Response JSON Object:

  • memberId (string) – Hex encoding of SHA-256 of a member certificate’s fingerprint. (required)

  • stateDigest (string) – Hex-encoding of SHA-256 hash of the root of the service’s merkle tree. This should be signed by a new member and submitted as an ACK to mark that member as Active. (required)

GET /gov/recovery/encrypted-shares/{memberId}

Retrieve a member’s recovery share, encrypted with that member’s share-encryption key.

Parameters:

  • memberId (string) – ID of CCF member who this recovery share belongs to.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 200 OK – The request has succeeded.

  • default – An unexpected error response.

Response Headers:

  • x-ms-error-code – String error code indicating what went wrong.

Response JSON Object:

  • encryptedShare (string) – Base-64 encoding of a member’s encrypted share. (required)

POST /gov/recovery/members/{memberId}:recover

Provide a recovery share for the purpose of completing a service recovery.

Parameters:

  • memberId (string) – Identifier for member this recovery state applies to.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 200 OK – The request has succeeded.

  • default – An unexpected error response.

Response Headers:

  • x-ms-ccf-transaction-id – Identifier for transaction this response was read from. The service state may be altered by other write requests. Reads at the same transactionId describe a consistent single point in the service history.

  • x-ms-error-code – String error code indicating what went wrong.

Response JSON Object:

  • message (string) – Human-readable description of current recovery progress. (required)

  • recoveryThreshold (integer) – A non-negative JSON-safe integer (ie max is 2^53 - 1) (required)

  • submittedCount (integer) – A non-negative JSON-safe integer (ie max is 2^53 - 1) (required)

GET /gov/service/constitution

Retrieve the constitution which controls governance changes on this service.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 200 OK – The request has succeeded.

  • default – An unexpected error response.

Response Headers:

  • x-ms-ccf-transaction-id – Identifier for transaction this response was read from. The service state may be altered by other write requests. Reads at the same transactionId describe a consistent single point in the service history.

  • x-ms-error-code – String error code indicating what went wrong.

Response JSON Object:

  • constitution (string) – Javascript source code of constitution. (required)

GET /gov/service/info

Returns general information about the service, including whether it is a recovery or original service.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 200 OK – The request has succeeded.

  • default – An unexpected error response.

Response Headers:

  • x-ms-ccf-transaction-id – Identifier for transaction this response was read from. The service state may be altered by other write requests. Reads at the same transactionId describe a consistent single point in the service history.

  • x-ms-error-code – String error code indicating what went wrong.

Response JSON Object:

  • certificate (string) – PEM encoding of a cryptographic identifier. Contains a base64-encoded payload wrapped in content type identifiers. (required)

  • configuration.maximumNodeCertificateValidityDays (integer) – A non-negative JSON-safe integer (ie max is 2^53 - 1) (required)

  • configuration.recentCoseProposalsWindowSize (integer) – A non-negative JSON-safe integer (ie max is 2^53 - 1) (required)

  • creationTransactionId (string) – Uniquely identifies an atomic transaction within a CCF service. Composed of a term number and sequence number. Sequence numbers increase monotonically, apart from during elections where the service may reuse an existing sequence number. Each election will result in a new, higher term number being used for the conflicting and future sequence numbers. (required)

  • previousServiceCreationTransactionId (string) – Uniquely identifies an atomic transaction within a CCF service. Composed of a term number and sequence number. Sequence numbers increase monotonically, apart from during elections where the service may reuse an existing sequence number. Each election will result in a new, higher term number being used for the conflicting and future sequence numbers.

  • recoveryCount (integer) – A non-negative JSON-safe integer (ie max is 2^53 - 1) (required)

  • serviceData (any) – Arbitrary service-defined metadata about this service. May be used by constitution or application code, but will not affect any core framework decisions.

  • status (string) – State machine values for current service lifetime. New services start in Opening, and transition to Open via a governance proposal. They will only accept user transactions on the /app endpoints once they are Open. Recovery services have additional states where they must wait for members to submit sufficient recovery shares to access the previous ledger secrets, and while they are decrypting and replaying the previous ledger contents. (required)

GET /gov/service/javascript-app

Retrieve details of Javascript application and execution engine.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 200 OK – The request has succeeded.

  • default – An unexpected error response.

Response Headers:

  • x-ms-ccf-transaction-id – Identifier for transaction this response was read from. The service state may be altered by other write requests. Reads at the same transactionId describe a consistent single point in the service history.

  • x-ms-error-code – String error code indicating what went wrong.

Response JSON Object:

  • endpoints (object) – The collection of endpoints exposed by the application. Keyed by path. (required)

GET /gov/service/join-policy

Retrieve policy data which determines whether new nodes are permitted to join the service. This describes the hardware attestations which are acceptable to the service, demonstrating a joining node is running approved code.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 200 OK – The request has succeeded.

  • default – An unexpected error response.

Response Headers:

  • x-ms-ccf-transaction-id – Identifier for transaction this response was read from. The service state may be altered by other write requests. Reads at the same transactionId describe a consistent single point in the service history.

  • x-ms-error-code – String error code indicating what went wrong.

Response JSON Object:

  • sgx.measurements[] (string) –

  • snp.hostData (object) – Collection of acceptable host data values. (required)

  • snp.measurements[] (string) –

  • snp.uvmEndorsements (object) – Collection of acceptable UVM endorsements. Keyed by endorser’s did. (required)

GET /gov/service/jwk

Returns information about OpenID Connect identity providers.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 200 OK – The request has succeeded.

  • default – An unexpected error response.

Response Headers:

  • x-ms-ccf-transaction-id – Identifier for transaction this response was read from. The service state may be altered by other write requests. Reads at the same transactionId describe a consistent single point in the service history.

  • x-ms-error-code – String error code indicating what went wrong.

Response JSON Object:

  • caCertBundles (object) – Collection of CAs used to authenticate connections with issuers. Keyed by governance-controlled bundle names. (required)

  • issuers (object) – Collection of JWT issuers. Keyed by issuer ID. (required)

  • keys (object) – Collection of retrieved JWKs. Keyed by kid. (required)

GET /gov/service/members

Retrieve list of all members who govern this service.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 200 OK – The request has succeeded.

  • default – An unexpected error response.

Response Headers:

  • x-ms-ccf-transaction-id – Identifier for transaction this response was read from. The service state may be altered by other write requests. Reads at the same transactionId describe a consistent single point in the service history.

  • x-ms-error-code – String error code indicating what went wrong.

Response JSON Object:

  • nextLink (string) – The link to the next page of items

  • value[].certificate (string) – PEM encoding of a cryptographic identifier. Contains a base64-encoded payload wrapped in content type identifiers. (required)

  • value[].memberData (any) – Arbitrary service-defined metadata about this member. May be used by constitution or application code, but will not affect any core framework decisions.

  • value[].memberId (string) – Hex encoding of SHA-256 of a member certificate’s fingerprint. (required)

  • value[].publicEncryptionKey (string) – PEM encoding of a cryptographic identifier. Contains a base64-encoded payload wrapped in content type identifiers.

  • value[].status (string) – Possible states for a CCF governing member. (required)

GET /gov/service/members/{memberId}

Retrieve a single governing member, by ID.

Parameters:

  • memberId (string) – ID of CCF member who this object refers to.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 200 OK – The request has succeeded.

  • default – An unexpected error response.

Response Headers:

  • x-ms-ccf-transaction-id – Identifier for transaction this response was read from. The service state may be altered by other write requests. Reads at the same transactionId describe a consistent single point in the service history.

  • x-ms-error-code – String error code indicating what went wrong.

Response JSON Object:

  • certificate (string) – PEM encoding of a cryptographic identifier. Contains a base64-encoded payload wrapped in content type identifiers. (required)

  • memberData (any) – Arbitrary service-defined metadata about this member. May be used by constitution or application code, but will not affect any core framework decisions.

  • memberId (string) – Hex encoding of SHA-256 of a member certificate’s fingerprint. (required)

  • publicEncryptionKey (string) – PEM encoding of a cryptographic identifier. Contains a base64-encoded payload wrapped in content type identifiers.

  • status (string) – Possible states for a CCF governing member. (required)

GET /gov/service/nodes

Retrieve list of all nodes participating in this service.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 200 OK – The request has succeeded.

  • default – An unexpected error response.

Response Headers:

  • x-ms-ccf-transaction-id – Identifier for transaction this response was read from. The service state may be altered by other write requests. Reads at the same transactionId describe a consistent single point in the service history.

  • x-ms-error-code – String error code indicating what went wrong.

Response JSON Object:

  • nextLink (string) – The link to the next page of items

  • value[].certificate (string) – PEM encoding of a cryptographic identifier. Contains a base64-encoded payload wrapped in content type identifiers. (required)

  • value[].nodeData (any) – Arbitrary service-defined metadata about this node. May be used by constitution or application code, but will not affect any core framework decisions.

  • value[].nodeId (string) – Hex encoding of SHA-256 of a node’s public key. (required)

  • value[].quoteInfo.format (string) – Discriminator property for QuoteInfo. (required)

  • value[].retiredCommitted (boolean) – This is false during node’s normal operation. It transitions to true once the node has been retired, and that retirement has been committed by the service. At this point it is safe to terminate a node. Terminating a node any earlier may affect liveness of the service. (required)

  • value[].rpcInterfaces (object) – A collection of interfaces by which this node may be contacted. Some may be limited to private networks, and others may be DNS names or internet-public network addresses. The keys are arbitrary strings determined by the node operator. (required)

  • value[].status (string) – Lifecycle state of a CCF node. Nodes will generally start as Pending, then transition to Trusted, then to Retired. They are only full participants in the service while they are Trusted. (required)

GET /gov/service/nodes/{nodeId}

Retrieve a single node, by ID.

Parameters:

  • nodeId (string) – ID of CCF node who this object refers to.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 200 OK – The request has succeeded.

  • default – An unexpected error response.

Response Headers:

  • x-ms-ccf-transaction-id – Identifier for transaction this response was read from. The service state may be altered by other write requests. Reads at the same transactionId describe a consistent single point in the service history.

  • x-ms-error-code – String error code indicating what went wrong.

Response JSON Object:

  • certificate (string) – PEM encoding of a cryptographic identifier. Contains a base64-encoded payload wrapped in content type identifiers. (required)

  • nodeData (any) – Arbitrary service-defined metadata about this node. May be used by constitution or application code, but will not affect any core framework decisions.

  • nodeId (string) – Hex encoding of SHA-256 of a node’s public key. (required)

  • quoteInfo.format (string) – Discriminator property for QuoteInfo. (required)

  • retiredCommitted (boolean) – This is false during node’s normal operation. It transitions to true once the node has been retired, and that retirement has been committed by the service. At this point it is safe to terminate a node. Terminating a node any earlier may affect liveness of the service. (required)

  • rpcInterfaces (object) – A collection of interfaces by which this node may be contacted. Some may be limited to private networks, and others may be DNS names or internet-public network addresses. The keys are arbitrary strings determined by the node operator. (required)

  • status (string) – Lifecycle state of a CCF node. Nodes will generally start as Pending, then transition to Trusted, then to Retired. They are only full participants in the service while they are Trusted. (required)

GET /gov/service/transactions/{transactionId}

Get status of transaction by transaction ID, to determine whether it has committed.

Parameters:

  • transactionId (string) – Identifier of the requested transaction.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 200 OK – The request has succeeded.

  • default – An unexpected error response.

Response Headers:

  • x-ms-error-code – String error code indicating what went wrong.

Response JSON Object:
GET /gov/service/transactions/commit

Get latest committed transaction.

Query Parameters:

  • api-version (string) – The API version to use for this operation.

Status Codes:

  • 200 OK – The request has succeeded.

  • default – An unexpected error response.

Response Headers:

  • x-ms-error-code – String error code indicating what went wrong.

Response JSON Object:

  • status (string) – Possible states for a CCF transaction. See docs for details: https://microsoft.github.io/CCF/main/use_apps/verify_tx.html#checking-for-commit (required)

  • transactionId (string) – Uniquely identifies an atomic transaction within a CCF service. Composed of a term number and sequence number. Sequence numbers increase monotonically, apart from during elections where the service may reuse an existing sequence number. Each election will result in a new, higher term number being used for the conflicting and future sequence numbers. (required)