Recovery and continuity

Recovery is not merely regaining access to an application account. For Acorn, recovery means restoring the cryptographic keys and authority of the wallet and locating enough relay-backed state to continue operating its funds and records.

The practical recovery model is:

key material + location of encrypted state = component continuity

What must be recovered

An Acorn recovery bundle contains:

Item	Purpose	Sensitivity
Seed phrase	Derives the wallet keypair for wallets generated by Acorn or initialized from external entropy.	Secret
`nsec`	Direct encoding of the Nostr private key.	Secret
Home relay	Identifies the primary location of relay-backed wallet state.	Not normally secret

For a wallet generated by Acorn, the original 12-word seed phrase and its derived nsec are alternative paths to the same private-key authority. A wallet created from externally supplied 256-bit entropy has a 24-word BIP39 phrase with the same recovery role. A wallet imported from an existing nsec does not have an Acorn-generated seed phrase; the nsec itself must be backed up. None of these secrets should ever be pasted into chats, issue trackers, logs, or untrusted websites.

External entropy can be selected with acorn init --entropy. Acorn reads the 64-character hexadecimal value through a hidden confirmation prompt, converts it directly to a BIP39 phrase, and never stores the raw entropy. This path is intended for hardware, offline, or independently audited randomness sources—not for hashes of passwords or other guessable text.

What recovery restores

Restoring the keypair restores the Acorn component's cryptographic authority. The keypair can then locate, verify, decrypt, and continue compatible wallet state. It does not, by itself, restore or prove a person's identity.

Recovery may restore:

encrypted wallet metadata;
private records visible on the selected relay;
Cashu proof state stored by the wallet;
transaction history and operational cursors; and
configuration preferences stored as recoverable records.

Recovery does not prove who the human operator is. It also does not make stale ecash proofs spendable: the issuing mint remains authoritative about whether a proof is valid or spent.

Rejected swaps and relay cleanup

Abandoning a pending incoming transfer

For test receipts whose remaining value you intentionally accept losing, use the CLI configured to the receiving Acorn:

acorn pending-transfers
acorn abandon-transfer <full-event-id> --reason "Abandoning test transfer"

The command displays the wallet and amount and asks for confirmation. It reads the receipt again under the wallet lock, verifies the acknowledged amount and provisional status, then publishes a verified abandoned journal entry with a timestamp and reason. The stored token is removed, but the event ID remains to prevent rediscovery. Other receipts, wallet proofs, balances and swap-recovery records are not modified. This is not a refund, payment confirmation or secure erasure of historical relay copies. Unresolved swap recovery may still block later payments and requires separate recovery or review.

Pause other applications or workers using this Acorn before abandonment to avoid racing a reconciliation already in progress. Both commands use the usual CLI configuration (--config / ACORN_CONFIG); no private key needs to be re-entered. acorn pending-transfers --json emits only public receipt identifiers and amounts, mint/unit/status metadata, and the wallet public key—not bearer tokens. Listing does not contact mints or initialize the wallet through load_data.

Recovery-journal safeguards

A mint rejection and a relay persistence failure are separate outcomes. When a mint definitively rejects a submitted swap, Acorn records that rejection in its encrypted recovery journal before retiring the prepared intent. If journal cleanup fails, the error preserves the mint's rejection and does not claim that the request was never submitted. Continuity receipts stay pending: a cleanup failure must not trigger spent-token retirement or fresh individual swaps.

A later attempt can retire an intent with a recorded rejection, including after a process restart. For the same input batch it reports the earlier rejection without resubmission; after verified cleanup, the receipt reconciler can isolate individual tokens through its existing spent-batch fallback.

If the rejection itself could not be durably recorded, or an older intent lacks an outcome marker, Acorn retains the normal restore-only safety boundary. An empty restore response is not proof that deleting recovery information is safe. These cases still require recovery or operator review; upgrading does not erase old recovery records or establish where previously spent value went.

Recovery across environments

The same Acorn wallet can be restored into another compatible environment:

lost device       -> replacement device
retired app       -> compatible application
failed provider   -> another trusted operator
unavailable host  -> another FreeBSD jail or appliance
failed relay      -> verified replica or alternate home relay

The surrounding software can change while the wallet lineage continues. This is why the continuity boundary is the keypair and recoverable protocol state, not a particular process or screen.

Availability is part of recovery

Perfect key backup is not enough if the only copy of the encrypted state is unavailable. A home relay tells Acorn where the wallet currently lives, but it should be a pointer rather than an irreplaceable destination.

Acorn therefore treats replication and migration as recovery concerns:

signed encrypted events can be copied to another suitable relay;
a target should be read back and verified before it is trusted;
another relay can become the new home after verification; and
particularly sensitive deployments can use private or firewalled relays.

Relay replication protects event availability. It does not reconcile divergent proof histories or determine whether ecash is spendable. Proof-state recovery must include mint verification.

Trusted operators and recovery

A provider may run Acorn for a user and make recovery straightforward. That is a valid model when the trust boundary is clear.

If the operator can access the private key, the user is delegating operational authority to that operator. If signing occurs locally or inside constrained hardware, the operator may provide the service surface without holding the full authority boundary.

In either case, a user-controlled deployment should have a credible answer to:

Can this wallet continue if the current application or operator disappears?

Safe recovery practice

Keep recovery material offline or in a trusted secrets manager.
Maintain more than one protected copy in locations that do not share the same physical failure risk.
Record the home relay alongside the key material.
Test recovery with small balances before relying on it.
Verify replicated state before changing the home relay.
Treat any exposed seed phrase or nsec as a potential wallet compromise.
Give externally generated entropy the same protection as the resulting seed phrase and nsec.
Do not assume that a relay backup replaces mint proof verification.

Acorn's CLI can display recovery material only after an explicit warning and confirmation. This is intentionally a sensitive operation, not routine status output.

Current boundary

Acorn has demonstrated recovery interoperability between its CLI and the Safebox web application. The project remains developer-stage software. Recovery behavior, configuration safety, transfer interruption handling, and package validation remain release gates, so only small test balances should be used.

Explore relay availability and reciprocal resilience Return to the Nostr-native approach