User Wallet Data Format

Abstract

This specification defines a canonical, complete, portable file format for exporting Wallet Toolbox data for a single user as one blob.

The format is intended to support:

strong user data portability
GDPR and similar access/export requirements
wallet import and export
storage-provider migration
backup, archival, and forensic recovery

This specification is based on the Wallet Toolbox storage implementation. It defines a canonical plaintext payload format for a single-user export. Encryption and protected transport are out of scope for this document and belong in a separate extension.

Motivation

Wallet data portability is only meaningful if the exported artifact is complete, stable, and implementation-neutral.

Exporting only high-level balances or transaction lists is insufficient. A serious wallet export must preserve:

all user-owned records
all user-linked proof and broadcast state
deleted/tombstoned rows
wallet-local metadata needed to reconstruct labels, baskets, certificates, sync state, and action history

Wallet Toolbox already has a rich schema that captures this information, but it does not yet define a canonical single-file export format. This specification fills that gap.

Specification

1. Scope

This specification defines the canonical plaintext payload for exporting all Wallet Toolbox data for one user.

It does not define:

encryption of the export blob
compression of the export blob
transport protocols for moving the blob
multi-user export containers
chain-wide or storage-global operational logs unrelated to one user
root-key, profile, or encrypted snapshot material that is not part of the Wallet Toolbox storage schema

2. Conformance

An implementation conforms to BRC-38 if it can:

export a single user's Wallet Toolbox data into the canonical format defined here
parse a BRC-38 blob and reconstruct the exported dataset semantics
preserve all included row values, relationships, tombstones, and binary payloads without loss

3. Canonical File Form

The canonical BRC-38 artifact is a UTF-8 JSON document serialized according to RFC 8785 JSON Canonicalization Scheme (JCS).

The canonical unencrypted file extension SHOULD be:

.brc38.json

If a deployment wraps, compresses, or encrypts the document, the canonical BRC-38 payload remains the inner JSON document defined here.

4. Top-Level Document

The canonical top-level object MUST have the following shape:

{
  "brc": 38,
  "title": "User Wallet Data Format",
  "formatVersion": 1,
  "exportedAt": "2026-04-23T20:00:00.000Z",
  "sourceStorage": {
    "created_at": "2026-04-01T00:00:00.000Z",
    "updated_at": "2026-04-23T20:00:00.000Z",
    "storageIdentityKey": "<hex>",
    "storageName": "Primary Wallet Storage",
    "chain": "main",
    "dbtype": "SQLite",
    "maxOutputScript": 1024
  },
  "user": {
    "...": "..."
  },
  "tables": {
    "provenTxs": [],
    "provenTxReqs": [],
    "outputBaskets": [],
    "transactions": [],
    "commissions": [],
    "outputs": [],
    "outputTags": [],
    "outputTagMaps": [],
    "txLabels": [],
    "txLabelMaps": [],
    "certificates": [],
    "certificateFields": [],
    "syncStates": []
  }
}

Top-level requirements:

brc MUST equal 38.
title MUST equal User Wallet Data Format.
formatVersion MUST equal 1 for this version of the format.
exportedAt MUST be the UTC timestamp at which the export payload was finalized.
sourceStorage MUST contain the exported storage's current settings row in portable form.
user MUST contain exactly one exported user row in portable form.
tables MUST contain every array listed above, even if empty.

5. Canonical Value Encoding

5.1 Timestamps

All timestamp values MUST be exported as strings in UTC using the exact form:

YYYY-MM-DDTHH:MM:SS.sssZ

Offsets other than Z MUST NOT be used.

5.2 Binary Data

Fields stored in Wallet Toolbox as number[] byte arrays MUST be exported as standard RFC 4648 base64 strings with padding.

No whitespace is permitted in base64 values.

The following fields are binary:

TableCommission.lockingScript
TableOutput.lockingScript
TableProvenTx.merklePath
TableProvenTx.rawTx
TableProvenTxReq.rawTx
TableProvenTxReq.inputBEEF
TableTransaction.inputBEEF
TableTransaction.rawTx

5.3 Structured JSON-in-String Fields

The Wallet Toolbox schema stores some structured values as JSON strings. In BRC-38 these MUST be exported as decoded JSON values, not as embedded JSON strings.

The affected fields are:

TableProvenTxReq.history
TableProvenTxReq.notify
TableSyncState.syncMap
TableSyncState.errorLocal
TableSyncState.errorOther

Their portable BRC-38 forms are:

history: object
notify: object
syncMap: object
errorLocal: object or omitted
errorOther: object or omitted

5.4 Optional Fields

If a field is absent or undefined in the source dataset, it MUST be omitted from the exported JSON rather than emitted as null.

6. Export Closure

The exported dataset for a user is the following closure over the Wallet Toolbox schema.

6.1 Required Singletons

The export MUST include:

exactly one user row for the requested user identity
exactly one sourceStorage object derived from the exporting storage's settings row

6.2 User-Owned Tables

The export MUST include every row from the following tables where userId equals the exported user's userId:

output_baskets
transactions
commissions
outputs
output_tags
tx_labels
certificates
certificate_fields
sync_states

6.3 User-Linked Map Tables

The export MUST include:

every tx_labels_map row whose txLabelId references an exported tx_labels row
every output_tags_map row whose outputTagId references an exported output_tags row

An exporter SHOULD additionally verify that:

every exported tx_labels_map.transactionId references an exported transaction
every exported output_tags_map.outputId references an exported output

6.4 User-Linked Proof Tables

The export MUST include:

every proven_tx_reqs row whose txid matches the txid of an exported transaction
every proven_txs row whose provenTxId is referenced by:
- an exported transaction, or
- an exported proven_tx_reqs row

6.5 Excluded Storage-Global Tables

The export MUST NOT include storage-global tables that are not scoped to a single user.

In the Wallet Toolbox implementation this means:

monitor_events MUST NOT be included

7. Portable Row Forms

The BRC-38 portable row forms are defined below.

7.1 User

{
  "created_at": "2026-04-01T00:00:00.000Z",
  "updated_at": "2026-04-23T20:00:00.000Z",
  "userId": 1,
  "identityKey": "<hex>",
  "activeStorage": "<storageIdentityKey>"
}

7.2 Proven Transaction

{
  "created_at": "2026-04-01T00:00:00.000Z",
  "updated_at": "2026-04-23T20:00:00.000Z",
  "provenTxId": 7,
  "txid": "<hex>",
  "height": 900000,
  "index": 12,
  "merklePath": "<base64>",
  "rawTx": "<base64>",
  "blockHash": "<hex>",
  "merkleRoot": "<hex>"
}

7.3 Proven Transaction Request

{
  "created_at": "2026-04-01T00:00:00.000Z",
  "updated_at": "2026-04-23T20:00:00.000Z",
  "provenTxReqId": 8,
  "provenTxId": 7,
  "status": "completed",
  "attempts": 2,
  "notified": true,
  "txid": "<hex>",
  "batch": "abc123",
  "history": {
    "notes": []
  },
  "notify": {
    "transactionIds": [42]
  },
  "rawTx": "<base64>",
  "inputBEEF": "<base64>"
}

history MUST conform to:

{
  "notes": [
    {
      "when": "2026-04-23T20:00:00.000Z",
      "what": "sent"
    }
  ]
}

notify MUST conform to:

{
  "transactionIds": [1, 2, 3]
}

7.4 Output Basket

{
  "created_at": "2026-04-01T00:00:00.000Z",
  "updated_at": "2026-04-23T20:00:00.000Z",
  "basketId": 2,
  "userId": 1,
  "name": "default",
  "numberOfDesiredUTXOs": 32,
  "minimumDesiredUTXOValue": 1000,
  "isDeleted": false
}

7.5 Transaction

{
  "created_at": "2026-04-01T00:00:00.000Z",
  "updated_at": "2026-04-23T20:00:00.000Z",
  "transactionId": 42,
  "userId": 1,
  "provenTxId": 7,
  "status": "completed",
  "reference": "<base64>",
  "isOutgoing": true,
  "satoshis": 1234,
  "description": "Payment",
  "version": 1,
  "lockTime": 0,
  "txid": "<hex>",
  "inputBEEF": "<base64>",
  "rawTx": "<base64>"
}

7.6 Commission

{
  "created_at": "2026-04-01T00:00:00.000Z",
  "updated_at": "2026-04-23T20:00:00.000Z",
  "commissionId": 3,
  "userId": 1,
  "transactionId": 42,
  "satoshis": 5,
  "keyOffset": "<string>",
  "isRedeemed": false,
  "lockingScript": "<base64>"
}

7.7 Output

{
  "created_at": "2026-04-01T00:00:00.000Z",
  "updated_at": "2026-04-23T20:00:00.000Z",
  "outputId": 11,
  "userId": 1,
  "transactionId": 42,
  "basketId": 2,
  "spendable": true,
  "change": false,
  "outputDescription": "payment output",
  "vout": 0,
  "satoshis": 1234,
  "providedBy": "you",
  "purpose": "payment",
  "type": "P2PKH",
  "txid": "<hex>",
  "senderIdentityKey": "<hex>",
  "derivationPrefix": "<base64>",
  "derivationSuffix": "<base64>",
  "customInstructions": "optional",
  "spentBy": 99,
  "sequenceNumber": 0,
  "spendingDescription": "optional",
  "scriptLength": 25,
  "scriptOffset": 0,
  "lockingScript": "<base64>"
}

7.8 Output Tag

{
  "created_at": "2026-04-01T00:00:00.000Z",
  "updated_at": "2026-04-23T20:00:00.000Z",
  "outputTagId": 4,
  "userId": 1,
  "tag": "invoice",
  "isDeleted": false
}

7.9 Output Tag Map

{
  "created_at": "2026-04-01T00:00:00.000Z",
  "updated_at": "2026-04-23T20:00:00.000Z",
  "outputTagId": 4,
  "outputId": 11,
  "isDeleted": false
}

7.10 Transaction Label

{
  "created_at": "2026-04-01T00:00:00.000Z",
  "updated_at": "2026-04-23T20:00:00.000Z",
  "txLabelId": 5,
  "userId": 1,
  "label": "expenses",
  "isDeleted": false
}

7.11 Transaction Label Map

{
  "created_at": "2026-04-01T00:00:00.000Z",
  "updated_at": "2026-04-23T20:00:00.000Z",
  "txLabelId": 5,
  "transactionId": 42,
  "isDeleted": false
}

7.12 Certificate

{
  "created_at": "2026-04-01T00:00:00.000Z",
  "updated_at": "2026-04-23T20:00:00.000Z",
  "certificateId": 6,
  "userId": 1,
  "type": "<base64>",
  "serialNumber": "<base64>",
  "certifier": "<hex>",
  "subject": "<hex>",
  "verifier": "<hex>",
  "revocationOutpoint": "<txid>.<vout>",
  "signature": "<hex>",
  "isDeleted": false
}

7.13 Certificate Field

{
  "created_at": "2026-04-01T00:00:00.000Z",
  "updated_at": "2026-04-23T20:00:00.000Z",
  "userId": 1,
  "certificateId": 6,
  "fieldName": "email",
  "fieldValue": "[email protected]",
  "masterKey": "<base64>"
}

7.14 Sync State

{
  "created_at": "2026-04-01T00:00:00.000Z",
  "updated_at": "2026-04-23T20:00:00.000Z",
  "syncStateId": 9,
  "userId": 1,
  "storageIdentityKey": "<hex>",
  "storageName": "Backup Storage",
  "status": "success",
  "init": true,
  "refNum": "<string>",
  "syncMap": {
    "provenTx": { "entityName": "provenTx", "idMap": {}, "count": 0 },
    "outputBasket": { "entityName": "outputBasket", "idMap": {}, "count": 0 },
    "transaction": { "entityName": "transaction", "idMap": {}, "count": 0 },
    "provenTxReq": { "entityName": "provenTxReq", "idMap": {}, "count": 0 },
    "txLabel": { "entityName": "txLabel", "idMap": {}, "count": 0 },
    "txLabelMap": { "entityName": "txLabelMap", "idMap": {}, "count": 0 },
    "output": { "entityName": "output", "idMap": {}, "count": 0 },
    "outputTag": { "entityName": "outputTag", "idMap": {}, "count": 0 },
    "outputTagMap": { "entityName": "outputTagMap", "idMap": {}, "count": 0 },
    "certificate": { "entityName": "certificate", "idMap": {}, "count": 0 },
    "certificateField": { "entityName": "certificateField", "idMap": {}, "count": 0 },
    "commission": { "entityName": "commission", "idMap": {}, "count": 0 }
  },
  "when": "2026-04-23T20:00:00.000Z",
  "satoshis": 123456,
  "errorLocal": {
    "code": "example",
    "description": "example",
    "stack": "optional"
  },
  "errorOther": {
    "code": "example",
    "description": "example"
  }
}

Each sync error object MUST conform to:

{
  "code": "string",
  "description": "string",
  "stack": "optional string"
}

8. Array Ordering

For canonical serialization, the arrays inside tables MUST be sorted ascending as follows:

provenTxs by provenTxId
provenTxReqs by provenTxReqId
outputBaskets by basketId
transactions by transactionId
commissions by commissionId
outputs by outputId
outputTags by outputTagId
outputTagMaps by outputId, then outputTagId
txLabels by txLabelId
txLabelMaps by transactionId, then txLabelId
certificates by certificateId
certificateFields by certificateId, then fieldName
syncStates by syncStateId

9. Relationship Integrity

An exporter MUST ensure that every foreign-key-like reference inside the payload resolves within the exported document, except where the source schema intentionally stores an optional unresolved reference.

At minimum:

every exported transaction.userId MUST equal user.userId
every exported output.userId MUST equal user.userId
every exported output.transactionId MUST reference an exported transaction
every exported commission.transactionId MUST reference an exported transaction
every exported txLabelMap.txLabelId MUST reference an exported transaction label
every exported txLabelMap.transactionId MUST reference an exported transaction
every exported outputTagMap.outputTagId MUST reference an exported output tag
every exported outputTagMap.outputId MUST reference an exported output
every exported certificateField.certificateId MUST reference an exported certificate

If user.activeStorage does not equal sourceStorage.storageIdentityKey, the exporter MUST still preserve the exact user.activeStorage value.

10. Import Semantics

BRC-38 defines the portable payload, not a mandatory database insertion strategy.

Importers:

MUST preserve row values and relationships semantically
MAY preserve numeric primary IDs exactly
MAY remap numeric primary IDs during import, provided every internal reference is updated consistently
MUST preserve tombstones such as isDeleted
MUST preserve status fields exactly

Importers MAY treat the following as operationally sensitive and choose whether to activate them immediately after import:

user.activeStorage
syncStates

However, a conforming importer MUST still parse and preserve those values in the imported dataset.

11. Privacy and Security

BRC-38 exports are intentionally complete and sensitive.

A BRC-38 blob may contain:

raw transactions
merkle proofs
wallet labeling and description data
certificate contents
encrypted field material and derivation metadata
sync history and storage topology hints

Implementations MUST treat BRC-38 blobs as highly sensitive user data.

12. Implementation Notes

This specification is based on the Wallet Toolbox schema:

users
proven_txs
proven_tx_reqs
output_baskets
transactions
commissions
outputs
output_tags
output_tags_map
tx_labels
tx_labels_map
certificates
certificate_fields
sync_states
storage settings as export metadata

The storage-global monitor_events table is intentionally excluded because it is not scoped to a single user.

References

PreviousBasket and Custom Instructions Extension for Bitcoin Outpoints NextUser Wallet Data Format Encryption Extension

Last updated 19 days ago

Was this helpful?

hashtagAbstract

hashtagMotivation

hashtagSpecification

hashtag1. Scope

hashtag2. Conformance

hashtag3. Canonical File Form

hashtag4. Top-Level Document

hashtag5. Canonical Value Encoding

hashtag5.1 Timestamps

hashtag5.2 Binary Data

hashtag5.3 Structured JSON-in-String Fields

hashtag5.4 Optional Fields

hashtag6. Export Closure

hashtag6.1 Required Singletons

hashtag6.2 User-Owned Tables

hashtag6.3 User-Linked Map Tables

hashtag6.4 User-Linked Proof Tables

hashtag6.5 Excluded Storage-Global Tables

hashtag7. Portable Row Forms

hashtag7.1 User

hashtag7.2 Proven Transaction

hashtag7.3 Proven Transaction Request

hashtag7.4 Output Basket

hashtag7.5 Transaction

hashtag7.6 Commission

hashtag7.7 Output

hashtag7.8 Output Tag

hashtag7.9 Output Tag Map

hashtag7.10 Transaction Label

hashtag7.11 Transaction Label Map

hashtag7.12 Certificate

hashtag7.13 Certificate Field

hashtag7.14 Sync State

hashtag8. Array Ordering

hashtag9. Relationship Integrity

hashtag10. Import Semantics

hashtag11. Privacy and Security

hashtag12. Implementation Notes

hashtagReferences

Abstract

Motivation

Specification

1. Scope

2. Conformance

3. Canonical File Form

4. Top-Level Document

5. Canonical Value Encoding

5.1 Timestamps

5.2 Binary Data

5.3 Structured JSON-in-String Fields

5.4 Optional Fields

6. Export Closure

6.1 Required Singletons

6.2 User-Owned Tables

6.3 User-Linked Map Tables

6.4 User-Linked Proof Tables

6.5 Excluded Storage-Global Tables

7. Portable Row Forms

7.1 User

7.2 Proven Transaction

7.3 Proven Transaction Request

7.4 Output Basket

7.5 Transaction

7.6 Commission

7.7 Output

7.8 Output Tag

7.9 Output Tag Map

7.10 Transaction Label

7.11 Transaction Label Map

7.12 Certificate

7.13 Certificate Field

7.14 Sync State

8. Array Ordering

9. Relationship Integrity

10. Import Semantics

11. Privacy and Security

12. Implementation Notes

References