feat(flatkv): introduce interface layer (Store/Iterator) and typed keys

[blindchaser]

Describe your changes and provide context

This PR introduces the FlatKV interface layer, designed to bridge x/evm state access with a multi-DB storage architecture:

• Store Interface: Defines a unified contract for EVM state storage that internally maps logical keys to isolated physical DBs (accounts, code, storage).

• Type-Safe Keys: Adds strong types (Address, CodeHash, AccountKey, etc.) and constructors to prevent raw byte manipulation errors.

• Key Mapping: Implements ParseEVMKey to robustly translate x/evm memiavl keys into internal DB selectors.

• Iterator Semantics: Adopts PebbleDB-style iterator semantics (Next/Prev/SeekGE) with explicit support for multiplexed iteration across the multi-DB layout.

Testing performed to validate your change

[github-actions]

The latest Buf updates on your PR. Results from workflow Buf / buf (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	✅ passed	✅ passed	✅ passed	Jan 20, 2026, 9:48 PM

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6e680a7ea3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

* Return Exporter interface, not Exporter

The method signature Exporter(version int64) (*Exporter, error) returns a pointer to an interface, which is almost always a mistake in Go. Callers will have to dereference just to call methods, and it becomes easy to return a non-nil pointer that wraps a nil interface (e.g., exp != nil but *exp == nil), which will still panic when methods are invoked once the interface grows methods. Returning the interface value (Exporter) avoids these nil-check pitfalls and matches standard Go API semantics.

Useful? React with 👍 / 👎.

[codecov]

Codecov Report

❌ Patch coverage is 63.71681% with 41 lines in your changes missing coverage. Please review.
✅ Project coverage is 44.02%. Comparing base (e52b2a7) to head (74060ba).

Files with missing lines	Patch %	Lines
sei-db/state_db/sc/flatkv/keys.go	66.66%	23 Missing ⚠️
sei-db/state_db/sc/flatkv/evm_memiavl_mapper.go	59.09%	9 Missing and 9 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2710      +/-   ##
==========================================
+ Coverage   44.00%   44.02%   +0.02%     
==========================================
  Files        1980     1982       +2     
  Lines      162724   162837     +113     
==========================================
+ Hits        71612    71695      +83     
- Misses      84592    84611      +19     
- Partials     6520     6531      +11     

Flag	Coverage Δ
sei-chain	46.22% <63.71%> (+0.02%)	⬆️
sei-cosmos	38.20% <ø> (ø)
sei-db	68.72% <ø> (ø)
sei-tendermint	47.32% <ø> (+0.03%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
sei-db/state_db/sc/flatkv/evm_memiavl_mapper.go	59.09% <59.09%> (ø)
sei-db/state_db/sc/flatkv/keys.go	66.66% <66.66%> (ø)

... and 19 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.