User Wallet Data Format
Ty Everett ([email protected])
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:
Top-level requirements:
brcMUST equal38.titleMUST equalUser Wallet Data Format.formatVersionMUST equal1for this version of the format.exportedAtMUST be the UTC timestamp at which the export payload was finalized.sourceStorageMUST contain the exported storage's currentsettingsrow in portable form.userMUST contain exactly one exported user row in portable form.tablesMUST 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.lockingScriptTableOutput.lockingScriptTableProvenTx.merklePathTableProvenTx.rawTxTableProvenTxReq.rawTxTableProvenTxReq.inputBEEFTableTransaction.inputBEEFTableTransaction.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.historyTableProvenTxReq.notifyTableSyncState.syncMapTableSyncState.errorLocalTableSyncState.errorOther
Their portable BRC-38 forms are:
history: objectnotify: objectsyncMap: objecterrorLocal: object or omittederrorOther: 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
userrow for the requested user identityexactly one
sourceStorageobject 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_basketstransactionscommissionsoutputsoutput_tagstx_labelscertificatescertificate_fieldssync_states
6.3 User-Linked Map Tables
The export MUST include:
every
tx_labels_maprow whosetxLabelIdreferences an exportedtx_labelsrowevery
output_tags_maprow whoseoutputTagIdreferences an exportedoutput_tagsrow
An exporter SHOULD additionally verify that:
every exported
tx_labels_map.transactionIdreferences an exported transactionevery exported
output_tags_map.outputIdreferences an exported output
6.4 User-Linked Proof Tables
The export MUST include:
every
proven_tx_reqsrow whosetxidmatches thetxidof an exported transactionevery
proven_txsrow whoseprovenTxIdis referenced by:an exported transaction, or
an exported
proven_tx_reqsrow
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_eventsMUST NOT be included
7. Portable Row Forms
The BRC-38 portable row forms are defined below.
7.1 User
7.2 Proven Transaction
7.3 Proven Transaction Request
history MUST conform to:
notify MUST conform to:
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
Each sync error object MUST conform to:
8. Array Ordering
For canonical serialization, the arrays inside tables MUST be sorted ascending as follows:
provenTxsbyprovenTxIdprovenTxReqsbyprovenTxReqIdoutputBasketsbybasketIdtransactionsbytransactionIdcommissionsbycommissionIdoutputsbyoutputIdoutputTagsbyoutputTagIdoutputTagMapsbyoutputId, thenoutputTagIdtxLabelsbytxLabelIdtxLabelMapsbytransactionId, thentxLabelIdcertificatesbycertificateIdcertificateFieldsbycertificateId, thenfieldNamesyncStatesbysyncStateId
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.userIdMUST equaluser.userIdevery exported
output.userIdMUST equaluser.userIdevery exported
output.transactionIdMUST reference an exported transactionevery exported
commission.transactionIdMUST reference an exported transactionevery exported
txLabelMap.txLabelIdMUST reference an exported transaction labelevery exported
txLabelMap.transactionIdMUST reference an exported transactionevery exported
outputTagMap.outputTagIdMUST reference an exported output tagevery exported
outputTagMap.outputIdMUST reference an exported outputevery exported
certificateField.certificateIdMUST 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
isDeletedMUST preserve status fields exactly
Importers MAY treat the following as operationally sensitive and choose whether to activate them immediately after import:
user.activeStoragesyncStates
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:
usersproven_txsproven_tx_reqsoutput_basketstransactionscommissionsoutputsoutput_tagsoutput_tags_maptx_labelstx_labels_mapcertificatescertificate_fieldssync_statesstorage
settingsas export metadata
The storage-global monitor_events table is intentionally excluded because it is not scoped to a single user.
References
Last updated
Was this helpful?

