Personal Wallet Daemon #1
Labels
No labels
prio_critical
prio_low
type_bug
type_contact
type_issue
type_lead
type_question
type_story
type_task
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
lhumina_code/hero_wallet#1
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Personal Wallet Daemon — Minimal Spec
1. Purpose
A local/service daemon exposing an OpenRPC API for a multi-chain personal wallet and treasury system.
Initial chains:
Storage backend:
The daemon is responsible for:
2. Correct Nomenclature
Use this structure:
2.1 Wallet
A wallet is the top-level container for a user’s holdings and configuration.
A wallet contains:
Example:
Personal WalletTreasury WalletSavings Wallet2.2 Chain Account
A chain account is the identity on a specific blockchain.
Examples:
Fields:
This is the thing that actually owns assets on-chain.
2.3 Asset
An asset is a transferable unit tracked on a blockchain.
Examples:
An asset must always be identified by:
Do not rely only on symbol, because
USDCexists on many chains.2.4 Holding
A holding is the amount of a given asset in a given chain account.
Example:
0xabc...holds14.25 USDCon Ethereum mainnet2.5 Transaction
A transaction is an on-chain transfer or state-changing operation.
Examples:
2.6 Contact
A contact is a user-defined destination profile.
A contact may contain:
Example:
Alice0x...bc1...alice.near3. Recommended Data Model
3.1 Main entities
Wallet
ChainAccount
Asset
Holding
Transaction
Contact
ContactAddress
PriceSnapshot
SyncState
4. Architecture
4.1 Core services inside daemon
Minimal internal modules:
1. OpenRPC API layer
Exposes methods over Unix socket or TCP.
2. Wallet service
Manages wallets, accounts, contacts, holdings metadata.
3. Chain adapters
One adapter per chain:
near_adapterethereum_adapterbitcoin_adapterEach adapter implements the same interface:
4. Sync engine
Continuously or on-demand syncs chain state into Redis.
5. Pricing engine
Fetches market prices and computes portfolio values.
6. Transfer engine
Creates sends, cross-account sends, later cross-chain flows.
7. Key/signing service
Reads signing material from encrypted Redis and signs transactions.
5. Important Functional Concepts
5.1 Wallet vs account
A wallet is your logical container.
A chain account is your actual blockchain identity.
So yes, this is the right hierarchy:
Wallet
→ contains multiple chain accounts
→ each chain account holds multiple assets
→ each asset has one or more holdings / balances
→ transactions change holdings
That is the cleanest model.
5.2 Asset identity
Never identify assets only by ticker.
Use canonical identifiers like:
bitcoin:mainnet:btcethereum:mainnet:ethethereum:mainnet:erc20:0xA0b8...near:mainnet:nearnear:mainnet:ft:<contract_id>5.3 Cross-chain transfer
There is no true native “send between chains” in one primitive.
So define this as a workflow, not a transaction type only.
Possible modes:
Model it as:
6. Sync Model
6.1 Why local sync
You want your own full historical view in Redis so the daemon can answer quickly without always hitting the chain.
Good.
6.2 Sync responsibilities
For each chain account, sync should fetch:
6.3 Sync modes
Full sync
From account creation or configured start block.
Incremental sync
From last known cursor/block.
Reconciliation
Periodic re-check of recent transactions in case of reorgs or late indexing.
6.4 Chain-specific notes
Bitcoin
Need UTXO-aware model internally, even if exposed as simple balance externally.
Store:
Ethereum
Need to track:
NEAR
Need to track:
7. Minimal OpenRPC Surface
7.1 Wallet management
7.2 Chain account management
7.3 Asset catalog
7.4 Contacts
7.5 Sync
7.6 Transactions
7.7 Transfers
7.8 Pricing / portfolio
7.9 Swaps / DeFi
Later, not required day one.
8. Suggested API Semantics
8.1 Prefer explicit chain/network everywhere
Every method should require or return:
Never assume defaults invisibly.
8.2 Two-stage transaction flow
Do not combine everything into one unsafe call.
Preferred lifecycle:
tx.buildtx.signtx.broadcastThen convenience wrapper:
tx.send8.3 Idempotency
For sends and sync operations, support idempotency keys.
Important for retries.
8.4 Watch-only support
Support accounts without private keys.
This is useful for treasury monitoring.
9. Minimal Rust Module Layout
10. Redis Storage Strategy
Use Redis as a durable state cache + store.
Recommended keyspaces:
Also maintain indexes:
11. Security Minimum
Even if Redis is encrypted, the daemon should still behave safely.
Minimum requirements:
11.1 Separate signing from querying
Internally separate read-only chain access from signing operations.
11.2 Key references
Application code should preferably work with
signer_key_ref, not raw private keys everywhere.11.3 Sensitive method boundaries
Methods like
tx.signandtx.sendshould be clearly permissioned and audited.11.4 Audit log
Store:
11.5 Safe defaults
12. Portfolio and Pricing
12.1 Price model
Track asset prices against quote currencies:
This gives relative value views.
12.2 Holdings valuation
For each holding compute:
12.3 Historical portfolio
Optional later, but useful:
snapshot periodic holdings so you can show portfolio over time.
13. DeFi / Swap Model
This should be optional per chain.
13.1 On-chain swap support
For chains where supported, expose:
13.2 Minimal abstraction
A swap is not a generic transfer.
Model separately:
13.3 Day-one recommendation
Do not make swaps part of the core send path.
Keep as separate module.
14. Cross-Chain Recommendation
For V1:
For V1.5/V2:
Reason:
cross-chain is operationally much more complex and should be treated as orchestrated workflows.
15. Chain Abstraction Trait
Your adapter trait should look conceptually like this:
That keeps all three chains aligned.
16. Minimal V1 Scope
Must have
Should have
Not in V1 unless needed
17. Best Naming Recommendation
Use these names in the spec:
This is clear and scalable.
18. One-line Product Definition
A local OpenRPC wallet daemon that manages multi-chain accounts, assets, transfers, sync, pricing, and treasury state across NEAR, Ethereum, and Bitcoin, backed by encrypted Redis.
19. Final Design Advice
Do not design this around “wallet holds currencies.”
Design it around:
wallet
→ chain accounts
→ assets
→ holdings
→ transactions
That model survives growth, supports multiple chains cleanly, and keeps Bitcoin, Ethereum, and NEAR compatible under one abstraction.
use skills
Implementation Spec — hero_wallet
This comment captures the full implementation plan for the Personal Wallet Daemon, mapping the issue spec onto Hero ecosystem conventions.
1. Workspace Layout
Following the standard Hero three-crate model:
2. Crate Responsibilities
hero_wallet_server~/hero/var/sockets/hero_wallet_server.sock. No TCP.hero_wallet_sdkopenrpc_client!macro fromopenrpc.json. Thin utility wrappers if needed.hero_wallet_uiopenrpc_proxy!for/rpcproxy. SDK for aggregation routes. Binds Unix socket at~/hero/var/sockets/hero_wallet_ui.sock.hero_wallet--start/--stop. Registers server + UI as actions with hero_proc vialifecycle::restart_service().hero_wallet_examples3. Data Model (Redis)
All entities from the issue spec, stored in encrypted Redis with these keyspaces:
Indexes:
idx:wallet:by_owner:{owner_id}-> wallet_idsidx:account:by_chain:{blockchain}:{network}-> account_idsidx:account:by_address:{address}-> account_ididx:tx:by_hash:{tx_hash}-> tx_ididx:asset:by_chain:{blockchain}:{network}-> asset_idsAsset Identity
Canonical asset IDs follow the pattern
{blockchain}:{network}:{type}:{identifier}:bitcoin:mainnet:native:btcethereum:mainnet:native:ethethereum:mainnet:erc20:0xA0b8...near:mainnet:native:nearnear:mainnet:ft:usdc.near4. ChainAdapter Trait
Implemented by
NearAdapter,EthereumAdapter,BitcoinAdapter.5. OpenRPC API Surface
All methods require explicit
blockchain+networkparameters where applicable. The fullopenrpc.jsonspec will be the single source of truth.5.1 System
5.2 Wallet Management
5.3 Chain Account Management
5.4 Asset Catalog
5.5 Contacts
5.6 Sync
5.7 Transactions (two-stage flow)
5.8 Transfers
5.9 Pricing / Portfolio
5.10 Swaps (V2, not in V1)
6. CLI Binary — hero_wallet
The CLI binary is the only binary with
--start/--stop. It useshero_proc_sdkto register two actions:hero_wallet_serverandhero_wallet_uihave no--start/--stop, noclap, nohero_proc_sdkdependency.7. Admin Dashboard Tabs
The
hero_wallet_uidashboard follows the Hero UI Dashboard standard:Navbar
<i class="bi bi-wallet2"></i> Hero WalletSidebar — Wallet Stats
Domain Tabs
bi-wallet2bi-link-45degbi-coinbi-arrow-left-rightbi-peoplebi-pie-chartUtility Tabs
bi-journal-textbi-graph-upbi-shield-gearbi-book8. Security Model
signer_key_ref) in Redis — application code never handles raw private keys directlytx.signandtx.sendare sensitive methods — all calls logged to audit trailtx.buildreturns unsigned, user must explicitly calltx.signthentx.broadcastsigner_key_ref, read-only operations only)0o770)Audit log stored in Redis:
9. Sync Engine
Modes
sync.account/ first runlast_scanned_block/last_scanned_cursorChain-Specific Sync Details
Bitcoin: UTXO-aware. Store individual UTXOs with spent/unspent state. Track confirmations. Expose simplified balance externally.
Ethereum: Track native ETH + ERC-20 balances. Parse Transfer event logs. Track gas fees and nonce.
NEAR: Track native NEAR + fungible tokens (NEP-141). Handle receipt-based finality model.
Scheduler
Background tokio task runs incremental sync on a configurable interval (default: 30s). Each chain adapter implements cursor-based pagination so sync can resume from last position.
10. Pricing Engine
portfolio.getAllocationreturns percentage breakdown by asset and by chain11. V1 Scope Checklist
Must Have
openrpc.jsonwith all V1 methodsopenrpc_client!macroShould Have
Not V1
12. Build & Run
Makefile targets
Socket paths
Installed binaries
13. Implementation Order
rpc.health,rpc.discoveropenrpc_client!macro, verify examples compile--start/--stop.forgejo/workflows/Test Results
All 5 crates compile and build successfully:
hero_wallet_server— JSON-RPC daemon binaryhero_wallet_sdk— Generated OpenRPC client libraryhero_wallet— CLI binary with lifecycle managementhero_wallet_ui— Admin dashboard binaryhero_wallet_examples— Usage examplesImplementation Summary
What was built
A complete V1 personal wallet daemon following Hero service conventions:
5 crates in workspace:
openrpc_client!macro + raw RPC proxy--start/--stoplifecycle via hero_proc + subcommands for all operationsKey features implemented:
chain:network:type[:address]Files created: ~35 source files across 5 crates + workspace config
What's deferred to V2
Implementation committed:
b49e200Browse:
b49e200