From 2162f1a93923e520711a63f9406c2896ff84efd4 Mon Sep 17 00:00:00 2001 From: Shixian Sheng Date: Wed, 1 May 2024 15:54:24 -0400 Subject: [PATCH] Update README.md Signed-off-by: Shixian Sheng --- README.md | 35 +++++++++++++++++------------------ 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index ee231d25f9..4077f04249 100644 --- a/README.md +++ b/README.md @@ -14,27 +14,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](docs/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/docs/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](docs/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/docs/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](docs/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/docs/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](docs/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/docs/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](docs/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/docs/features/Endorser.md). ### Scaled Deployments @@ -42,7 +42,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](docs/features/JsonLdCredentials.md#vc-api) and a postman demo is available [here](docs/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/docs/features/JsonLdCredentials.md#vc-api) and a postman demo is available [here](https://github.com/hyperledger/aries-cloudagent-python/blob/main/docs/features/JsonLdCredentials.md#vc-api). ## Example Uses @@ -65,7 +65,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](docs/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/docs/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 +73,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](docs/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/docs/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](docs/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](docs/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/docs/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/docs/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](docs/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/docs/deploying/Poetry.md) -[Traction Workshop]: docs/demo/Aries-Workshop.md +[Traction Workshop]: https://github.com/hyperledger/aries-cloudagent-python/blob/main/docs/demo/Aries-Workshop.md ## About the ACA-Py Admin API -The [overview of ACA-Py’s API](docs/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/docs/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 +98,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](docs/testing/Troubleshooting.md) document contains some +[Troubleshooting](https://github.com/hyperledger/aries-cloudagent-python/blob/main/docs/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 +113,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)