Engineering-ready product design

Page-by-page specification for M Wallet implementation.

Route map and module boundaries

This product should be built as one identity-bound account system, with wallet, payment, IBC, credential, and cold-signing modules composed around the selected account.

Entry /home Account switcher, MID state, balances, payment request, official alert.

Money /wallet FCA, USDF, future MXCD, external assets, receive address, swap entry.

Payment /pay QR contact, payment request, structured notes, receipt, confirmation.

Business /ibc/accounts/{company_id} Company account, roles, invoices, receipts, service records.

Identity /mid/credentials Digital ID, license, address proof, tax number, certificates.

Security /wallet/vault NFC Vault Card, protected assets, signing sessions, recovery.

Official /notifications Signed broadcasts, renewal notices, security alerts, payment deep links.

Service /services/invoices/{id} Official invoice, payment rail selection, receipt attachment.

Control /settings/security Trusted devices, passkeys, limits, notification preferences, recovery.

Shared /receipts/{id} Payment, swap, IBC, credential proof, and service-payment record.

Module

Primary owner

Shared resources

Must produce

Identity and accounts

User, MID credential, account, role, device session.

All modules read selected account context.

Account authorization result and audit trail.

Wallet and swap

Balances, asset metadata, quote, order, transaction.

Vault policy, receipt service, network status.

Quote response, transaction result, receipt.

Payment conversation

Verified contact, typed message, payment request.

Balance service, transaction service, receipt service.

Message state, settlement state, receipt reference.

IBC and services

Company account, role assignment, invoice, filing record.

Credential proof, service invoice, payment rail.

Signed service event and company-bound receipt.

Implementation principles

Backend engineers should treat M Wallet as a verified account system. Addresses, assets, cards, invoices, and receipts all belong to an identity-bound account context.

Identity first

Every sensitive operation references user_id, mid_id, account_id, device session, and risk context.

Accounts are containers

Personal, IBC, Vault, Merchant, and Agent accounts should share a common account model with type-specific permissions.

Receipts are records

Payment, swap, invoice, and credential-sharing actions produce immutable receipts or audit events.

Structured communication

Payment conversation is not open chat. It stores typed messages: contact card, request, note, receipt, confirmation.

Policy gates

Swap, IBC payments, large withdrawals, credential sharing, and Vault Card signing must pass policy checks.

Future rails are explicit

MXCD-related features should be marked as future or policy-gated until official approvals and reserve frameworks exist.

Core data model

These objects form the minimum backend vocabulary. Frontend screens should be able to compose all pages from these resources.

User and MID credential

Represents a verified person and their identity assurance state.

user_idPrimary user UUID

mid_iddid:mid identifier

kyc_levelbasic / resident / business

credential_statusactive / expiring / revoked

residency_statusnone / pending / active

risk_flagsarray of policy flags

Account

Common account container for personal wallet, IBC company wallet, Vault account, and future account types.

account_idAccount UUID

account_typepersonal / ibc / vault / merchant

display_nameUser-facing account name

primary_addressFC Chain address

rolesowner / director / agent / accountant

policy_profilelimits and approval rules

Asset balance

Balances are scoped to accounts and networks. External assets remain separate from FC Chain primary rails.

asset_codeFCA / USDF / MXCD / BTC / ETH

networkfc_chain / bitcoin / ethereum / tron / solana / bnb

availableSpendable amount

lockedPending, vault, or policy-held

fiat_valueUSD display value

rail_typenative / payment / future / external

Payment conversation

Typed structured messages around verified contacts and payments.

conversation_idThread UUID

counterparty_midVerified contact DID

message_typecontact / request / note / receipt / confirmation

amountOptional amount

asset_codeUSDF / FCA / future MXCD

statusdraft / pending / paid / settled / declined

IBC account

Company-specific wallet and service record connected to a MID owner or authorized role.

company_idIBC UUID

registry_numberOfficial company number

company_statusdraft / active / renewal_due / suspended

role_assignmentsUsers and roles

invoice_idsService and government invoices

receipt_idsAttached records

Credential card

Apple Wallet style credential, issued by an authority and shareable through selective disclosure.

credential_idCard UUID

credential_typemid / driver_license / address / tax / ibc_certificate

issuer_idAuthority or registry

statuspending / verified / expiring / revoked

expires_atRenewal trigger

disclosure_rulesWhat can be shared

Vault card

NFC cold wallet card and signing-session state for high-value actions.

vault_card_idCard UUID

card_statusactive / backup / lost / disabled

card_roleprimary / backup_1 / backup_2

protected_assetsAssets or accounts covered

last_signed_atLast NFC signature

signing_policyThreshold and limits

Notification and broadcast

Signed official broadcast, payment notice, IBC invoice notice, or security alert.

notice_idNotification UUID

channelpayment / official / security / ibc

signature_statusverified / failed / unknown

prioritylow / normal / urgent

target_account_idOptional account scope

action_urlDeep link route

Page-by-page implementation spec

Each page can be implemented independently as long as it respects account context, role policy, typed actions, and audit logging.

01. Home · Resident account dashboard

Primary landing page showing account switcher, MID credential state, FC Chain balances, fast actions, latest payment request, and high-level infrastructure status.

/home

UI sections

Header with app identity and notifications
Personal / IBC account switcher
MID credential summary
Total assets and FCA/USDF split
Send, request, swap, receive, scan actions
Latest verified payment request

Required data

me with MID state
accounts[]
selected_account
balances[]
latest_payment_request
notification_counts

Actions

Switch account
Open pay composer
Open swap quote
Open QR scanner
Review payment request
Open official broadcast

GET sessionGET /v1/me

List accountsGET /v1/accounts

Account summaryGET /v1/accounts/{account_id}/summary

Latest inboxGET /v1/inbox?account_id={id}&limit=3

loadingno MID credentialMID verifiedIBC account availablepayment request pendingofficial alert unread

02. Wallet · Assets and controlled swap

Shows primary FC Chain rails, external networks, USDF/MXCD policy note, controlled swap module, and MID Vault Card status.

/wallet

UI sections

Primary rail: FCA, USDF, MXCD future
Policy-safe USDF/MXCD note
Swap widget
External network assets
MID Vault Card module

Required data

balances[] by network
asset_metadata[]
swap_supported_pairs[]
vault_status
network_status[]

Actions

Deposit or receive
Withdraw or send
Preview swap
Open Vault Card
View asset details
Copy receive address

BalancesGET /v1/accounts/{account_id}/balances

Asset metadataGET /v1/assets/metadata

Swap pairsGET /v1/swap/pairs?account_id={id}

Vault statusGET /v1/vault/cards?account_id={id}

zero balancepending depositnetwork degradedasset disabledMXCD future only

03. Swap · Verified asset conversion

Controlled exchange flow for FC Chain internal pairs. MVP should start with USDF and FCA. Future MXCD routes remain policy-gated.

/wallet/swap

UI sections

From asset selector
To asset selector
Quote output
Route and policy metadata
Preview confirmation
Swap receipt

Required data

account_limits
eligible_assets[]
quote_id
rate and expires_at
fees[]
policy_result

Backend rules

Quote expires quickly
Use idempotency key on execution
Large swap may require Vault Card
Generate swap receipt
Audit quote and execution

QuotePOST /v1/swap/quotes

ExecutePOST /v1/swap/orders

Order detailGET /v1/swap/orders/{order_id}

ReceiptGET /v1/receipts/{receipt_id}

quote loadingquote expiredinsufficient balancelimit exceededvault requiredsettled

04. Pay · QR contact and payment conversation

Structured payment communication around verified contacts. This is not open chat; it is a transaction-supporting message system.

/pay

UI sections

MID QR scanner / contact add
Payment templates
Conversation timeline
Request review
Receipt sharing

Message types

contact_card
payment_request
payment_note
receipt
confirmation

Rules

Only verified contacts can request payment
No arbitrary free text in MVP
Notes must attach to payment record
Receipts link to settlement transaction

Scan resolvePOST /v1/contacts/resolve-qr

Add contactPOST /v1/contacts

Conversation listGET /v1/payment-conversations

Create messagePOST /v1/payment-conversations/{id}/messages

unknown QRcontact verifiedrequest pendingpaidsettleddeclined

05. IBC · Company wallet account

Independent company account space with its own FC Chain address, balances, roles, invoices, receipts, and vault policies.

/ibc/accounts/{company_id}

UI sections

Company identity header
Operating wallet balance
Vault reserve
Role grid
Bills and receipts
Application path

Roles

Owner: full signing
Director: approve bills
Agent: file services
Accountant: read receipts

Rules

IBC operations require role check
Government invoices are signed
Large withdrawals require Vault Card
Receipts attach to company record

List companiesGET /v1/ibc/accounts

Company detailGET /v1/ibc/accounts/{company_id}

InvoicesGET /v1/ibc/accounts/{company_id}/invoices

RolesGET /v1/ibc/accounts/{company_id}/roles

no companydraft applicationactive companyrenewal duerole deniedinvoice due

06. Credential Center · Digital cards and certificates

Verified cards for personal and business credentials, with status lifecycle and selective disclosure.

/mid/credentials

Card types

MID Digital ID
Driver license
Address proof
Tax number
IBC certificate
Good standing certificate

Status lifecycle

pending review
verified
expiring soon
renewal required
revoked
archived

Actions

View card
Share limited proof
Request renewal
Export proof QR
Attach to IBC service

List cardsGET /v1/credentials

Card detailGET /v1/credentials/{credential_id}

Create proofPOST /v1/credentials/{credential_id}/proofs

Renewal requestPOST /v1/credentials/{credential_id}/renewals

empty walletpending reviewverifiedexpiring soonrevokedproof generated

07. MID Vault Card · NFC cold wallet

Card-based cold signing for large transfers, company reserve withdrawals, and protected long-term holdings.

/wallet/vault

UI sections

Primary card status
Backup cards
Protected assets
Signing flow
Lost card procedure

Signing session

Review transaction
Biometric confirmation
Tap NFC card
Card signs payload
App broadcasts transaction

Rules

Never expose card secret
Signing payload must be human-readable before tap
Backup card enrollment requires step-up authentication
Lost card disables future signing

CardsGET /v1/vault/cards

Start signingPOST /v1/vault/signing-sessions

Submit signaturePOST /v1/vault/signing-sessions/{id}/signature

Report lostPOST /v1/vault/cards/{card_id}/report-lost

no cardactive cardbackup readytap requiredsignature failedcard lost

08. Broadcast and notifications

Signed official channel for government messages, IBC renewal reminders, payment requests, and security alerts.

/notifications

Channels

payment
official broadcast
security alert
IBC invoice
credential renewal

Required data

signature_status
issuer_id
priority
target_account_id
action_url

Rules

Official notices must verify signature
Failed signatures should be quarantined
Security alerts may require immediate user action
Notifications should deep link to records

InboxGET /v1/notifications

Mark readPOST /v1/notifications/{notice_id}/read

Verify issuerGET /v1/issuers/{issuer_id}

PreferencesPATCH /v1/notification-preferences

unreadsignedsignature failedurgentaction requiredarchived

09. Service payment · Invoice to receipt

Official service fee payment path for registry renewals, filings, certificates, and future government services.

/services/invoices/{invoice_id}

UI sections

Invoice summary
Issuer and signature status
Eligible payment rails
Role approval checks
Payment confirmation
Receipt record

Required data

invoice_id
issuer_signature
amount
accepted_assets[]
service_context
receipt_id

Rules

Only signed invoices are payable
IBC invoices require role approval
Payment result creates receipt
Receipt attaches to service record
Use idempotency key

Invoice detailGET /v1/services/invoices/{invoice_id}

Pay invoicePOST /v1/services/invoices/{invoice_id}/payments

ReceiptGET /v1/receipts/{receipt_id}

ExportGET /v1/receipts/{receipt_id}/export.pdf

invoice duesignature verifiedrole deniedpayment processingsettledreceipt filed

10. Settings and recovery · Account control center

Operational security surface for trusted devices, passkeys, transaction limits, notification preferences, recovery contacts, and account export controls.

/settings/security

UI sections

Profile and selected account context
Trusted devices
Passkeys and biometrics
Payment and swap limits
Recovery and backup cards
Notification preferences

Required data

device_sessions[]
auth_methods[]
limit_profile
recovery_methods[]
vault_cards[]
notification_preferences

Rules

Removing a device requires step-up authentication
Limit increases should trigger cooling period
Recovery changes create urgent security notice
Export actions must be audited

DevicesGET /v1/security/devices

Auth methodsGET /v1/security/auth-methods

LimitsPATCH /v1/accounts/{account_id}/limits

RecoveryPOST /v1/security/recovery-methods

device trustednew loginstep-up requiredcooling periodrecovery pendingexport ready

Payload and event contracts

These examples are intentionally small. They define the shape engineers need for frontend integration, idempotency, audit logs, and future compliance review.

Payment request message

{
  "message_type": "payment_request",
  "conversation_id": "conv_123",
  "counterparty_mid": "did:mid:resident:789",
  "account_id": "acct_personal_01",
  "amount": "125.00",
  "asset_code": "USDF",
  "note_template": "service_payment",
  "expires_at": "2026-05-01T00:00:00Z"
}

Swap quote request

{
  "account_id": "acct_personal_01",
  "from_asset": "USDF",
  "to_asset": "FCA",
  "amount": "250.00",
  "idempotency_key": "uuid-client-generated",
  "policy_context": {
    "purpose": "wallet_rebalance"
  }
}

Credential proof request

{
  "credential_id": "cred_driver_license_01",
  "scope": ["name", "credential_status", "expiry"],
  "recipient_type": "service",
  "recipient_id": "registry_service",
  "expires_in_seconds": 900,
  "user_consent": true
}

Vault signing session

{
  "account_id": "acct_ibc_01",
  "operation_type": "large_transfer",
  "human_readable_payload": "Send 4,500 USDF to FC...9A2",
  "required_card_role": "primary",
  "expires_at": "2026-04-26T12:30:00Z"
}

Signed official broadcast

{
  "notice_id": "notice_2026_001",
  "channel": "official",
  "issuer_id": "dro_registry",
  "signature_status": "verified",
  "priority": "urgent",
  "action_url": "/services/invoices/inv_001"
}

Receipt object

{
  "receipt_id": "rcpt_001",
  "source_type": "service_payment",
  "account_id": "acct_ibc_01",
  "transaction_hash": "0x...",
  "asset_code": "USDF",
  "amount": "350.00",
  "status": "settled",
  "audit_event_id": "audit_001"
}

Permission and security policy

Security is account-specific. The backend should calculate required assurance before every sensitive operation and return the next required step.

Action

Minimum assurance

Backend result

View balances

Authenticated device session

Return balances scoped to allowed account IDs.

Send small payment

MID active + passkey or biometric

Create transaction, receipt, audit event.

Swap USDF/FCA

MID active + account limits + quote policy

Return quote or required step-up challenge.

IBC invoice payment

Valid company role + signed invoice + payment policy

Create payment and attach receipt to company record.

Large transfer

Biometric + MID Vault Card signing

Start signing session and wait for NFC signature.

Share credential proof

Credential verified + user consent

Generate limited proof token with expiry and audit event.

Backend build checklist

This is the practical checklist I would hand to engineering before implementation planning.

Foundation

User, MID credential, account, role, and device-session tables
Account-scoped API authorization middleware
Audit event table for every sensitive action

Ledger and assets

Balance service by account and network
Asset metadata and network status service
Pending transaction and receipt generation

Payment conversation

Verified contact resolver from MID QR
Typed message model only
Payment request to transaction linkage

IBC accounts

Company account model
Role assignments and approval rules
Invoice, receipt, export, and service-record attachment

Credential Center

Credential card lifecycle
Issuer and signature verification
Selective disclosure proof endpoint

Vault Card

NFC card registry
Signing session lifecycle
Lost card and backup card flows

Swap

Quote service with expiry
Execution endpoint with idempotency
Limit, risk, and future MXCD policy gates

Notifications

Signed official broadcast verification
Inbox service with channels
Deep links to payment, IBC, credential, and security records

Phase 1 · Core accountMID credential, account switcher, balances, receive address, basic receipts.

Phase 2 · Payment layerQR contact, typed payment request, payment note, receipt, confirmation.

Phase 3 · IBC servicesCompany account, role policy, signed invoices, service payment, records.

Phase 4 · Advanced securityControlled swap, Vault Card signing, external rails, future MXCD policy gates.

MVP recommendation: build Identity + account switcher + balances + payment conversation + IBC invoices + receipts first. Add controlled swap and Vault Card signing as gated modules after the core account and audit model is stable.