Signing Agent
Get started
This guide explains how to start using the Signing Agent in a test environment. You will create an account in the Sandbox Qredo Web App and transfer some testnet assets. The Signing Agent will automatically approve your transaction.
Preliminary steps
Step 1: Set up a Qredo account
1. Create a Qredo account. Go to the Sandbox Qredo Web App, sign in, and set up the Qredo Signing App on your phone.
2. Add an Organization. Click on your profile name, click on Add Organization, and fill in the required fields.
3. Create a Fund. Switch to your organization profile, click on Create Fund, and fill in the required fields.
4. Create a Wallet. Click on your Fund, click on Add Wallet, and follow the flow to create a Standard Wallet.
5. Enable testnet assets. Click on your profile name and go to your organization Settings. Then navigate to Preferences, click on Edit Preferences, and switch the Testnet Assets slider.
6. Make sure there are some testnet assets in you wallet. You can use faucets to get them.
You can always restore your account from Master Seed, as described in this tutorial: Restore from Master Seed
Please note that if you're recovering a Sandbox account, in the Step 5 you need to append the following to your email: @https://sandbox.qredo.network/api/v1/
For example: [email protected]@https://sandbox.qredo.network/api/v1/
Step 2: Build a Docker image
1. Clone the Signing Agent repository to a local directory with your preferred command-line tool. Make sure to clone the correct version of the Agent:
git clone --branch v1.0.1 https://github.com/qredo/signing-agent.git
2. Install and run Docker.
3. In the command line, go to the /singing-agent directory (the root of the repository) and build a Docker image:
./build.sh docker_latest
Check the Images tab in Docker: you will see a new image named signing-agent.
4. Create a /volume directory in any location and make sure you have read & write access:
mkdir volume
chmod a+rw volume
Later you will create a Docker volume in this directory.
5. Copy the config-template.yaml file from the /signing-agent directory to the /volume directory and rename it to config.yaml.
This file contains settings of your Signing Agent. Later you will edit it to adjust the settings.
Step 3: Generate keys
1. Go to the /signing-agent directory of the repository and create a file named apikey_prod.
2. In the Web App, go to your Organization settings and navigate to API > Partner API. Generate a Partner API Production key, then copy and paste it to apikey_prod.
3. In the command line, generate a private key in the /signing-agent directory:
openssl genrsa -out private.pem 2048
4. Generate the corresponding public key and save it to a file called public.pem:
openssl rsa -in private.pem -outform PEM -pubout -out public.pem
5. Open public.pem and copy the entire content of the public key, including -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----. Go to your Organization settings in the Web App, navigate to API > Partner API > Production, and register the public key.
Start
Step 4: Start the image
1. In the command line, go to the /signing-agent directory and start the Signing Agent Docker image:
docker run -ti --rm -v {path-to-the-volume-directory}:/volume -p 8007:8007 signing-agent:latest
This command automatically creates a Docker volume in the /volume directory you created before. If you check the Volumes tab in Docker, you will see a new volume named volume.
2. Check the messages returned by the command line and make sure that the Signing Agent hasn't yet started automatically approving transactions:
Agent is not yet configured, auto-approval not started
Don't close the window where the image is running: otherwise it will be stopped. Later you can revisit if to read the Signing Agent logs.
Step 5: Register the Agent
1. Start the command line in a new window/tab, go to the /signing-agent/examples directory and register your keys:
. ./set-keys.sh prod
2. Register your Signing Agent (you can specify any name, i.e. my-agent):
./register.sh my-agent
Your private information will be stored in the ccstore.db file, which is automatically created in the /volume directory. While this is fine if you're just testing Signing Agent, in a real-life situation we suggest you take extra measures to protect your information, like using a coud storage and key management service. The exact way depends on your infrastructure. Learn more here: Cloud-based storage for secrets.
3. Check the response and copy the value returned in agentID:
{"agentID":"Bn1MNQZ3kA6xXtwRrzeCy6MCtRYbV19aLyzLNGiDAYnJ","feedURL":"ws://0.0.0.0:8007/api/v1/client/feed"}
4. In the Web App, add the Signing Agent to your Organization: navigate to Members & Roles, click on Add Member, search the Agent by agentID you copied, review & save changes.
5. Go to your Wallet, navigate to Policies, and add the Signing Agent to the Transaction and Withdrawal policies. Set the Threshold to 1 of 2 in both cases.
We don't recommend setting the 2 of 2 threshold. There is a risk of locking your assets in the wallet in case one of the members is no longer able to approve transactions.
Usage
Step 6: Start approving transactions
1. Go to the window where the Signing Agent image is running and terminate the process with Ctrl + C.
2. Open the config.yaml file stored in the /volume directory. Set autoApproval: enabled to true and save the file. Now the Signing Agent will automatically approve all transactions.
It's not the most typical usage of the Signing Agent. Later you may want to create rules defining when the Signing Agent must approve or reject transactions.
3. Start the image again:
docker run -ti --rm -v {path-to-the-volume-directory}:/volume -p 8007:8007 signing-agent:latest
4. In the Web App, perform a transfer to another wallet. You will receive a push notification from the Signing App on your phone. Authorize the transaction in the Signing App.
5. You will receive a second notification asking you to approve the transaction. However, it's not necessary: the transaction will be automatically approved by the Signing Agent. Check the logs in the window where the Signing Agent image is running:
autoapprover/auto_approver.go:103 AutoApproval: action [2NPDO839ztEa5lVVH09OOXLbI6r] approved automatically
Step 7: Start listening to a WebSocket feed
While the Signing Agent is running, it's using a WebSocket feed to tracking the activity associated with your account.
To see the feed, go to the window where the Signing Agent image is running. For example, when you authorize a transaction and it's waiting for approval, the following message is returned:
[{"id":"2NPDO839ztEa5lVVH09OOXLbI6r","coreClientID":"DtmMHrSvNhaYfhHtn49tj5XkLcxW1RQrYXMrRkEWkQJi","type":"ApproveTransfer","status":"pending","timestamp":1679556788,"expireTime":1679560388}]
You can also establish a new WebSocket connection. Use the following URL:wss://sandbox-api.qredo.network/api/v1/p/coreclient/feed
Step 8: Start using the Signing Agent API
While the Signing Agent image is running, you can use the Signing Agent API.
For example, to check the Signing Agent status, use GET /healthcheck/status. Run the following in the command line:
curl -X GET 'http://localhost:8007/api/v1/healthcheck/status'
This endpoint returns the WebSocket feed URL and other details:
{"websocket":{"readyState":"OPEN","remoteFeedURL":"wss://sandbox-api.qredo.network/api/v1/p/coreclient/feed","localFeedURL":"ws://0.0.0.0:8007/api/v1/client/feed","connectedClients":0}}
The available endpoints are listed the Signing Agent API reference. This API allows getting information about the Signing Agent, registering a new Agent, and approving or rejecting transactions.
You can add your own logic to authorize or reject transactions. For example, you can base it on the amount of assets transferred. To get information about transactions, use the WebSocket feed.