# Adding Endorser Support to BPA

The [Business Partner Agent (BPA)](https://github.com/hyperledger-labs/business-partner-agent) provides a UI and some value-added capabilities for businesses to run on an Aries network.

The BPA consists of a backend set of services (implemented in Java) that provide an interface to the BPA agent's aca-py instance. This backend exposes a set of HTTP endpoints, and provides a listener endpoint to receive webhooks from the aca-py agent.

Adding Endorser support will involve the following changes, which are described below.

artifact Vue_App {
  folder Author {
      artifact Manage_Schema
      artifact Manage_Cred_Def
  }
  folder Endorser {
     artifact Connections
     artifact Transactions
  }
}

artifact backend {
    together {
        artifact BPA_API {
          folder Txn_Endorser_API {
          }
          folder Txn_Author_API {
          }
        }

        artifact BPA_Web_Hooks {
          folder Endorser_Hooks {
          }
        }
    }

    together {
        database BPA_db #line.dotted

        artifact aca_py {
          database wallet
        }
    }
}

Vue_App --[hidden]d-> backend
Endorser -down-> Txn_Endorser_API
Author -down-> Txn_Author_API
Txn_Endorser_API --> aca_py
Txn_Author_API --> aca_py
aca_py -up-> Endorser_Hooks
Endorser_Hooks .down.> BPA_db
Txn_Endorser_API .down.> BPA_db
Txn_Author_API .down.> BPA_db

## Configuration and Startup Support

Each BPA instance will need to be configured as Endorser or Author (Endorser can write to the ledger; Author can't). The Endorser will also need to be configured as to whether they will provide Endorser services or not (for example a BPA can be setup with an Endorser DID but only to write their own information to the ledger).

For Authors, they will need a configuration setting for the default Endorser to connect to (Endorser endpoint and DID, and possibly a static invitation to connect).

For Authors the connection to the Endorser would be automatic (on startup, if there is no Endorser connection, then establish one). For Endorsers, the BPA could be setup to either accept Author connections automatically or provide a UI to manually list/accept Author connection requests.

## Adding Backend Endorser Protocol Support

The backend code exposes endpoints for the Vue app to call aca-py services. Support will need to be added for aca-py's "transaction" API's, which are used to query transactions, ask for endorsement (Author), endorse or refuse to endorse (Endorser) and write the transaction to the ledger (Author or Endorser).

Support will have to be added to the schema and credential definition endpoints to support the additional "Endorser Protocol" parameters - should the transaction be written to the ledger directly? And if not, what are the Endorser settings?

A separate BPA database may need to be established. The functionality *can* be implemented by just relying on aca-py's internal queues (transaction exchange records etc.) however if any meaningful configuration or auditing needs to be applied (for example a record of *who* endorsed *what* transactions *when*) then a BPA database would need to be implemented.

## Adding Frontend Support for the Endorser Role

The Endorser will need a UI to:

- View/approve author connections
- View/approve/reject transaction endorsement requests

Approval of Author connections and transaction endorsements *could* be configured to be automatic (or could be based on rules) however at minimum the Endorser UI would need to list transactions and their status (awaiting endorsement, endorsed, etc.) and provide some filtering capabilities (e.g. show me Endorsements for the past week).

Integration with aca-py would be via the backend API endpoints.

Note that the Endorser role and whether to provide Endorsement support to Authors would be two separate configurations (i.e. an Endorser can write their own transactions to the ledger buy *may* not want to provide Endorsement services to other Authors).

Relevant backend functions:

- Connection API
- List Transactions
- Endorse transaction request
- Reject transaction request

Relevant web hooks:

- Depending on configuration, automatically approve Author Connection requests and Endorsement requests

## Adding Frontend Support for the Author Role

If an Author does not have write access to the ledger, then they *must* be configured with an Endorser. Establishing a connection to the Endorser should be automatic and configured via configuration settings.

If an Author creates a Schema or Credential Definition, then the UI must provide the additional parameters to the API endpoint - a flag to indicate that the transaction must be endorsed, and the relevant Endorser info (i.e. the connection id). The existing UI for creating the Schema or Credential Definition would not need to change.

The Schema/Credential Definition *List* UI would also need to display any transactions-in-flight, and potentially give the Author the option to cancel or re-send the transaction to the endorser.

Once the transaction is endorsed and the Schema or Credential Definition created, then the transaction need not be displayed.

Relevant backend functions:

- Create Schema
- Create Credential Definition
- Request Endorsement
- Resend Endorsement Request
- Cancel Endorsement Request
- Write Transaction to Ledger
- List Transactions

Relevant web hooks:

- Receive endorsed transaction - the web hook would automatically call the "write" endpoint when an Endorsement message was received
- Potentially send notifications upon receipt of other message types

## Modes and their Policies/Rules

To implement mentioned features the BPA needs to support three modes:

1. ENDORSER_PRIVATE - which is the default
2. ENDORSER_PUBLIC
3. AUTHOR

Each mode requires a different set of rules/policies in the backend to be run either on startup or during runtime.

1. ENDORSER_PRIVATE

This is basically what we have now, meaning all functionality that is added to support the other modes should not affect that one.

2. ENDORSER_PUBLIC

- Accepts any connection
- Can auto accept further endorser requests from the same connection after the first one has been allowed
- Throttling of requests

3. AUTHOR

- Auto connect to endorser on startup

Also each mode needs different startup flags. If this gets to complicated I would recommend to switch to micronaut's configuration properties so that the BPA can fail if the configured properties do not match the configured mode.

### Switching between the modes

We have two options here, first do not allow switching between the modes and fail on startup if that happens. Second, allow where it makes sense.

- AUTHOR -> ENDORSER_XXX depends if indy even allows this
- ENDORSER_PUBLIC -> ENDORSER_PRIVATE - probably deny
- ENDORSER_PRIVATE -> ENDORSER_PUBLIC - allow
- ENDORSER -> AUTHOR - probably deny, but in theory a endorser could always use another endorser especially if we think multi ledger where one might be endorser on one and author on another

## Feature Toggles

To sepparate the modes in the frontend/backend the BPA needs to dynamically enable/disable features so that not all three are active at the same time. To do this we have several options.

1. In the Frontend

The UI can load the current state from the backend and then show/hide certain parts.

2. In the Backend

Here we need the following

- For endpoints that stay the same, but should do diffenrent things based on the mode we need either consistency checks, and/or a toggle that switches the implementation based on the mode
- For whole new API's like the endorser functionality the whole thing needs to be made a conditional bean so that the bean is not available to the other modes. Basically the same behaviour that we implemented in the web mode
- Mode specific implementations should be maintained in a sepparate package below impl
- Startup tasks should also be sepparated by mode and maybe based on a rules engine