Export Organizational Wallets

The Wallet Export feature allows you to retrieve the full private keys of your organizational wallets when the organization is in Trustless MPC mode. It is designed for disaster recovery, auditing, and platform portability. Standard-mode wallets have no export path, as described under Security Model Differences below.

[!IMPORTANT] Owner Only Access: For security reasons, the extraction and export of organizational wallet private keys can ONLY be initiated by the Owner of the organization. API keys belonging to other members or system integrations are strictly barred from this operation.

Security Model Differences

The availability and mechanism of wallet exports depend entirely on your chosen MPC security model.

1. Trustless MPC

In Trustless MPC, Planbok nodes do not store your organization's entropy shards in a way that allows reconstruction without your real-time input.

• How it works: To export a private key, the Owner must provide the encryptedOrganizationSecret with the verify context.
• Advantage: You maintain ultimate "sovereignty" over your assets. Even if our systems were offline, you could use your secret and our open-source recovery tools to reconstruct your keys.

2. Standard MPC

In Standard MPC, signing is simplified because entropy shards are stored within the secure MPC nodes.

• Export Constraint: Standard mode signs with a valid organization API key and does not take a per-request owner secret, so there is no owner-supplied secret to authorize an export. Standard-mode wallets are therefore not exportable. If you require key portability, select Trustless MPC during organization setup.

Quickstart: Exporting a Private Key

If your organization is in Trustless MPC mode, follow these steps to export a wallet's private key.

Step 1: Generate the Verification Secret

Use the Planbok encryption script with the verify context. This context is specifically reserved for high-sensitivity operations like key export.

Code
node generate-encrypted-organization-secret.js verify

Step 2: Initiate Export from the Dashboard

Because this operation is extremely sensitive, it must be initiated by the Organization Owner through the Planbok Dashboard, and it cannot be authorized with just any API key.

Authentication: Owner Session (JWT)

Request Body:

Code
{
  "encryptedOrganizationSecret": "BASE64_ENCRYPTED_DATA_HERE"
}

Step 3: Receive and Decode the Data

Once the request is validated:

1. An authorized export derives the keys for the owner from the secret the owner supplies and the stored salt.
2. A Base64 encoded payload is generated and sent directly to the Owner's registered email address.
3. You must decode this payload to retrieve the CSV data containing your addresses and private keys.

Decoding via Script: You can use the decode-organization-private-keys-data.js script from our public repository:

Code
# 1. Paste your base64 data into the script
# 2. Run the script
node decode-organization-private-keys-data.js

Manual Decoding: Alternatively, you can decode it via terminal:

Code
echo "YOUR_BASE64_DATA" | base64 --decode > organization_keys.csv

Best Practices

1. Air-gapped Environments: Perform key exports on secure, air-gapped machines whenever possible.
2. Ephemeral Secrets: The encryptedOrganizationSecret expires after 5 minutes. Generate it immediately before the export call.
3. Immediate Migration: Key export is typically used for migrating funds to cold storage. It is recommended to sweep the funds to a new address after a key has been exposed via export.