# Set up and run CloudSign

## Overview

Programmatic MPC using Cloud Sign requires the following workflow:

1. Setup 3 Cloud Sign devices in the Wallet-as-a-Service (Palisade) console and securely store the pairing key for each device
2. Run all Cloud Sign nodes, each with its respective pairing key
3. Approve or have an administrator approve each Cloud Sign device
4. Create an MPC quorum comprising the Cloud Sign devices
5. Create an MPC key with the Cloud Sign quorum


Why 3 devices?
We're setting up 3 Cloud Sign devices because a single MPC quorum requires a total of 3 signers (with 2 required to sign transactions).

# Cloud Sign device setup in Wallet-as-a-Service (Palisade) console

Login to the Wallet-as-a-Service (Palisade) console as administrator or a standard user. Navigate to [devices](https://app.sandbox.palisade.co/devices) page.

1. Click [Add a device](https://app.sandbox.palisade.co/devices/create).
2. Choose CloudSign as device type.
3. Give the device a meaningful name.
4. Click Save and continue


![CloudSign device creation](https://files.readme.io/14c7c6cefc0d7efcbc1996016100bc1f3a20827f7d1c0e4f4ad769ff8cfec636-cs1.png)

You should see the following screen.

![CloudSign pairing key screen](https://files.readme.io/83a1ed3b37698e3685ca1bbfcd771bc211dbb4a36b20e7d9b24318b947b81d8d-cs2.png)

You have created a Cloud Sign device in the Wallet-as-a-Service (Palisade) console with the specified name. By default, the device is in an 'Unpaired' state, indicating that it has not been initialised and is not available for use.

The Cloud Sign node that you will run in the next step requires the pairing key which you can copy from this screen. The pairing key contains one-time authentication credentials so it is important to keep it safe.

Securely copy and record the pairing key.

Repeat above steps (from adding a new device to the Wallet-as-a-Service (Palisade) console to copying and recording the pairing key) for a total of 3 times, one for each Cloud Sign device.

# Cloud Sign node setup

## 1. Network architecture requirements

Set up your AWS environment with the following essential resources:

* AWS SDK
* Docker
* EC2 machine


We also recommend setting up an IAM Role and Amazon KMS Key to enable the database to be encrypted securely using `DB_ENCRYPTION_KEY_REF` - see section 5 below.

## 2. Authenticate your AWS account

Wallet-as-a-Service (Palisade) uses AWS IAM authentication for external facing cloud access. Export the following variables using the credentials **provided to you by Palisade**:


```shell
export AWS_ACCESS_KEY_ID=<palisade_provided_access_key_id>
export AWS_SECRET_ACCESS_KEY=<palisade_provided_secret_access_key>
export AWS_DEFAULT_REGION=eu-west-2
```

> **Important:** These credentials are provided by Palisade specifically for accessing the CloudSign docker repository. Please keep these variables confidential as they contain credentials that grant access to Wallet-as-a-Service (Palisade)'s docker repository.


## 3. Login to Wallet-as-a-Service (Palisade)'s docker repository

Once the environment variables for `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` are set, execute the following to login to the Wallet-as-a-Service (Palisade)'s docker repository:


```shell
aws ecr get-login-password --region eu-west-2 | docker login --username AWS --password-stdin 335650072995.dkr.ecr.eu-west-2.amazonaws.com
```

## 4. Pull the CloudSign docker image


```shell
docker pull 335650072995.dkr.ecr.eu-west-2.amazonaws.com/external/custody/cloudsign/app:1.12.0
```

## 5. Quick Start CloudSign (testing only)

Run the following command to start a CloudSign node in the foreground:


```bash
docker run \
  -v /path/to/volume:/var/cloudsign \
  -e DB_ENCRYPTION_KEY_HEX=YOUR_ENCRYPTION_KEY \
  -e PAIRING_KEY=YOUR_PAIRING_KEY \
  -e LOG_LEVEL=debug \
  --rm \
  --name cloudsign-node \
  -it 335650072995.dkr.ecr.eu-west-2.amazonaws.com/external/custody/cloudsign/app:1.12.0
```

Replace `/path/to/volume` with your desired shard storage location.

Data is encrypted by default using the encryption key provided in `DB_ENCRYPTION_KEY_HEX`. This directory must be backed up and protected and the encryption key changed before first use.

Navigate to your Wallet-as-a-Service (Palisade) dashboard and add a new CloudSign device, then use the generated `PAIRING_KEY` from the Wallet-as-a-Service (Palisade) dashboard.

Note that this will run a CloudSign node in a container called `cloudsign-node`.

Production recommendation
We recommend using the `DB_ENCRYPTION_KEY_REF` in production with the ARN of the Amazon KMS key instead of the `DB_ENCRYPTION_KEY_HEX` as it provides a more secure way of handling the encryption secret. This approach ensures that all node data is encrypted using a physical HSM. Note that if you use this approach, your CloudSign node must have "encrypt" and "decrypt" permissions on Amazon KMS.

## 6. Run the CloudSign node

Run the CloudSign node using docker-compose script. The following example script runs 3 CloudSign nodes, on the basis that 3 CloudSign devices have been added in Wallet-as-a-Service (Palisade):


```yaml
services:
  cloudsign1:
    image: 335650072995.dkr.ecr.eu-west-2.amazonaws.com/external/custody/cloudsign/app:1.12.0
    container_name: cloudsign1
    environment:
      DB_ENCRYPTION_KEY_HEX: ${ENCRYPTION_KEY_1}
      PAIRING_KEY: ${PAIRING_KEY_1}
    volumes:
      - ${VOLUME_1}:/var/cloudsign
  cloudsign2:
    image: 335650072995.dkr.ecr.eu-west-2.amazonaws.com/external/custody/cloudsign/app:1.12.0
    container_name: cloudsign2
    environment:
      DB_ENCRYPTION_KEY_HEX: ${ENCRYPTION_KEY_2}
      PAIRING_KEY: ${PAIRING_KEY_2}
    volumes:
      - ${VOLUME_2}:/var/cloudsign
  cloudsign3:
    image: 335650072995.dkr.ecr.eu-west-2.amazonaws.com/external/custody/cloudsign/app:1.12.0
    container_name: cloudsign3
    environment:
      DB_ENCRYPTION_KEY_HEX: ${ENCRYPTION_KEY_3}
      PAIRING_KEY: ${PAIRING_KEY_3}
    volumes:
      - ${VOLUME_3}:/var/cloudsign
```

It requires the `ENCRYPTION_KEY`, `PAIRING_KEY` and `VOLUME` suffixed by a number identifying the CloudSign node.

Example `.env` file configuration:


```shell
# cloudsign1
ENCRYPTION_KEY_1=c6516198ba86603e2fda776706b44373d5630cd2e89352772a9b75cda2df67ed
PAIRING_KEY_1=eyJkZXZpY2VJZCI6ImQz...8ifQ==
VOLUME_1=/tmp/cloudsign1

# cloudsign2
ENCRYPTION_KEY_2=0c92f60527b778f2f0036067429b3982d2c7f79ef657943f0e18c1e918362aa6
PAIRING_KEY_2=eyJkZXZpY2VJZCI6IjJm...8ifQ==
VOLUME_2=/tmp/cloudsign2

# cloudsign3
ENCRYPTION_KEY_3=bf7e463d11347c486f4b8e79284a02e0543369009ff0d1efc1d2644fe63b21a7
PAIRING_KEY_3=eyJkZXZpY2VJZCI6Ijg5...8ifQ==
VOLUME_3=/tmp/cloudsign3
```

Please note that directories defined in `VOLUME_x` environment variable need to exist before running the docker-compose script.

# Approve Cloud Sign devices

Once the Cloud Sign instances are running, each device in the Wallet-as-a-Service (Palisade) console will move from 'Unpaired' state to 'Waiting for approval' state. This indicates that the Cloud Sign devices have been initialized but are not yet ready to use.

An administrator needs to approve each of the Cloud Sign devices from the Wallet-as-a-Service (Palisade) console in order to make them usable.

Once the Cloud Sign devices have been approved, they will move to 'Paired' state. They are now ready to use in an MPC quorum.

# Create an MPC quorum

Each Cloud Sign device can be a member of many quorums. In order to initialize a quorum, navigate to the Controls → MPC Quorums section of the Wallet-as-a-Service (Palisade) console and click 'Create quorum'.

1. Select Quorum type to be Cloud Sign
2. Give a meaningful name and a description
3. Select the 3 Cloud Sign devices to be part of that quorum
4. Select 2 under the Required signatures drop down


Important
This is a one-time action. A quorum cannot be changed once created.

Click Create to create the quorum. The Cloud Sign nodes will be notified of the quorum creation request and will subsequently join the quorum. Once all devices have successfully joined the quorum, the quorum will move to 'Confirmed' state.

# Create an MPC key

A MPC key requires at least one MPC quorum in 'Confirmed' state. Navigate to the Vaults → *[your vault]* section. Click Create key. Fill out the relevant details:

1. Give the key a meaningful name and description
2. Select the blockchain you want to use
3. Select keystore as 'MPC'
4. Select the quorum you recently created


Important
Select the method for securely generating and storing your key. This cannot be changed once the key is created.

Each of the Cloud Sign nodes participating in the selected quorum will receive a notification for provisioning the key. Once the key provisioning is complete, the key page will reflect the key status.

A successfully provisioned key will display a public address and can be enabled for use.

# Network setup options

## 1. Single node setup

A single node setup is suitable in cases where you are one of the shard holders among other shard holders. It assumes that you are not holding the entire quorum yourself, i.e. hosting all of the CloudSign devices.

![Single node setup architecture](https://files.readme.io/e6ef56d0dfb3cba971b8c03da4168e13898d8d3d6e99cbdb183aa6d0e57a8223-image.png)

Here, we have one CloudSign instance running on an EC2 machine. The state is stored on a mounted EBS volume, on an encrypted disk. It has outbound connectivity through a NAT in a public subnet to the Wallet-as-a-Service (Palisade) Platform as well as the MPC Messaging Layer. Please note that the NAT gateway here does not allow any inbound traffic.

## 2. Quorum setup

A quorum setup is suitable when you are holding all the shards of the quorum. The reference below lowers network risk and provides redundancy in case of loss or unavailability of some shards.

![Quorum setup architecture](https://files.readme.io/6109ba5c94d4160e1f9babd881f2890be174cb76ea1d439c962f06772b483ffa-image_1.png)

Here, we have a 2/3 quorum setup (two of the three CloudSign devices in the quorum are required to sign transactions). The setup of each individual CloudSign instance is no different than the single node setup described above.

## Best practices

We strongly suggest adhering to the below best practices when setting up both single node and quorum networks:

* Use separate AWS Accounts or Organizations to further segregate access and privileges for CloudSign
* Use separate single purpose multi region replicated KMS keys for encrypting disks and EBS volumes
* EC2 must not allow any inbound access (including SSH)
* Ensure EC2 instances are using trusted AMIs
* Ensure the EBS volumes are backed up securely using snapshots


## Troubleshooting

| Problem | Cause | Solution |
|  --- | --- | --- |
| Device stays in **Unpaired** | Node not running or pairing key incorrect | Verify container is running; check pairing key matches |
| Device stuck on **Waiting for approval** | No administrator approval | Have an administrator approve the device |
| Quorum not moving to **Confirmed** | One or more nodes offline | Ensure all 3 Cloud Sign containers are running |
| Key provisioning fails | Quorum not confirmed or nodes unreachable | Verify quorum status is **Confirmed**; check node connectivity |


Docker image version
Confirm the current Cloud Sign Docker image version with your Palisade representative before deployment.