# Indy Transaction Flow

The following sequence diagram illustrates a scenario where a Transaction Author requests endorsments from four Endorser Agents.

Actor Author
Author --> Author_Agent: Write Transaction
Author_Agent --> Author_Agent: Prepare Signed Transaction
Author_Agent -> Endorser1: Endorse Request
note left
Author needs 2 endorsements
from 4 possible Endorsers
end note
Actor Endorser
Endorser1 --> Endorser
note right
Endorser may require a UI
to monitor/approve requests
end note
Author_Agent <-- Endorser1: Endorse Response
Author_Agent --> Endorser2: Another Endorse Request
Author_Agent <-- Endorser2: Another Endorse Response
note right
The first 2 Endorsers respond
with signatures
end note
Author_Agent --> Endorser3: Another Endorse Request
Author_Agent <-- Endorser3: Endorse Refuse
note right
The 3rd Endorser refuses
to endorse
end note
Author_Agent -->x Endorser4: Another Endorse Request
note right
There is no response from
Endorser 4 so the Agent
re-sends the request
end note
Author_Agent --> Endorser4: Re-send Endorse Request
Author_Agent x<-- Endorser4: Endorse Response is lost
Author_Agent --> Author_Agent: Prepare Endorsed Transaction
note left
Enough Endorsers respond so 
the Agent prepares the endorsed
Transaction
end note
Database Ledger
Author_Agent --> Ledger: Write Endorsed Transaction
note left
Agent writes the endorsed
Transaction to the Ledger
end note
Author <-- Author_Agent:  Confirm Transaction Write

In this example, the Author needs 2 signatures to write a transaction to the ledger, and has four possible Endorsers available.

The "Please Sign This" Protocol itself (which is used in the above example for Endorsement) is just a simple request/response and is repeated for each of the Endorsers (or more generally "Signers").

The possible Signer responses are:

- Respond with a signature - this is the scenario illustrated for the first two Endorsers. In one case, the Endorser Agent presents the request to a user for approval
- Respond with a refusal to sign (e.g. Endorser 3 above)
- Not respond - as in the case of Endorser 4 the Author doesn't receive a response, so re-sends the request

Once the Author has enough signatures they can write the transaction to the ledger an ignore any subsequent requests.

The more general "Please Sign This" protocol can be illustrated as:

Actor Requester
Requester --> Requester_Agent: Initiate Request
Requester_Agent -> Signer_Agent: Please Sign Request
Actor Signer
Signer_Agent --> Signer: Notify
Signer_Agent <-- Signer: Sign
Requester_Agent <-- Signer_Agent: Sign Response
Requester <-- Requester_Agent:  Confirm Sign Response

If multiple signatures are required, the Requester must send multiple requests, either serially or in parallel, depending on the multi-sig requirements. This functionality is outside the scope of the "please sign this" protocol.

## Aca-py Implementation - Signer (Endorser)

The Signer agent needs to identify Connections as Requester (or Author) Connections (that can send attachments to be signed). (This assumes the Connections are setup in advance.)

As Aca-py receives Sign (Endorse) requests, it saves them in Sign/Endorse Exchange records and notifies the controller via webhook notifications. If the controller supports a UI it can display these requests and allow a user to accept/refuse the request. (Aca-py should also support an `--auto-sign-requests` flag for testing.)

Note - suggestion is to use the Aries Aca-py Plugin Toolbox to provide a demo UI.

## Aca-py Implementation - Requester (Author)

The Requester agent needs to identify Connections as Signer (Endorser) Connections (this assumes the Connections are setup in advance), *or* configure the Agent as an Signer (in which case it can sign its own requests, and in the Indy transaction scenario, write its own transactions to the Ledger).

In the Indy case, when the Author initiates any ledger write request (write transaction, write schema or cred def), if the Author doesn't have write ledger access, the agent will:

- Assemble an Endorser Exchange record, containing Endorsement Requests for each Endorser available
- Save this record (which will trigger a notification to the Controller)
- Send an Endorsement Request to each Endorser (which will also trigger Controller notifications)
- Update the Endorser Exchange record as responses are received (which will also trigger Contoller notifications)
- Write the ledger transaction once enough responses (signatures) have been received

It will be up to the Controller to take action if any of the following situations occur:

- Responses are not received from some/all Endorsers within the requested timeframe (the Controller can trigger requests to be re-sent)
- Not enough positive responses (signatures) are received to write the transaction (i.e. Endorsers responsd with "won't" or "can't" sign)

Note - for api's that write transactions to the ledger (like schemas or cred defs) the suggestion is to add a new api that understands how to interact with the Endorser protocol, and will return different status values than the existing api.

# "Please Sign This" Protocol

This protocol allows one agent to request another agent to sign an attachment and return the signature.

For Indy, in order to submit transactions to the ledger, it is often necessary for agents to obtain signatures from one or more endorsers. This protocol allows Authors to request signatures from Endorsers using DIDComm, and enable the Authors to create Indy transactions that can be written to the ledger.

## "Please Sign This" Request Message

This message represents a request from a "requester" to a "signer" to provide a signature for the attachment(s) included in the request. The request will indicate the attached message type as well as the requested signature type, and "goal codes" will be included to indicate the "goal" of the requester, and stated goal of the signer.

The message attachment will follow the structure defined in Aries RFC 0017 and *may* be signed (using a JWS signature, outside of the attachment itself).

When working with a transaction request for an Indy-Node ledger, the attached message must be a prepared Indy transaction, setting the `endorser` field to the public DID of the Endorser, and then signing the request using the public DID of the submitter. Depending on the ledger instance, the transaction author agreement acceptance (`taaAcceptance`) must also be added before signing the request. The transaction signature and TAA acceptance are part of the attachment and *not* the attachment's JWS signature, which may *also* be present.

Question - what does the Indy transaction look like for multiple endorsers? Since the endorser did is part of the transaction (that gets signed) how do you support multi signatures?

{
  "@type": "http://didcomm.org/sign-attachment/%VER/signature-request",
  "@id": "fce30ed1-96f8-44c9-95cf-b274288009dc",
  "comment": "some comment",
  "signature_request": [{
      "context": "did:sov",
      "method": "add-signature",
      "signature_type": "<requested signature type>",
      "signer_goal_code": "transaction.endorse",
      "author_goal_code": "ledger.transaction.write"
  }],
  "~timing": {
    "expires_time": "2020-12-13T17:29:06+0000"
  },
  "formats" : [{
    "attach_id" : "<attach@id value>",
    "format" : "<format-and-version>",
  }],
  "messages~attach": [{
    "@id": "143c458d-1b1c-40c7-ab85-4d16808ddf0a",
    "mime-type": "application/json",
    "data": {
      "json": {
        "endorser": "V4SGRU86Z58d6TV7PBUe6f",
        "identifier": "LjgpST2rjsoxYegQDRm7EL",
        "operation": {
          "data": {
            "attr_names": ["first_name", "last_name"],
            "name": "test_schema",
            "version": "2.1"
          },
          "type": "101"
        },
        "protocolVersion": 2,
        "reqId": 1597766666168851000,
        "signatures": {
          "LjgpST2rjsoxYegQDRm7EL": "4uq1mUATKMn6Y9sTgwqaGWGTTsYm7py2c2M8x1EVDTWKZArwyuPgjUEw5UBysWNbkf2SN6SqVwbfSqCfnbm1Vnfw"
        },
        "taaAcceptance": { 
          "mechanism": "manual",
          "taaDigest": "f50feca75664270842bd4202c2ab977006761d36bd6f23e4c6a7e0fc2feb9f62",
          "time": 1597708800
        }
      }
    }
  }]
}

The attachment signature, if present:

{
  "@type": "http://didcomm.org/sign-attachment/%VER/signature-request",
  "@id": "fce30ed1-96f8-44c9-95cf-b274288009dc",
  "comment": "some comment",
  "signature_request": [{ ...}],
  "~timing": { ...},
  "formats" : [{ ... }],
  "messages~attach": [{
    "@id": "143c458d-1b1c-40c7-ab85-4d16808ddf0a",
    "mime-type": "application/json",
    "data": {
      "json": { ... },
      "base64": "eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ... (bytes omitted to shorten)",
      "jws": {
        // payload: ...,  <-- omitted: refer to base64 content when validating
        "header": {
          "kid": "did:key:z6MkmjY8GnV5i9YTDtPETC2uUAW6ejw3nk5mXF5yci5ab7th"
        },
        "protected": "eyJhbGciOiJFZERTQSIsImlhdCI6MTU4Mzg4... (bytes omitted)",
        "signature": "3dZWsuru7QAVFUCtTd0s7uc1peYEijx4eyt5... (bytes omitted)"
      }
    }
  }]
}

Note that since an Indy transaction *includes* a signature, there is no reason to JWS-sign the attachment.

## "Please Sign This" Response Message

This message represents the response from the "signer" to the "requester" containing the response to the "please sign this" request. The response will contain the requested signature(s), or an indicator that the signer can't or won't sign the request. The request can contain multiple attachments, so the response can contain multiple signatures (or refusals). The response will *not* include the attachment(s) from the request, but each signature will include the `@id` of the associated attachment.

{
  "@type": "http://didcomm.org/sign-attachment/%VER/signature-response",
  "@id": "ece30ed1-96f8-44c9-95cf-b274288009dc",
  "~thread": {
    "thid": "fce30ed1-96f8-44c9-95cf-b274288009dc"
  },
  "signature_response": [{
      "message_id": "143c458d-1b1c-40c7-ab85-4d16808ddf0a",
      "context": "did:sov",
      "method": "add-signature",
      "signer_goal_code": "transaction.endorse" # or "transaction.refuse",
      "signature_type": "<requested signature type>",
      "signature": { ... structure determined by signature type ... }
  }]
}

In the case of an error, a problem report *should* be returned to the requesting agent instead of an endorsement response message. (However if the endorser declines to endorse, they will return a response with that goal code.)

The receipt of an endorsement response should be acknowledged using an ACK.

Question - do we need an ACK? If the Author doesn't receive the signature they can re-request it, the Endorser shouldn't have to track who has received the signature or not.

We *may* want to support a "revoke request" message, so the Author can notify the Endorsers once they've received enough signatures.

# Development Plan

## Aca-py

Note there are additional API endpoints to create transactions and monitor the queue (for both Requesters/Authors and Signers/Endorsers). (See #2 and #3 below.)

For existing endpoints that write ledger transactions (schema, cred def, etc.) the proposal is to add additional endpoints for the "endorser" version of the transaction. The existing endpoints (that assume ledger write capabilities) can be deprecated and removed once existing controllers are updated to use the new "endorser" endpoints. (See #6 below.)

1. Update Connection API to add metadata (tags or roles) to a connection
- Identify Connection as "Endorser" or "Author" (note that other roles may be required for different use cases)
- Query by tag/role
- There is support for "their_role" in some of the API's:
- GET /connections has filter by "their_role"
- /create-static includes "their_role" but /create-invitation and /receive-invitation don't
- Add a new endpoint POST /connections/{conn_id}/update-role {"role": ["r1", "r2", ...]}
- Change the role attribute from scaler to array (a connection can have multiple roles)

2. Define "Please Sign This" API for:

Note that this is the underlying, generic, "Please Sign This" protocol.

a. Requester:
- Create Request
- Query Requests
- Cancel Request
- Resend "Request to Sign"
- Cancel "Request to Sign"

b. Signer:
- Query Requests
- Sign Request and Return
- Refuse Request and Return

3. Define Endorser API for:

Note that these requests, specific to Indy Ledger Transactions, use the underlying "Please Sign This" api, with appropriate attachments and signature requests.

a. Transaction Author:
- Create transaction (to be signed)
- POST /ledger/transaction/create-txn
- *** not sure if this is necessary, or just build into existing API's for schema, cred def etc.
- Query transaction (check status)
- GET /ledger/transaction
- GET /ledger/transaction/{txn_exch_id}
- Cancel transaction (before ledger write)
- POST /ledger/transaction/{txn_exch_id}/cancel-txn
- Resend Endorser request (Endorser didn't reply or refused to sign)
- POST /ledger/transaction/{txn_exch_id}/endorser
{"resend": ["conn_id", "conn_id", ...], "cancel": ["conn_id", ...]}
- Cancel Endorser request
- included in above endpoint

b. Endorser:
- Query transaction
- GET /ledger/transaction
- GET /ledger/transaction/{txn_exch_id}
- Sign transaction and return
- POST /ledger/transaction/{txn_exch_id}/endorse
{"sign": { }, "reject": {...}}
- Refuse transaction and return message
- included in above endpoint

4. Define messages

Note that these are the generic "Please Sign This" request and response.

The Indy Ledger Trasaction Endorse Request and Response will use these messages with appropriate attachment and signature request.

- Send request - request to sign, request cancel, resend
- Return response - signed or not

5. Controller Callback
- Add callbacks on receipt of any inbound messages, and on the transaction write

6. Integrate ledger write protocol into:
- Build into the indy ledger self._submit() method
- will return status of "success", "failed" or "queued for endorsement"
- existing controllers may break - assume that create schema or cred def returns an id if successful
- think about adding an "endorse_and_submit" method - if the wallet DID has write access this can just write to the ledger, if not it will create the transaction and queue for endorsement
- the existing "create" methods would return an error if they can't write to the ledger
- TAA acceptance
- DID create
- Schema create
- ledger.indy.create_and_send_schema()
- calls indy.ledger.build_schema_request() to build the transaction
- ... and then self._submit(), which submits to the ledger
- Cred def create
- ledger.create_and_send_credential_definition()
- calls indy.ledger.build_cred_def_request() to build the transaction
- ... and then self._submit(), which submits to the ledger
- Revocation registry create/update

7. Write transaction to ledger
- Assemble transaction with signatures and write to the ledger

8. Unit/Integration Tests
- Unit tests for all new/updated aca-py code
- Integration tests? (test flow between Transaction Author and Endorser?)
- Add tests to the aries-test-framework and the aca-py backchannel (new tag for endorser tests)

9. Documentation
- Test swagger page for new API
- Tutorial (AliceEndorsesATransaction)
- Update to the Alice/Faber demo?

## Aries Toolbox

1. Incorporate Connection Role into aca-py connection role/tag
2. Add menu option for Transaction Author (create, query, etc)
3. Add menu option for Endorser (query, sign, etc)
4. Update aries-acapy-toolbox-plugin