diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 7039053f..0a065f84 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,5 +1,158 @@ # Aries Cloud Agent Python Changelog +## 1.0.0rc4 + +### July 8, 2024 + +This time we mean it! Release 1.0.0rc4 is, despite the non-zero RC number, the first Release Candidate for what will soon be the official ACA-Py 1.0.0. We started to do a 1.0.0 sequence (releasing several RCs) a long time ago, and decided to gate the transition on some requirements that were not as important as we thought at the time. Now we are **really** ready to publish ACA-Py Release 1.0.0. This release is again pulling from the `main` branch. The previous 1.0.0 RC, `rc3`, was approximately equal to [ACA_Py Release 0.8.2](#082). As such, this RC is a **MAJOR** change from that last one. + +Release 1.0.0rc4 includes just over 100 PRs merged since [Release 0.12.1](#0121). The vast majority of that work was in hardening the product in preparation for this 1.0.0 release. While there are a number of new features, the majority of the focus has been on eliminating technical debt and improving the underlying implementation. The full list of PRs in this release can be [found below](#100rc4-categorized-list-of-pull-requests). here are the highlights of the release: + +- The default underlying Python version has been upgraded to 3.12. Happily, there were minimal code changes to enable the upgrade to 3.12 from the previous Python 3.9. +- Pagination support has been added to a number of Admin API queries for object lists, enabling the development of better user interfaces for large deployments. +- Cleanup in the ACA-Py AnonCreds Revocation Registry handling to prevent errors that were found occurring under certain specific conditions. +- Upgraded pull request and release pipeline, including: + - Enabling a much more aggressive approach to dependabot notifications, beyond just those for security vulnerabilities. Along with those upgrades, we've moved to newer/better build pipeline tooling, such as switching from Black to Ruff, and re-enable per pull request code coverage notifications. + - Many of the PRs in this release are related to dependency updates from dependabot or applied directly. + - A switch to more used tooling, such as a switch from black to ruff. + - Improvements in coverage monitoring of pull requests. +- The start of a [DIDComm v2](https://identity.foundation/didcomm-messaging/spec/) implementation in ACA-Py. The work is not complete, as we are taking an incremental approach to adding DIDComm v2 support. +- A decorator has been added for enabling direct support for Admin API authentication. Previously, the only option to enable (the necessary) Admin API was to put the API behind a proxy that could manage authentication. With this update, ACA-Py deployments can handle authentication directly, without a proxy. +- We have dropped support for the old, archived [Indy SDK]. If you have not migrated your deployment off of the Indy SDK, you must do so now. See this [Indy SDK to Askar migration documentation](#https://aca-py.org/latest/deploying/IndySDKtoAskarMigration/) for guidance. +- Support added for using AnonCreds in [W3C VCDM](https://www.w3.org/TR/vc-data-model-1.1/) format. The support is not fully completed, but on the way. + +### 1.0.0rc4 Breaking Changes + +With the focus of the pull requests for this release on stabilizing the implementation, there were a few breaking changes: + +- The default underlying Python version has been upgraded to 3.12. +- Support for the Indy SDK has been dropped. It had been previously deprecated. See this [Indy SDK to Askar migration documentation](#https://aca-py.org/latest/deploying/IndySDKtoAskarMigration/) for guidance. +- The webhook sent after receipt of presentation by a verifier has been updated to include all of the information needed by the verifier so that the controller does not have to call the "Verify Presentation" endpoint. The issue with calling that endpoint after the presentation has been received is that there is a race condition between the controller and the ACA-Py cleanup process deleting completed Present Proof protocol instances. See [\##3081](https://github.com/hyperledger/aries-cloudagent-python/pull/#3081) for additional details. + +#### 1.0.0rc4 Categorized List of Pull Requests + +- DIDComm and Connection Establishment updates/fixes: + - fix: didexchange manager not checking the did-rotate content correctly [\##3057](https://github.com/hyperledger/aries-cloudagent-python/pull/#3057) [gmulhearn-anonyome](https://github.com/gmulhearn-anonyome) + - fix: respond to did:peer:1 with did:peer:4 [\##3050](https://github.com/hyperledger/aries-cloudagent-python/pull/#3050) [dbluhm](https://github.com/dbluhm) + - DIDComm V2 Initial Implementation [\##2959](https://github.com/hyperledger/aries-cloudagent-python/pull/#2959) [TheTechmage](https://github.com/TheTechmage) + - Feature: use decorators for admin api authentication [\##2860](https://github.com/hyperledger/aries-cloudagent-python/pull/#2860) [esune](https://github.com/esune) + +- Admin API, Startup, OpenAPI/Swagger Updates and Improvements: + - 🐛 fix IndyAttrValue bad reference in OpenAPI spec [\##3090](https://github.com/hyperledger/aries-cloudagent-python/pull/#3090) [ff137](https://github.com/ff137) + - 🎨 improve record querying logic [\##3083](https://github.com/hyperledger/aries-cloudagent-python/pull/#3083) [ff137](https://github.com/ff137) + - 🐛 fix storage record pagination with post-filter query params [\##3082](https://github.com/hyperledger/aries-cloudagent-python/pull/#3082) [ff137](https://github.com/ff137) + - ✨ Add pagination support for listing Connection, Cred Ex, and Pres Ex records [\##3033](https://github.com/hyperledger/aries-cloudagent-python/pull/#3033) [ff137](https://github.com/ff137) + - ✨ Adds support for paginated storage queries, and implements pagination for the wallets_list endpoint [\##3000](https://github.com/hyperledger/aries-cloudagent-python/pull/#3000) [ff137](https://github.com/ff137) + - Enable no-transport mode as startup parameter [\##2990](https://github.com/hyperledger/aries-cloudagent-python/pull/#2990) [PatStLouis](https://github.com/PatStLouis) + +- Test and Demo updates: + - Postgres Demo - Upgrade postgres and change entrypoint file [\##3004](https://github.com/hyperledger/aries-cloudagent-python/pull/#3004) [jamshale](https://github.com/jamshale) + - Example integration test issuing 2 credentials under the same schema [\##2948](https://github.com/hyperledger/aries-cloudagent-python/pull/#2948) [ianco](https://github.com/ianco) + +- Credential Exchange updates and fixes: + - Add by_format to terse webhook for presentations [\##3081](https://github.com/hyperledger/aries-cloudagent-python/pull/#3081) [ianco](https://github.com/ianco) + - Use anoncreds registry for holder credential endpoints [\##3063](https://github.com/hyperledger/aries-cloudagent-python/pull/#3063) [jamshale](https://github.com/jamshale) + - For proof problem handler, allow no connection record (OOB cases), prevent unhandled exception [\##3068](https://github.com/hyperledger/aries-cloudagent-python/pull/#3068) [loneil](https://github.com/loneil) + - Handle failed tails server issuance [Anoncreds] [\##3049](https://github.com/hyperledger/aries-cloudagent-python/pull/#3049) [jamshale](https://github.com/jamshale) + - Prevent getting stuck with no active registry [\##3032](https://github.com/hyperledger/aries-cloudagent-python/pull/#3032) [jamshale](https://github.com/jamshale) + - Fix and refactor anoncreds revocation recovery [\##3029](https://github.com/hyperledger/aries-cloudagent-python/pull/#3029) [jamshale](https://github.com/jamshale) + - Fix issue with requested to revoke before registry creation [\##2995](https://github.com/hyperledger/aries-cloudagent-python/pull/#2995) [jamshale](https://github.com/jamshale) + - Add support for revocable credentials in vc_di handler [\##2967](https://github.com/hyperledger/aries-cloudagent-python/pull/#2967) [EmadAnwer](https://github.com/EmadAnwer) + - Fix clear revocation logic [\##2956](https://github.com/hyperledger/aries-cloudagent-python/pull/#2956) [jamshale](https://github.com/jamshale) + - Anoncreds - Send full registry list when getting revocation states [\##2946](https://github.com/hyperledger/aries-cloudagent-python/pull/#2946) [jamshale](https://github.com/jamshale) + - Add missing VC-DI/LD-Proof verification method option [\##2867](https://github.com/hyperledger/aries-cloudagent-python/pull/#2867) [PatStLouis](https://github.com/PatStLouis) + - feat: Integrate AnonCreds with W3C VCDI Format Support in ACA-Py [\##2861](https://github.com/hyperledger/aries-cloudagent-python/pull/#2861) [sarthakvijayvergiya](https://github.com/sarthakvijayvergiya) + - Correct the response type in send_rev_reg_def [\##2355](https://github.com/hyperledger/aries-cloudagent-python/pull/#2355) [ff137](https://github.com/ff137) + +- Upgrade Updates and Improvements: + - Re-enable ledger plugin when --no-legder is set [\##3070](https://github.com/hyperledger/aries-cloudagent-python/pull/#3070) [PatStLouis](https://github.com/PatStLouis) + - 🐛 fix wallet_update when only extra_settings requested [\##2612](https://github.com/hyperledger/aries-cloudagent-python/pull/#2612) [ff137](https://github.com/ff137) + - Upgrade to anoncreds via api endpoint [\##2922](https://github.com/hyperledger/aries-cloudagent-python/pull/#2922) [jamshale](https://github.com/jamshale) + +- Release management pull requests: + - 1.0.0rc4 [\#3092](https://github.com/hyperledger/aries-cloudagent-python/pull/3092) [swcurran](https://github.com/swcurran) + +- Documentation, publishing process updates: + - fix: print provision messages when auto-provision is triggered [\##3077](https://github.com/hyperledger/aries-cloudagent-python/pull/#3077) [TheTechmage](https://github.com/TheTechmage) + - Rule D417 [\##3072](https://github.com/hyperledger/aries-cloudagent-python/pull/#3072) [jamshale](https://github.com/jamshale) + - Fix - only run integration tests on opened PR's [\##3042](https://github.com/hyperledger/aries-cloudagent-python/pull/#3042) [jamshale](https://github.com/jamshale) + - docs: added section on environment variables [\##3028](https://github.com/hyperledger/aries-cloudagent-python/pull/#3028) [Executioner1939](https://github.com/Executioner1939) + - Fix deprecation warnings [\##2756](https://github.com/hyperledger/aries-cloudagent-python/pull/#2756) [ff137](https://github.com/ff137) + - 🎨 clarify LedgerError message when TAA is required and not accepted [\##2545](https://github.com/hyperledger/aries-cloudagent-python/pull/#2545) [ff137](https://github.com/ff137) + - Chore: fix marshmallow warnings [\##2398](https://github.com/hyperledger/aries-cloudagent-python/pull/#2398) [ff137](https://github.com/ff137) + - Fix formatting and grammatical errors in different readme's [\##2222](https://github.com/hyperledger/aries-cloudagent-python/pull/#2222) [ff137](https://github.com/ff137) + - Fix broken link in README [\##2221](https://github.com/hyperledger/aries-cloudagent-python/pull/#2221) [ff137](https://github.com/ff137) + - Manage integration tests with GitHub Actions (#2952) [\##2996](https://github.com/hyperledger/aries-cloudagent-python/pull/#2996) [jamshale](https://github.com/jamshale) + - Update README.md [\##2927](https://github.com/hyperledger/aries-cloudagent-python/pull/#2927) [KPCOFGS](https://github.com/KPCOFGS) + - Add anoncreds migration guide [\##2881](https://github.com/hyperledger/aries-cloudagent-python/pull/#2881) [jamshale](https://github.com/jamshale) + - Fix formatting and grammatical errors in different readme's [\##2222](https://github.com/hyperledger/aries-cloudagent-python/pull/#2222) [ff137](https://github.com/ff137) + - Fix broken link in README [\##2221](https://github.com/hyperledger/aries-cloudagent-python/pull/#2221) [ff137](https://github.com/ff137) + +- Dependencies and Internal Updates: + - Switch from black to ruff [\##3080](https://github.com/hyperledger/aries-cloudagent-python/pull/#3080) [jamshale](https://github.com/jamshale) + - Upgrade python to version 3.12 [\##3067](https://github.com/hyperledger/aries-cloudagent-python/pull/#3067) [jamshale](https://github.com/jamshale) + - Use a published version of aiohttp-apispec [\##3019](https://github.com/hyperledger/aries-cloudagent-python/pull/#3019) [jamshale](https://github.com/jamshale) + - Add sonarcloud badges [\##3014](https://github.com/hyperledger/aries-cloudagent-python/pull/#3014) [jamshale](https://github.com/jamshale) + - Switch from pytz to dateutil [\##3012](https://github.com/hyperledger/aries-cloudagent-python/pull/#3012) [jamshale](https://github.com/jamshale) + - feat: soft binding for plugin flexibility [\##3010](https://github.com/hyperledger/aries-cloudagent-python/pull/#3010) [dbluhm](https://github.com/dbluhm) + - feat: inject profile and session [\##2997](https://github.com/hyperledger/aries-cloudagent-python/pull/#2997) [dbluhm](https://github.com/dbluhm) + - ✨ Faster uuid generation [\##2994](https://github.com/hyperledger/aries-cloudagent-python/pull/#2994) [ff137](https://github.com/ff137) + - Sonarcloud with code coverage [\##2968](https://github.com/hyperledger/aries-cloudagent-python/pull/#2968) [jamshale](https://github.com/jamshale) + - Fix Snyk sarif file [\##2961](https://github.com/hyperledger/aries-cloudagent-python/pull/#2961) [pradeepp88](https://github.com/pradeepp88) + - Add OpenSSF Scorecard GHA - weekly [\##2955](https://github.com/hyperledger/aries-cloudagent-python/pull/#2955) [swcurran](https://github.com/swcurran) + - Fix Snyk Container scanning workflow [\##2951](https://github.com/hyperledger/aries-cloudagent-python/pull/#2951) [WadeBarnes](https://github.com/WadeBarnes) + - chore: updating dependabot to support gha, python, docker and dev container packages [\##2945](https://github.com/hyperledger/aries-cloudagent-python/pull/#2945) [rajpalc7](https://github.com/rajpalc7) + - fix(interop): overly strict validation [\##2943](https://github.com/hyperledger/aries-cloudagent-python/pull/#2943) [dbluhm](https://github.com/dbluhm) + - ⬆️ Upgrade test and lint dependencies [\##2939](https://github.com/hyperledger/aries-cloudagent-python/pull/#2939) [ff137](https://github.com/ff137) + - ⬆️ Upgrade aiohttp-apispec [\##2920](https://github.com/hyperledger/aries-cloudagent-python/pull/#2920) [ff137](https://github.com/ff137) + - ⬆️ Upgrade pydid (pydantic v2) [\##2919](https://github.com/hyperledger/aries-cloudagent-python/pull/#2919) [ff137](https://github.com/ff137) + - feat: drop indy sdk [\##2892](https://github.com/hyperledger/aries-cloudagent-python/pull/#2892) [dbluhm](https://github.com/dbluhm) + - Change middleware registration order [\##2796](https://github.com/hyperledger/aries-cloudagent-python/pull/#2796) [PatStLouis](https://github.com/PatStLouis) + - ⬆️ Upgrade pytest to 8.0 [\##2773](https://github.com/hyperledger/aries-cloudagent-python/pull/#2773) [ff137](https://github.com/ff137) + - ⬆️ Update pytest-asyncio to 0.23.4 [\##2764](https://github.com/hyperledger/aries-cloudagent-python/pull/#2764) [ff137](https://github.com/ff137) + - Upgrade pre-commit and flake8 dependencies; fix flake8 warnings [\##2399](https://github.com/hyperledger/aries-cloudagent-python/pull/#2399) [ff137](https://github.com/ff137) + - ⬆️ upgrade requests to latest [\##2336](https://github.com/hyperledger/aries-cloudagent-python/pull/#2336) [ff137](https://github.com/ff137) + - ⬆️ upgrade pyjwt to latest; introduce leeway to jwt.decode [\##2335](https://github.com/hyperledger/aries-cloudagent-python/pull/#2335) [ff137](https://github.com/ff137) + - ⬆️ upgrade packaging to latest [\##2334](https://github.com/hyperledger/aries-cloudagent-python/pull/#2334) [ff137](https://github.com/ff137) + - ⬆️ upgrade marshmallow to latest [\##2322](https://github.com/hyperledger/aries-cloudagent-python/pull/#2322) [ff137](https://github.com/ff137) + - Upgrade codegen tools in scripts/generate-open-api-spec and publish Swagger 2.0 and OpenAPI 3.0 specs [\##2246](https://github.com/hyperledger/aries-cloudagent-python/pull/#2246) [ff137](https://github.com/ff137) + +- Dependabot PRs: + - chore(deps): Bump certifi from 2024.6.2 to 2024.7.4 in /demo/playground/examples in the pip group [\##3084](https://github.com/hyperledger/aries-cloudagent-python/pull/#3084) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump aries-askar from 0.3.1 to 0.3.2 [\##3088](https://github.com/hyperledger/aries-cloudagent-python/pull/#3088) [dependabot bot](https://github.com/dependabot bot) + - chore(deps-dev): Bump ruff from 0.5.0 to 0.5.1 [\##3087](https://github.com/hyperledger/aries-cloudagent-python/pull/#3087) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump mkdocs-material from 9.5.27 to 9.5.28 [\##3089](https://github.com/hyperledger/aries-cloudagent-python/pull/#3089) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump certifi from 2024.6.2 to 2024.7.4 in the pip group [\##3085](https://github.com/hyperledger/aries-cloudagent-python/pull/#3085) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump requests from 2.32.2 to 2.32.3 [\##3076](https://github.com/hyperledger/aries-cloudagent-python/pull/#3076) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump uuid-utils from 0.8.0 to 0.9.0 [\##3075](https://github.com/hyperledger/aries-cloudagent-python/pull/#3075) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump mike from 2.0.0 to 2.1.2 [\##3074](https://github.com/hyperledger/aries-cloudagent-python/pull/#3074) [dependabot bot](https://github.com/dependabot bot) + - chore(deps-dev): Bump ruff from 0.4.10 to 0.5.0 [\##3073](https://github.com/hyperledger/aries-cloudagent-python/pull/#3073) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump dawidd6/action-download-artifact from 5 to 6 in the all-actions group [\##3064](https://github.com/hyperledger/aries-cloudagent-python/pull/#3064) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump markupsafe from 2.0.1 to 2.1.5 [\##3062](https://github.com/hyperledger/aries-cloudagent-python/pull/#3062) [dependabot bot](https://github.com/dependabot bot) + - chore(deps-dev): Bump pydevd-pycharm from 193.6015.41 to 193.7288.30 [\##3060](https://github.com/hyperledger/aries-cloudagent-python/pull/#3060) [dependabot bot](https://github.com/dependabot bot) + - chore(deps-dev): Bump ruff from 0.4.4 to 0.4.10 [\##3058](https://github.com/hyperledger/aries-cloudagent-python/pull/#3058) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump the pip group with 2 updates [\##3046](https://github.com/hyperledger/aries-cloudagent-python/pull/#3046) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump urllib3 from 2.2.1 to 2.2.2 in /demo/playground/examples in the pip group [\##3045](https://github.com/hyperledger/aries-cloudagent-python/pull/#3045) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump marshmallow from 3.20.2 to 3.21.3 [\##3038](https://github.com/hyperledger/aries-cloudagent-python/pull/#3038) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump packaging from 23.1 to 23.2 [\##3037](https://github.com/hyperledger/aries-cloudagent-python/pull/#3037) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump mkdocs-material from 9.5.10 to 9.5.27 [\##3036](https://github.com/hyperledger/aries-cloudagent-python/pull/#3036) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump configargparse from 1.5.5 to 1.7 [\##3035](https://github.com/hyperledger/aries-cloudagent-python/pull/#3035) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump uuid-utils from 0.7.0 to 0.8.0 [\##3034](https://github.com/hyperledger/aries-cloudagent-python/pull/#3034) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump dawidd6/action-download-artifact from 3 to 5 in the all-actions group [\##3027](https://github.com/hyperledger/aries-cloudagent-python/pull/#3027) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Update prompt-toolkit requirement from ~=2.0.9 to ~=2.0.10 in /demo [\##3026](https://github.com/hyperledger/aries-cloudagent-python/pull/#3026) [dependabot bot](https://github.com/dependabot bot) + - chore(deps-dev): Bump pytest from 8.2.1 to 8.2.2 [\##3025](https://github.com/hyperledger/aries-cloudagent-python/pull/#3025) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump pydid from 0.5.0 to 0.5.1 [\##3024](https://github.com/hyperledger/aries-cloudagent-python/pull/#3024) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump sphinx from 1.8.4 to 1.8.6 [\##3021](https://github.com/hyperledger/aries-cloudagent-python/pull/#3021) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump actions/checkout from 3 to 4 in the all-actions group [\##3011](https://github.com/hyperledger/aries-cloudagent-python/pull/#3011) [dependabot bot](https://github.com/dependabot bot) + - Merge all demo dependabot PRs [\##3008](https://github.com/hyperledger/aries-cloudagent-python/pull/#3008) [PatStLouis](https://github.com/PatStLouis) + - Merge all poetry dependabot PRs [\##3007](https://github.com/hyperledger/aries-cloudagent-python/pull/#3007) [PatStLouis](https://github.com/PatStLouis) + - chore(deps): Bump hyperledger/aries-cloudagent-python from py3.9-0.9.0 to py3.9-0.12.1 in /demo/multi-demo [\##2976](https://github.com/hyperledger/aries-cloudagent-python/pull/#2976) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump hyperledger/aries-cloudagent-python from py3.9-0.10.4 to py3.9-0.12.1 in /demo/playground [\##2975](https://github.com/hyperledger/aries-cloudagent-python/pull/#2975) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump hyperledger/aries-cloudagent-python from py3.9-0.9.0 to py3.9-0.12.1 in /demo/docker-agent [\##2973](https://github.com/hyperledger/aries-cloudagent-python/pull/#2973) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump sphinx-rtd-theme from 1.1.1 to 1.3.0 in /docs [\##2970](https://github.com/hyperledger/aries-cloudagent-python/pull/#2970) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump untergeek/curator from 8.0.2 to 8.0.15 in /demo/elk-stack/extensions/curator [\##2969](https://github.com/hyperledger/aries-cloudagent-python/pull/#2969) [dependabot bot](https://github.com/dependabot bot) + - chore(deps): Bump ecdsa from 0.16.1 to 0.19.0 in the pip group across 1 directory [\##2933](https://github.com/hyperledger/aries-cloudagent-python/pull/#2933) [dependabot bot](https://github.com/dependabot bot) + ## 0.12.1 ### April 26, 2024 diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 369ab200..43cf58c9 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -19,7 +19,7 @@ Contributions are made pursuant to the Developer's Certificate of Origin, availa A configuration for [pre-commit](https://pre-commit.com/) is included in this repository. This is an optional tool to help contributors commit code that follows the formatting requirements enforced by the CI pipeline. Additionally, it can be used to help contributors write descriptive commit messages that can be parsed by changelog generators. -On each commit, pre-commit hooks will run that verify the committed code complies with ruff and is formatted with black. To install the ruff and black checks: +On each commit, pre-commit hooks will run that verify the committed code complies and formats with ruff. To install the ruff checks: ```bash pre-commit install diff --git a/docs/README.md b/docs/README.md index 81193788..3450e95f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,9 +1,13 @@ # Hyperledger Aries Cloud Agent - Python -[![pypi releases](https://img.shields.io/pypi/v/aries_cloudagent)](https://pypi.org/project/aries-cloudagent/) -[![codecov](https://codecov.io/gh/hyperledger/aries-cloudagent-python/branch/main/graph/badge.svg)](https://codecov.io/gh/hyperledger/aries-cloudagent-python) - - +

+ + + +   +   +   +

> An easy to use Aries agent for building SSI services using any language that supports sending/receiving HTTP requests. @@ -14,27 +18,27 @@ Check it out! It's much easier to navigate than this GitHub repo for reading the Hyperledger Aries Cloud Agent Python (ACA-Py) is a foundation for building Verifiable Credential (VC) ecosystems. It operates in the second and third layers of the [Trust Over IP framework (PDF)](https://trustoverip.org/wp-content/uploads/2020/05/toip_050520_primer.pdf) using [DIDComm messaging](https://github.com/hyperledger/aries-rfcs/tree/main/concepts/0005-didcomm) and [Hyperledger Aries](https://www.hyperledger.org/use/aries) protocols. The "cloud" in the name means that ACA-Py runs on servers (cloud, enterprise, IoT devices, and so forth), and is not designed to run on mobile devices. -ACA-Py is built on the Aries concepts and features that make up [Aries Interop Profile (AIP) 2.0](https://github.com/hyperledger/aries-rfcs/tree/main/concepts/0302-aries-interop-profile#aries-interop-profile-version-20). [ACA-Py’s supported Aries protocols](./features/SupportedRFCs.md) include, most importantly, protocols for issuing, verifying, and holding verifiable credentials using both [Hyperledger AnonCreds] verifiable credential format, and the [W3C Standard Verifiable Credential Data Model] format using JSON-LD with LD-Signatures and BBS+ Signatures. Coming soon -- issuing and presenting [Hyperledger AnonCreds] verifiable credentials using the [W3C Standard Verifiable Credential Data Model] format. +ACA-Py is built on the Aries concepts and features that make up [Aries Interop Profile (AIP) 2.0](https://github.com/hyperledger/aries-rfcs/tree/main/concepts/0302-aries-interop-profile#aries-interop-profile-version-20). [ACA-Py’s supported Aries protocols](https://github.com/hyperledger/aries-cloudagent-python/blob/main/./features/SupportedRFCs.md) include, most importantly, protocols for issuing, verifying, and holding verifiable credentials using both [Hyperledger AnonCreds] verifiable credential format, and the [W3C Standard Verifiable Credential Data Model] format using JSON-LD with LD-Signatures and BBS+ Signatures. Coming soon -- issuing and presenting [Hyperledger AnonCreds] verifiable credentials using the [W3C Standard Verifiable Credential Data Model] format. [Hyperledger AnonCreds]: https://www.hyperledger.org/use/anoncreds [W3C Standard Verifiable Credential Data Model]: https://www.w3.org/TR/vc-data-model/ To use ACA-Py you create a business logic controller that "talks to" an ACA-Py instance (sending HTTP requests and receiving webhook notifications), and ACA-Py handles the Aries and DIDComm protocols and related functionality. Your controller can be built in any language that supports making and receiving HTTP requests; knowledge of Python is not needed. Together, this means you can focus on building VC solutions using familiar web development technologies, instead of having to learn the nuts and bolts of low-level cryptography and Trust over IP-type Aries protocols. -This [checklist-style overview document](./features/SupportedRFCs.md) provides a full list of the features in ACA-Py. +This [checklist-style overview document](https://github.com/hyperledger/aries-cloudagent-python/blob/main/./features/SupportedRFCs.md) provides a full list of the features in ACA-Py. The following is a list of some of the core features needed for a production deployment, with a link to detailed information about the capability. ### Multi-Tenant -ACA-Py supports "multi-tenant" scenarios. In these scenarios, one (scalable) instance of ACA-Py uses one database instance, and are together capable of managing separate secure storage (for private keys, DIDs, credentials, etc.) for many different actors. This enables (for example) an "issuer-as-a-service", where an enterprise may have many VC issuers, each with different identifiers, using the same instance of ACA-Py to interact with VC holders as required. Likewise, an ACA-Py instance could be a "cloud wallet" for many holders (e.g. people or organizations) that, for whatever reason, cannot use a mobile device for a wallet. Learn more about multi-tenant deployments [here](./features/Multitenancy.md). +ACA-Py supports "multi-tenant" scenarios. In these scenarios, one (scalable) instance of ACA-Py uses one database instance, and are together capable of managing separate secure storage (for private keys, DIDs, credentials, etc.) for many different actors. This enables (for example) an "issuer-as-a-service", where an enterprise may have many VC issuers, each with different identifiers, using the same instance of ACA-Py to interact with VC holders as required. Likewise, an ACA-Py instance could be a "cloud wallet" for many holders (e.g. people or organizations) that, for whatever reason, cannot use a mobile device for a wallet. Learn more about multi-tenant deployments [here](https://github.com/hyperledger/aries-cloudagent-python/blob/main/./features/Multitenancy.md). ### Mediator Service -Startup options allow the use of an ACA-Py as an Aries [mediator](https://github.com/hyperledger/aries-rfcs/tree/main/concepts/0046-mediators-and-relays#summary) using core Aries protocols to coordinate its mediation role. Such an ACA-Py instance receives, stores and forwards messages to Aries agents that (for example) lack an addressable endpoint on the Internet such as a mobile wallet. A live instance of a public mediator based on ACA-Py is available [here](https://indicio-tech.github.io/mediator/) from Indicio Technologies. Learn more about deploying a mediator [here](./features/Mediation.md). See the [Aries Mediator Service](https://github.com/hyperledger/aries-mediator-service) for a "best practices" configuration of an Aries mediator. +Startup options allow the use of an ACA-Py as an Aries [mediator](https://github.com/hyperledger/aries-rfcs/tree/main/concepts/0046-mediators-and-relays#summary) using core Aries protocols to coordinate its mediation role. Such an ACA-Py instance receives, stores and forwards messages to Aries agents that (for example) lack an addressable endpoint on the Internet such as a mobile wallet. A live instance of a public mediator based on ACA-Py is available [here](https://indicio-tech.github.io/mediator/) from Indicio Technologies. Learn more about deploying a mediator [here](https://github.com/hyperledger/aries-cloudagent-python/blob/main/./features/Mediation.md). See the [Aries Mediator Service](https://github.com/hyperledger/aries-mediator-service) for a "best practices" configuration of an Aries mediator. ### Indy Transaction Endorsing -ACA-Py supports a Transaction Endorsement protocol, for agents that don't have write access to an Indy ledger. Endorser support is documented [here](./features/Endorser.md). +ACA-Py supports a Transaction Endorsement protocol, for agents that don't have write access to an Indy ledger. Endorser support is documented [here](https://github.com/hyperledger/aries-cloudagent-python/blob/main/./features/Endorser.md). ### Scaled Deployments @@ -42,7 +46,7 @@ ACA-Py supports deployments in scaled environments such as in Kubernetes environ ### VC-API Endpoints -A set of endpoints conforming to the vc-api specification are included to manage w3c credentials and presentations. They are documented [here](./features/JsonLdCredentials.md#vc-api) and a postman demo is available [here](./features/JsonLdCredentials.md#vc-api). +A set of endpoints conforming to the vc-api specification are included to manage w3c credentials and presentations. They are documented [here](https://github.com/hyperledger/aries-cloudagent-python/blob/main/./features/JsonLdCredentials.md#vc-api) and a postman demo is available [here](https://github.com/hyperledger/aries-cloudagent-python/blob/main/./features/JsonLdCredentials.md#vc-api). ## Example Uses @@ -65,7 +69,7 @@ For those new to SSI, Aries and ACA-Py, there are a couple of Linux Foundation e The latter is the most useful for developers wanting to get a solid basis in using ACA-Py and other Aries Frameworks. -Also included here is a much more concise (but less maintained) [Getting Started Guide](./gettingStarted/README.md) that will take you from knowing next to nothing about decentralized identity to developing Aries-based business apps and services. You’ll run an Indy ledger (with no ramp-up time), ACA-Py apps and developer-oriented demos. The guide has a table of contents so you can skip the parts you already know. +Also included here is a much more concise (but less maintained) [Getting Started Guide](https://github.com/hyperledger/aries-cloudagent-python/blob/main/./gettingStarted/README.md) that will take you from knowing next to nothing about decentralized identity to developing Aries-based business apps and services. You’ll run an Indy ledger (with no ramp-up time), ACA-Py apps and developer-oriented demos. The guide has a table of contents so you can skip the parts you already know. ### Understanding the Architecture @@ -73,22 +77,22 @@ There is an [architectural deep dive webinar](https://www.youtube.com/watch?v=FX ![drawing](./aca-py_architecture.png) -You can extend ACA-Py using plug-ins, which can be loaded at runtime. Plug-ins are mentioned in the [webinar](https://docs.google.com/presentation/d/1K7qiQkVi4n-lpJ3nUZY27OniUEM0c8HAIk4imCWCx5Q/edit#slide=id.g5d43fe05cc_0_145) and are [described in more detail here](./features/PlugIns.md). An ever-expanding set of ACA-Py plugins can be found +You can extend ACA-Py using plug-ins, which can be loaded at runtime. Plug-ins are mentioned in the [webinar](https://docs.google.com/presentation/d/1K7qiQkVi4n-lpJ3nUZY27OniUEM0c8HAIk4imCWCx5Q/edit#slide=id.g5d43fe05cc_0_145) and are [described in more detail here](https://github.com/hyperledger/aries-cloudagent-python/blob/main/./features/PlugIns.md). An ever-expanding set of ACA-Py plugins can be found in the [Aries ACA-Py Plugins repository]. Check them out -- it might have the very plugin you need! [Aries ACA-Py Plugins repository]: https://github.com/hyperledger/aries-acapy-plugins ### Installation and Usage -Use the ["install and go" page for developers](./features/DevReadMe.md) if you are comfortable with Trust over IP and Aries concepts. ACA-Py can be run with Docker without installation (highly recommended), or can be installed [from PyPi](https://pypi.org/project/aries-cloudagent/). In the repository `/demo` folder there is a full set of demos for developers to use in getting up to speed quickly. Start with the [Traction Workshop] to go through a complete ACA-Py-based Issuer-Holder-Verifier flow in about 20 minutes. Next, the [Alice-Faber Demo](./demo/README.md) is a great way for developers try a zero-install example of how to use the ACA-Py API to operate a couple of Aries Agents. The [Read the Docs](https://aries-cloud-agent-python.readthedocs.io/en/latest/) overview is also a way to understand the internal modules and APIs that make up an ACA-Py instance. +Use the ["install and go" page for developers](https://github.com/hyperledger/aries-cloudagent-python/blob/main/./features/DevReadMe.md) if you are comfortable with Trust over IP and Aries concepts. ACA-Py can be run with Docker without installation (highly recommended), or can be installed [from PyPi](https://pypi.org/project/aries-cloudagent/). In the repository `/demo` folder there is a full set of demos for developers to use in getting up to speed quickly. Start with the [Traction Workshop] to go through a complete ACA-Py-based Issuer-Holder-Verifier flow in about 20 minutes. Next, the [Alice-Faber Demo](https://github.com/hyperledger/aries-cloudagent-python/blob/main/./demo/README.md) is a great way for developers try a zero-install example of how to use the ACA-Py API to operate a couple of Aries Agents. The [Read the Docs](https://aries-cloud-agent-python.readthedocs.io/en/latest/) overview is also a way to understand the internal modules and APIs that make up an ACA-Py instance. -If you would like to develop on ACA-Py locally note that we use Poetry for dependency management and packaging, if you are unfamiliar with poetry please see our [cheat sheet](./deploying/Poetry.md) +If you would like to develop on ACA-Py locally note that we use Poetry for dependency management and packaging, if you are unfamiliar with poetry please see our [cheat sheet](https://github.com/hyperledger/aries-cloudagent-python/blob/main/./deploying/Poetry.md) -[Traction Workshop]: ./demo/Aries-Workshop.md +[Traction Workshop]: https://github.com/hyperledger/aries-cloudagent-python/blob/main/./demo/Aries-Workshop.md ## About the ACA-Py Admin API -The [overview of ACA-Py’s API](./features/AdminAPI.md) is a great starting place for learning about the ACA-Py API when you are starting to build your own controller. +The [overview of ACA-Py’s API](https://github.com/hyperledger/aries-cloudagent-python/blob/main/./features/AdminAPI.md) is a great starting place for learning about the ACA-Py API when you are starting to build your own controller. An ACA-Py instance puts together an OpenAPI-documented REST interface based on the protocols that are loaded. This is used by a controller application (written in any language) to manage the behavior of the agent. The controller can initiate actions (e.g. issuing a credential) and can respond to agent events (e.g. sending a presentation request after a connection is accepted). Agent events are delivered to the controller as webhooks to a configured URL. @@ -98,7 +102,7 @@ Technical note: the administrative API exposed by the agent for the controller t There are a number of resources for getting help with ACA-Py and troubleshooting any problems you might run into. The -[Troubleshooting](./testing/Troubleshooting.md) document contains some +[Troubleshooting](https://github.com/hyperledger/aries-cloudagent-python/blob/main/./testing/Troubleshooting.md) document contains some guidance about issues that have been experienced in the past. Feel free to submit PRs to supplement the troubleshooting document! Searching the [ACA-Py GitHub issues](https://github.com/hyperledger/aries-cloudagent-python/issues) @@ -113,15 +117,14 @@ The initial implementation of ACA-Py was developed by the Government of British [BC Digital Trust]: https://digital.gov.bc.ca/digital-trust/ -See the [MAINTAINERS.md](./MAINTAINERS.md) file for a list of the current ACA-Py +See the [MAINTAINERS.md](https://github.com/hyperledger/aries-cloudagent-python/blob/main/MAINTAINERS.md) file for a list of the current ACA-Py maintainers, and the guidelines for becoming a Maintainer. We'd love to have you -join the team if you are willing and able to carry out the [duties of a -Maintainer](./MAINTAINERS.md#the-duties-of-a-maintainer). +join the team if you are willing and able to carry out the [duties of a Maintainer](https://github.com/hyperledger/aries-cloudagent-python/blob/main/MAINTAINERS.md#the-duties-of-a-maintainer). ## Contributing -Pull requests are welcome! Please read our [contributions guide](./CONTRIBUTING.md) and submit your PRs. We enforce [developer certificate of origin](https://developercertificate.org/) (DCO) commit signing — [guidance](https://github.com/apps/dco) on this is available. We also welcome issues submitted about problems you encounter in using ACA-Py. +Pull requests are welcome! Please read our [contributions guide](https://github.com/hyperledger/aries-cloudagent-python/blob/main/CONTRIBUTING.md) and submit your PRs. We enforce [developer certificate of origin](https://developercertificate.org/) (DCO) commit signing — [guidance](https://github.com/apps/dco) on this is available. We also welcome issues submitted about problems you encounter in using ACA-Py. ## License -[Apache License Version 2.0](LICENSE) +[Apache License Version 2.0](https://github.com/hyperledger/aries-cloudagent-python/blob/main/LICENSE) diff --git a/docs/deploying/ContainerImagesAndGithubActions.md b/docs/deploying/ContainerImagesAndGithubActions.md index bdc28e19..6e891fcd 100644 --- a/docs/deploying/ContainerImagesAndGithubActions.md +++ b/docs/deploying/ContainerImagesAndGithubActions.md @@ -22,22 +22,18 @@ Multiple variants are available; see [Tags](#tags). ACA-Py is a foundation for building decentralized identity applications; to this end, there are multiple variants of ACA-Py built to suit the needs of a variety -of environments and workflows. There are currently two main variants: +of environments and workflows. The following variants exist: - "Standard" - The default configuration of ACA-Py, including: - Aries Askar for secure storage - Indy VDR for Indy ledger communication - Indy Shared Libraries for AnonCreds -- "Indy" - The legacy configuration of ACA-Py, including: - - Indy SDK Wallet for secure storage - - Indy SDK Ledger for Indy ledger communication - - Indy SDK for AnonCreds -These two image variants are largely distinguished by providers for Indy Network -and AnonCreds support. The Standard variant is recommended for new projects. -Migration from an Indy based image (whether the new Indy image variant or the -original BC Gov images) to the Standard image is outside of the scope of this -document. +In the past, two image variants were published. These two variants are largely +distinguished by providers for Indy Network and AnonCreds support. The Standard +variant is recommended for new projects. Migration from an Indy based image +(whether the new Indy image variant or the original BC Gov images) to the +Standard image is outside of the scope of this document. The ACA-Py images built by this project are tagged to indicate which of the above variants it is. Other tags may also be generated for use by developers. @@ -48,8 +44,6 @@ Tag | Variant | Example | Description ------------------------|----------|--------------------------|-------------------------------------------------------------------------------------------------| py3.9-X.Y.Z | Standard | py3.9-0.7.4 | Standard image variant built on Python 3.9 for ACA-Py version X.Y.Z | py3.10-X.Y.Z | Standard | py3.10-0.7.4 | Standard image variant built on Python 3.10 for ACA-Py version X.Y.Z | -py3.9-indy-A.B.C-X.Y.Z | Indy | py3.9-indy-1.16.0-0.7.4 | Standard image variant built on Python 3.9 for ACA-Py version X.Y.Z and Indy SDK Version A.B.C | -py3.10-indy-A.B.C-X.Y.Z | Indy | py3.10-indy-1.16.0-0.7.4 | Standard image variant built on Python 3.10 for ACA-Py version X.Y.Z and Indy SDK Version A.B.C | ### Image Comparison @@ -63,7 +57,7 @@ variants and between the BC Gov ACA-Py images. - Uses container's system python environment rather than `pyenv` - Askar and Indy Shared libraries are installed as dependencies of ACA-Py through pip from pre-compiled binaries included in the python wrappers - Built from repo contents -- Indy Image +- Indy Image (no longer produced but included here for clarity) - Based on slim variant of Debian - Built from multi-stage build step (`indy-base` in the Dockerfile) which includes Indy dependencies; this could be replaced with an explicit `indy-python` image from the Indy SDK repo - Includes `libindy` but does **NOT** include the Indy CLI @@ -86,24 +80,19 @@ variants and between the BC Gov ACA-Py images. - Tests (`.github/workflows/tests.yml`) - A reusable workflow that runs tests for the Standard ACA-Py variant for a given python version. -- Tests (Indy) (`.github/workflows/tests-indy.yml`) - A reusable workflow that - runs tests for the Indy ACA-Py variant for a given python and indy version. - PR Tests (`.github/workflows/pr-tests.yml`) - Run on pull requests; runs tests - for the Standard and Indy ACA-Py variants for a "default" python version. - Check this workflow for the current default python and Indy versions in use. + for the Standard ACA-Py variant for a "default" python version. + Check this workflow for the current default python version in use. - Nightly Tests (`.github/workflows/nightly-tests.yml`) - Run nightly; runs - tests for the Standard and Indy ACA-Py variants for all currently supported + tests for the Standard ACA-Py variant for all currently supported python versions. Check this workflow for the set of currently supported - versions and Indy version(s) in use. + versions in use. - Publish (`.github/workflows/publish.yml`) - Run on new release published or when manually triggered; builds and pushes the Standard ACA-Py variant to the Github Container Registry. -- Publish (Indy) (`.github/workflows/publish-indy.yml`) - Run on new release - published or when manually triggered; builds and pushes the Indy ACA-Py - variant to the Github Container Registry. - Integration Tests (`.github/workflows/integrationtests.yml`) - Run on pull requests (to the hyperledger fork only); runs BDD integration tests. -- Black Format (`.github/workflows/blackformat.yml`) - Run on pull requests; +- Format (`.github/workflows/format.yml`) - Run on pull requests; checks formatting of files modified by the PR. - CodeQL (`.github/workflows/codeql.yml`) - Run on pull requests; performs CodeQL analysis. diff --git a/docs/design/UpgradeViaApi.md b/docs/design/UpgradeViaApi.md new file mode 100644 index 00000000..0ddb8904 --- /dev/null +++ b/docs/design/UpgradeViaApi.md @@ -0,0 +1,103 @@ +# Upgrade via API Design + +#### To isolate an upgrade process and trigger it via API the following pattern was designed to handle multitenant scenarios. It includes an is_upgrading record in the wallet(DB) and a middleware to prevent requests during the upgrade process. + +#### The diagam below descripes the sequence of events for the anoncreds upgrade process which it was designed for, but the architecture can be used for any upgrade process. + +```mermaid +sequenceDiagram + participant A1 as Agent 1 + participant M1 as Middleware + participant IAS1 as IsAnoncredsSingleton Set + participant UIPS1 as UpgradeInProgressSingleton Set + participant W as Wallet (DB) + participant UIPS2 as UpgradeInProgressSingleton Set + participant IAS2 as IsAnoncredsSingleton Set + participant M2 as Middleware + participant A2 as Agent 2 + + Note over A1,A2: Start upgrade for non-anoncreds wallet + A1->>M1: POST /anoncreds/wallet/upgrade + M1-->>IAS1: check if wallet is in set + IAS1-->>M1: wallet is not in set + M1-->>UIPS1: check if wallet is in set + UIPS1-->>M1: wallet is not in set + M1->>A1: OK + A1-->>W: Add is_upgrading = anoncreds_in_progress record + A1->>A1: Upgrade wallet + A1-->>UIPS1: Add wallet to set + + Note over A1,A2: Attempted Requests During Upgrade + + Note over A1: Attempted Request + A1->>M1: GET /any-endpoint + M1-->>IAS1: check if wallet is in set + IAS1-->>M1: wallet is not in set + M1-->>UIPS1: check if wallet is in set + UIPS1-->>M1: wallet is in set + M1->>A1: 503 Service Unavailable + + Note over A2: Attempted Request + A2->>M2: GET /any-endpoint + M2-->>IAS2: check if wallet is in set + IAS2->>M2: wallet is not in set + M2-->>UIPS2: check if wallet is in set + UIPS2-->>M2: wallet is not in set + A2-->>W: Query is_upgrading = anoncreds_in_progress record + W-->>A2: record = anoncreds_in_progress + A2->>A2: Loop until upgrade is finished in seperate process + A2-->>UIPS2: Add wallet to set + M2->>A2: 503 Service Unavailable + + Note over A1,A2: Agent Restart During Upgrade + A1-->>W: Get is_upgrading record for wallet or all subwallets + W-->>A1: + A1->>A1: Resume upgrade if in progress + A1-->>UIPS1: Add wallet to set + + Note over A2: Same as Agent 1 + + Note over A1,A2: Upgrade Completes + + Note over A1: Finish Upgrade + A1-->>W: set is_upgrading = anoncreds_finished + A1-->>UIPS1: Remove wallet from set + A1-->>IAS1: Add wallet to set + A1->>A1: update subwallet or restart + + Note over A2: Detect Upgrade Complete + A2-->>W: Check is_upgrading = anoncreds_finished + W-->>A2: record = anoncreds_in_progress + A2->>A2: Wait 1 second + A2-->>W: Check is_upgrading = anoncreds_finished + W-->>A2: record = anoncreds_finished + A2-->>UIPS2: Remove wallet from set + A2-->>IAS2: Add wallet to set + A2->>A2: update subwallet or restart + + Note over A1,A2: Restarted Agents After Upgrade + + A1-->W: Get is_upgrading record for wallet or all subwallets + W-->>A1: + A1->>IAS1: Add wallet to set if record = anoncreds_finished + + Note over A2: Same as Agent 1 + + Note over A1,A2: Attempted Requests After Upgrade + + Note over A1: Attempted Request + A1->>M1: GET /any-endpoint + M1-->>IAS1: check if wallet is in set + IAS1-->>M1: wallet is in set + M1-->>A1: OK + + Note over A2: Same as Agent 1 +``` + + +##### An example of the implementation can be found via the anoncreds upgrade components. + - `aries_cloudagent/wallet/routes.py` in the `upgrade_anoncreds` controller + - the upgrade code in `wallet/anoncreds_upgrade.py` + - the middleware in `admin/server.py` in the `upgrade_middleware` function + - the singleton sets in `wallet/singletons.py` + - the startup process in `core/conductor.py` in the `check_for_wallet_upgrades_in_progress` function \ No newline at end of file diff --git a/docs/features/AnoncredsControllerMigration.md b/docs/features/AnoncredsControllerMigration.md new file mode 100644 index 00000000..235bb797 --- /dev/null +++ b/docs/features/AnoncredsControllerMigration.md @@ -0,0 +1,675 @@ +# Anoncreds Controller Migration + +To upgrade an agent to use anoncreds a controller should implement the required changes to endpoints and payloads in a way that is backwards compatible. The controller can then trigger the upgrade via the upgrade endpoint. + +## Step 1 - Endpoint Payload and Response Changes + +There is endpoint and payload changes involved with creating **schema, credential definition and revocation objects**. Your controller will need to implement these changes for any endpoints it uses. + +A good way to implement this with backwards compatibility is to get the wallet type via **/settings** and handle the existing endpoints when **wallet.type** is **askar** and the new anoncreds endpoints when **wallet.type** is **askar-anoncreds**. In this way the controller will handle both types of wallets in case the upgrade fails. After the upgrade is successful and stable the controller can be updated to only handle the new anoncreds endpoints. + +## Schemas + +#### Creating a Schema: + +- Change endpoint from **POST /schemas** to **POST /anoncreds/schema** +- Change payload and parameters from + +``` +params + - conn_id + - create_transaction_for_endorser +``` + +```json +{ + "attributes": ["score"], + "schema_name": "simple", + "schema_version": "1.0" +} +``` + +to + +```json +{ + "options": { + "create_transaction_for_endorser": false, + "endorser_connection_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" + }, + "schema": { + "attrNames": ["score"], + "issuerId": "WgWxqztrNooG92RXvxSTWv", + "name": "Example schema", + "version": "1.0" + } +} +``` + +- options are not required +- **_issuerId_** is the public did to be used on the ledger +- The payload responses have changed + +**_Responses_** + +Without endorsement: + +```json +{ + "sent": { + "schema_id": "PzmGpSeCznzfPmv9B1EBqa:2:simple:1.0", + "schema": { + "ver": "1.0", + "id": "PzmGpSeCznzfPmv9B1EBqa:2:simple:1.0", + "name": "simple", + "version": "1.0", + "attrNames": ["score"], + "seqNo": 541 + } + }, + "schema_id": "PzmGpSeCznzfPmv9B1EBqa:2:simple:1.0", + "schema": { + "ver": "1.0", + "id": "PzmGpSeCznzfPmv9B1EBqa:2:simple:1.0", + "name": "simple", + "version": "1.0", + "attrNames": ["score"], + "seqNo": 541 + } +} +``` + +to + +```json +{ + "job_id": "string", + "registration_metadata": {}, + "schema_metadata": {}, + "schema_state": { + "schema": { + "attrNames": ["score"], + "issuerId": "WgWxqztrNooG92RXvxSTWv", + "name": "Example schema", + "version": "1.0" + }, + "schema_id": "WgWxqztrNooG92RXvxSTWv:2:schema_name:1.0", + "state": "finished" + } +} +``` + +With endorsement: + +```json +{ + "sent": { + "schema": { + "attrNames": [ + "score" + ], + "id": "WgWxqztrNooG92RXvxSTWv:2:schema_name:1.0", + "name": "schema_name", + "seqNo": 10, + "ver": "1.0", + "version": "1.0" + }, + "schema_id": "WgWxqztrNooG92RXvxSTWv:2:schema_name:1.0" + }, + "txn": {...} +} +``` + +to + +```json +{ + "job_id": "12cb896d648242c8b9b0fff3b870ed00", + "schema_state": { + "state": "wait", + "schema_id": "RbyPM1EP8fKCrf28YsC1qK:2:simple:1.1", + "schema": { + "issuerId": "RbyPM1EP8fKCrf28YsC1qK", + "attrNames": [ + "score" + ], + "name": "simple", + "version": "1.1" + } + }, + "registration_metadata": { + "txn": {...} + }, + "schema_metadata": {} +} +``` + +#### Getting schemas: + +- Change endpoint from **GET /schemas/created** to **GET /anoncreds/schemas** +- Response payloads have no change + +#### Getting a schema: + +- Change endpoint from **GET /schemas/{schema_id}** to **GET /anoncreds/schema/{schema_id}** +- Response payload changed from + +```json +{ + "schema": { + "attrNames": ["score"], + "id": "WgWxqztrNooG92RXvxSTWv:2:schema_name:1.0", + "name": "schema_name", + "seqNo": 10, + "ver": "1.0", + "version": "1.0" + } +} +``` + +to + +```json +{ + "resolution_metadata": {}, + "schema": { + "attrNames": ["score"], + "issuerId": "WgWxqztrNooG92RXvxSTWv", + "name": "Example schema", + "version": "1.0" + }, + "schema_id": "WgWxqztrNooG92RXvxSTWv:2:schema_name:1.0", + "schema_metadata": {} +} +``` + +## Credential Definitions + +#### Creating a credential definition: + +- Change endpoint from **POST /credential-definitions** to **POST /anoncreds/credential-definition** +- Change payload and parameters from + +``` +params + - conn_id + - create_transaction_for_endorser +``` + +```json +{ + "revocation_registry_size": 1000, + "schema_id": "WgWxqztrNooG92RXvxSTWv:2:simple:1.0", + "support_revocation": true, + "tag": "default" +} +``` + +to + +```json +{ + "credential_definition": { + "issuerId": "WgWxqztrNooG92RXvxSTWv", + "schemaId": "WgWxqztrNooG92RXvxSTWv:2:schema_name:1.0", + "tag": "default" + }, + "options": { + "create_transaction_for_endorser": false, + "endorser_connection_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "revocation_registry_size": 1000, + "support_revocation": true + } +} +``` + +- options are not required, revocation will default to false +- _**issuerId**_ is the public did to be used on the ledger +- _**schemaId**_ is the schema id on the ledger +- The payload responses have changed + +**_Responses_** + +Without Endoresment: + +```json +{ + "sent": { + "credential_definition_id": "CZGamdZoKhxiifjbdx3GHH:3:CL:558:default" + }, + "credential_definition_id": "CZGamdZoKhxiifjbdx3GHH:3:CL:558:default" +} +``` + +to + +```json +{ + "schema_state": { + "state": "finished", + "schema_id": "BpGaCdTwgEKoYWm6oPbnnj:2:simple:1.0", + "schema": { + "issuerId": "BpGaCdTwgEKoYWm6oPbnnj", + "attrNames": ["score"], + "name": "simple", + "version": "1.0" + } + }, + "registration_metadata": {}, + "schema_metadata": { + "seqNo": 555 + } +} +``` + +With Endorsement: + +```json +{ + "sent": { + "credential_definition_id": "WgWxqztrNooG92RXvxSTWv:3:CL:20:tag" + }, + "txn": {...} +} +``` + +```json +{ + "job_id": "7082e58aa71d4817bb32c3778596b012", + "credential_definition_state": { + "state": "wait", + "credential_definition_id": "RbyPM1EP8fKCrf28YsC1qK:3:CL:547:default", + "credential_definition": { + "issuerId": "RbyPM1EP8fKCrf28YsC1qK", + "schemaId": "RbyPM1EP8fKCrf28YsC1qK:2:simple:1.1", + "type": "CL", + "tag": "default", + "value": { + "primary": {...}, + "revocation": {...} + } + } + }, + "registration_metadata": { + "txn": {...} + }, + "credential_definition_metadata": {} +} +``` + +#### Getting credential definitions: + +- Change endpoint from **GET /credential-definitons/created** to **GET /anoncreds/credential-defintions** +- Response payloads have no change + +#### Getting a credential definition: + +- Change endpoint from **GET /credential-definitons/{schema_id}** to **GET /anoncreds/credential-defintion/{cred_def_id}** +- Response payload changed from + +```json +{ + "credential_definition": { + "id": "WgWxqztrNooG92RXvxSTWv:3:CL:20:tag", + "schemaId": "20", + "tag": "tag", + "type": "CL", + "value": {...}, + "revocation": {...} + }, + "ver": "1.0" + } +} +``` + +to + +```json +{ + "credential_definition": { + "issuerId": "WgWxqztrNooG92RXvxSTWv", + "schemaId": "WgWxqztrNooG92RXvxSTWv:2:schema_name:1.0", + "tag": "default", + "type": "CL", + "value": {...}, + "revocation": {...} + } + }, + "credential_definition_id": "WgWxqztrNooG92RXvxSTWv:3:CL:20:tag", + "credential_definitions_metadata": {}, + "resolution_metadata": {} +} +``` + +## Revocation + +Most of the changes with revocation endpoints only require prepending `/anoncreds` to the path. There are some other subtle changes listed below. + +#### Create and publish registry definition + +- The endpoints **POST /revocation/create-registry** and **POST /revocation/registry/{rev_reg_id}/definition** have been replaced by the single endpoint **POST /anoncreds/revocation-registry-definition** +- Instead of creating the registry with **POST /revocation/create-registry** and payload + +```json +{ + "credential_definition_id": "WgWxqztrNooG92RXvxSTWv:3:CL:20:tag", + "max_cred_num": 1000 +} +``` + +- And then publishing with **POST /revocation/registry/{rev_reg_id}/definition** + +``` +params + - conn_id + - create_transaction_for_endorser +``` + +- Use **POST /anoncreds/revocation-registry-definition** with payload + +```json +{ + "options": { + "create_transaction_for_endorser": false, + "endorser_connection_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" + }, + "revocation_registry_definition": { + "credDefId": "WgWxqztrNooG92RXvxSTWv:2:schema_name:1.0", + "issuerId": "WgWxqztrNooG92RXvxSTWv", + "maxCredNum": 777, + "tag": "default" + } +} +``` + +- options are not required, revocation will default to false +- _**issuerId**_ is the public did to be used on the ledger +- _**credDefId**_ is the cred def id on the ledger +- The payload responses have changed + +**_Responses_** + +Without endorsement: + +```json +{ + "sent": { + "revocation_registry_id": "CZGamdZoKhxiifjbdx3GHH:4:CL:558:default" + }, + "revocation_registry_id": "CZGamdZoKhxiifjbdx3GHH:4:CL:558:default" +} +``` + +to + +```json +{ + "revocation_registry_definition_state": { + "state": "finished", + "revocation_registry_definition_id": "BpGaCdTwgEKoYWm6oPbnnj:4:BpGaCdTwgEKoYWm6oPbnnj:3:CL:555:default:CL_ACCUM:default", + "revocation_registry_definition": { + "issuerId": "BpGaCdTwgEKoYWm6oPbnnj", + "revocDefType": "CL_ACCUM", + "credDefId": "BpGaCdTwgEKoYWm6oPbnnj:3:CL:555:default", + "tag": "default", + "value": {...} + } + }, + "registration_metadata": {}, + "revocation_registry_definition_metadata": { + "seqNo": 569 + } +} +``` + +With endorsement: + +```json +{ + "sent": { + "result": { + "created_at": "2021-12-31T23:59:59Z", + "cred_def_id": "WgWxqztrNooG92RXvxSTWv:3:CL:20:tag", + "error_msg": "Revocation registry undefined", + "issuer_did": "WgWxqztrNooG92RXvxSTWv", + "max_cred_num": 1000, + "pending_pub": [ + "23" + ], + "record_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "revoc_def_type": "CL_ACCUM", + "revoc_reg_def": { + "credDefId": "WgWxqztrNooG92RXvxSTWv:3:CL:20:tag", + "id": "WgWxqztrNooG92RXvxSTWv:4:WgWxqztrNooG92RXvxSTWv:3:CL:20:tag:CL_ACCUM:0", + "revocDefType": "CL_ACCUM", + "tag": "string", + "value": {...}, + "ver": "1.0" + }, + "revoc_reg_entry": {...}, + "revoc_reg_id": "WgWxqztrNooG92RXvxSTWv:4:WgWxqztrNooG92RXvxSTWv:3:CL:20:tag:CL_ACCUM:0", + "state": "active", + "tag": "string", + "tails_hash": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV", + "tails_local_path": "string", + "tails_public_uri": "string", + "updated_at": "2021-12-31T23:59:59Z" + } + }, + "txn": {...} +} +``` + +to + +```json +{ + "job_id": "25dac53a1fb84cb8a5bf1b4362fbca11", + "revocation_registry_definition_state": { + "state": "wait", + "revocation_registry_definition_id": "RbyPM1EP8fKCrf28YsC1qK:4:RbyPM1EP8fKCrf28YsC1qK:3:CL:547:default:CL_ACCUM:default", + "revocation_registry_definition": { + "issuerId": "RbyPM1EP8fKCrf28YsC1qK", + "revocDefType": "CL_ACCUM", + "credDefId": "RbyPM1EP8fKCrf28YsC1qK:3:CL:547:default", + "tag": "default", + "value": {...} + } + }, + "registration_metadata": { + "txn": {...} + }, + "revocation_registry_definition_metadata": {} +} +``` + +#### Send revocation entry or list to ledger + +- Changes from **POST /revocation/registry/{rev_reg_id}/entry** to **POST /anoncreds/revocation-list** +- Change from + +``` +params + - conn_id + - create_transaction_for_endorser +``` + +to + +```json +{ + "options": { + "create_transaction_for_endorser": false, + "endorser_connection_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" + }, + "rev_reg_def_id": "WgWxqztrNooG92RXvxSTWv:4:WgWxqztrNooG92RXvxSTWv:3:CL:20:tag:CL_ACCUM:0" +} +``` + +- options are not required +- _**rev_reg_def_id**_ is the revocation registry definition id on the ledger +- The payload responses have changed + +**_Responses_** + +Without endorsement: + +```json +{ + "sent": { + "revocation_registry_id": "BpGaCdTwgEKoYWm6oPbnnj:4:BpGaCdTwgEKoYWm6oPbnnj:3:CL:555:default:CL_ACCUM:default" + }, + "revocation_registry_id": "BpGaCdTwgEKoYWm6oPbnnj:4:BpGaCdTwgEKoYWm6oPbnnj:3:CL:555:default:CL_ACCUM:default" +} +``` + +to + +```json + +``` + +#### Get current active registry: + +- Change from **GET /revocation/active-registry/{cred_def_id}** to **GET /anoncreds/revocation/active-registry/{cred_def_id}** +- No payload changes + +#### Rotate active registry + +- Change from **POST /revocation/active-registry/{cred_def_id}/rotate** to **POST /anoncreds/revocation/active-registry/{cred_def_id}/rotate** +- No payload changes + +#### Get credential revocation status + +- Change from **GET /revocation/credential-record** to **GET /anoncreds/revocation/credential-record** +- No payload changes + +#### Publish revocations + +- Change from **POST /revocation/publish-revocations** to **POST /anoncreds/revocation/publish-revocations** +- Change payload and parameters from + +``` +params + - conn_id + - create_transaction_for_endorser +``` + +```json +{ + "rrid2crid": { + "additionalProp1": ["12345"], + "additionalProp2": ["12345"], + "additionalProp3": ["12345"] + } +} +``` + +to + +```json +{ + "options": { + "create_transaction_for_endorser": false, + "endorser_connection_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" + }, + "rrid2crid": { + "additionalProp1": ["12345"], + "additionalProp2": ["12345"], + "additionalProp3": ["12345"] + } +} +``` + +- options are not required + +#### Get registries + +- Change from **GET /revocation/registries/created** to **GET /anoncreds/revocation/registries** +- No payload changes + +#### Get registry + +- Changes from **GET /revocation/registry/{rev_reg_id}** to **GET /anoncreds/revocation/registry/{rev_reg_id}** +- No payload changes + +#### Fix reocation state + +- Changes from **POST /revocation/registry/{rev_reg_id}/fix-revocation-entry-state** to **POST /anoncreds/revocation/registry/{rev_reg_id}/fix-revocation-state** +- No payload changes + +#### Get number of issued credentials + +- Changes from **GET /revocation/registry/{rev_reg_id}/issued** to **GET /anoncreds/revocation/registry/{rev_reg_id}/issued** +- No payload changes + +#### Get credential details + +- Changes from **GET /revocation/registry/{rev_reg_id}/issued/details** to **GET /anoncreds/revocation/registry/{rev_reg_id}/issued/details** +- No payload changes + +#### Get revoked credential details + +- Changes from **GET /revocation/registry/{rev_reg_id}/issued/indy_recs** to **GET /anoncreds/revocation/registry/{rev_reg_id}/issued/indy_recs** +- No payload changes + +#### Set state manually + +- Changes from **PATCH /revocation/registry/{rev_reg_id}/set-state** to **PATCH /anoncreds/revocation/registry/{rev_reg_id}/set-state** +- No payload changes + +#### Upload tails file + +- Changes from **PUT /revocation/registry/{rev_reg_id}/tails-file** to **PUT /anoncreds/registry/{rev_reg_id}/tails-file** +- No payload changes + +#### Download tails file + +- Changes from **GET /revocation/registry/{rev_reg_id}/tails-file** to **GET /anoncreds/revocation/registry/{rev_reg_id}/tails-file** +- No payload changes + +#### Revoke a credential + +- Changes from **POST /revocation/revoke** to **POST /anoncreds/revocation/revoke** +- Change payload and parameters from + +#### Clear pending revocations + +- **POST /revocation/clear-pending-revocations** has been removed. + +#### Delete tails file + +- Endpoint **DELETE /revocation/delete-tails-server** has been removed + +#### Update tails file + +- Endpoint **PATCH /revocation/registry/{rev_reg_id}** has been removed + +#### Additional Endpoints + +- **PUT /anoncreds/registry/{rev_reg_id}/active** is available to set the active registry + +## Step 2 - Trigger the upgrade via the upgrade endpoint + +The upgrade endpoint is at **POST /anoncreds/wallet/upgrade**. + +You need to be careful doing this, as there is no way to downgrade the wallet. It is recommended highly recommended to back-up any wallets and to test the upgrade in a development environment before upgrading a production wallet. + +Params: `wallet_name` is the name of the wallet to upgrade. Used to prevent accidental upgrades. + +The behavior for a base wallet (standalone) or admin wallet in multitenant mode is slightly different from the behavior of a subwallet (or tenant) in multitenancy mode. However, the upgrade process is the same. + +1. Backup the wallet +2. Scale down any controller instances on old endpoints +3. Call the upgrade endpoint +4. Scale up the controller instances to handle new endpoints + +### Base wallet (standalone) or admin wallet in multitenant mode: + +The agent will get a 503 error during the upgrade process. Any agent instance will shut down when the upgrade is complete. It is up to the aca-py agent to start up again. After the upgrade is complete the old endpoints will no longer be available and result in a 400 error. + +The aca-py agent will work after the restart. However, it will receive a warning for having the wrong wallet type configured. It is recommended to change the `wallet-type` to `askar-anoncreds` in the agent configuration file or start-up command. + +### Subwallet (tenant) in multitenancy mode: + +The sub-tenant which is in the process of being upgraded will get a 503 error during the upgrade process. All other sub-tenants will continue to operate normally. After the upgrade is complete the sub-tenant will be able to use the new endpoints. The old endpoints will no longer be available and result in a 403 error. Any aca-py agents will remain running after the upgrade and it's not required that the aca-py agent restarts. diff --git a/docs/features/DevReadMe.md b/docs/features/DevReadMe.md index d9525913..4864f346 100644 --- a/docs/features/DevReadMe.md +++ b/docs/features/DevReadMe.md @@ -7,6 +7,7 @@ See the [README](../README.md) for details about this repository and information - [Introduction](#introduction) - [Developer Demos](#developer-demos) - [Running](#running) + - [Configuring ACA-PY: Environment Variables](#configuring-aca-py-environment-variables) - [Configuring ACA-PY: Command Line Parameters](#configuring-aca-py-command-line-parameters) - [Docker](#docker) - [Locally Installed](#locally-installed) @@ -42,6 +43,26 @@ To put ACA-Py through its paces at the command line, checkout our [demos](../dem ## Running +### Configuring ACA-PY: Environment Variables + +All CLI parameters in ACA-PY have equivalent environment variables. To convert a CLI argument to an environment +variable: + +1. **Basic Conversion**: Convert the CLI argument to uppercase and prefix it with `ACAPY_`. For example, `--admin` + becomes `ACAPY_ADMIN`. + +2. **Multiple Parameters**: Arguments that take multiple parameters, such as `--admin 0.0.0.0 11000`, should be wrapped + in an array. For example, `ACAPY_ADMIN="[0.0.0.0, 11000]"` +3. **Repeat Parameters**: Arguments like `-it `, which can be repeated, must be wrapped inside + another array and string escaped. For example, instead of: `-it http 0.0.0.0 11000 ws 0.0.0.0 8023` + use: `ACAPY_INBOUND_TRANSPORT=[[\"http\",\"0.0.0.0\",\"11000\"],[\"ws\",\"0.0.0.0\",\"8023\"]]` + +For a comprehensive list of all arguments, argument groups, CLI args, and their environment variable equivalents, please +see +the [argparse.py](https://github.com/hyperledger/aries-cloudagent-python/blob/main/aries_cloudagent/config/argparse.py) +file. + + ### Configuring ACA-PY: Command Line Parameters ACA-Py agent instances are configured through the use of command line @@ -220,8 +241,6 @@ The `manage` script is described in detail [here](https://github.com/hyperledger We use [Ruff](https://github.com/astral-sh/ruff) to enforce a coding style guide. -We use [Black](https://black.readthedocs.io/en/stable/) to automatically format code. - Please write tests for the work that you submit. Tests should reside in a directory named `tests` alongside the code under test. Generally, there is one test file for each file module under test. Test files _must_ have a name starting with `test_` to be automatically picked up the test runner. diff --git a/docs/features/SupportedRFCs.md b/docs/features/SupportedRFCs.md index 2e604885..c0dff61b 100644 --- a/docs/features/SupportedRFCs.md +++ b/docs/features/SupportedRFCs.md @@ -8,7 +8,7 @@ ACA-Py or the repository `main` branch. Reminders (and PRs!) to update this page welcome! If you have any questions, please contact us on the #aries channel on [Hyperledger Discord](https://discord.gg/hyperledger) or through an issue in this repo. -**Last Update**: 2024-05-01, Release 0.12.1 +**Last Update**: 2024-07-08, Release 1.0.0rc4 > The checklist version of this document was created as a joint effort > between [Northern Block](https://northernblock.io/), [Animo Solutions](https://animo.id/) and the Ontario government, on behalf of the Ontario government. @@ -22,7 +22,7 @@ ACA-Py and other Aries Frameworks and Agents. | AIP Version | Supported | Notes | | - | :-------: | -------- | | AIP 1.0 | :white_check_mark: | Fully supported. | -| AIP 2.0 | :white_check_mark: | Fully supported, with a couple of very minor exceptions noted [below](#aip-20). | +| AIP 2.0 | :white_check_mark: | Fully supported. | A summary of the Aries Interop Profiles and Aries RFCs supported in ACA-Py can be found [later in this document](#supported-rfcs). @@ -77,9 +77,9 @@ A summary of the Aries Interop Profiles and Aries RFCs supported in ACA-Py can b | --- | :--: | -- | | [Aries Askar] | :white_check_mark: | Recommended - Aries Askar provides equivalent/evolved secure storage and cryptography support to the "indy-wallet" part of the Indy SDK. When using Askar (via the `--wallet-type askar` startup parameter), other functionality is handled by [CredX](https://github.com/hyperledger/indy-shared-rs) (AnonCreds) and [Indy VDR](https://github.com/hyperledger/indy-vdr) (Indy ledger interactions). | | [Aries Askar]-AnonCreds | :white_check_mark: | Recommended - When using Askar/AnonCreds (via the `--wallet-type askar-anoncreds` startup parameter), other functionality is handled by [AnonCreds RS](https://github.com/hyperledger/anoncreds-rs) (AnonCreds) and [Indy VDR](https://github.com/hyperledger/indy-vdr) (Indy ledger interactions).

This `wallet-type` will eventually be the same as `askar` when we have fully integrated the AnonCreds RS library into ACA-Py. | -| [Indy SDK](https://github.com/hyperledger/indy-sdk/tree/master/docs/design/003-wallet-storage) | :warning: Deprecated | **To be removed in the next Major/Minor release of ACA-Py** Full support for the features of the "indy-wallet" secure storage capabilities found in the Indy SDK. | +| [Indy SDK](https://github.com/hyperledger/indy-sdk/tree/master/docs/design/003-wallet-storage) | :x: | **Removed in ACA-Py Release 1.0.0rc4** | -> New installations of ACA-Py should **NOT** use the [Indy SDK]. Existing deployments using the [Indy SDK] should transition to [Aries Askar] and related components as soon as possible. +> Existing deployments using the [Indy SDK] **MUST** transition to [Aries Askar] and related components as soon as possible. See the [Indy SDK to Askar Migration Guide] for guidance. [Aries Askar]: https://github.com/hyperledger/aries-askar [Indy SDK]: https://github.com/hyperledger/indy-sdk/tree/master/docs/design/003-wallet-storage diff --git a/docs/features/devcontainer.md b/docs/features/devcontainer.md index 316b1fd6..73dc62b1 100644 --- a/docs/features/devcontainer.md +++ b/docs/features/devcontainer.md @@ -44,11 +44,11 @@ To open ACA-Py in a devcontainer, we open the *root* of this repository. We can #### devcontainer.json -When the [.devcontainer/devcontainer.json](https://github.com/hyperledger/aries-cloudagent-python/blob/main/.devcontainer/devcontainer.json) is opened, you will see it building... it is building a Python 3.9 image (bash shell) and loading it with all the ACA-Py requirements (and black). We also load a few Visual Studio settings (for running Pytests and formatting with Flake and Black). +When the [.devcontainer/devcontainer.json](https://github.com/hyperledger/aries-cloudagent-python/blob/main/.devcontainer/devcontainer.json) is opened, you will see it building... it is building a Python 3.12 image (bash shell) and loading it with all the ACA-Py requirements. We also load a few Visual Studio settings (for running Pytests and formatting with Ruff). ### Poetry -The Python libraries / dependencies are installed using [`poetry`](https://python-poetry.org). For the devcontainer, we *DO NOT* use virtual environments. This means you will not see or need venv prompts in the terminals and you will not need to run tasks through poetry (ie. `poetry run black .`). If you need to add new dependencies, you will need to add the dependency via poetry *AND* you should rebuild your devcontainer. +The Python libraries / dependencies are installed using [`poetry`](https://python-poetry.org). For the devcontainer, we *DO NOT* use virtual environments. This means you will not see or need venv prompts in the terminals and you will not need to run tasks through poetry (ie. `poetry run ruff check .`). If you need to add new dependencies, you will need to add the dependency via poetry *AND* you should rebuild your devcontainer. In VS Code, open a Terminal, you should be able to run the following commands: @@ -56,7 +56,6 @@ In VS Code, open a Terminal, you should be able to run the following commands: python -m aries_cloudagent -v cd aries_cloudagent ruff check . -black . --check poetry --version ``` @@ -72,10 +71,9 @@ Found 1 error. #### extensions -We have added Black formatter and Ruff extensions. Although we have added launch settings for both `ruff` and `black`, you can also use the extension commands from the command palette. +We have added Ruff extensions. Although we have added launch settings for both `ruff`, you can also use the extension commands from the command palette. -- `Ruff: Format Document` -- `Ruff: Fix all auto-fixable problems` +- `ruff (format) - aries_cloudagent` More importantly, these extensions are now added to document save, so files will be formatted and checked. We advise that after each time you rebuild the container that you also perform: `Developer: Reload Window` to ensure the extensions are loaded correctly. diff --git a/docs/gettingStarted/AriesDeveloperDemos.md b/docs/gettingStarted/AriesDeveloperDemos.md index 69fde702..338498f6 100644 --- a/docs/gettingStarted/AriesDeveloperDemos.md +++ b/docs/gettingStarted/AriesDeveloperDemos.md @@ -21,3 +21,12 @@ and then use your new wallet to get and present credentials in some sample scena verifiable credential experience in 30 minutes or less. [BC Gov Showcase]: https://digital.gov.bc.ca/digital-trust/showcase/ + +## Indicio Developer Demo + +Minimal Aca-Py demo that can be used by developers to isolat and test features: + +- Minimal Setup (everything runs in containers) +- Quickly reproduce an issue or demonstrate a feature by writing one simple script or pytest tests. + +[Indicio Aca-Py Minimal Example](https://github.com/Indicio-tech/acapy-minimal-example) diff --git a/docs/testing/UnitTests.md b/docs/testing/UnitTests.md index 786517f1..a167128a 100644 --- a/docs/testing/UnitTests.md +++ b/docs/testing/UnitTests.md @@ -251,7 +251,7 @@ async def receive_invitation( function.`assert_called_once()` - pytest.mark setup in `setup.cfg` - can be attributed at function or class level. Example, `@pytest.mark.indy` + can be attributed at function or class level. Example, `@pytest.mark.askar` - Code coverage ![Code coverage screenshot](https://i.imgur.com/VhNYcje.png)