Add AccountRestorationProcessor for Improved Key Rotation and Multi-Key Account Discoverability

[0xjunha]

Description

This PR introduces a new sdk-processor AccountRestorationProcessor to help solve account discoverability challenges for key rotation and offchain multi-key.

By indexing (auth key -> account) mappings for all account types and (public keys -> auth key derivation) & (auth key -> multi-key layout) mappings for multi-key accounts, a wallet can quickly find all account addresses tied to a public key and avoid losing access when an account rotation happens.

To implement this, the PR introduces the AccountRestorationProcessor and the following three new tables.

New tables

AuthKeyAccountAddress

• Purpose: Maps authentication keys to their corresponding account addresses (for all account types).
• Relationship: 1:N (one auth key can back multiple account addresses by account rotations).
• Primary Key: address
• Upserted on each user transaction.

Example

• This table indexes all user transactions
• The 4th and 5th rows of the image have different values for auth_key and address, indicating that the account had been rotated.

AuthKeyMultikeyLayout

• Purpose: Describes the composition of multi-key authentication keys (e.g., public keys, key types, threshold). This information is required for constructing multi-key transaction authenticator.
• Relationship: 1:1 (it’s extremely unlikely for two different sets of public keys to derive the same auth key).
• Primary Key: auth_key
• Note: multikey_layout_with_prefixes is an ordered list of public keys with 1-byte prefixes indicating key type of each public key (e.g., 0x00 for Ed25519 Generalized). If the prefix is missing, the public key is legacy Ed25519 type.

Example

• This table indexes user transactions with multi-key authenticator only.
• Public keys in the array of the multikey_layout_with_prefixes column value are prefixed with public key types (0x00 and 0x01)
• For multi_ed25519 multi-key type, public keys won't have any prefixes.

PublicKeyAuthKey

• Purpose: Maps public keys to the corresponding authentication keys of multi-key accounts.
• Relationship: N:N (one public key can appear in multiple multi-key auth keys, and a single multi-key auth key include multiple public keys).
• Primary Key: (public_key, public_key_type, auth_key)
• Note: public_key is not prefixed with the key type. Instead, there's a dedicated String column for that (public_key_type).

Example

• This table indexes user transactions with multi-key authenticator only.
• verified==TRUE means that the public key was historically used at least once for authenticating a transaction. E.g., for the auth_key 0xb697..., public_keys 0x0450... and 0x7226... were used for authenticating a transaction (2-of-3 multi-key scheme)

Notes

• While many sdk-processors rely on transaction parsing logic from legacy processors, this PR places the relevant logic in an account_restoration_utils module under rust/processor/src/db/postgres/models/account_restoration_models/, since there isn't an existing processor equivalent.

Links

• PublicKey to Addresses Eng Design Review

Tests

• Tested on Devnet, Integration tests WIP

[codecov]

Codecov Report

Attention: Patch coverage is 0% with 542 lines in your changes missing coverage. Please review.

Project coverage is 47.7%. Comparing base (1130af5) to head (76ce1aa).

Files with missing lines	Patch %	Lines
...nt_restoration_models/account_restoration_utils.rs	0.0%	279 Missing ⚠️
...estoration_processor/account_restoration_storer.rs	0.0%	129 Missing ⚠️
...or/src/processors/account_restoration_processor.rs	0.0%	75 Missing ⚠️
rust/processor/src/db/postgres/schema.rs	0.0%	30 Missing ⚠️
...oration_processor/account_restoration_extractor.rs	0.0%	24 Missing ⚠️
...k-processor/src/config/indexer_processor_config.rs	0.0%	2 Missing ⚠️
...t_restoration_models/auth_key_account_addresses.rs	0.0%	1 Missing ⚠️
...unt_restoration_models/auth_key_multikey_layout.rs	0.0%	1 Missing ⚠️
...account_restoration_models/public_key_auth_keys.rs	0.0%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##            main    #660     +/-   ##
=======================================
- Coverage   49.0%   47.7%   -1.4%     
=======================================
  Files        233     240      +7     
  Lines      27308   27850    +542     
=======================================
- Hits       13391   13293     -98     
- Misses     13917   14557    +640     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[dermanyang]

@0xjunha would you mind adding some screenshots of rows from local DB with explanations confirming expected behavior please?

[0xjunha]

@0xjunha would you mind adding some screenshots of rows from local DB with explanations confirming expected behavior please?

Edited the PR description to include some screenshots! @dermanyang

[dermanyang]

Suggested change

	"Invalid db config for AccountTransactionsProcessor {:?}",
	"Invalid db config for AccountRestorationProcessor {:?}",

[dermanyang]

Can you add some context into a doc string above this struct please? Same with the other structs. Just copy pasting the descriptions you have in the PR about the tables is sufficient imo. Thanks!