> ## Documentation Index
> Fetch the complete documentation index at: https://www.dynamic.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Storage Best Practices

> How to securely store delegated key shares and wallet API keys after decryption.

<Card title="Recommended: JavaScript SDK with React Hooks" icon="react" href="/javascript/reference/react-quickstart" color="#4779FE">
  For new React apps, we recommend the JavaScript SDK with React Hooks (`@dynamic-labs-sdk/react-hooks`) instead of the legacy React SDK documented here. The JS SDK comes with many benefits such as a much smaller bundle size and other optimizations. Use the [React quickstart (JavaScript SDK)](/javascript/reference/react-quickstart) to get started.
</Card>

After decrypting the delegated materials, proper storage is critical. The `delegatedShare` and `walletApiKey`, in combination with your Dynamic developer API key, provide full signing authority and must be protected with defense-in-depth strategies.

## Recommended Storage Approaches

<AccordionGroup>
  <Accordion title="1. Envelope Encryption with Cloud KMS (Recommended)">
    Use a cloud Key Management Service to encrypt the decrypted materials before storing them in your database.

    **AWS KMS Example:**

    ```ts theme={"system"}
    import { KMSClient, EncryptCommand, DecryptCommand } from '@aws-sdk/client-kms';

    const kmsClient = new KMSClient({ region: 'us-east-1' });

    async function encryptWithKMS(plaintext: string, keyId: string) {
      const command = new EncryptCommand({
        KeyId: keyId,
        Plaintext: Buffer.from(plaintext),
      });
      const response = await kmsClient.send(command);
      return response.CiphertextBlob; // Store this in your database
    }

    async function decryptWithKMS(ciphertext: Uint8Array) {
      const command = new DecryptCommand({
        CiphertextBlob: ciphertext,
      });
      const response = await kmsClient.send(command);
      return Buffer.from(response.Plaintext).toString('utf8');
    }
    ```

    **Benefits:**

    * Centralized key management with automatic rotation
    * Hardware-backed security (FIPS 140-2 Level 3)
    * Audit logging of all encryption/decryption operations
    * Fine-grained IAM policies
  </Accordion>

  <Accordion title="2. Google Cloud KMS & Secret Manager">
    Similar to AWS KMS, but integrated with Google Cloud's ecosystem.

    ```ts theme={"system"}
    import { SecretManagerServiceClient } from '@google-cloud/secret-manager';
    import { KeyManagementServiceClient } from '@google-cloud/kms';

    const secretClient = new SecretManagerServiceClient();
    const kmsClient = new KeyManagementServiceClient();

    async function storeSecret(projectId: string, secretId: string, payload: string) {
      const [version] = await secretClient.addSecretVersion({
        parent: `projects/${projectId}/secrets/${secretId}`,
        payload: {
          data: Buffer.from(payload, 'utf8'),
        },
      });
      return version.name;
    }
    ```
  </Accordion>

  <Accordion title="3. Azure Key Vault">
    Microsoft Azure's managed secrets and key management service.

    ```ts theme={"system"}
    import { SecretClient } from '@azure/keyvault-secrets';
    import { DefaultAzureCredential } from '@azure/identity';

    const credential = new DefaultAzureCredential();
    const vaultUrl = `https://${vaultName}.vault.azure.net`;
    const client = new SecretClient(vaultUrl, credential);

    async function storeSecret(name: string, value: string) {
      await client.setSecret(name, value);
    }
    ```
  </Accordion>
</AccordionGroup>

## Security Requirements Checklist

Regardless of your storage method, follow these requirements:

* **Never log plaintext materials** — redact `delegatedShare` and `walletApiKey` from all logs, error messages, and monitoring
* **Encrypt at rest** — use AES-256-GCM or equivalent; ensure database/storage has encryption enabled
* **Encrypt in transit** — all communication must use TLS 1.3
* **Implement access controls** — restrict which services and roles can decrypt materials
* **Enable audit logging** — track all access to encrypted materials with timestamps and actor identity
* **Separate encryption keys** — don't reuse keys across environments (dev/staging/prod)
* **Use unique encryption per record** — generate new IVs for each encryption operation
* **Implement key rotation** — rotate encryption keys periodically (e.g., every 90 days)
* **Plan for key compromise** — document incident response for key material exposure
* **Secure deletion** — overwrite secrets in memory after use; use secure deletion for storage

## Storage Schema Example

```sql theme={"system"}
CREATE TABLE delegated_shares (
  id UUID PRIMARY KEY,
  user_id VARCHAR(255) NOT NULL,
  wallet_id VARCHAR(255) NOT NULL,
  chain VARCHAR(10) NOT NULL,

  -- Encrypted with KMS/Vault
  encrypted_delegated_share BYTEA NOT NULL,
  encrypted_wallet_api_key BYTEA NOT NULL,

  -- Metadata for key management
  encryption_key_id VARCHAR(255) NOT NULL,
  encryption_algorithm VARCHAR(50) DEFAULT 'AES-256-GCM',

  -- Audit fields
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  last_accessed_at TIMESTAMP,
  access_count INTEGER DEFAULT 0,

  -- Indexes
  INDEX idx_user_wallet (user_id, wallet_id),
  INDEX idx_created_at (created_at)
);
```

## What NOT to Do

<Warning>
  * **Never store plaintext shares in databases, files, or environment variables**
  * **Never commit encryption keys or shares to version control**
  * **Never use the same encryption key across all users**
  * **Never skip signature verification before storing materials**
  * **Never rely solely on database encryption without application-level encryption**
  * **Never expose decrypted materials through APIs or logs**
</Warning>