State

The Utila CLI uses a state system to securely store persistent data required for operations like transaction signing. This includes device private keys, key shares, and other sensitive information that must be preserved between CLI sessions.

State Architecture

The state system consists of two main components that work together to provide secure, flexible storage:

Storage Location

The state location determines where your state data is stored. The CLI supports multiple storage locations:

• Local filesystem (default): Stores state on your local machine
• Google Cloud Storage (GCS): Stores state in a GCS bucket
• Amazon S3: Stores state in an S3 bucket

For production use cases, especially when running the CLI on multiple machines or in automated environments, cloud storage is recommended.

State Encryption Provider

The state encryption provider determines how your state data is encrypted. The CLI supports multiple encryption options:

• Passphrase: Password-based encryption using Argon2id
• GCP KMS: Encryption using GCP Key Management Service
• AWS KMS: Encryption using AWS Key Management Service

For production environments, it is strongly recommended to use a KMS-based encryption provider for enhanced security.

State File Organization

State data follows a hierarchical structure for easy management:

state/
└── vaults/
    └── {vault-id}/
        └── devices/
            └── {device-id}/
                ├── private_key.pem
                └── key_shares/
                    └── {key-share-id}/
                        └── key_share.json

Each file in the state is encrypted independently, and encryption metadata is stored alongside the encrypted data.

Configuration

Configure your state system by configuring state location and state encryption provider.

State Location

Methods to configure (listed by precedence):

1. Command-line flag: --state-location
2. Environment variable: UTILA_STATE_LOCATION
3. Config command: utila config set state-location

Supported values:

• File paths: ~/.utila/state, /var/lib/utila/state, file:///var/lib/utila/state
• Cloud storage: s3://my-utila-state-bucket, gs://my-utila-state-bucket

Default: ~/.utila/state (or ~/.config/utila if existing state is found there)

Encryption Provider

Methods to configure (listed by precedence):

1. Command-line flag: --state-encryption-provider
2. Environment variable: UTILA_STATE_ENCRYPTION_PROVIDER
3. Config command: utila config set state-encryption-provider

Supported values:

• Passphrase: passphrase (password-based encryption)
• AWS KMS: awskms://arn:aws:kms:region:account:key/key-id
• GCP KMS: gcpkms://projects/project/locations/location/keyRings/ring/cryptoKeys/key

Available Commands

The CLI provides several commands to manage your state:

Use utila [command] --help for detailed options and examples.

Security Best Practices

✅ Do This

• Use encryption in all environments, especially production
• Choose KMS providers for production workloads (better key management and audit trails)
• Use cloud storage for multi-machine setups and automated workflows
• Backup your state regularly, particularly before migrations or major changes
• Implement proper IAM policies to restrict access to state storage locations
• Test your backup and recovery procedures periodically

⚠️ Avoid This

• Never commit state files containing private keys to version control systems
• Don't use weak passphrases if using passphrase-based encryption
• Avoid storing state in publicly accessible cloud storage buckets
• Don't share state files between different environments without proper security review

Common Scenarios

Local Development:

# Use default local storage with passphrase
utila config set state-encryption-provider passphrase

Production with Cloud Storage:

# Configure S3 storage with AWS KMS
utila config set state-location s3://company-utila-state
utila config set state-encryption-provider awskms://arn:aws:kms:us-east-1:123456789:key/abcd-1234

Migration Example:

# Move from local to cloud storage
utila state move s3://backup-bucket