|
| 1 | +# Troubleshooting Aries Cloud Agent Python <!-- omit in toc --> |
| 2 | + |
| 3 | +This document contains some troubleshooting information that contributors to the |
| 4 | +community think may be helpful. Most of the content here assumes the reader has |
| 5 | +gotten started with ACA-Py and has arrived here because of an issue that came up |
| 6 | +in their use of ACA-Py. |
| 7 | + |
| 8 | +Contributions (via pull request) to this document are welcome. Topics added here |
| 9 | +will mostly come from reported issues that contributors think would be helpful |
| 10 | +to the larger community. |
| 11 | + |
| 12 | +## Table of Contents <!-- omit in toc --> |
| 13 | + |
| 14 | +- [Unable to Connect to Ledger](#unable-to-connect-to-ledger) |
| 15 | + - [Local ledger running?](#local-ledger-running) |
| 16 | + - [Any Firewalls](#any-firewalls) |
| 17 | +- [Damaged, Unpublishable Revocation Registry](#damaged-unpublishable-revocation-registry) |
| 18 | + |
| 19 | +## Unable to Connect to Ledger |
| 20 | + |
| 21 | +The most common issue hit by first time users is getting an error on startup "unable to connect to ledger". Here are a list of things to check when you see that error. |
| 22 | + |
| 23 | +### Local ledger running? |
| 24 | + |
| 25 | +Unless you specify via startup parameters or environment variables that you are using a public Hyperledger Indy ledger, ACA-Py assumes that you are running a local ledger -- an instance of [von-network](https://github.com/bcgov/von-network). |
| 26 | +If that is the cause -- have you started your local ledger, and did it startup properly. Things to check: |
| 27 | + |
| 28 | +- Any errors in the startup of von-network? |
| 29 | +- Is the von-network webserver (usually at `https:/localhost:9000`) accessible? If so, can you click on and see the Genesis File? |
| 30 | +- Do you even need a local ledger? If not, you can use a public sandbox ledger, |
| 31 | + such as the [Dev Greenlight ledger](), likely by just prefacing your ACA-Py |
| 32 | + command with `LEDGER_URL=http://dev.greenlight.bcovrin.vonx.io`. For example, |
| 33 | + when running the Alice-Faber demo in the [demo](demo) folder, you can run (for |
| 34 | + example), the Faber agent using the command: |
| 35 | + `LEDGER_URL=http://dev.greenlight.bcovrin.vonx.io ./run_demo faber` |
| 36 | + |
| 37 | +### Any Firewalls |
| 38 | + |
| 39 | +Do you have any firewalls in play that might be blocking the ports that are used by the ledger, notably 9701-9708? To access a ledger |
| 40 | +the ACA-Py instance must be able to get to those ports of the ledger, regardless if the ledger is local or remote. |
| 41 | + |
| 42 | +## Damaged, Unpublishable Revocation Registry |
| 43 | + |
| 44 | +We have discovered that in the ACA-Py AnonCreds implementation, it is possible |
| 45 | +to get into a state where the publishing of updates to a Revocation Registry |
| 46 | +(RevReg) is impossible. This can happen where ACA-Py starts to publish an update |
| 47 | +to the RevReg, but the write transaction to the Hyperledger Indy ledger fails |
| 48 | +for some reason. When a credential revocation is published, aca-py (via indy-sdk |
| 49 | +or askar/credx) updates the revocation state in the wallet as well as on the |
| 50 | +ledger. The revocation state is dependant on whatever the previous revocation |
| 51 | +state is/was, so if the ledger and wallet are mis-matched the publish will fail. |
| 52 | +(Andrew/s PR # 1804 (merged) should mitigate but probably won't completely |
| 53 | +eliminate this from happening). |
| 54 | + |
| 55 | +For example, in case we've seen, the write RevRegEntry transaction failed at the |
| 56 | +ledger because there was a problem with accepting the TAA (Transaction Author |
| 57 | +Agreement). Once the error occurred, the RevReg state held by the ACA-Py agent, |
| 58 | +and the RevReg state on the ledger were different. Even after the ability to |
| 59 | +write to the ledger was restored, the RevReg could still not be published |
| 60 | +because of the differences in the RevReg state. Such a situation can now be |
| 61 | +corrected, as follows: |
| 62 | + |
| 63 | +To address this issue, some new endpoints were added to ACA-Py in Release 0.7.4, |
| 64 | +as follows: |
| 65 | + |
| 66 | +- GET `/revocation/registry/<id>/issued` - counts of the number of issued/revoked |
| 67 | + within a registry |
| 68 | +- GET `/revocation/registry/<id>/issued/details` - details of all credentials |
| 69 | + issued/revoked within a registry |
| 70 | +- GET `/revocation/registry/<id>/issued/indy_recs` - calculated rev_reg_delta from |
| 71 | + the ledger |
| 72 | + - This is used to compare ledger revoked vs wallet revoked credentials, which |
| 73 | + is essentially the state of the RevReg on the ledger and in ACA-Py. Where |
| 74 | + there is a difference, we have an error. |
| 75 | +- PUT `/revocation/registry/<id>/fix-revocation-entry-state` - publish an update |
| 76 | + to the RevReg state on the ledger to bring it into alignment with what is in |
| 77 | + the ACA-Py instance. |
| 78 | + - There is a boolean parameter (`apply_ledger_update`) to control whether the |
| 79 | + ledger entry actually gets published so, if you are so inclined, you can |
| 80 | + call the endpoint to see what the transaction would be, before you actually |
| 81 | + try to do a ledger update. This will return: |
| 82 | + - `rev_reg_delta` - same as the ".../indy_recs" endpoint |
| 83 | + - `accum_calculated` - transaction to write to ledger |
| 84 | + - `accum_fixed` - If `apply_ledger_update`, the transaction actually written |
| 85 | + to the ledger |
| 86 | + |
| 87 | +Note that there is (currently) a backlog item to prevent the wallet and ledger |
| 88 | +from getting out of sync (e.g. don't update the ACA-Py RevReg state if the |
| 89 | +ledger write fails), but even after that change is made, having this ability |
| 90 | +will be retained for use if needed. |
| 91 | + |
| 92 | +We originally ran into this due to the TAA acceptance getting lost when |
| 93 | +switching to multi-ledger (as described |
| 94 | +[here](https://github.com/hyperledger/aries-cloudagent-python/blob/main/Multiledger.md#a-special-warning-for-taa-acceptance). |
| 95 | +Note that this is one reason how this "out of sync" scenario can occur, but |
| 96 | +there may be others. |
| 97 | + |
| 98 | +We add an integration test that demonstrates/tests this issue [here](https://github.com/hyperledger/aries-cloudagent-python/blob/main/demo/features/taa-txn-author-acceptance.feature#L67). |
| 99 | + |
| 100 | +To run the scenario either manually or using the integration tests, you can do the following: |
| 101 | + |
| 102 | +- Start von-network in TAA mode: |
| 103 | + - `./manage start --taa-sample --logs` |
| 104 | +- Start the tails server as usual: |
| 105 | + - `./manage start --logs` |
| 106 | +- To run the scenario manually, start faber and let the agent know it needs to TAA-accept before doing any ledger writes: |
| 107 | + - `./run_demo faber --revocation --taa-accept`, and then you can run through all the transactions using the Swagger page. |
| 108 | +- To run the scenario via an integration test, run: |
| 109 | + - `./run_bdd -t @taa_required` |
0 commit comments