# Revocation Registry Handling in ACA-Py

This document covers a proposed division of labour between the controller and ACA-Py in managing revocation registries.

On this first draft, the details of the API cover only the necessary data and may be missing required information. I'm sure this is naive and there are complications to doing this, but from an information management perspective, this is a possible division of labour/tracking between ACA-Py and the Controller.

## Division of Responsibilities

The division of responsibility is defined such that the Controller deals with credentials from a business perspective, while ACA-Py handles the messy work of interacting with the Indy ledger as required. For example, the Controller need not know anything about what revocation register is being used, or when a revocation register is used up and a new one is needed. Those are messy things that only ACA-Py needs to worry about.

In this section is a list of the responsibilities. The remainder of the document describes the how those responsibilities manifest in actions, and provides some detail of those actions.

### Controller Responsibilities

- Define the Credential Definition, optionally with revocation support using registries of a given size and tails file location
- Publish the tails files
- It would really be nice if this was NOT the controller's problem. Possible?
- Issue credentials
- Persist the ID of issued credentials
- Revoke credentials
- Publish revocations

### ACA-Py Responsibilities

- Create and publish the cred_def and initial rev_reg (if needed)
- Track the issuing of credentials
- When required, transition to a new RevReg
- When a RevReg is first use, create a new one that will be used when the current one is exhausted
- Track revoked but not published credential IDs
- Publish RevEntry transaction with all "to be published" IDs

## Create/Publish Credential Definition

Controller calls API:

- POST /credential_definition/create
- Issuer DID
- Schema ID
- Revocation Y/N
- Revocation Size - between 10 and 20k
- Tails File Locations (server prefix)

### ACA-Py:

- Generate credential definition
- Store information about the creddef in wallet:
- `creddef_id` from Indy and other indy-sdk data
- Tails server location (from query param)
- RevReg size (from query param)
- Active RevReg (initially Null)
- If Revocation is "Y"
- Generate initial Revocation Registry (see below)

On completion, send event to controller with "creddef_id" (or put into "ready" state?). Tails file generation takes a while, depending on its size.

### Controller:

Tracks the Cred Def ID and uses it when needed.

## Generate RevReg

### ACA-Py

An async task managed within ACA-Py, with parameters `creddef_id`, `revreg_size` and `tails_file_location`. Concurrency constraint -- when needed, must be executed exactly once.

For a given `creddef_id`, number of creds per RevReg

- create a new RevReg
- Store information about the RevReg in the wallet
- Indy RevReg ID (implict link back to CredDef)
- RevReg Size
- send event to the Controller with information to allow publishing the tails file
- _Assumes ACA-Py instance cannot publish the tails file_

### Controller

On receipt of a "tails file created" message, Controller publishes the tails file.

## Credential Issue

### ACA-Py

Via an event after /send or /issue, ACA-Py delivers back to the issuer the ID the credential issued, which is either:

- If not using Revocation
- The a credential_id that is (likely) an incrementing number
- If using Revocation
- The a credential ID in the form `RevReg ID+CredInRevRegID`

Other information might be returned, such as the issueance timestamp.

If the issuance triggers a transition from the current RevReg to the next (all credentials issued), add an async task to generate the next RevReg. Note that this transition occurs on the issueance of the very first credential from the CredDef, as the "Current Rev Reg" goes from `Null` to the ID of the first RevReg.

Note that there is a potential concurrency issue if multiple instances of ACA-Py discover in parallel that the current RevReg is full, request the created but not active RevReg be activated, and request the generation of a new RevReg.

If the issuance cannot be completed because there are no available credentials, an error should be returned to the Controller. This should not happen in the normal course of operation as if the current RevReg is full, there is a RevReg already to go.

### Controller

The Controller tracks the credential ID returned in the event with other information about the entity to which it was issued.

## Credential Revoke

### Controller

- POST /credential_definition/revoke
- CredDef ID
- Credential ID
- Recall that this includes both the RevRegID and the CredID within that RevRegId
- Hmm...that ID also contains the CredDef ID, so perhaps the CredDef ID is not needed?
- Publish [Y/N]

### ACA-Py

Adds to a list of pending revocations for the given `creddef_id`.

If publish is true, invokes the async `publishRevocation` action (defined below).

## Publish Revocations

### Controller

- Post /credential_definition/publish_revocation
- Can be invoked as a byproduct of the "Credential Revoke" endpoint described above.

### ACA-Py

- Get the list of pending revocations
- Concurrency handling needed here.
- For each RevReg_ID found in the list
- For each CredID found for that RevRegID
- Update the accumulator (or whatever needs to be done)
- Prepare and execute the RevEntry transaction to publish the revocations
- Send "RevPublishCompleted" event to the Controller with the status of the process