# Aries Endorser Service

## Requirements (from Stephen)

Please create a basic Endorser Service using ACA-Py that can be deployed as needed and used to provide Hyperledger Indy network endorsing of transactions for authors to a given network. The following is a brief summary of the requirements for the service, all of which are based on current functionality of ACA-Py.

1. Be configured to have a public DID that is used for connections
- Since we ultimately want to allow a single Endorser service to support multiple networks, the Endorser DID and public DID should be handled separately, even if they are the same DID.
- Note not currently supported
2. Be configured to start up with a given endorser DID for a given network
- The Service should know what network there Endorser is far, even if it Endorsers transactions only for a single network.
- Note currently only supports a single network
3. An "allow" list of connections for which Endorsements are permitted.
- Note each connection can be configured to auto-endorse or allow manual endorsements
5. A mechanism to allow for extending the "allow" list of authors in a way that is as convenient as possible.
- For example, accept the connection, receive an endorsement request, reject it, notify (somehow) somebody that a new author has a requested endorsing, update the allow list.
- Ultimately, we want a UI for the service that allows for interactive handling of the allow list.
- We need right away a method to know what authors are authorized to use the service. Perhaps an endpoint that lists the allow list along with the metadata about the authors. That means that the administrators should include sufficient information on the allow list to be displayed
- e.g. name of service, URL for service, name of service contact, etc.
- Note this configuration is added to the connection, once the Author is connected
6. Define a deployment approach for DTS that enables deploying two instances of the service (dev, test, prod each) supporting:
- dev: BCovrin, CANdy-Dev
- test: Sovrin Staging, CANdy-Dev (later test)
- prod: Sovrin MainNet, CANdy-Dev (later prod)
- Note deploy configuration is in a separate repository than the Endorser service itself; currently each network will require a separate Endorser service
7. Instructions for how to setup authors to use the service.
- Note TBD once we have a service setup and we have confirmed how Authors will be setup

This could become a Hyperledger Aries repo.

## Repositories

The [aries-endorser-service](https://github.com/bcgov/aries-endorser-service) repository will contain the code necessary to run the endorser service, including scripts to run the service locally (for developers and implementers looking to evaluate the service).
- Existing repo, see notes above

The [dts-endorser-service](https://github.com/bcgov/dts-endorser-service) will contain the deployment scripts, configuration etc for the DTS deployment of the endorser service.
- TBD

## Design

The endorser service will consist of the following components:

artifact aries-endorser-service {
    folder acapy_agent
    folder endorser_controller 
    folder endorser_ui
    database endorser_db
    database agent_db
    folder local_config
}

endorser_ui -right-> endorser_controller
endorser_controller -right-> acapy_agent
endorser_controller -down-> endorser_db
acapy_agent -down-> agent_db
endorser_db -[hidden]down-> local_config

artifact dts-endorser-service {
    folder deployment_config
}

deployment_config -up-> local_config

The `acapy_agent` will be a deployment of [aca-py](https://github.com/hyperledger/aries-cloudagent-python), configured to run as an [Endorser](https://github.com/hyperledger/aries-cloudagent-python/blob/main/Endorser.md).

The `endorser_controller` will manage the aca-py agent's connections and all endorsement requests. Per the above requirements, this controller will:

Manage connections:

- Accept connection requests from Authors. The controller can optionally (based on configuration) auto-accept all connection requests, or allow an administrator to manually accept or reject requests.
- One option is to define a proof request that the Endorser will automatically send to each connected Author, and then the Author could prove their authorization to use the Endorser by supplying a proof. This would allow an issuer to authorize Authors to use the Endorser service (and possibly other services) by issuing them a known credential.
- Allow administrator to record meta-data about the connection - e.g. name of service, URL for service, name of service contact, etc.
- The Administrator can optionally flag the connection as "auto-endorse" (if all endorsement requests are to be endorsed automatically) or "manual-endorse" (if endorsement requests are all to be approved by an administrator).
- In addition to the allow list for connections, having an allow list for dids would also be useful (in an application we're building (Animo) we do it based on did)
- Note this is not implemented yet

Manage traction endorsements:

- Auto-endorse, or allow an Administrator to endorse/reject endorsement request (based on global and connection-specific configuration) for each transaction endorsement request
- Optionally write the endorsed transaction to the ledger (based on Author request in each transaction, using the `please_write` attribute)
- Provide reports to the Administrator to allow review and audit history of transaction endorsements (and writes)
- Reports are still TBD

Other configuration:

- Allow configuration for a public DID to be used for connections, and a separate DID (written to the ledger, known to Authors, but not necessarily the Endorser's configured "public" DID) used to endorse transactions
- I think this requires an aca-py update
- Note not yet supported in the Endorser service
- Allow endorsements for multiple ledgers - this will require a separate Endorser DID per ledger, and potentially a separate public DID for connections as well
- I think this requires an aca-py update
- Note not yet supported in the Endorser service
- Auto-accept connections, or manually approve connections
- Or "proof required" to establish connection with endorser (not yet implemented)
- Auto-endorse transactions, manually approve all transactions, or "per-connection" configuration

## Endorser Controller Design

The endorser controller code will inclde the following components:

folder acapy
folder endorser_ui
folder endorser_controller {
    folder endpoints {
        component webhooks
        component contacts
        component endorse_requests
    }
    folder endpoint_models {
    }
    folder services {
        component webhook_handlers
        component auto_state_handlers
        component endorse_services
    }
    folder db-models {
        component contact_table
        component endorse_req_table
    }
}
database endorser_db
acapy -down-> webhooks
endorser_ui -down-> contacts
endorser_ui -down-> endorse_requests
endpoints -right-> endpoint_models
webhooks -down-> webhook_handlers
webhook_handlers -down-> auto_state_handlers
webhook_handlers -right-> endorse_services
auto_state_handlers -right-> endorse_services
contacts -down-> endorse_services
endorse_requests -down-> endorse_services
endorse_services -down-> contact_table
endorse_services -down-> endorse_req_table
endorse_services -right-> endorser_db

- endpoints - provides http services for aca-py and the endorser UI to invoke services
- services - provides the functionality to implement each services, specifically:
- webhook handlers - functions to support each aca-py invoked webhook, by webhook type and state
- auto_state_handlers - determine if the controller should auto-respond to web hooks (e.g. to auto-endorse received requests) and invoke the necessary service
- endorse_services - the actual implementation of each service
- db - mapping objects for endorser database tables

## Deployment Approach

The [aries-endorser-service](https://github.com/bcgov/aries-endorser-service) repository contains scripts and configuration for running locally:

- docker and docker-compose scripts for building and running containers locally
- configuration to support a local installation

The [dts-endorser-service](https://github.com/bcgov/dts-endorser-service) will contain scripts and configuration for running an endorser instance on openshift.

Regarding support for multiple instances of the service (e.g. 2 instances in `dev`, one supporting `BCovrin` and one supporting `CANdy-Dev`) this will require deployment of 2 separate instances of the endorser service (or multiple instances to support multiple ledgers). (Multi-tenancy is not an option (currently) as aca-py supports only one writable ledger, and this is configured for aca-py globally, not per-tenant.)

Note this deployment support is similar to:

- [Issuer Kit](https://github.com/bcgov/issuer-kit) - a tool for setting up new VC issuers
- [Essential Services Delivery](https://github.com/bcgov/essential-services-delivery) demo - an example of a specific demplyment of Issuer Kit (in this case for several issuers to support the essential services demo)

## Aca-Py Configuration

The Endorser service runs the Aca-Py agent with all "auto" flags disabled. The Endorser controller is responsible for handling all requests explicitely (if the Endorser is configured to "auto" respond to a connection or endorsement request, the Controller will handle it).

## Endorser Controller API

Connections:

- list connections
- list pending connection requests
- accept connection request
- reject connection request
- add/update connection meta-data
- configure connection status (auto-endorse, etc)
- disable/delete connection (maybe just set to auto-reject endorsement requests?)

Transactions:

- list endorsement requests
- endorse transaction
- reject endorsement request

Audit/History (TBD):

- list endorsed transactions (by connection, date or all)
- list endorsement stats (by connection, date or all)