diff --git a/DevReadMe.md b/DevReadMe.md index becd98cbae..99eb209a1b 100644 --- a/DevReadMe.md +++ b/DevReadMe.md @@ -4,46 +4,67 @@ See the [README](README.md) for details about this repository and information ab ## Table of Contents -- [Introduction](#Introduction) -- [Installing](#Installing) -- [Developer Demos](#Developer-Demos) -- [Running](#Running) -- [Developing](#Developing) - - [Prerequisites](#Prerequisites) - - [Running Locally](#Running-Locally) - - [Running Tests](#Running-Tests) - - [Development Workflow](#Development-Workflow) - - [Dynamic Injection of Services](#Dynamic-Injection-of-Services) +- [Introduction](#introduction) +- [Developer Demos](#developer-demos) +- [Running](#running) + - [Configuring ACA-PY: Command Line Parameters](#configuring-aca-py-command-line-parameters) + - [Docker](#docker) + - [Locally Installed](#locally-installed) + - [About ACA-Py Command Line Parameters](#about-aca-py-command-line-parameters) + - [Provisioning a Wallet](#provisioning-a-wallet) +- [Developing](#developing) + - [Prerequisites](#prerequisites) + - [Running Locally](#running-locally) + - [Running Tests](#running-tests) + - [Development Workflow](#development-workflow) + - [Dynamic Injection of Services](#dynamic-injection-of-services) ## Introduction -Aries Cloud Agent Python (ACA-Py) is a configurable, extensible, non-mobile Aries agent that implements an easy way for developers to build decentralized identity applications that use verifiable credentials. +Aries Cloud Agent Python (ACA-Py) is a configurable, extensible, non-mobile Aries agent that implements an easy way for developers to build decentralized identity services that use verifiable credentials. The information on this page assumes you are developer with a background in decentralized identity, Indy, Aries and verifiable credentials. If you aren't familiar with those concepts and projects, please use our [Getting Started Guide](docs/GettingStartedAriesDev/README.md) to learn more. -## Installing - -This package is [available on PyPI](https://pypi.org/project/aries-cloudagent/) and can be installed with the following command: - -``` -pip install aries-cloudagent -``` - ## Developer Demos To put ACA-Py through its paces at the command line, checkout our [demos](docs/GettingStartedAriesDev/AriesDeveloperDemos.md) page. ## Running -After installing the PyPi package, the executable `aca-py` should be available in your PATH. +### Configuring ACA-PY: Command Line Parameters + +ACA-Py agent instances are configured through the use of command line parameters. Use the `--help` option +to discover the available command line parameters. + +### Docker + +To run a docker container based on the code in the current repo, use the following commands from the root folder of the repository to check the version, list the available modes of operation, and see all of the command line parameters: + +```bash +scripts/run_docker --version +scripts/run_docker --help +scripts/run_docker provision --help +scripts/run_docker start --help +``` + +### Locally Installed -Find out more about the available command line parameters by running: +If you installed the PyPi package, the executable `aca-py` should be available on your PATH. + +Use the following commands from the root folder of the repository to check the version, list the available modes of operation, and see all of the command line parameters: ```bash +aca-py --version aca-py --help +aca-py provision --help +aca-py start --help ``` -Currently you must specify at least one _inbound_ and one _outbound_ transport. +### About ACA-Py Command Line Parameters + +ACA-Py invocations are separated into two types - initially provisioning an agent (`provision`) and starting a new agent process (`start`). This separation enables not having to pass in some encryption-related parameters required for provisioning when starting an agent instance. This improves security in production deployments. + +When starting an agent instance, at least one _inbound_ and one _outbound_ transport MUST be specified. For example: @@ -61,61 +82,19 @@ aca-py start --inbound-transport http 0.0.0.0 8000 \ --outbound-transport http ``` -Currently, Aries Cloud Agent Python ships with both inbound and outbound transport drivers for `http` and `websockets`. More information on how to develop your own transports will be coming soon. - -Most configuration parameters are provided to the the agent at startup. Refer to the section below for details on all available command-line arguments. - -### Command Line Arguments - -| **argument** | **format example** | **effect** | **required** | -| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | -| `--inbound-transport`, `-it` | `--inbound-transport http 0.0.0.0 8000` | Defines the inbound transport(s) to listen on. This parameter can be passed multiple times to create multiple interfaces. Supported internal transport types are `http` and `ws`. | `true` | -| `--outbound-transport`, `-ot` | `--outbound-transport http` | Defines the outbound transport(s) to support for outgoing messages. This parameter can be passed multiple times to supoort multiple transport types. Supported internal transport types are `http` and `ws`. | `true` | -| `--log-config` | `--log-config /path/to/log/config.ini` | Provides a custom [python logging config file](https://docs.python.org/3/library/logging.config.html#logging-config-fileformat) to use. By default, a [default logging config](config/default_logging_config.ini) is used. | `false` | -| `--log-file` | `--log-file /path/to/logfile` | Overrides the output destination for the root logger as defined by the log config file. | `false` | -| `--log-level` | `--log-level debug` | Specifies the python log level. | `false` | -| `--endpoint`, `-e` | `--endpoint https://example.com/agent-endpoint` | Specifies the endpoint for which other agents should contact this agent. This endpoint could point to a different agent if routing is configured. The endpoint is used in the formation of a connection with another agent. | `false` | -| `--label`, `-l` | `--label "My Agent"` | Specifies the label for this agent. This label is publicized to other agents as part of forming a connection. | `false` | -| `--seed` | `--seed 00000000000000000000000000000000` | Specifies the seed for the creation of a public did for use with a Hyperledger Indy ledger | `false` | -| `--storage-type` | `--storage-type basic` | Specifies the type of storage provider to use for the internal storage engine. This storage interface is used to store internal state. Supported internal storage types are `basic` (memory) and `indy`. | `false` | -| `--wallet-key` | `--wallet-key b548y2b1919s71081583` | Specifies the master key value to use when opening the wallet. | `false` | -| `--wallet-name` | `--wallet-name my_wallet` | Specifies the wallet name. This is useful if you have multiple wallets. | `false` | -| `--wallet-type` | `--wallet-type basic` | Specifies the type of indy wallet provider to use. Supported internal storage types are `basic` (memory) and `indy`. | `false` | -| `--wallet-storage-type` | `--wallet-storage-type postgres_storage` | Specifies the type of indy wallet backend to use. Supported internal storage types are `basic` (memory), `indy`, and `postgres_storage`. | `false` | -| `--wallet-storage-config` | `--wallet-storage-config {"url":"localhost:5432"}` | Provides configuration data to the indy wallet storage driver. | `false` | -| `--wallet-storage-creds` | `--wallet-storage-creds {"account":"postgres","password":"mysecretpassword", "admin_account":"postgres","admin_password":"mysecretpassword"}` | Provides credential data to the indy wallet storage driver. | `false` | -| `--pool-name` | `--pool-name my_pool` | Specifies the name of the indy pool to be opened. This is useful if you have multiple pool configurations. | `false` | -| `--genesis-transactions` | `--genesis-transactions {"reqSignature":{},"txn":{"data":{"d... ` | Specifies the genesis transactions to use to connect to an Hyperledger Indy ledger. | `false` | -| `--genesis-url` | `--genesis-url https://example.com/genesis` | Specifies the url from which to download the genesis transaction data. For example, the [Sovrin Network genesis transactions](https://raw.githubusercontent.com/sovrin-foundation/sovrin/master/sovrin/pool_transactions_live_genesis). | `false` | -| `--admin` | `--admin 0.0.0.0 5050` | Specifies the host and port on which to run the administrative server. If not provided, no admin server is made available. | `false` | -| `--admin-insecure-mode` | `--admin-insecure-mode` | Instructs the agent to run the admin web server in insecure mode. The admin server will be publicly available to anyone who has access to the interface. | `false` | -| `--admin-api-key` | `--admin-api-key abc123` | Instructs the agent to protect all admin endpoints with the provided API key. The API must be pass in the header `X-API-Key: `. | `false` | -| `--debug` | `--debug` | Enables a remote debugging service that can be accessed using [ptvsd](https://github.com/Microsoft/ptvsd). The framework will wait for the debugger to connect at start-up. | `false` | -| `--debug-connections` | `--debug-connections` | Enables additional logging of connection information. | `false` | -| `--public-invites` | `--public-invites` | Allows the creation and reception of invitations from the public DID. | `false` | -| `--auto-accept-invites` | `--auto-accept-invites` | Instructs the agent to automatically accept invites. | `false` | -| `--auto-accept-requests` | `--auto-accept-requests` | Instructs the agent to automatically connection requests. | `false` | -| `--auto-ping-connection` | `--auto-ping-connection` | Instructs the agent to automatically send a trust ping to a connection after it is formed. | `false` | -| `--auto-respond-messages` | `--auto-respond-messages` | Instructs the agent to automatically respond to basic messages. | `false` | -| `--auto-respond-credential-offer` | `--auto-respond-credential-offer` | Instructs the agent to automatically respond to indy credential offers with a credential request. | `false` | -| `--auto-respond-presentation-request` | `--auto-respond-presentation-request` | Instructs the agent to automatically respond to indy presentation requests with a constructed presentation if exactly one credential can be retrieved for every referent in the presentation request. | `false` | -| `--auto-verify-presentation` | `--auto-verify-presentation` | Instructs the agent to automatically verify a presentation when it is received. | `false` | -| `--no-receive-invites` | `--no-receive-invites` | Disables the receive invitations administration function. | `false` | -| `--help-link` | `--help-link` | Defines the help URL for the administration interface. | `false` | -| `--invite` | `--invite` | Generates and print a new connection invitation URL on start-up. | `false` | -| `--timing` | `--timing` | Includes timing information in response messages. | `false` | -| `--protocol` | `--protocol` | Instructs the agent to load an external protocol module. | `false` | -| `--webhook-url` | `--webhook-url` | Instructs the agent to send webhooks containing internal state changes to a URL. This is useful for a controller to monitor changes and prompt new behaviour using the admin API. | `false` | +ACA-Py ships with both inbound and outbound transport drivers for `http` and `ws` (websockets). Additional transport drivers can be added as pluggable implementations. See the existing implementations in the [transports module](aries_cloudagent/transport) for getting starting on adding a new transport. + +Most configuration parameters are provided to the the agent at startup. Refer to the `Running` sections above for details on listing the available command line parameters. ### Provisioning a Wallet -It is possible to provision an Indy wallet before running an agent to avoid passing in the wallet seed on every invocation of `aca-py start`. +It is possible to provision an Indy wallet before running an agent to avoid passing in the wallet seed on every invocation of an agent (e.g. on every `aca-py start ...`). ```bash aca-py provision --wallet-type indy --seed $SEED ``` -For additional options, execute `aca-py provision --help`. +For additional `provision` options, execute `aca-py provision --help`. ## Developing @@ -125,19 +104,21 @@ For additional options, execute `aca-py provision --help`. ### Running Locally -To run the locally, we recommend using the provided Docker images to run the software. +For local development, we recommend using the provided Docker scripts to run the ACA-Py software. ```bash ./scripts/run_docker start ``` +For example: + ```bash ./scripts/run_docker start --inbound-transport http 0.0.0.0 10000 --outbound-transport http --debug --log-level DEBUG ``` -To enable the [ptvsd](https://github.com/Microsoft/ptvsd) Python debugger for Visual Studio/VSCode use the `debug` flag +To enable the [ptvsd](https://github.com/Microsoft/ptvsd) Python debugger for Visual Studio/VSCode use the `--debug` command line parameter. -Publish any ports you will be using from the docker container using the PORTS environment variable. For example: +Any ports you will be using from the docker container should be published using the `PORTS` environment variable. For example: ```bash PORTS="5000:5000 8000:8000 1000:1000" ./scripts/run_docker start --inbound-transport http 0.0.0.0 10000 --outbound-transport http --debug --log-level DEBUG @@ -147,7 +128,7 @@ Refer to [the previous section](#Running) for instructions on how to run the sof ### Running Tests -To run the test suite, use the following script: +To run the ACA-Py test suite, use the following script: ```bash ./scripts/run_tests diff --git a/README.md b/README.md index ffd802434d..fc74c1a8bf 100644 --- a/README.md +++ b/README.md @@ -7,30 +7,92 @@ -## Table of Contents +> An easy to use Aries agent for building SSI services using any language that supports sending/receiving HTTP requests. + +Hyperledger Aries Cloud Agent Python (ACA-Py) is a foundation for building self-sovereign identity (SSI) / decentralized identity services running in non-mobile environments using DIDcomm messaging, the did:peer DID method, and verifiable credentials. With ACA-Py, SSI developers can focus on building services using familiar web development technologies instead of trying to learn the nuts and bolts of low-level SDKs. + +As we create ACA-Py, we're also building resources so that developers with a wide-range of backgrounds can get productive with ACA-Py in a hurry. Checkout the [resources](#resources) section below and jump in. -- [Introduction](#Introduction) -- [Resources](#Resources) +The "cloud" in Aries Cloud Agent - Python does **NOT** mean that ACA-Py cannot be used as an edge agent. ACA-Py is suitable for use in any non-mobile agent scenario, including as an enterprise edge agent for +issuing, verifying and holding verifiable credentials. -## Introduction +## Table of Contents + +- [Background](#background) +- [Install](#install) +- [Usage](#usage) +- [Security](#security) +- [API](#api) +- [Resources](#resources) + - [Quickstart](#quickstart) + - [Architectural Deep Dive](#architectural-deep-dive) + - [Getting Started Guide](#getting-started-guide) +- [Contributing](#contributing) +- [Publishing Releases](#publishing-releases) +- [License](#license) -Hyperledger Aries Cloud Agent Python (ACA-Py) is a foundation for building decentralized identity applications and services running in non-mobile environments using DIDcomm messaging, the did:peer method, and verifiable credentials. With ACA-Py, Hyperledger Indy and Aries developers can focus on building applications using familiar web development technologies instead of trying to learn the nuts and bolts of low-level SDKs. ACA-Py is built on the Aries concepts and features defined in the [Aries RFC](https://github.com/hyperledger/aries-rfcs) repository. [This document](https://github.com/hyperledger/aries-cloudagent-python/blob/master/SupportedRFCs.md) contains a (reasonably up to date) list of supported Aries RFCs by the current ACA-Py implementation. +## Background -The ACA-Py development model is pretty straight forward for those familiar with web development. An ACA-Py instance is always deployed with a paired "controller" application that provides the business logic for that Aries agent. The controller receives webhook event notifications from its instance of ACA-Py and uses an HTTP API exposed by the ACA-Py instance to provide direction on how to respond to those events. The source of the business logic is left to your imagination. An interface to a legacy system? A user interface for a person? Custom code to implement a new service? You can build your controller in any language that supports making and receiving HTTP requests. Wait...that's every language! +Developing an ACA-Py-based application is pretty straight forward for those familiar with web development. An ACA-Py instance is always deployed with a paired "controller" application that provides the business logic for that ACA-Py agent. The controller receives webhook event notifications from its instance of ACA-Py and uses an HTTP API exposed by the ACA-Py instance to provide direction on how to respond to those events. No ACA-Py/Python development is needed--just deploy an ACA-Py instance from PyPi (examples available). The source of the business logic is your imagination. An interface to a legacy system? A user interface for a person? Custom code to implement a new service? You can build your controller in any language that supports making and receiving HTTP requests. Wait...that's every language! ACA-Py currently supports "only" Hyperledger Indy's verifiable credentials scheme (which is pretty powerful). We are experimenting with adding support to ACA-Py for other DID Ledgers and verifiable credential schemes. -As we create ACA-Py, we're building resources so that developers with a wide-range of backgrounds can get productive with ACA-Py in a hurry. Scan the resources below and jump in. +ACA-Py is built on the Aries concepts and features defined in the [Aries RFC](https://github.com/hyperledger/aries-rfcs) repository. [This document](https://github.com/hyperledger/aries-cloudagent-python/blob/master/SupportedRFCs.md) contains a (reasonably up to date) list of supported Aries RFCs by the current ACA-Py implementation. + +## Install + +ACA-Py can be run with docker without installation, or can be installed [from PyPi](https://pypi.org/project/aries-cloudagent/). Use the following command to install it locally: + +```bash +pip install aries-cloudagent +``` + +## Usage + +Instructions for running ACA-Py can be [found here](https://github.com/hyperledger/aries-cloudagent-python/blob/master/DevReadMe.md#running). + +## Security + +The administrative API exposed by the agent for the controller to use must be protected with an API key +(using the `--admin-api-key` command line arg) or deliberately left unsecured using the +`--admin-insecure-mode` command line arg. The latter should not be used other than in development if the API +is not otherwise secured. + +## API + +A deployed instance of an ACA-Py agent assembles an API from the protocols loaded with the agent that is used by a controller application (written in any language) to control the behaviour of the agent. The controller can initiate agent actions such as issuing a credential, and can respond to agent events, such +as requesting a proof after the DID Exchange process. Agent events are delivered to the controller as webhooks to a configured URL. ## Resources -If you are experienced decentralized identity developer that knows Indy, is already familiar with the concepts behind Aries, and want to play with the code and perhaps start contributing, a traditional "install and go" page for developers can be found [here](https://github.com/hyperledger/aries-cloudagent-python/blob/master/DevReadMe.md). +### Quickstart + +If you are an experienced decentralized identity developer that knows Indy, are already familiar with the concepts behind Aries, want to play with the code, and perhaps even start contributing to the project, an "install and go" page for developers can be found [here](https://github.com/hyperledger/aries-cloudagent-python/blob/master/DevReadMe.md). + +### Architectural Deep Dive + +The ACA-Py team presented an architectural deep dive webinar that can be viewed [here](https://zoom.us/recording/play/Pr-gdxAUVciy7MtPE9tkNAuSLT_Pl_NEYMeW2XxQRitjXtQajl3X5y7L_A1CCRee?autoplay=true&startTime=1563894122000). Slides from the webinar can be found [here](https://docs.google.com/presentation/d/1K7qiQkVi4n-lpJ3nUZY27OniUEM0c8HAIk4imCWCx5Q/edit#slide=id.g5d43fe05cc_0_77). + +### Getting Started Guide -For everyone else, we've created a [Getting Started Guide](https://github.com/hyperledger/aries-cloudagent-python/blob/master/docs/GettingStartedAriesDev/README.md) that will take you from knowing next to nothing about decentralized identity to developing Aries-based business apps and services in a hurry. Along the way, you'll run some early Indy apps, apps built on ACA-Py and developer-oriented demos for interacting with ACA-Py. The guide has a good table of contents so that you can skip the parts you already know. +For everyone those new to SSI, Indy and Aries, we've created a [Getting Started Guide](https://github.com/hyperledger/aries-cloudagent-python/blob/master/docs/GettingStartedAriesDev/README.md) that will take you from knowing next to nothing about decentralized identity to developing Aries-based business apps and services in a hurry. Along the way, you'll run some early Indy apps, apps built on ACA-Py and developer-oriented demos for interacting with ACA-Py. The guide has a good table of contents so that you can skip the parts you already know. We'll soon have a ReadTheDocs site published with docstrings extracted from the ACA-Py code. -Not sure where your focus should be? Building apps? Aries? Indy? Indy's Blockchain? Ursa? Here is a [document](https://github.com/hyperledger/aries-cloudagent-python/blob/master/docs/GettingStartedAriesDev/IndyAriesDevOptions.md) that goes through the technical stack to show how it the projects fit together, so you can decide where you want to focus your efforts. +Not sure where your focus should be? Building apps? Aries? Indy? Indy's Blockchain? Ursa? Here is a [document](https://github.com/hyperledger/aries-cloudagent-python/blob/master/docs/GettingStartedAriesDev/IndyAriesDevOptions.md) that goes through the technical stack to show how the projects fit together, so you can decide where you want to focus your efforts. The initial implementation of ACA-Py was developed by the Verifiable Organizations Network (VON) team based at the Province of British Columbia. To learn more about VON and what's happening with decentralized identity in British Columbia, please go to [https://vonx.io](https://vonx.io). +## Contributing + +Pull requests are welcome! Please read our [contributions guide](https://github.com/hyperledger/aries-cloudagent-python/blob/master/CONTRIBUTING.md) and submit your PRs. We enforce [developer certificate of origin](https://developercertificate.org/) (DCO) commit signing. See guidance [here](https://github.com/apps/dco). + +We also welcome issues submitted about problems you encounter in using ACA-Py. + +## Publishing Releases + +The [publishing](https://github.com/hyperledger/aries-cloudagent-python/blob/master/PUBLISHING.md) document provides information on tagging a release and publishing the release artifacts to PyPi. + +## License + +[Apache License Version 2.0](https://github.com/hyperledger/aries-cloudagent-python/blob/master/LICENSE) \ No newline at end of file diff --git a/aries_cloudagent/config/argparse.py b/aries_cloudagent/config/argparse.py index 4405c9bfa1..1e1bd8e142 100644 --- a/aries_cloudagent/config/argparse.py +++ b/aries_cloudagent/config/argparse.py @@ -87,35 +87,48 @@ def add_arguments(self, parser: ArgumentParser): type=str, nargs=2, metavar=("", ""), - help="Enable the administration API on a given host and port", + help="Specify the host and port on which to run the administrative server.\ + If not provided, no admin server is made available.", ) parser.add_argument( "--admin-api-key", type=str, metavar="", - help="Set the api key for the admin API.", + help="Protect all admin endpoints with the provided API key.\ + API clients (e.g. the controller) must pass the key in the HTTP\ + header using 'X-API-Key: '. Either this parameter or the\ + '--admin-insecure-mode' parameter MUST be specified.", ) parser.add_argument( "--admin-insecure-mode", action="store_true", - help="Do not protect the admin API with token authentication.z", + help="Run the admin web server in insecure mode. DO NOT USE FOR\ + PRODUCTION DEPLOYMENTS. The admin server will be publicly available\ + to anyone who has access to the interface. Either this parameter or\ + the '--api-key' parameter MUST be specified.", ) parser.add_argument( "--no-receive-invites", action="store_true", - help="Disable the receive invitations administration function", + help="Prevents an agent from receiving invites by removing the\ + '/connections/receive-invite' route from the administrative\ + interface. Default: false.", ) parser.add_argument( "--help-link", type=str, metavar="", - help="Define the help URL for the administration interface", + help="A URL to an administrative interface help web page that a controller\ + user interface can get from the agent and provide as a link to users.", ) parser.add_argument( "--webhook-url", action="append", metavar="", - help="Send webhooks to a given URL", + help="Send webhooks containing internal state changes to the specified\ + URL. This is useful for a controller to monitor agent events and respond\ + to those events using the admin API. If not specified, webhooks are not\ + published by the agent.", ) def get_settings(self, args: Namespace): @@ -160,71 +173,85 @@ class DebugGroup(ArgumentGroup): def add_arguments(self, parser: ArgumentParser): """Add debug command line arguments to the parser.""" parser.add_argument( - "--debug", action="store_true", help="Enable debugging features" + "--debug", + action="store_true", + help="Enables a remote debugging service that can be accessed\ + using ptvsd for Visual Studio Code. The framework will wait\ + for the debugger to connect at start-up. Default: false." ) parser.add_argument( "--debug-seed", dest="debug_seed", type=str, metavar="", - help="Specify the debug seed to use", + help="Specify the debug seed to use.", ) parser.add_argument( "--debug-connections", action="store_true", - help="Enable additional logging around connections", + help="Enable additional logging around connections. Default: false.", ) parser.add_argument( "--debug-credentials", action="store_true", - help="Enable additional logging around credential exchanges", + help="Enable additional logging around credential exchanges.\ + Default: false.", ) parser.add_argument( "--debug-presentations", action="store_true", - help="Enable additional logging around presentation exchanges", + help="Enable additional logging around presentation exchanges.\ + Default: false.", ) parser.add_argument( "--invite", action="store_true", - help="Generate and print a new connection invitation URL", + help="After startup, generate and print a new connection invitation\ + URL. Default: false.", ) parser.add_argument( "--auto-accept-invites", action="store_true", - help="Auto-accept connection invitations", + help="Automatically accept invites without firing a webhook event or\ + waiting for an admin request. Default: false.", ) parser.add_argument( "--auto-accept-requests", action="store_true", - help="Auto-accept connection requests", + help="Automatically connection requests without firing a webhook event\ + or waiting for an admin request. Default: false.", ) parser.add_argument( "--auto-respond-messages", action="store_true", - help="Auto-respond to basic messages", + help="Automatically respond to basic messages indicating the message was\ + received. Default: false.", ) parser.add_argument( "--auto-respond-credential-offer", action="store_true", - help="Auto-respond to credential offers with credential request", + help="Automatically respond to Indy credential offers with a credential\ + request. Default: false", ) parser.add_argument( "--auto-respond-presentation-request", action="store_true", - help="Auto-respond to presentation requests with a presentation " - + "if exactly one credential exists to satisfy the request", + help="Automatically respond to Indy presentation requests with a\ + constructed presentation if exactly one credential can be retrieved\ + for every referent in the presentation request. Default: false.", ) parser.add_argument( "--auto-store-credential", action="store_true", - help="Automatically store a credential upon receipt.", + help="Automatically store an issued credential upon receipt.\ + Default: false.", ) parser.add_argument( "--auto-verify-presentation", action="store_true", - help="Automatically verify a presentation when it is received", + help="Automatically verify a presentation when it is received.\ + Default: false.", ) def get_settings(self, args: Namespace) -> dict: @@ -272,7 +299,9 @@ def add_arguments(self, parser: ArgumentParser): "--storage-type", type=str, metavar="", - help="Specify the storage implementation to use", + help="Specifies the type of storage provider to use for the internal\ + storage engine. This storage interface is used to store internal state.\ + Supported internal storage types are 'basic' (memory) and 'indy'.", ) def get_settings(self, args: Namespace) -> dict: @@ -295,28 +324,34 @@ def add_arguments(self, parser: ArgumentParser): "--ledger-pool-name", type=str, metavar="", - help="Specify the pool name", + help="Specifies the name of the indy pool to be opened.\ + This is useful if you have multiple pool configurations.", ) parser.add_argument( "--genesis-transactions", type=str, dest="genesis_transactions", metavar="", - help="Specify the genesis transactions as a string", + help="Specifies the genesis transactions to use to connect to\ + an Hyperledger Indy ledger. The transactions are provided as string\ + of JSON e.g. '{\"reqSignature\":{},\"txn\":{\"data\":{\"d... '", ) parser.add_argument( "--genesis-file", type=str, dest="genesis_file", metavar="", - help="Specify a file from which to read the genesis transactions", + help="Specifies a local file from which to read the genesis transactions.", ) parser.add_argument( "--genesis-url", type=str, dest="genesis_url", metavar="", - help="Specify a url from which to fetch the genesis transactions", + help="Specifies the url from which to download the genesis\ + transactions. For example, if you are using 'von-network',\ + the URL might be 'http://localhost:9000/genesis'.\ + Genesis transactions URLs are available for the Sovrin test/main networks.", ) def get_settings(self, args: Namespace) -> dict: @@ -355,7 +390,8 @@ def add_arguments(self, parser: ArgumentParser): type=str, metavar="", default=None, - help="Redirect log output to a named file", + help="Overrides the output destination for the root logger (as defined\ + by the log config file) to the named .", ) parser.add_argument( "--log-level", @@ -363,8 +399,8 @@ def add_arguments(self, parser: ArgumentParser): type=str, metavar="", default=None, - help="Specifies a custom logging level " - + "(debug, info, warning, error, critical)", + help="Specifies a custom logging level as one of:\ + ('debug', 'info', 'warning', 'error', 'critical')", ) def get_settings(self, args: Namespace) -> dict: @@ -392,23 +428,26 @@ def add_arguments(self, parser: ArgumentParser): action="append", required=False, metavar="", - help="Provide external protocol modules", + help="Load as external protocol module. Multiple\ + instances of this parameter can be specified.", ) parser.add_argument( "--auto-ping-connection", action="store_true", - help="Automatically send a trust ping when a " - + "connection response is accepted", + help="Automatically send a trust ping immediately after a\ + connection response is accepted. Some agents require this before\ + marking a connection as 'active'. Default: false.", ) parser.add_argument( "--public-invites", action="store_true", - help="Send invitations and receive requests via the public DID", + help="Send invitations out, and receive connection requests,\ + using the public DID for the agent. Default: false.", ) parser.add_argument( "--timing", action="store_true", - help="Including timing information in response messages", + help="Include timing information in response messages.", ) def get_settings(self, args: Namespace) -> dict: @@ -442,7 +481,10 @@ def add_arguments(self, parser: ArgumentParser): nargs=3, required=True, metavar=("", "", ""), - help="Choose which interface(s) to listen on", + help="REQUIRED. Defines the inbound transport(s) on which the agent\ + listens for receiving messages from other agents. This parameter can\ + be specified multiple times to create multiple interfaces.\ + Supported inbound transport types are 'http' and 'ws'.", ) parser.add_argument( @@ -453,7 +495,10 @@ def add_arguments(self, parser: ArgumentParser): action="append", required=True, metavar="", - help="Choose which outbound transport handlers to register", + help="REQUIRED. Defines the outbound transport(s) on which the agent\ + will send outgoing messages to other agents. This parameter can be passed\ + multiple times to supoort multiple transport types. Supported outbound\ + transport types are 'http' and 'ws'.", ) parser.add_argument( @@ -461,8 +506,13 @@ def add_arguments(self, parser: ArgumentParser): "--endpoint", type=str, metavar="", - help="Specify the default endpoint to use when " - + "creating connection invitations and requests", + help="Specifies the endpoint to put into invitations and DIDDocs\ + to inform other agents of where they should send messages destined\ + for this agent. The endpoint could be one of the specified inbound\ + transports for this agent, or the endpoint could be that of\ + another agent (e.g. 'https://example.com/agent-endpoint') if the\ + routing of messages to this agent by a mediator is configured.\ + The endpoint is used in the formation of a connection with another agent.", ) parser.add_argument( @@ -470,8 +520,8 @@ def add_arguments(self, parser: ArgumentParser): "--label", type=str, metavar="