Sidecar Custody: The Obligation to Keep Your DID History

Sep 4, 2026

Introduction

The post about private DID resolution explained why did:btcr2 keeps DID documents off-chain. With sidecar delivery, the controller gives the document and its update history directly to each party that must resolve the DID. Thus, the on-chain data contains only opaque hashes, and DIDs can be pairwise and non-correlatable by default. This is one of the better properties of the method.

Sidecar delivery also creates an obligation. On day one, it is easy to underestimate this obligation. On day one thousand, it can be impossible to repair the damage. Bitcoin will keep the commitment permanently, but Bitcoin does not know what the commitment means. The bytes that explain the commitment are only in the locations where you put them. If all copies of these bytes disappear, the anchor becomes a permanent record of data that nobody can read.

This post is about that obligation. It explains three topics:

  • The data that you must keep.
  • What happens if you do not keep it.
  • How to keep it and also keep the privacy that is the reason for sidecar delivery.

The Data That You Must Keep

The retention set depends on the identifier type and on the history of the identifier.

A key-based identifier with no updates requires no retention. For k-prefix DIDs, the resolver derives the initial document deterministically from the DID string. If you give a party the DID, that party can make the initial document with no other input. This is the zero-cost creation property, and it also gives zero-cost retention. This DID has no sidecar data, because all the data is already in the identifier.

An external identifier requires the genesis document. For x-prefix DIDs, the resolver makes the initial document with a find-and-replace operation on a genesis document from the controller. The identifier commits to the genesis document, but it does not contain it. If no copy of that document exists, in your sidecar data or in CAS, resolution fails at the first version. This is a serious single point of failure in the model. It exists from the time of creation, before any update occurs.

Any identifier with updates requires every update. After the first update of a DID, resolution replays the update history. Each BTCR2 Signed Update must be available to each party that resolves the DID. Each update has a JSON Patch, a sourceHash, a targetHash, a targetVersionId, and a Data Integrity proof. The updates are plain JSON objects. With sidecar delivery, the controller gives the updates to the resolver as a list in the Sidecar Data.

Aggregate beacons add proofs. If a CAS or SMT beacon announced your updates, the update payload alone is not sufficient. The verifier also needs the data that shows the inclusion of your specific update in the aggregate. For an SMT beacon, this data is the SMT proof with its nonce, collapsed bitmap, and sibling hashes. For a CAS beacon, it is the Beacon Announcement Map that the on-chain hash commits to.

The Sidecar Data structure of the spec gives these requirements for sidecar delivery:

  • casUpdates is REQUIRED if the DID used a CAS Beacon to publish an update. This property holds the Beacon Announcement Maps, which the spec calls CAS Announcements.
  • smtProofs MUST contain one SMT Proof for each Beacon Signal of an SMT Beacon that the resolver finds. This includes Beacon Signals that announce no update for your DID.
  • The spec says: "The DID controller keeps each SMT Proof (data structure) for the life of the DID."
  • The SMT Proof definition adds: "If the DID controller does not have the nonce, the SMT Proof of that Beacon Signal cannot be verified."

Thus, an aggregate beacon makes the retention set larger. It does not move the obligation to a different party. This is a property of the beacon type, not of the mechanism that you use to distribute the update data.

The retention set only increases. The method has no compaction step and no checkpoint that lets you discard earlier updates. Version 40 does not make versions 1 to 39 unnecessary. The reason is that the resolver replays the history and verifies each proof against the keys in the document at that version. The history is the mechanism itself, not only an archive of it.

The Failure Mode Is Not Graceful

Many people think that a loss of sidecar data moves a DID back to an earlier state. This is not correct. The loss breaks the DID.

For example, a DID has three updates, and the controller lost the payload of the second update. A resolver finds the Beacon Signals on-chain, because they are permanent and public. Thus, the resolver knows that three updates occurred. It can get updates one and three. It cannot get update two.

The spec has a named error for this case, MISSING_UPDATE_DATA. The spec defines the error as follows: "Data that is necessary to find what a Beacon Signal announces for the DID is not in the Sidecar Data and not in CAS." The resolver raises this error if it cannot get an update from either source. The spec says that all did:btcr2 operations "must abort" when such an error occurs, so resolution stops there.

An implementation also cannot skip the lost update. Update three declares targetVersionId 4, but the resolver still has version 2. A gap of more than one version raises LATE_PUBLISHING. Thus, the resolver does not get to the sourceHash check of update three. In both cases, the late publishing protection does its work: it refuses to resolve the DID and does not guess.

Thus, the result is not "the DID resolves to an earlier version". The result is "the DID does not resolve". For a verifier, a DID with a gap in its history looks the same as a DID whose controller tries to hide an update. The method cannot see a difference between an honest data loss and an update that a controller hides on purpose. The design fails closed, and the Beacons section says so directly: "Any on-chain Beacon Signal that cannot be processed renders the related DID invalid."

This fact changes how you must think about backup. A loss of sidecar data is not a partial loss that leaves you some capability. If you do not keep all the data, the DID does not resolve.

The Obligation Lasts Longer Than You Expect

Two factors make the retention period much longer than most people expect.

Credentials stay in use long after issuance. For example, an issuer issues a credential in 2026 and signs it with a key from version 4 of its DID document. This credential verifies only if a verifier can resolve the DID at version 4. The credential can be a professional certification with a ten-year life, or a supply chain attestation that a regulator asks about years later. In these cases, the sidecar data for version 4 must be available for as long as any party can check the credential. The retention period of the credential sets the retention period of the DID history, and this period is usually longer than people expect.

Verifiers sometimes must verify again. For example, a verifier checked a credential in 2026 and recorded "verified". This record is a conclusion, not evidence. If a party disputes that conclusion, the verifier must do the verification again. To do this, the verifier must resolve the issuer's DID as it was at the time of issuance.

If the verifier did not keep the sidecar data that it got, it depends on the issuer. The issuer must still have the data, and the issuer must still agree to give it. For an audit, this position is weak.

Thus, each deployment must decide if verifiers archive the sidecar data that they get. For each use case with audit or dispute exposure, we recommend that verifiers archive it. Make this an explicit policy, and do not depend on a cache that stays by accident. But archives work against the privacy model, because each archived copy is one more location of the history. The next section examines this conflict, and the conflict has no clean solution.

The Conflict Between Privacy and Durability

The obvious solution for durability is publication. If you put the update history in a permanent, replicated location, it is no longer your problem.

But publication removes the reason for sidecar delivery. With closed-loop resolution, only parties that have the sidecar data can resolve the DID. This property makes pairwise, non-correlatable identifiers possible. If you publish the history to a public store, any party can resolve the DID. Then the DID becomes a public, linkable identity. Thus, you exchange the privacy property of the method for an operational convenience.

First, one distinction is necessary. did:btcr2 defines two ways to give update data to a resolver: sidecar and CAS. This choice does not depend on the beacon type. A CAS beacon alone does not put your update data in CAS. Three facts show this:

Publication is a separate opt-in. The spec says that a mix of the two mechanisms on one identifier is NOT RECOMMENDED. Thus, make the decision once for each DID, and keep it for the life of the identifier.

These are the realistic options and their actual costs:

Self-custody. Keep the data yourself, with real backups. Of these options, this option gives the most privacy. The durability is exactly as good as your operational discipline. Over a ten-year period, that discipline can be weaker than an organization expects.

Publish to CAS. In practice, this opt-in means IPFS. The spec says that IPFS is "the only known CAS to provide a deterministic mapping from a SHA-256 hash". IPFS gives you replication and content addresses, but it has two problems.

First, IPFS is public. Any party with the CID can get the content, and any party can calculate the CID from the SHA-256 hash of the update. For a Singleton beacon, that hash is exactly the data that is already on-chain.

Second, IPFS does not guarantee persistence. Content stays available only while a node pins it, and the hope that someone will pin it is not a retention policy. Thus, you change a storage problem into a problem of who pins the content. That problem is easier to manage, but it is not solved.

Encrypt and publish widely. Encrypt the update payloads, copy the ciphertext to many convenient locations, and keep the key. This option keeps both privacy and durability. The durability problem becomes a key custody problem. An earlier post examined key custody, and established practices exist for key custody. The risk is that a key loss now destroys data that is otherwise intact.

Also, an encrypted backup that nobody tests can fail when you try to restore it. If you use this option, you must do restore drills.

Escrow. A third party keeps a copy under a contract. This option works, but it adds the type of trusted intermediary that the architecture tries to avoid. It can still be the correct answer for some organizations. For example, the actual failure mode of an organization can be corporate dissolution, not technical loss. Evaluate escrow for that failure mode, and do not reject it only on principle.

If a deployment stays on sidecar distribution, we recommend that it combine the other three options:

  • Self-custody as the primary copy.
  • Encrypted replication as the secondary protection.
  • Escrow, if the identifier supports obligations that must continue after the organization stops operation.

These three options are backup strategies, and you can use them together. Publication to CAS is the other distribution mechanism, not a fourth backup. Thus, you choose it once for each identifier, and you do not add it on top of the other options.

Handoff

Some of the scenarios that can destroy sidecar data are organizational, not technical.

Employee departure. One person sets up the DID. The update history is in a directory on the computer of that person, with a backup in the personal cloud storage of that person. Then the person leaves the company. Operational assets such as signing keys and certificates can disappear in this way, and sidecar data can too. To prevent this, treat sidecar data as a corporate asset with a named owner and a documented location.

Acquisition. A company buys a different company, and the DID is part of the purchase, because it anchors credentials that the buyer must now honor. If the sidecar data is not in the data room, the buyer gets an identifier that it cannot resolve. Put sidecar data on the checklist for technical due diligence, next to the domain names and the code signing certificates. Do not assume that a standard checklist includes it.

Dissolution. A company closes, and it shuts down its infrastructure. The credentials that it issued can still be in use for years. A person or an organization must be responsible for the history after the company no longer exists. The company must make that arrangement while it still can.

Vendor transition. If a managed service operated your beacon, your update history can be in the systems of that vendor. Read the exit clause about data export before you sign the contract, not after.

Format Stability

A smaller but real concern is that the data must stay interpretable, not only present.

The wire format is stable by design. Updates are plain JSON. The hash algorithm is SHA-256 over documents that JCS canonicalizes. JCS is intentionally strict, and you need this property for an operation that you will do again in fifteen years. JSON Patch is a stable RFC. These formats are not likely to change.

One dependency needs a caveat. The spec requires the context URL https://btcr2.dev/context/v1 in each DID document and in each update. The spec also requires that concrete representations conform to JSON-LD 1.1. Resolution does not need to dereference that URL, because the hash is SHA-256 over JSON that JCS canonicalizes. But as of September 2026, the URL does not resolve. If a tool in your restore process fetches JSON-LD contexts, archive a copy of the context with the data.

The risk is in your own layer. Sometimes sidecar data is in a proprietary database schema, a vendor-specific blob format, or a compression format of one library version. Then you can read the data only with software that you possibly do not use later.

Store the JSON as JSON. Use a simple compression format with many implementations, or use no compression. Keep a plain-text description of the files with them. The person who restores the data can be a different person, who does not know btcr2.

A Minimum Viable Policy

For an organization that deploys btcr2 today:

  • Name an owner. Sidecar data needs a person and a team that are accountable for it. Record their names in a location that continues to exist after that person leaves.
  • Store the data as plain JSON. Use one file for each update, with the version id as the file name. Put the files in a location that your normal backup process includes.
  • Follow the 3-2-1 rule. Keep three copies, on two types of media, with one copy off-site, as CISA recommends. This rule is simple and well known.
  • Test restores on a schedule. A backup that nobody tests is only an assumption. Restore the data into a clean environment, and resolve the DID completely.
  • Keep the data for the life of the longest-lived credential, not for the life of the DID. Calculate that period explicitly.
  • Put the retention process in the runbook, the disaster recovery plan, and the M&A checklist.
  • Decide the archive policy for verifiers. Write it into the terms that you give to verifiers, so that the expectation is explicit and not an assumption.
  • For x-prefix identifiers, make a separate backup of the genesis document immediately. You cannot derive it from other data, and it exists before the first update.

Conclusion

Sidecar delivery is a good design, but it moves a cost and does not remove it. It gives real privacy: closed-loop resolution, pairwise identifiers, and no meaningful data on-chain. The price of this privacy is a permanent retention obligation. The obligation increases with each update, and if you do not meet it, the failure is complete, not partial.

The technical work is not difficult: files, backups, restore tests, and a named owner. Retention fails because the obligation is invisible in the first year, and after the fifth year you cannot recover a loss. Bitcoin will still have your anchors in 2036. You decide now if anyone can still read them, even if you do not know that you make this decision.

Next week, the series examines infrastructure. We explain what is necessary to run the Bitcoin node that finds those anchors. We also explain why the choice between an indexed RPC and your own traversal of blocks is a decision about trust, not about capacity.

Jintek LLC