Deploy production worlds using AWS KMS

The MUD equivalent of root (opens in a new tab) is the owner of the root namespace, by default this is the address that deployed the World. Because this address is so powerful, its private key needs to be very secure. We recommend as best practice to use AWS Key Management Service (opens in a new tab) as the deployer for Worlds in production.

Sign up with AWS

1. If you do not already have an AWS account, create one (opens in a new tab). The free tier is sufficient for this purpose.

2. Sign in as a Root user.

Create an IAM user and an access key with permission to use the key to sign

1. In the AWS console click Services in the top-left corner and then Security, Identity, & Compliance > IAM.

2. Click Access management > Users and then click Create user.

3. Create a user called Appname_world_owner. Do not give it any permission for now.

4. Click the user name and select the Security credentials tab.

5. Scroll down and click Create access key. Select Command Line Interface (CLI) and click the confirmation. For the description tag value write Appname_world_owner_access.

6. Click Show to see the access key and keep the access key and secret access key in a safe place.

Create an Ethereum public/private key pair

You can read additional details about this process in the AWS documentation (opens in a new tab).

1. In the AWS console click Services in the top-left corner and then Security, Identity, & Compliance > Key Management Service.

2. Click Create a key and select Customer managed key. Select these parameters:

   Parameter	Value
   Key type	Asymmetric
   Key usage	Sign and verify
   Key spec	ECC_SECG_OP256K1
   Alias	Appname_world_owner_address
   Key administrators	None
   Key deletion	Clear (only root can delete this key)
   Key users	Appname_world_owner

   Sample key policy

   {
     "Id": "key-consolepolicy-3",
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "Enable IAM User Permissions",
         "Effect": "Allow",
         "Principal": {
           "AWS": "arn:aws:iam::339713099434:root"
         },
         "Action": "kms:*",
         "Resource": "*"
       },
       {
         "Sid": "Allow use of the key",
         "Effect": "Allow",
         "Principal": {
           "AWS": "arn:aws:iam::339713099434:user/Appname_world_owner"
         },
         "Action": ["kms:DescribeKey", "kms:GetPublicKey", "kms:Sign", "kms:Verify"],
         "Resource": "*"
       },
       {
         "Sid": "Allow attachment of persistent resources",
         "Effect": "Allow",
         "Principal": {
           "AWS": "arn:aws:iam::339713099434:user/Appname_world_owner"
         },
         "Action": ["kms:CreateGrant", "kms:ListGrants", "kms:RevokeGrant"],
         "Resource": "*",
         "Condition": {
           "Bool": {
             "kms:GrantIsForAWSResource": "true"
           }
         }
       }
     ]
   }

3. Write down the key ID.

Install and configure the AWS CLI

1. Install the AWS CLI from the website (opens in a new tab).

2. Set the AWS environment variables.

   Variable	Value
   AWS_ACCESS_KEY_ID	The access key you created
   AWS_SECRET_ACCESS_KEY	The secret access key
   AWS_REGION	AWS region (the first component of the console's domain name, such as us-east-2)
   AWS_ENDPOINT_URL	https:// followed by the hostname from the AWS console (opens in a new tab) for your region
   AWS_KMS_KEY_ID	The key ID for the world owner address, such as 6e8dcfb6-24fe-4fb0-a9ce-afb560f8ce7b

Use the new key

1. Get the key's deployment address and fund it. For example, if you already have your private key in $PRIVATE_KEY you can use this command to send 1 ETH to the new address on Holesky.

   AWS_ADDRESS=`cast wallet address --aws`
   export ETH_RPC_URL=https://ethereum-holesky-rpc.publicnode.com
   cast send $AWS_ADDRESS --private-key $PRIVATE_KEY --value 1ether

2. Update scripts as needed. Scripts cannot rely on reading the deployment key from the local environment when you use KMS. Instead, use vm.startBroadcast() without any parameters to get the signature using whatever mechanism is used with forge, such as KMS.

3. To deploy a new World, run this command.

   pnpm mud deploy --kms

4. If you need to run forge scripts, use this command.

   forge script --aws

   Forge will automatically detect the AWS configuration from the environment variables.