feat(account-tree-controller): add payload/snapshot support - #9826

ccharly · 2026-08-11T16:09:44Z

Explanation

First part of the new :{import,export}State actions for the account-tree.

This PR only exposes the new payload/snapshot types that will be used to import/export.

References

feat(account-tree-controller)!: add {import,export}State actions #9663

Checklist

I've updated the test suite for new or updated code as appropriate
I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
I've communicated my changes to consumers by updating changelogs for packages I've changed
I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

Note

Medium Risk
Touches secret-bearing payload shapes and validation redaction for mnemonics/private keys; behavior is new and isolated to types/tests until controller actions land.

Overview
Introduces a new state/ layer for upcoming account-tree import/export: a versioned AccountTreePayload (v1, mnemonic + private-key wallets), IdMap for local controller IDs ↔ stable wallet:… payload IDs, and an immutable AccountTreeSnapshot for serialize/deserialize and selective export via filterWallets / filterGroups / filterAllGroups.

payload.ts defines portable wallet/group shapes (optional secrets), Superstruct validation with fail-closed version pinning, contiguous mnemonic group indices, and sensitive() on mnemonic/private-key fields so validation errors do not leak secrets. utils adds byte encoding helpers, deepFreeze, and safe validation error formatting.

Controller exportState / importState are not wired in this PR—only the types and snapshot machinery plus tests.

^{Reviewed by Cursor Bugbot for commit 7aaee50. Bugbot is set up for automated code reviews on this repo. Configure here.}

ccharly · 2026-08-11T16:27:12Z

Using no-changelog for this one, since it's purely internal for the moment. I'll make sure to update the main PR with this PR reference:

feat(account-tree-controller)!: add {import,export}State actions #9663

See: 9e0e993

gantunesr

Looks good overall

Would be good to have an integration test for the flow export→filter→serialize→deserialize. This is probably covered in the next PR for the controller wiring

gantunesr · 2026-08-11T20:07:11Z

+export type ExportStateOptions = {
+  /** When `true`, secrets (mnemonic / private keys) are included. Requires the vault to be unlocked. */
+  includeSecrets?: boolean;
+};


do you think there is any explicit cleanup/teardown to do when secrets are exported?

To like clearing them out of memory?

Like you'd like to have them being passed as options to control this?

I investigated this a bit with claude.

The real problem is that we use raw string for the secrets, and it makes it hard to zero-ing memory completely with those (since we don't own the real memory buffer for those, only the view/value on it).

If we really wanted to do this, we would need to use real buffer types like ArrayBuffer or Uint8Array. But that means our payload will need special encoding functions (at least, to make it compatible with JSON-encoding for example).

Like we could have a .stringify() and .parse(json) for example.

But that would yet another steps before/after the snapshot's serialize and deserialize.

After discussing a bit about this internally, I actually went for a different way of encoding those in our payload, so we "limit" the window of when those sensitive values are used.

They are just encoded differently, so it's more or less security-by-obscurity, but it's slightly better than having them in clear I think (and that's aligned with how we encode them elsewhere in the codebase)

ccc122e

ccharly · 2026-08-12T08:40:39Z

+   * @throws If `raw` is not a valid payload or its version is unsupported.
+   */
+  static async deserialize(raw: unknown): Promise<AccountTreeSnapshot> {
+    // TODO: Use migration framework here.


Decided to omit the migration part for now. My plan was to use our new generic migration framework that we created for keyrings. Though, it's not needed here (we expect a v1 payload + the migration framework needs a slight rework around version handling + flattening the state/data being migrated).

Delaying this work for a bit to not block this PR.

…ages

ccharly · 2026-08-12T10:04:04Z

Looks good overall

Would be good to have an integration test for the flow export→filter→serialize→deserialize. This is probably covered in the next PR for the controller wiring

We indeed have some round-trips "integration" tests on the controller itself, to make sure the combo :exportState and :importState can be used together.

If needed, I'll add even more scenarios to also include filtering in this mix!

…nd-snapshot

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 7aaee50. Configure here.}

cursor · 2026-08-12T17:49:51Z

+  value: exactOptional(sensitive(BytesStruct)),
+  metadata: AccountWalletPayloadMetadataStruct,
+  groups: AccountWalletMnemonicGroupsStruct,
+});


Group IDs lack cross-field checks

Medium Severity

Mnemonic group validation checks contiguous groupIndex values but never checks that each group id belongs to the parent wallet or that its sub-id matches groupIndex, even though the documented format is <walletPayloadId>/<groupIndex>. Inconsistent ids therefore pass deserialize and can desync import mapping from derivation indices.

Additional Locations (1)

packages/account-tree-controller/src/state/payload.ts#L85-L93

^{Reviewed by Cursor Bugbot for commit 7aaee50. Configure here.}

That's true even though we are the producer of this payload, so we "know" we won't be doing that.

We can fix that with refine and a stricter validation, but that's not vital honestly.

…etaMask#9663) ## Explanation New `{export,import}State` actions. This is the implementation for this ADR: - MetaMask/decisions#231 ## References - ADR MetaMask/decisions#231 - Split to: - MetaMask#9826 - MetaMask#9863 - MetaMask#9864 ## Checklist - [ ] I've updated the test suite for new or updated code as appropriate - [ ] I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate - [ ] I've communicated my changes to consumers by [updating changelogs for packages I've changed](https://github.com/MetaMask/core/tree/main/docs/processes/updating-changelogs.md) - [ ] I've introduced [breaking changes](https://github.com/MetaMask/core/tree/main/docs/processes/breaking-changes.md) in this PR and have prepared draft pull requests for clients and consumer packages to resolve them  --- > [!NOTE] > **High Risk** > Touches secret export/import and keyring/multichain wallet creation; incorrect handling could leak or corrupt credentials or account metadata. > > **Overview** > **Adds `AccountTreeController:exportState` and `AccountTreeController:importState`** so clients can snapshot and restore the account tree via a **version-1 wire format** (`AccountTreeSnapshot`, payload types, and `IdMap` are re-exported from the package). > > `exportState` builds a snapshot of wallets/groups (names, pinned, hidden, etc.); with **`includeSecrets: true`** and an unlocked vault it can include mnemonics and private keys. **`exportState` rejects when the vault is locked**, including metadata-only exports. `importState` accepts only validated `AccountTreeSnapshot` instances (untrusted data must use `deserialize` first); it can create new HD wallets via `MultichainAccountService` and private-key accounts via `KeyringController`, then apply metadata to existing and new entries. > > Tests add messenger action coverage, a controller-level metadata round-trip, dedicated **export→serialize→deserialize→import** integration tests for mnemonic/private-key secrets, and test harness updates (`KeyringController:withController`, multichain create actions, shared wallet fixtures). > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 6078457. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>

ccharly added 3 commits August 11, 2026 18:05

feat(account-tree-controller): add payload/snapshot support

f380090

chore: revert exported types (will get exported in final PR)

bf35e90

refactor: move formatValidationErrorMessages to utils

4a3eef7

ccharly added the no-changelog label Aug 11, 2026

ccharly marked this pull request as ready for review August 11, 2026 16:28

ccharly requested a review from a team as a code owner August 11, 2026 16:28

ccharly temporarily deployed to default-branch August 11, 2026 16:28 — with GitHub Actions Inactive

cursor Bot reviewed Aug 11, 2026

View reviewed changes

Comment thread packages/account-tree-controller/src/state/id-map.ts

Comment thread packages/account-tree-controller/src/state/snapshot.ts

ccharly added 2 commits August 11, 2026 18:44

fix: use assert to prevent overwrites in id-map

8bca2e7

fix: add comments about contiguous account groups for mnemonic wallets

e2009c4

ccharly enabled auto-merge August 11, 2026 17:11

gantunesr reviewed Aug 11, 2026

View reviewed changes

test: more test about secret redaction

585b045

ccharly commented Aug 12, 2026

View reviewed changes

refactor: cosmetic

2db451c

cursor Bot reviewed Aug 12, 2026

View reviewed changes

Comment thread packages/account-tree-controller/src/state/payload.test.ts

test: even more tests about secret redaction (2 layers)

ee63cf4

cursor Bot reviewed Aug 12, 2026

View reviewed changes

Comment thread packages/account-tree-controller/src/state/utils.test.ts

ccharly added 2 commits August 12, 2026 11:54

chore: lint

e577067

test: fix test with sensitive redaction and formatValidationErrorMess…

d611e59

…ages

gantunesr previously approved these changes Aug 12, 2026

View reviewed changes

ccharly added this pull request to the merge queue Aug 12, 2026

ccharly removed this pull request from the merge queue due to a manual request Aug 12, 2026

refactor: use encoded bytes for mnemonics/private-key values

ccc122e

ccharly dismissed gantunesr’s stale review via ccc122e August 12, 2026 17:26

Merge branch 'main' into cc/feat/account-tree-export-import-payload-a…

7aaee50

…nd-snapshot

cursor Bot reviewed Aug 12, 2026

View reviewed changes

ccharly enabled auto-merge August 12, 2026 19:20

gantunesr approved these changes Aug 12, 2026

View reviewed changes

ccharly added this pull request to the merge queue Aug 12, 2026

Merged via the queue into main with commit c6f8528 Aug 12, 2026
276 of 280 checks passed

ccharly deleted the cc/feat/account-tree-export-import-payload-and-snapshot branch August 12, 2026 21:40

ccharly mentioned this pull request Aug 13, 2026

feat(account-tree-controller)!: add {import,export}State actions #9663

Merged

4 tasks

Uh oh!

Uh oh!

Conversation

ccharly commented Aug 11, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Explanation

References

Checklist

Uh oh!

ccharly commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gantunesr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gantunesr Aug 11, 2026

Choose a reason for hiding this comment

Uh oh!

ccharly Aug 11, 2026

Choose a reason for hiding this comment

Uh oh!

ccharly Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

ccharly Aug 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ccharly Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ccharly commented Aug 12, 2026

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 12, 2026

Choose a reason for hiding this comment

Group IDs lack cross-field checks

Uh oh!

ccharly Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ccharly commented Aug 11, 2026 •

edited by cursor Bot

Loading

ccharly commented Aug 11, 2026 •

edited

Loading

ccharly Aug 12, 2026 •

edited

Loading