A patch release to add the verification of a linkage between an inbound message and its associated connection (if any) before processing the message. Also adds some additional cleanup/fix PRs from the main branch (see list below) that might be useful for deployments currently using Release 0.12.1.
+There are no breaking changes in this release.
+main branch:Release 0.12.1 is a small patch to cleanup some edge case issues in the handling of Out of Band invitations, revocation notification webhooks, and connection querying uncovered after the 0.12.0 release. Fixes and improvements were also made to the generation of ACA-Py's OpenAPI specifications.
+There are no breaking changes in this release.
+Out of Band Invitations and Connection Establishment updates/fixes:
+ +OpenAPI/Swagger updates, fixes and cleanups:
+ +Test and Demo updates:
+ +Credential Exchange updates and fixes:
+ +Endorsement of Indy Transactions fixes:
+ +Documentation publishing process updates:
+ +Dependencies and Internal Updates:
+Release management pull requests:
+ +Release 0.12.0 is a large release with many new capabilities, feature improvements, upgrades, and bug fixes. Importantly, this release completes the ACA-Py implementation of Aries Interop Profile v2.0, and enables the elimination of unqualified DIDs. While only deprecated for now, all deployments of ACA-Py SHOULD move to using only fully qualified DIDs as soon as possible.
+Much progress has been made on did:peer support in this release, with the handling of inbound DID Peer 1 added, and inbound and outbound support for DID Peer 2 and 4. Much attention was also paid to making sure that the Peer DID and DID Exchange capabilities match those of Credo-TS (formerly Aries Framework JavaScript). The completion of that work eliminates the remaining places where "unqualified" DIDs were being used, and to enable the "connection reuse" feature in the Out of Band protocol when using DID Peer 2 and 4 DIDs in invitations. See the document Qualified DIDs for details about how to control the use of DID Peer 2 or 4 in an ACA-Py deployment, and how to eliminate the use of unqualified DIDs. Support for DID Exchange v1.1 has been added to ACA-Py, with support for DID Exchange v1.0 retained, and we've added support for DID Rotation.
Work continues towards supporting ledger agnostic AnonCreds, and the new Hyperledger AnonCreds Rust library. Some of that work is in this release, the rest will be in the next release.
+Attention was given in the release to simplifying the handling of JSON-LD Data Integrity Verifiable Credentials.
+An important change in this release is the re-organization of the ACA-Py documentation, moving the vast majority of the documents to the folders within the docs folder -- a long overdue change that will allow us to soon publish the documents on https://aca-py.org directly from the ACA-Py repository, rather than from the separate aries-acapy-docs currently being used.
A big developer improvement is a revamping of the test handling to eliminate ~2500 warnings that were previously generated in the test suite. Nice job @ff137!
+A deployment of this release that uses DID Peer 2 and 4 invitations may encounter problems interacting with agents deployed using older Aries protocols. Led by the Aries Working Group, the Aries community is encouraging the upgrade of all ecosystem deployments to accept all commonly used qualified DIDs, including DID Peer 2 and 4. See the document Qualified DIDs for more details about the transition to using only qualified DIDs. If deployments you interact with are still using unqualified DIDs, please encourage them to upgrade as soon as possible.
+Specifically for those upgrading their ACA-Py instance that create Out of Band invitations with more than one handshake_protocol, the protocol for the connection has been removed. See [Issue #2879] contains the details of this subtle breaking change.
New deprecation notices were added to ACA-Py on startup and in the OpenAPI/Swagger interface. Those added are listed below. As well, we anticipate 0.12.0 being the last ACA-Py release to include support for the previously deprecated Indy SDK.
+did:sov:... as a Protocol Doc URIhttps://didcomm.org/.DID Handling and Connection Establishment Updates/Fixes
+DID Peer and DID Resolver Updates and Fixes
+AnonCreds and Ledger Agnostic AnonCreds RS Changes
+Hyperledger Indy ledger related updates and fixes
+JSON-LD Verifiable Credential/DIF Presentation Exchange updates
+Credential Exchange (Issue, Present) Updates
+Multitenancy Updates and Fixes
+Other Fixes, Demo, DevContainer and Documentation Fixes
+Dependencies and Internal Updates
+CI/CD, Testing, and Developer Tools/Productivity Updates
+Release management pull requests
+ +Release 0.11.0 is a relatively large release of new features, fixes, and +internal updates. 0.11.0 is planned to be the last significant update before we +begin the transition to using the ledger agnostic AnonCreds +Rust in a release that is expected +to bring Admin/Controller API changes. We plan to do patches to the 0.11.x +branch while the transition is made to using [Anoncreds Rust].
+An important addition to ACA-Py is support for signing and verifying +SD-JWT verifiable credentials. We expect this to be the first of the changes +to extend ACA-Py to support OpenID4VC protocols.
+This release and Release 0.10.5 contain a high priority fix to correct
+an issue with the handling of the JSON-LD presentation verifications, where the
+status of the verification of the presentation.proof in the Verifiable
+Presentation was not included when determining the verification value (true or
+false) of the overall presentation. A forthcoming security advisory will cover
+the details. Anyone using JSON-LD presentations is recommended to upgrade to one
+of these versions of ACA-Py as soon as possible.
In the CI/CD realm, substantial changes were applied to the source base in +switching from:
+pip to Poetry for packaging and
+dependency management,asynctest to IsolatedAsyncioTestCase and AsyncMock
+objects now included in Python's builtin unittest package for unit testing.These are necessary and important modernization changes, with the latter two +triggering many (largely mechanical) changes to the codebase.
+In addition to the impacts of the change for developers in switching from pip
+to Poetry, the only significant breaking change is the (overdue) transition of
+ACA-Py to always use the new DIDComm message type prefix, changing the DID
+Message prefix from the old hardcoded did:sov:BzCbsNYhMrjHiqZDTUASHg;spec to
+the new hardcoded https://didcomm.org value, and using the new DIDComm MIME
+type in place of the old. The vast majority (all?) Aries deployments have long
+since been updated to accept both values, so this change just forces the use of
+the newer value in sending messages. In updating this, we retained the old
+configuration parameters most deployments were using
+(--emit-new-didcomm-prefix and --emit-new-didcomm-mime-type) but updated the
+code to set the configuration parameters to true even if the parameters were
+not set. See [PR #2517].
The JSON-LD verifiable credential handling of JSON-LD contexts has been updated +to pre-load the base contexts into the repository code so they are not fetched +at run time. This is a security best practice for JSON-LD, and prevents errors +in production when, from time to time, the JSON-LD contexts are unavailable +because of outages of the web servers where they are hosted. See [PR #2587].
+A Problem Report message is now sent when a request for a credential is received +and there is no associated Credential Exchange Record. This may happen, for +example, if an issuer decides to delete a Credential Exchange Record that has +not be answered for a long time, and the holder responds after the delete. See +[PR #2577].
+Release 0.10.5 is a high priority patch release to correct an issue with the
+handling of the JSON-LD presentation verifications, where the status of the
+verification of the presentation.proof in the Verifiable Presentation was not
+included when determining the verification value (true or false) of the
+overall presentation. A forthcoming security advisory will cover the details.
Anyone using JSON-LD presentations is recommended to upgrade to this version +of ACA-Py as soon as possible.
+Release 0.10.4 is a patch release to correct an issue with the handling of did:key routing
+keys in some mediator scenarios, notably with the use of [Aries Framework Kotlin]. See the
+details in the PR and [Issue #2531 Routing for agents behind a aca-py based mediator is broken].
Thanks to codespree for raising the issue and providing the fix.
+ +Release 0.10.3 is a patch release to add an upgrade process for very old +versions of Aries Cloud Agent Python (circa 0.5.2). If you have a long +time deployment of an issuer that uses revocation, this release could correct +internal data (tags in secure storage) related to revocation registries. +Details of the about the triggering problem can be found in [Issue #2485].
+The upgrade is applied by running the following command for the ACA-Py +instance to be upgraded:
+./scripts/run_docker upgrade --force-upgrade --named-tag fix_issue_rev_reg
Release 0.10.2 is a patch release for 0.10.1 that addresses three specific regressions found +in deploying Release 0.10.1. The regressions are to fix:
+http and ws (websocket) service endpoint with the same ID cannot
+message that agent. A scenario is an ACA-Py issuer connecting to an Endorser with both http and
+ws service endpoints. The updates made in 0.10.1 to improve ACA-Py DID resolution did not account
+for this scenario and needed a tweak to work ([Issue #2474], [PR #2475]).Release 0.10.1 contains a breaking change, an important fix for a regression
+introduced in 0.8.2 that impacts certain deployments, and a number of fixes and
+updates. Included in the updates is a significant internal reorganization of the
+DID and connection management code that was done to enable more flexible uses of
+different DID Methods, such as being able to use did:web DIDs for DIDComm
+messaging connections. The work also paves the way for coming updates related to
+support for did:peer DIDs for DIDComm. For details on the change see
+[PR #2409], which includes some of the best pull request documentation ever
+created.
Release 0.10.1 has the same contents as 0.10.0. An error on PyPi prevented the +0.10.0 release from being properly uploaded because of an existing file of the same +name. We immediately released 0.10.1 as a replacement.
+The regression fix is for ACA-Py deployments that use multi-use invitations but
+do NOT use the --auto-accept-connection-requests flag/processing. A change
+in 0.8.2 (PR [#2223]) suppressed an extra webhook event firing during
+the processing after receiving a connection request. An unexpected side effect
+of that change was that the subsequent webhook event also did not fire, and as a
+result, the controller did not get any event signalling a new connection request
+had been received via the multi-use invitation. The update in this release
+ensures the proper event fires and the controller receives the webhook.
See below for the breaking changes and a categorized list of the pull requests +included in this release.
+Updates in the CI/CD area include adding the publishing of a nightly container
+image that includes any changes in the main branch since the last nightly was
+published. This allows getting the "latest and greatest" code via a container image
+vs. having to install ACA-Py from the repository. In addition, Snyk scanning
+was added to the CI pipeline, and Indy SDK tests were removed from the pipeline.
[#2352] is a breaking change related to the storage of presentation exchange
+records in ACA-Py. In previous releases, presentation exchange protocol state
+data records were retained in ACA-Py secure storage after the completion of
+protocol instances. With this release the default behavior changes to deleting
+those records by default, unless the ----preserve-exchange-records flag is
+set in the configuration. This extends the use of that flag that previously
+applied only to issue credential records. The extension matches the initial
+intention of the flag--that it cover both issue credential and present proof
+exchanges. The "best practices" for ACA-Py is that the controller (business
+logic) store any long-lasting business information needed for the service that
+is using the Aries Agent, and ACA-Py storage should be used only for data
+necessary for the operation of the agent. In particular, protocol state data
+should be held in ACA-Py only as long as the protocol is running (as it is
+needed by ACA-Py), and once a protocol instance completes, the controller should
+extract and store the business information from the protocol state before it is
+deleted from ACA-Py storage.
Release 0.10.1 has the same contents as 0.10.0. An error on PyPi prevented the +0.10.0 release from being properly uploaded because of an existing file of the +same name. We immediately released 0.10.1 as a replacement.
+Release 0.9.0 is an important upgrade that changes (PR [#2302]) the dependency +on the now archived Hyperledger Ursa project to its updated, improved +replacement, AnonCreds CL-Signatures. This important change is ONLY available +when using Aries Askar as the wallet type, which brings in both [Indy VDR] and +the CL-Signatures via the latest version of CredX from the indy-shared-rs +repository. The update is NOT available to those that are using the Indy +SDK. All new deployments of ACA-Py SHOULD use Aries Askar. Further, we +strongly recommend that all deployments using the Indy SDK with ACA-Py +upgrade their installation to use Aries Askar and the related components using +the migration scripts available. An Indy SDK to Askar migration document added +to the aca-py.org documentation site, and a deprecation warning added to the +ACA-Py startup.
+The second big change in this release is that we have upgraded the primary +Python version from 3.6 to 3.9 (PR [#2247]). In this case, primary means that +Python 3.9 is used to run the unit and integration tests on all Pull Requests. +We also do nightly runs of the main branch using Python 3.10. As +of this release we have dropped Python 3.6, 3.7 and 3.8, and introduced new +dependencies that are not supported in those versions of Python. For those that +use the published ACA-Py container images, the upgrade should be easily handled. +If you are pulling ACA-Py into your own image, or a non-containerized +environment, this is a breaking change that you will need to address.
+Please see the next section for all breaking changes, and the subsequent section +for a categorized list of all pull requests in this release.
+In addition to the breaking Python 3.6 to 3.9 upgrade, there are two other +breaking changes that may impact some deployments.
+[#2034] allows for additional flexibility in using public DIDs in invitations,
+and adds a restriction that "implicit" invitations must be proactively enabled
+using a flag (--requests-through-public-did). Previously, such requests
+would always be accepted if --auto-accept was enabled, which could lead to
+unexpected connections being established.
[#2170] is a change to improve message handling in the face of delivery errors +when using a persistent queue implementation such as the ACA-Py Redis Plugin. +If you are using the Redis plugin, you MUST upgrade to Redis Plugin Release +0.1.0 in conjunction with deploying this ACA-Py release. For those using their +own persistent queue solution, see the PR [#2170] comments for information +about changes you might need to make to your deployment.
+Release 0.8.2 contains a number of minor fixes and updates to ACA-Py, including +the correction of a regression in Release 0.8.0 related to the use of plugins +(see [#2255]). Highlights include making it easier to use tracing in a +development environment to collect detailed performance information about what +is going in within ACA-Py.
+This release pulls in indy-shared-rs Release 3.3 which fixes a serious issue in AnonCreds verification, as described in issue [#2036], where the verification of a presentation with multiple revocable credentials fails when using Aries Askar and the +other shared components. This issue occurs only when using Aries Askar and indy-credx Release 3.3.
+An important new feature in this release is the ability to set some instance +configuration settings at the tenant level of a multi-tenant deployment. See PR +[#2233].
+There are no breaking changes in this release.
+Version 0.8.1 is an urgent update to Release 0.8.0 to address an inability to
+execute the upgrade command. The upgrade command is needed for 0.8.0 Pull
+Request [#2116] - "UPGRADE: Fix multi-use invitation performance", which is
+useful for (at least) deployments of ACA-Py as a mediator. In the release, the
+upgrade process is revamped, and documented in Upgrading ACA-Py.
Key points about upgrading for those with production, pre-0.8.1 ACA-Py deployments:
+upgrade command. To date, there has been no need for this feature.Recent changes to Aries Askar have resulted in Askar supporting Postgres +version 11 and greater. If you are on Postgres 10 or earlier and want to upgrade +to use Askar, you must migrate your database to Postgres 10.
+We have also noted that in some container orchestration environments such as
+Red Hat's OpenShift and possibly other Kubernetes distributions, Askar using
+Postgres versions greater than 14 do not install correctly. Please monitor
+[Issue #2199] for an update to this limitation. We have found that Postgres 15 does
+install correctly in other environments (such as in docker compose setups).
upgrade Command0.8.0 is a breaking change that contains all updates since release 0.7.5. It
+extends the previously tagged 1.0.0-rc1 release because it is not clear when
+the 1.0.0 release will be finalized. Many of the PRs in this release were previously
+included in the 1.0.0-rc1 release. The categorized list of PRs separates those
+that are new from those in the 1.0.0-rc1 release candidate.
There are not a lot of new Aries Framework features in this release, as the +focus has been on cleanup and optimization. The biggest addition is the +inclusion with ACA-Py of a universal resolver interface, allowing an instance to +have both local resolvers for some DID Methods and a call out to an external +universal resolver for other DID Methods. Another significant new capability is +full support for Hyperledger Indy transaction endorsement for Authors and +Endorsers. A new repo +aries-endorser-service +has been created that is a pre-configured instance of ACA-Py for use as an +Endorser service.
+A recently completed feature that is outside of ACA-Py is a script to migrate +existing ACA-Py storage from Indy SDK format to Aries Askar format. This +enables existing deployments to switch to using the newer Aries Askar +components. For details see the converter in the +aries-acapy-tools repository.
+With this release, a new automated process publishes container images in the +Hyperledger container image repository. New images for the release are +automatically published by the GitHubAction Workflows: publish.yml and +publish-indy.yml. The actions are triggered when a release is tagged, so no +manual action is needed. The images are published in the Hyperledger Package +Repository under aries-cloudagent-python and a link to the packages added to +the repositories main page (under "Packages"). Additional information about the +container image publication process can be found in the document Container +Images and Github Actions.
+The ACA-Py container images are based on Python 3.6 and 3.9 slim-bullseye
+images, and are designed to support linux/386
+(x86), linux/amd64 (x64), and linux/arm64. However, for this release, the
+publication of multi-architecture containers is disabled. We are working to
+enable that through the updating of some dependencies that lack that capability.
+There are two flavors of image built for each Python version. One contains only
+the Indy/Aries Shared Libraries only (Aries
+Askar, Indy
+VDR and Indy Shared
+RS, supporting only the use of
+--wallet-type askar). The other (labelled indy) contains the Indy/Aries
+shared libraries and the Indy SDK (considered deprecated). For new deployments,
+we recommend using the Python 3.9 Shared Library images. For existing
+deployments, we recommend migrating to those images.
Those currently using the container images published by BC Gov on Docker +Hub should change to use +those published to the Hyperledger Package Repository under +aries-cloudagent-python.
+The break impacts existing deployments that support implicit connections, those
+initiated by another agent using a Public DID for this instance instead of an
+explicit invitation. Such deployments need to add the configuration parameter
+--requests-through-public-did to continue to support that feature. The use
+case is that an ACA-Py instance publishes a public DID on a ledger with a
+DIDComm service in the DIDDoc. Other agents resolve that DID, and attempt to
+establish a connection with the ACA-Py instance using the service endpoint.
+This is called an "implicit" connection in RFC 0023 DID
+Exchange.
Updates the handling of "unrevealed attributes" during verification of AnonCreds +presentations, allowing them to be used in a presentation, with additional data +that can be checked if for unrevealed attributes. As few implementations of +Aries wallets support unrevealed attributes in an AnonCreds presentation, this +is unlikely to impact any deployments.
+The default behavior in ACA-Py has been to keep the full text of all messages in +the protocol state object, and include the full protocol state object in the +webhooks sent to the controller. When the messages include an object that is +very large in all the messages, the webhook may become too big to be passed via +HTTP. For example, issuing a credential with a photo as one of the claims may +result in a number of copies of the photo in the protocol state object and +hence, very large webhooks. This change reduces the size of the webhook message +by eliminating redundant data in the protocol state of the "Issue Credential" +message as the default, and adds a new parameter to use the old behavior.
+The way that multiuse invitations in previous versions of ACA-Py caused +performance to degrade over time. An update was made to add state into the tag +names that eliminated the need to scan the tags when querying storage for the +invitation.
+If you are using multiuse invitations in your existing (pre-0.8.0 deployment
+of ACA-Py, you can run an upgrade to apply this change. To run upgrade from
+previous versions, use the following command using the 0.8.0 version of
+ACA-Py, adding you wallet settings:
aca-py upgrade <other wallet config settings> --from-version=v0.7.5 --upgrade-config-path ./upgrade.yml
Verifiable credential, presentation and revocation handling updates
+Out of Band (OOB) and DID Exchange / Connection Handling / Mediator
+--mediator-invitation with OOB invitation + cleanup #1970 (shaangill025)DID Registration and Resolution related updates
+Hyperledger Indy Endorser/Author Transaction Handling
+Admin API Additions
+ +Startup Command Line / Environment / YAML Parameter Updates
+Internal Aries framework data handling updates
+Unit, Integration, and Aries Agent Test Harness Test updates
+Dependency, Python version, GitHub Actions and Container Image Changes
+Demo and Documentation Updates
+Release management pull requests
+ +0.7.5 is a patch release to deal primarily to add PR #1881 DID Exchange in +ACA-Py 0.7.4 with explicit invitations and without auto-accept +broken. A +couple of other PRs were added to the release, as listed below, and in +Milestone 0.7.5.
++++
Existing multitenant JWTs invalidated when a new JWT is +generated: If you have a pre-existing implementation with existing Admin API +authorization JWTs, invoking the endpoint to get a JWT now invalidates the +existing JWT. Previously an identical JWT would be created. Please see this +comment on PR #1725 +for more details.
0.7.4 is a significant release focused on stability and production deployments. +As the "patch" release number indicates, there were no breaking changes in the +Admin API, but a huge volume of updates and improvements. Highlights of this +release include:
+In addition, there are a significant number of general enhancements, bug fixes, +documentation updates and code management improvements.
+This release is a reflection of the many groups stressing ACA-Py in production +environments, reporting issues and the resulting solutions. We also have a very +large number of contributors to ACA-Py, with this release having PRs from 22 +different individuals. A big thank you to all of those using ACA-Py, raising +issues and providing solutions.
+A lot of work has been put into this release related to performance and load
+testing, with significant updates being made to the key "shared component"
+ACA-Py dependencies (Aries Askar, Indy
+VDR) and Indy Shared RS (including
+CredX). We now recommend using
+those components (by using --wallet-type askar in the ACA-Py startup
+parameters) for new ACA-Py deployments. A wallet migration tool from indy-sdk
+storage to Askar storage is still needed before migrating existing deployment to
+Askar. A big thanks to those creating/reporting on stress test scenarios, and
+especially the team at LISSI for creating the
+aries-cloudagent-loadgenerator
+to make load testing so easy! And of course to the core ACA-Py team for
+addressing the findings.
The largest enhancement is in the area of the endorsing of Hyperledger Indy +ledger transactions, enabling an instance of ACA-Py to act as an Endorser for +Indy authors needing endorsements to write objects to an Indy ledger. We're +working on an Aries Endorser +Service based on the new +capabilities in ACA-Py, an Endorser to be easily operated by an organization, +ideally with a controller starter kit supporting a basic human and automated +approvals business workflow. Contributions welcome!
+A focus towards the end of the 0.7.4 development and release cycle was on the +handling of AnonCreds revocation in ACA-Py. Most important, a production issue +was uncovered where by an ACA-Py issuer's local Revocation Registry data could +get out of sync with what was published on an Indy ledger, resulting in an +inability to publish new RevRegEntry transactions -- making new revocations +impossible. As a result, we have added some new endpoints to enable an update to +the RevReg storage such that RevRegEntry transactions can again be published to +the ledger. Other changes were added related to revocation in general +and in the handling of tails files in particular.
+The team has worked a lot on evolving the persistent queue (PQ) approach +available in ACA-Py. We have landed on a design for the queues for inbound and +outbound messages using a default in-memory implementation, and the ability to +replace the default method with implementations created via an ACA-Py plugin. +There are two concrete, out-of-the-box external persistent queuing solutions +available for Redis +and Kafka. +Those ACA-Py persistent queue implementation repositories will soon be migrated +to the Aries project within the Hyperledger Foundation's GitHub organization. +Anyone else can implement their own queuing plugin as long as it uses the same +interface.
+Several new ways to control ACA-Py configurations were added, including new +startup parameters, Admin API parameters to control instances of protocols, and +additional web hook notifications.
+A number of fixes were made to the Credential Exchange protocols, both for V1 +and V2, and for both AnonCreds and W3C format VCs. Nothing new was added and +there no changes in the APIs.
+As well there were a number of internal fixes, dependency updates, documentation +and demo changes, developer tools and release management updates. All the usual +stuff needed for a healthy, growing codebase.
+Hyperledger Indy Endorser related updates:
+Additions to the startup parameters, Admin API and Web Hooks
+Persistent Queues
+Credential Revocation and Tails File Handling
+Issue Credential, Present Proof updates/fixes
+Mediator updates and fixes
+Multitenacy updates and fixes
+Dependencies and internal code updates/fixes
+transport_id variable assignment back to outbound enqueue method #1776 (amanji)Documentation and Demo Updates
+Code management and contributor/developer support updates
+Release management pull requests
+This release includes some new AIP 2.0 features out (Revocation Notification and +Discover Features 2.0), a major new feature for those using Indy ledger (multi-ledger support), +a new "version upgrade" process that automates updating data in secure storage required after +a new release, and a fix for a critical bug in some mediator scenarios. The release also includes several new +pieces of documentation (upgrade processing, storage database information and logging) and some other documentation +updates that make the ACA-Py Read The Docs site +useful again. And of course, some recent bug fixes and cleanups are included.
+There is a BREAKING CHANGE for those deploying ACA-Py with an external outbound queue +implementation (see PR #1501). +As far as we know, there is only one organization that has such an implementation and they +were involved in the creation of this PR, so we are not making this release a minor or major update. +However, anyone else using an external queue should be aware of the impact of this PR that is +included in the release.
+For those that have an existing deployment of ACA-Py with long-lasting connection records, an upgrade is needed to use +RFC 434 Out of Band and the "reuse connection" as the invitee. In PR #1453 +(details below) a performance improvement was made when finding a connection for reuse. The new approach +(adding a tag to the connection to enable searching) applies only to connections made using this ACA-Py +release and later, and "as-is" connections made using earlier releases of ACA-Py will not be found as reuse +candidates. A new "Upgrade deployment" capability (#1557, +described below) must be executed to update your deployment to add tags for all existing connections.
+The Supported RFCs document has been updated to reflect the addition of the +AIP 2.0 RFCs for which support was added.
+The following is an annotated list of PRs in the release, including a link to each PR.
+--version command line option #1589A mostly maintenance release with some key updates and cleanups based on community deployments and discovery. +With usage in the field increasing, we're cleaning up edge cases and issues related to volume deployments.
+The most significant new feature for users of Indy ledgers is a simplified approach for transaction authors getting their transactions +signed by an endorser. Transaction author controllers now do almost nothing other than configuring their instance to use an Endorser, +and ACA-Py takes care of the rest. Documentation of that feature is here.
+A relatively minor maintenance release to address issues found since the 0.7.0 Release. +Includes some cleanups of JSON-LD Verifiable Credentials and Verifiable Presentations
+inject_or method to dynamic injection framework to resolve typing ambiguity (#1376)Another significant release, this version adds support for multiple new protocols, credential formats, and extension methods.
+This is a significant release of ACA-Py with several new features, as well as changes to the internal architecture in order to set the groundwork for using the new shared component libraries: indy-vdr, indy-credx, and aries-askar.
+While ACA-Py had previous support for a basic routing protocol, this was never fully developed or used in practice. Starting with this release, inbound and outbound connections can be established through a mediator agent using the Aries Mediator Coordination Protocol. This work was initially contributed by Adam Burdett and Daniel Bluhm of Indicio on behalf of SICPA. Read more about mediation support.
+Started by BMW and completed by Animo Solutions and Anon Solutions on behalf of SICPA, this feature allows for a single ACA-Py instance to host multiple wallet instances. This can greatly reduce the resources required when many identities are being handled. Read more about multi-tenancy support.
+In addition to the Aries 0160 Connections RFC, ACA-Py now supports the Aries DID Exchange Protocol for connection establishment and reuse, as well as the Aries Out-of-Band Protocol for representing connection invitations and other pre-connection requests.
+This release includes an initial implementation of the Aries Issue Credential v2 protocol.
+There are several new endpoints available for controllers as well as new startup parameters related to the multi-tenancy and mediator features, see the feature description pages above in order to make use of these features. Additional admin endpoints are introduced for the DID Exchange, Issue Credential v2, and Out-of-Band protocols.
+When running aca-py start, a new wallet will no longer be created unless the --auto-provision argument is provided. It is recommended to always use aca-py provision to initialize the wallet rather than relying on automatic behaviour, as this removes the need for repeatedly providing the wallet seed value (if any). This is a breaking change from previous versions.
When running aca-py provision, an existing wallet will not be removed and re-created unless the --recreate-wallet argument is provided. This is a breaking change from previous versions.
The logic around revocation intervals has been tightened up in accordance with Present Proof Best Practices.
+The following are breaking changes to the internal APIs which may impact Python code extensions.
+Manager classes generally accept a Profile instance, where previously they accepted a RequestContext.
Admin request handlers now receive an AdminRequestContext as app["context"]. The current profile is available as app["context"].profile. The admin server now generates a unique context instance per request in order to facilitate multi-tenancy, rather than reusing the same instance for each handler.
In order to inject the BaseStorage or BaseWallet interfaces, a ProfileSession must be used. Other interfaces can be injected at the Profile or ProfileSession level. This is obtained by awaiting profile.session() for the current Profile instance, or (preferably) using it as an async context manager:
python=
+async with profile.session() as session:
+ storage = session.inject(BaseStorage)
inject method of a context is no longer async.https://didcomm.org message type prefix (currently opt-in via the --emit-new-didcomm-prefix flag) #705, #713accept-request API method #715,
+ #716names #706create-proof API method #700get-nym-role action #671did:key: handling in out-of-band protocol support #639names and attribute-value specifications in present-proof protocol #587/credential/{id} admin route #474>, <, <= in addition to >=) #457run_docker/run_demo scripts for Windows #357present-proof/create-request admin endpoint for creating connectionless presentation requests #356connections/create-static admin endpoint for creating static connections #354initiator to connection record queries to ensure uniqueness in the case of a self-connection #161This is the first PyPI release. The history begins with the transfer of aca-py from bcgov to hyperledger.
+Hyperledger is a collaborative project at The Linux Foundation. It is an open-source and open +community project where participants choose to work together, and in that process experience +differences in language, location, nationality, and experience. In such a diverse environment, +misunderstandings and disagreements happen, which in most cases can be resolved informally. In rare +cases, however, behavior can intimidate, harass, or otherwise disrupt one or more people in the +community, which Hyperledger will not tolerate.
+A Code of Conduct is useful to define accepted and acceptable behaviors and to promote high +standards of professional practice. It also provides a benchmark for self evaluation and acts as a +vehicle for better identity of the organization.
+This code (CoC) applies to any member of the Hyperledger community – developers, participants in +meetings, teleconferences, mailing lists, conferences or functions, etc. Note that this code +complements rather than replaces legal rights and obligations pertaining to any particular +situation.
+Hyperledger is committed to maintain a positive work environment. This +commitment calls for a workplace where participants at all levels behave according +to the rules of the following code. A foundational concept of this code is that we all share +responsibility for our work environment.
+Treat each other with respect, professionalism, fairness, and sensitivity to our many + differences and strengths, including in situations of high pressure and urgency.
+Never harass or bully anyone verbally, physically or + sexually.
+Never discriminate on the basis of personal characteristics or group + membership.
+Communicate constructively and avoid demeaning or + insulting behavior or language.
+Seek, accept, and offer objective work criticism, and acknowledge properly + the contributions of others.
+Be honest about your own qualifications, and about any circumstances that might lead to conflicts + of interest.
+Respect the privacy of others and the confidentiality of data you access.
+With respect to cultural differences, be conservative in what you do and liberal in what you + accept from others, but not to the point of accepting disrespectful, unprofessional or unfair or + unwelcome behavior or advances.
+Promote the rules of this Code and take action (especially if you are in a + leadership position) to bring the discussion back to a more civil level + whenever inappropriate behaviors are observed.
+Stay on topic: Make sure that you are posting to the correct channel and avoid off-topic + discussions. Remember when you update an issue or respond to an email you are potentially + sending to a large number of people.
+Step down considerately: Members of every project come and go, and the Hyperledger is no + different. When you leave or disengage from the project, in whole or in part, we ask that you do + so in a way that minimizes disruption to the project. This means you should tell people you are + leaving and take the proper steps to ensure that others can pick up where you left off.
+is acting in a way that reduces another person's dignity, sense of self-worth or respect within the +community.
+is the prejudicial treatment of an individual based on criteria such as: physical appearance, race, +ethnic origin, genetic differences, national or social origin, name, religion, gender, sexual +orientation, family or health situation, pregnancy, disability, age, education, wealth, domicile, +political view, morals, employment, or union activity.
+is treating another person with scorn or disrespect.
+is a record of the origin(s) and author(s) of a contribution.
+is any conduct, verbal or physical, that has the intent or effect of interfering with an individual, +or that creates an intimidating, hostile, or offensive environment.
+includes group Chairs, project maintainers, staff members, and Board members.
+includes the following persons:
+is the genuine consideration you have for someone (if only because of their status as participant in +Hyperledger, like yourself), and that you show by treating them in a polite and kind way.
+includes visual displays of degrading sexual images, sexually suggestive conduct, offensive remarks +of a sexual nature, requests for sexual favors, unwelcome physical contact, and sexual assault.
+Hard to define? Some questions to ask yourself are:
+includes requests for sexual favors, and other verbal or physical conduct of a sexual nature, where:
+is a tendency of individuals or groups to use persistent aggressive or unreasonable behavior (e.g. +verbal or written abuse, offensive conduct or any interference which undermines or impedes work) +against a co-worker or any professional relations.
+is the set of all available means of collaboration, including, but not limited to messages to +mailing lists, private correspondence, Web pages, chat channels, phone and video teleconferences, +and any kind of face-to-face meetings or discussions.
+To report incidents or to appeal reports of incidents, send email to Mike Dolan +(mdolan@linuxfoundation.org) or Angela +Brown (angela@linuxfoundation.org). Please +include any available relevant information, including links to any publicly +accessible material relating to the matter. Every effort will be taken to ensure +a safe and collegial environment in which to collaborate on matters relating to +the Project. In order to protect the community, the Project reserves the right +to take appropriate action, potentially including the removal of an individual +from any and all participation in the project. The Project will work towards an +equitable resolution in the event of a misunderstanding.
+This code is based on the +W3C’s Code of Ethics and Professional Conduct with some +additions from the Cloud Foundry‘s Code of Conduct.
+ + + + + + + + + + + + + +You are encouraged to contribute to the repository by forking and submitting a pull request.
+For significant changes, please open an issue first to discuss the proposed changes to avoid re-work.
+(If you are new to GitHub, you might start with a basic tutorial and check out a more detailed guide to pull requests.)
+Pull requests will be evaluated by the repository guardians on a schedule and if deemed beneficial will be committed to the main branch. Pull requests should have a descriptive name, include a summary of all changes made in the pull request description, and include unit tests that provide good coverage of the feature or fix. A Continuous Integration (CI) pipeline is executed on all PRs before review and contributors are expected to address all CI issues identified. Where appropriate, PRs that impact the
+end-user and developer demos in the repo should include updates or extensions to those demos to cover the new capabilities.
If you would like to propose a significant change, please open an issue first to discuss the work with the community.
+Contributions are made pursuant to the Developer's Certificate of Origin, available at https://developercertificate.org, and licensed under the Apache License, version 2.0 (Apache-2.0).
+A configuration for pre-commit 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:
+ +To install the commit message linter:
+ + + + + + + + + + + + + + +Maintainers are assigned the following scopes in this repository:
+| Scope | +Definition | +GitHub Role | +GitHub Team | +
|---|---|---|---|
| Admin | ++ | Admin | +aries-admins | +
| Maintainer | +The GitHub Maintain role | +Maintain | +aries-cloudagent-python committers | +
| Triage | +The GitHub Triage role | +Triage | +aries triage | +
| Read | +The GitHub Read role | +Read | +Aries Contributors | +
| Read | +The GitHub Read role | +Read | +TOC | +
| Read | +The GitHub Read role | +Read | +aries-framework-go-ext committers | +
| GitHub ID | +Name | +Scope | +LFID | +Discord ID | +Company Affiliation | +|
|---|---|---|---|---|---|---|
| andrewwhitehead | +Andrew Whitehead | +Admin | ++ | + | cywolf@gmail.com | +BC Gov | +
| dbluhm | +Daniel Bluhm | +Admin | ++ | + | daniel@indicio.tech | +Indicio PBC | +
| dhh1128 | +Daniel Hardman | +Admin | ++ | + | daniel.hardman@gmail.com | +Provident | +
| shaangill025 | +Shaanjot Gill | +Maintainer | ++ | + | gill.shaanjots@gmail.com | +BC Gov | +
| swcurran | +Stephen Curran | +Admin | ++ | + | swcurran@cloudcompass.ca | +BC Gov | +
| TelegramSam | +Sam Curren | +Maintainer | ++ | + | telegramsam@gmail.com | +Indicio PBC | +
| TimoGlastra | +Timo Glastra | +Admin | ++ | + | timo@animo.id | +Animo Solutions | +
| WadeBarnes | +Wade Barnes | +Admin | ++ | + | wade@neoterictech.ca | +BC Gov | +
| usingtechnology | +Jason Sherman | +Maintainer | ++ | + | tools@usingtechnolo.gy | +BC Gov | +
| Name | +GitHub ID | +Scope | +LFID | +Discord ID | +Company Affiliation | +|
|---|---|---|---|---|---|---|
| + | + | + | + | + | + | + |
Maintainers are expected to perform the following duties for this repository. The duties are listed in more or less priority order:
+This community welcomes contributions. Interested contributors are encouraged to +progress to become maintainers. To become a maintainer the following steps +occur, roughly in order.
+Being a maintainer is not a status symbol or a title to be carried +indefinitely. It will occasionally be necessary and appropriate to move a +maintainer to emeritus status. This can occur in the following situations:
+The process to move a maintainer from active to emeritus status is comparable to the process for adding a maintainer, outlined above. In the case of voluntary +resignation, the Pull Request can be merged following a maintainer PR approval. If the removal is for any other reason, the following steps SHOULD be followed:
+Returning to active status from emeritus status uses the same steps as adding a +new maintainer. Note that the emeritus maintainer already has the 5 required +significant changes as there is no contribution time horizon for those.
+ + + + + + + + + + + + + +The code to be published should be in the main branch. Make sure that all the PRs to go in the release are
+merged, and decide on the release tag. Should it be a release candidate or the final tag, and should it be
+a major, minor or patch release, per semver rules.
Once ready to do a release, create a local branch that includes the following updates:
+Create a PR branch from an updated main branch.
Update the CHANGELOG.md to add the new release. Only create a new section when working on the first release candidate for a new release. When transitioning from one release candidate to the next, or to an official release, just update the title and date of the change log section.
+Include details of the merged PRs included in this release. General process to follow:
+Gather the set of PRs since the last release and put them into a list. A good + tool to use for this is the + github-changelog-generator. + Steps:
+repo / public_repo.docker run -it --rm -v "$(pwd)":/usr/local/src/your-app
+ githubchangeloggenerator/github-changelog-generator --user hyperledger
+ --project aries-cloudagent-python --output 0.11.0rc2.md --since-tag 0.10.4
+ --future-release 0.11.1rc2 --release-branch main --token <your-token>In some cases, the approach above fails because of too many API calls. An +alternate approach to getting the list of PRs in the right format is to use OpenAI ChatGPT.
+Prepare the following ChatGPT request. Don't hit enter yet--you have to add the data.
+Generate from this the github pull request number, the github id of the author and the title of the pull request in a tab-delimited list
Get a list of the merged PRs since the last release by displaying the PR list in
+the GitHub UI, highlighting/copying the PRs and pasting them below the ChatGPT
+request, one page after another. Hit <Enter>, let the AI magic work, and you
+should have a list of the PRs in a nice table with a Copy link that you should click.
Once you have that, open this Google Sheet and highlight the A1 cell and
+paste in the ChatGPT data. A formula in column E will have the properly
+formatted changelog entries. Double check the list with the GitHub UI to make
+sure that ChatGPT isn't messing with you and you have the needed data.
If using ChatGPT doesn't appeal to you, try this scary sed/command line approach:
changelog.sed/Approved/d
+/updated /d
+/^$/d
+/^ [0-9]/d
+s/was merged.*//
+/^@/d
+s# by \(.*\) # [\1](https://github.com/\1)#
+s/^ //
+s# \#\([0-9]*\)# [\#\1](https://github.com/hyperledger/aries-cloudagent-python/pull/\1) #
+s/ / /g
+/^Version/d
+/tasks done/d
+s/^/- /
+is:pr is:merged sort:updated
+ merged:>2022-04-07) and for each page, highlight, and copy the text
+ of only the list of PRs on the page to use in the following step.sed -e :a -e '$!N;s/\n#/ #/;ta' -e 'P;D' <<EOF | sed -f changelog.sed,
+ paste in the copied text and then type EOF.
+ Redirect the output to a file, appending each page of output to the file.sed command in the pipeline merges the PR title and PR number
+ plus author lines onto a single line. The commands in the changelog.sed
+ file just clean up the data, removing unwanted lines, etc.wc of the file and there
+ should be one line per PR. You should scan the file as well, looking for
+ anomalies, such as missing \s before # characters. It's a pretty ugly process.curl command and the GitHub API is probably a much better and more
+ robust way to do this, but this was quick and dirty...Once you have the list of PRs:
+Add a narrative about the release above the PR that highlights what has gone into the release.
+Check to see if there are any other PRs that should be included in the release.
+Update the ReadTheDocs in the /docs folder by following the instructions in
+ the ./UpdateRTD.md file. That will likely add a number of new and modified
+ files to the PR. Eliminate all of the errors in the generation process,
+ either by mocking external dependencies or by fixing ACA-Py code. If
+ necessary, create an issue with the errors and assign it to the appropriate
+ developer. Experience has demonstrated to use that documentation generation
+ errors should be fixed in the code.
Search across the repository for the previous version number and update it
+ everywhere that makes sense. The CHANGELOG.md entry for the previous release
+ is a likely exception, and the pyproject.toml in the root MUST be
+ updated. You can skip (although it won't hurt) to update the files in the
+ open-api folder as they will be automagically updated by the next step in
+ publishing. The incremented version number MUST adhere to the Semantic
+ Versioning
+ Specification
+ based on the changes since the last published release. For Release
+ Candidates, the form of the tag is "0.11.0rc2". As of release 0.11.0 we
+ have dropped the previously used - in the release candidate version string
+ to better follow the semver rules.
Regenerate openapi.json and swagger.json by running
+ ../scripts/generate-open-api-spec from within the aries_cloudagent folder.
Command: cd aries_cloudagent;../scripts/generate-open-api-spec;cd ..
Double check all of these steps above, and then submit a PR from the branch. + Add this new PR to CHANGELOG.md so that all the PRs are included. + If there are still further changes to be merged, mark the PR as "Draft", + repeat ALL of the steps again, and then mark this PR as ready and then + wait until it is merged. It's embarrassing when you have to do a whole new + release just because you missed something silly...I know!
+Immediately after it is merged, create a new GitHub tag representing the + version. The tag name and title of the release should be the same as the + version in pyproject.toml. Use + the "Generate Release Notes" capability to get a sequential listing of the + PRs in the release, to complement the manually curated Changelog. Verify on + PyPi that the version is published.
+New images for the release are automatically published by the GitHubAction + Workflows: publish.yml and publish-indy.yml. The actions are triggered + when a release is tagged, so no manual action is needed. The images are + published in the Hyperledger Package Repository under + aries-cloudagent-python + and a link to the packages added to the repositories main page (under + "Packages").
+Additional information about the container image publication process can be + found in the document Container Images and Github Actions.
+Update the ACA-Py Read The Docs site by building the new "latest" (main + branch) and activating and building the new release. Appropriate permissions + are required to publish the new documentation version.
+Update the https://aca-py.org website with the latest documentation by + creating a PR and tag of the latest documentation from this site. Details + are provided in the aries-acapy-docs repository.
+If you think you have discovered a security issue in any of the Hyperledger projects, we'd love to +hear from you. We will take all security bugs seriously and if confirmed upon investigation we will +patch it within a reasonable amount of time and release a public security bulletin discussing the +impact and credit the discoverer.
+There are two ways to report a security bug. The easiest is to email a description of the flaw and +any related information (e.g. reproduction steps, version) to +security at hyperledger dot org.
+The other way is to file a confidential security bug in our +JIRA bug tracking system. Be sure to set the “Security Level” to +“Security issue”.
+The process by which the Hyperledger Security Team handles security bugs is documented further in +our Defect Response page on our +wiki.
+ + + + + + + + + + + + + +Read The Docs Documentation¶This document describes how to maintain the Read The Docs documentation that
+is generated from the ACA-Py code base. As the structure of the ACA-Py code
+evolves, the RTD files need to be regenerated and possibly updated, as described here.
To test generate and view the RTD documentation locally, you must install Sphinx and the +Sphinx RTD theme. Follow the instructions on the respective pages to install +and verify the installation on your system.
+To rebuild the project and settings from scratch (you'll need to move the generated index file up a level):
+rm -rf generated; sphinx-apidoc -f -M -o ./generated ../aries_cloudagent/ $(find ../aries_cloudagent/ -name '*tests*')
Note that the find command that is used to exclude any of the test python files from the RTD documentation.
Check the git status in your repo to see if the generator updates, adds or removes any existing RTD modules.
To auto-generate the module documentation locally run:
+ +Once generated, go into the _build folder and open index.html in a browser. Note that the _build is
+.gitignore'd and so will not be part of a git push.
This is the hard part; looking for errors in docstrings added by devs. Some tips:
+No module named 'async_timeout') can be solved by adding the module to the
+list of autodoc_mock_imports in the conf.py file in the ACA-Py docs folder.docs/README.mdOther than that, please investigate and fix things that you find. If there are fixes, it's usually +to adhere to the rules around processing docstrings, and especially around JSON samples.
+The file index.rst in the ACA-Py docs folder drive the RTD generation. It picks up all the modules
+in the source code, starting from the root ../aries_cloudagent folder. However, some modules
+are not picked up automatically from the root and have to be manually added to index.rst. To do that:
ls generated | grep "aries_cloudagent.[a-z]*.rst"If any are missing, you likely need to add them to the index.rst file in the toctree section of the file.
+You will see there are already several instances of that, notably "connections" and "protocols".
The RTD documentation is not currently auto-generated, so a manual re-generation of the documentation +is still required.
+++ + + + + + + + + + + + + +TODO: Automate this when new tags are applied to the repository.
+
Welcome to the Aries Cloud Agent Python documentation site. On this site you
+will find documentation for recent releases of ACA-Py. You'll find a few of the
+older versions of ACA-Py (pre-0.8.0), all versions since 0.8.0, and the
+main branch, which is the latest and greatest.
All of the documentation here is extracted from the Aries Cloud Agent Python repository. +If you want to contribute to the documentation, please start there.
+Ready to go? Scan the tabs in the page header to find the documentation you need now!
+In addition to this documentation site, the ACA-Py community also maintains an
+ACA-Py internals documentation site. The internals documentation consists of the
+docstrings extracted from the ACA-Py Python code and covers all of the
+(non-test) modules in the codebase. Check it out on the Aries Cloud
+Agent-Python ReadTheDocs site.
+As with this site, the ReadTheDocs documentation is version specific.
Got questions?
+#aries-cloudagent-python channel.File not found
+ ++ The site configured at this address does not + contain the requested file. +
+ +
+ If this is your site, make sure that the filename case matches the URL
+ as well as any file permissions.
+ For root URLs (like http://example.com/) you must provide an
+ index.html file.
+
+ Read the full documentation + for more information about using GitHub Pages. +
+ +
+
+
+
+ 
+
+ Put any assets (images, source for images, videos, etc.) in this folder to be referenced in the various documents for this repo.
+Plantuml diagrams are stored in this folder in source form in files ending in .puml and are generated manually using the ./genPlantuml script. The script uses a docker image from docker-hub and can be run without downloading any dependencies.
If you don't want to use the script, download plantuml and a command line utility and use that for the plantuml generation. I preferred not having any dependencies used (other than docker) and couldn't find +a nice way to run plantuml headless from a command line.
+It would be better to use a local Dockerfile vs. one found on Docker Hub. The one I did find was simple and straight forward.
I couldn't tell if the svg generation was working so just went with png. Not sure which would be better.
+ + + + + + + + + + + + + +