DataEscrow CLI Decryption Tool

A secure and user-friendly command-line interface for decrypting data stored in the DataEscrow system.

Overview

The DataEscrow CLI Decryption Tool provides decryption capabilities for three escrow types:

• DAO Escrow
• Zone Escrow
• Data Escrow

It offers robust security features, optimized performance, and a straightforward user experience.

Key Features

• Secure decryption for all escrow types
• Transaction data parsing and validation
• Ephemeral key management
• HMAC verification
• Comprehensive error handling and logging
• Docker container for easy deployment

Getting Started

Prerequisites

You need both Yarn (for development tooling) and Bun (to execute the CLI). Install them with whichever option fits your operating system:

• Yarn

  npm install -g yarn
  # or, if you have Node 16.10+, enable Corepack
  corepack enable

• Bun

  curl -fsSL https://bun.com/install | bash

  or

  npm install -g bun

Prepare Output Directory

All CLI examples write decrypted JSON files under out/. Create the folder once (it is git-ignored) before running any command:

mkdir -p out

Every command’s --outputFile path is relative to the project root unless you pass an absolute path. Files such as out/dao.json or out/data.json are JSON files; open them with any editor or by using cat/jq:

ls out                      # lists the decrypted files you have produced
cat out/dao.json            # quick look at the raw JSON

Basic Usage

For DAO Escrow:

bun run decrypt:escrow \
  --txHash=0x1234...abcd \
  --escrowType=DAO \
  --escrowPrivateKey=0x1234...abcd \
  --network=polygon \
  --outputFile=out/dao.json

For Zone Escrow:

bun run decrypt:escrow \
  --txHash=0x1234...abcd \
  --escrowType=Zone \
  --escrowPrivateKey=0x1234...abcd \
  --network=polygon \
  --outputFile=out/zone.json

For Data Escrow (requires ephemeral public key):

bun run decrypt:escrow \
  --txHash=0x1234...abcd \
  --escrowType=Data \
  --escrowPrivateKey=0x1234...abcd \
  --network=amoy \
  --outputFile=out/data.json \
  --ephemeralPublicKeyX=123...789

Command Options

• --txHash: Transaction hash (required)
• --escrowType: Type of escrow (DAO | Data | Zone)
• --escrowPrivateKey: Private key for decryption
• --network: Network to use (amoy | polygon)
• --outputFile: Path for the decrypted output
• --ephemeralPublicKeyX: Required for Data escrow type

Supplying Private Keys via Environment Variables

Instead of passing --escrowPrivateKey directly (which may leak secrets in shell history), you can set environment variables before running the CLI:

• DAO_ESCROW_PRIVATE_KEY
• ZONE_ESCROW_PRIVATE_KEY
• DATA_ESCROW_PRIVATE_KEY
• ESCROW_PRIVATE_KEY (fallback used when a type-specific variable is not set)

Use full hex strings with the 0x prefix as shown in the examples; the CLI expects that format when converting keys to bigints.

You can place the variables in a .env file and load them with a tool like direnv or dotenvx to keep secrets out of your shell history.

Example .env (store in project root and keep it out of version control):

cat .env
# .env
DAO_ESCROW_PRIVATE_KEY=0xabc123...def
ZONE_ESCROW_PRIVATE_KEY=0x456def...789
DATA_ESCROW_PRIVATE_KEY=0x999888...777
# Generic fallback if a type-specific variable is missing
ESCROW_PRIVATE_KEY=0xshared-backup-key

DAO & Zone Output Format

Decrypting DAO or Zone escrows now highlights the reusable ephemeralPublicKeyX right in the JSON output:

{
  "txHash": "0x...",
  "escrowType": "DAO",
  "data": {
    "ephemeralPublicKeyX": "24862...",
    "ephemeralPublicKeyY": "12834...",
    "ephemeralPublicKeyHex": {
      "x": "0x36d7...",
      "y": "0x1c8a..."
    },
    "usageHint": "Pass ephemeralPublicKeyX as --ephemeralPublicKeyX when running the Data escrow decrypt command."
  }
}

Copy the ephemeralPublicKeyX into the subsequent Data escrow run (--ephemeralPublicKeyX=<value>). The CLI also includes hex encodings for convenience when sharing across tooling.

Data Output Format

Data escrow decryptions return the fully reconstructed payload. Example (numbers shortened for brevity):

{
  "txHash": "0x...",
  "escrowType": "Data",
  "data": {
    "zAssetID": "8589934592",
    "zAccountID": "0",
    "zAccountZoneId": "1",
    "zAccountNonce": "21",
    "utxoInMerkleTreeSelector": [
      ["1", "0"],
      ["1", "0"]
    ],
    "utxoInPathIndices": [
      ["0", "1", "0", "..."],
      ["0", "0", "0", "..."]
    ],
    "utxoInOriginZoneIds": ["1", "1"],
    "utxoOutTargetZoneIds": ["1", "0"],
    "utxoInAmounts": ["0", "0"],
    "utxoOutAmounts": ["10", "0"],
    "utxoOutSpendingPublicKeys": [
      ["9665...87040", "13931...288865"],
      ["0", "1"]
    ]
  }
}

Decryption Process

The tool follows a secure decryption workflow:

1. Parse and validate transaction data
2. Extract escrow-specific encrypted messages
3. Compute shared keys using ephemeral keys
4. Verify HMAC for data integrity
5. Decrypt messages and format output

Detailed Usage Guide

Transaction Types

Currently supported transaction types:

• Main transaction
• SwapZAsset transaction

Escrow Types

Each escrow type has specific data handling:

• DAO Escrow: Uses derived ephemeral keys
• Zone Escrow: Uses derived ephemeral keys
• Data Escrow: Uses provided ephemeral public key

Role-Specific Guides

DAO Escrow Asistants

• Prerequisites: DAO private key, target network (amoy or polygon), transaction hash with data to decrypt.
• What the tool does: Automatically derives the ephemeral key from the transaction data. Produces the ephemeralPublicKeyX for Data Escrow shared secret calculation in the specified output file.
• Run it:

  bun run decrypt:escrow \
    --txHash=<dao-tx-hash> \
    --escrowType=DAO \
    --escrowPrivateKey=<dao-private-key> \
    --network=polygon \
    --outputFile=out/dao.json

• Result: JSON with the decrypted ephemeralPublicKeyX for Data Escrow usage.

Zone Escrow Asistants

• Prerequisites: Zone private key, target network (amoy or polygon), transaction hash with data to decrypt.
• What the tool does: Automatically derives the ephemeral key from the transaction data. Produces the ephemeralPublicKeyX for Data Escrow shared secret calculation in the specified output file.
• Run it:

  bun run decrypt:escrow \
    --txHash=<zone-tx-hash> \
    --escrowType=Zone \
    --escrowPrivateKey=<zone-private-key> \
    --network=amoy \
    --outputFile=out/zone.json

• Result: JSON with the decrypted ephemeralPublicKeyX for Data Escrow usage.

Data Escrow Asistants

• Prerequisites: Data escrow private key, ephemeralPublicKeyX provided by any of the Zone or DAO asistants, transaction hash, and network.
• What the tool does: Validates that the supplied ephemeralPublicKeyX matches the transaction, computes the shared secret, verifies HMAC integrity, and reconstructs the full data escrow payload.
• Run it:

  bun run decrypt:escrow \
    --txHash=<data-tx-hash> \
    --escrowType=Data \
    --escrowPrivateKey=<data-private-key> \
    --ephemeralPublicKeyX=<ephemeral-x-coordinate> \
    --network=polygon \
    --outputFile=out/data.json

• Result: JSON with detailed transaction data. Share only with trusted systems, as it contains sensitive account information.

Running with Docker

The repository ships with a multi-stage Dockerfile that bundles the CLI together with its Bun runtime.

1. Build the image (runs the type generation step and installs production deps):

   docker build -t dataescrow-cli .

2. Run a decryption command inside the container. Mount any local directory you want to use for outputs:

   mkdir -p out
   docker run --rm \
     -v "$(pwd)/out:/app/out" \
     dataescrow-cli \
     --txHash=0x1234...abcd \
     --escrowType=DAO \
     --escrowPrivateKey=0x1234...abcd \
     --network=polygon \
     --outputFile=out/dao.json

   Change the CLI flags as needed; the container entrypoint forwards all arguments to bun run scripts/decrypt.ts.

Advanced Features

• Custom transaction data configuration
• Verbose logging mode
• Data integrity checks
• Progress tracking for long operations

Development Status

Completed Features

• Core transaction data parsing
• Ephemeral key handling
• HMAC verification
• Basic CLI interface
• reconstruct the transaction data
• Docker support

Contributing

We welcome contributions! Please check our contribution guidelines before submitting issues or pull requests.

License

BUSL-1.1 - See LICENSE for details.

Support

Need help?

• Open an issue on our GitLab repository
• Check our documentation