Wallet Management

Each authenticated user automatically receives a proxy wallet (EVM, on the SPACE OS chain) and a native account (SPACE OS native chain).

For the rationale behind the three-wallet model, see Architecture.

Get proxy wallet

GET /api/keys/proxy
Authorization: Bearer <jwt>

Returns:

{ "proxyAddress": "0x..." }

Get native account

GET /api/keys/native
Authorization: Bearer <jwt>

Returns:

{ "nativeAccount": "...", "publicKey": "..." }

Get balances

GET /api/user/proxy-balances
Authorization: Bearer <jwt>

Returns:

{
  "space": "12.4500",
  "usdt": "0.00",
  "usdc": "10.00",
  "totalUsd": "11.83"
}

Who runs what — chain vs entities

TL;DR: SPACE OS the chain is a public protocol owned by no single entity. The chain doesn't "go bust". The entities that operate services around the chain (KIS pods, the foundation treasury, Keystone consultancy) are separate legal companies with their own insolvency posture.

There are four distinct things that get called "SPACE OS" colloquially. They have different failure modes + different legal postures:

For Mode 2 users, none of the entities above hold your keys — the keys live exclusively on your device's kisd-local sidecar. The operating company's status (or anyone else's) is irrelevant to whether your wallet keeps working.

Key custody

Proxy and native keys are held in KIS (Key Custody Service), a separate-trust-domain Rust service. Keys never appear in the app API process, in logs, or in backups outside KIS itself. A compromise of the main API does not compromise user funds.

KIS supports four custody modes (see the strategy wiki):

• Mode 0 — single central pod (today's default for net-new users)
• Mode 1 — regional pods (kis-eu-1, kis-us-1) for EU / US data residency and MiCA / GDPR alignment
• Mode 2 — user-hosted (Aether desktop sidecar; Phase 2 — shipped, including all four migration ceremonies)
• Mode 3 — threshold / MPC (Phase 3)

For Mode 1, signing requests route to the regional pod that holds the user's key — there is no cross-region failover (data residency takes precedence over availability). When a user changes jurisdictions or a regulatory shift requires re-domiciling a cohort, the cross-region migration ceremony moves their signing key from one regional pod to another via an X25519 + ChaCha20Poly1305 envelope; the relay (app-api) never sees cleartext.

Mode 2 lifecycle ceremonies

All four Mode-2-touching ceremonies are rotation events — wallet address changes, on-chain history threads through a sweep transaction, no key bytes ever cross the trust boundary. Distinct from cross-region above, which ferries the key but keeps the wallet address.

• Mode 0/1 → Mode 2 ("go sovereign") — operator + auto-orchestrated (/sweep-to); user opts in, funds sweep on-chain to a fresh device-held wallet.
• Mode 2 → Mode 0/1 ("give my keys back") — operator-driven for v1; user-initiated + KYC-gated path queued behind the Aether-cluster bridge. Above-threshold custody-acquisition events produce an append-only counsel-notification audit row for per-jurisdiction reporting.
• Mode 2 ↔ Mode 2 device-to-device (Phase 2.5) — user has new laptop, both devices online; sovereign-to-sovereign sweep brokered by app-api via session-token + 6-digit visualCode rendezvous. Sidecars own all keys; server orchestrates the chain side but cannot sign.
• Restore-from-recovery-phrase — Aether wizard path for the lost-device case. Restores the master from BIP-39; per-wallet keypairs (random-per-wallet under the master, NOT BIP-44-HD-derived) do NOT come back via mnemonic restore alone — explicit caveat copy in the wizard.

For users — what this means for you

For customers (product / Keystone)

Default deployment for net-new accounts on the operating company's hosted services: Mode 0 (central) for low-friction onboarding. Mode 1 enrolment kicks in automatically once a user declares EU or US residency (data-residency requirement). Mode 2 is opt-in; users who pick "sovereign" at signup go through the Aether-desktop setup flow + their keys never leave their device. (None of these touch the chain itself — they're choices about where the signing key for your on-chain wallet lives.)

Keystone deployments (sovereign on-prem for institutions, government, industry — see /keystone): a Keystone tenant gets a dedicated KIS pod in the customer's chosen jurisdiction (EU, US, SG, HK, AU, or on-prem). Mode 1 by default; Mode 2 available for individual users within the tenant who want device-side sovereignty. Mode 3 (TSS) is the institutional default once Phase 3 ships — neither side alone can sign without the other.

Integration paths:

• REST API (above): GET /api/keys/proxy, GET /api/keys/native, GET /api/user/proxy-balances. Keys live in KIS regardless of which mode.
• Aether desktop SDK: window.spaceos.* IPC for app-side signing requests (Mode 2 routes through the local sidecar).
• Proxy-contract pattern (see Architecture): server-side delegated signing for auto-pay, scheduled actions, subscriptions — works alongside Mode 2 so a sovereign user still gets the conveniences.

Support model: Mode 0/1 users get standard support including frozen-account / dispute resolution. Mode 2 users get setup support + the migration-ceremony runbooks (we can help walk a user through restoration or device migration) but not key recovery — by design, we never have the keys.

For compliance — regulatory mapping

Per-jurisdiction custody position summary

The four-mode model maps to different custody classifications across jurisdictions. Detailed analysis lives in KIS_LEGAL_MEMO.md (private; counsel-only) — this table summarises the public-facing position. Throughout, "operating company" = the regulated CASP/VASP entity (currently SPACE OS Ecosystem OÜ in the EU; sister entities elsewhere as we license per jurisdiction); the public chain itself + the foundation + Keystone are NOT the custodian, even on Mode 0/1.

The "outside scope" classification for Mode 2 across all six jurisdictions is the load-bearing legal position the counsel review package covers (T3 — counsel + auditor only). It rests on a 14-item "deliberately do NOT do" contract — the things that, if any SPACE OS entity did them, would reframe Mode 2 as custodial. Most load-bearing among them: no SPACE OS entity ever has the user's mnemonic, master key, or private key bytes at any point — neither the operating company, nor the foundation, nor Keystone, nor any successor.

AMLD6 (EU 2018/1673) — money-laundering directive mapping

MiCA (EU 2023/1114) — markets in crypto-assets

• Title V Authorisation — we operate as CASP (Crypto-Asset Service Provider) for Mode 0/1 custody. EU passporting via home-Member-State authorisation.
• Title III asset-referenced tokens / Title IV e-money tokens — out of scope (we don't issue stablecoins; we route to existing ones).
• Annex I §J — custody of crypto-assets on behalf of clients (Mode 0/1).
• MiCA Article 75 — operational segregation of client crypto-assets from own assets. Implemented via per-region KIS pods + the on-chain Vault separation pattern; client funds are NEVER on company operational wallets.
• Mode 2 — outside MiCA scope per the §9.1 outside-scope analysis.

GDPR (EU 2016/679) — data protection

Audit trail + retention

The audit-trail surfaces a regulator or compliance reviewer can verify:

Counsel handoff cadence: counsel reviews CounselNotificationLog rows on a per-quarter basis (or on-demand for incidents). The endpoint URLs above are linkable; counsel doesn't need direct DB access.

Threat model summary

                   Threat × mode matrix
                   ────────────────────

                            Mode 0    Mode 1   Mode 2    Mode 3
                            ──────    ──────   ──────    ──────
   app-api breach            SAFE      SAFE     SAFE     SAFE
                                (KIS isolated; partial-share-only)

   KIS pod compromise        DRAIN    REGION    N/A     PARTIAL
                                       ONLY              (only one
                                                          share lost)

   Insider exfiltration     SEVERE   SEVERE    NONE    LIMITED
                                       per region

   User device compromise    N/A      N/A     DRAIN     NEEDS
                                                         server
                                                         share too

   Mass phishing             SIG      SIG     DEVICE-   DEVICE-
                                              LOCAL     LOCAL

   Court / sanctions         CAN      CAN     CANNOT    CANNOT
                            comply   comply   comply    comply
                                                         unilaterally

   Single share leaked       N/A      N/A      N/A    INSUFFICIENT
                                                       to sign alone

What we explicitly DON'T protect against (documented for honesty + disclosure adequacy):

• Malware running with your user privilege on Mode 2 — can read your sealed-master sidecar files + brute-force your passphrase offline. Mitigation: Argon2id wrap-key (64MB / 3 iter / 4 lanes) makes brute-force expensive but not impossible. The sealed-mnemonic-on-disk is necessary for recovery; counsel reviews this trade-off explicitly.
• Hardware-level supply-chain attacks — pre-installed malware, compromised firmware. Out of scope; same threat model as any consumer software.
• Social engineering of the user — phishing-delivered visualCodes, fake "support requests" asking for the recovery phrase. Mitigation: explicit workflow copy at every step that says "never enter codes received via email/chat/support".
• The user themselves — losing the recovery phrase, deleting the wallet, sending funds to the wrong address. By design, Mode 2 puts these failure modes on the user; the wizard makes that disclosure verbatim before any wallet is created.

Insurance + liability

The Mode 2 "uninsured" line is verbatim in the mode-selection screen disclosure below. Disclosure adequacy is Q2 in the counsel review package.

Liability allocation:

• Mode 0/1: the operating company (the regulated CASP/VASP entity) bears the operational-failure liability — covered by its insurance + client-asset segregation per MiCA Art. 75 (and equivalents in UK/US/SG/HK/AU). On-chain protocol risk is the user's (e.g. a smart-contract exploit of a 3rd-party DeFi protocol — that's not on us regardless of mode).
• Mode 2: user bears all liability for key custody on the device. The Aether desktop's sidecar is open-source-auditable Rust; the operating company provides the code under permissive license + supports the protocol — but no SPACE OS entity supports the user's individual key recovery, because no entity has the keys.
• Chain-level: the public chain itself has no centralised liable party. Validators run independently under the Open Node Protocol; protocol-level failures (consensus halts, contentious forks) are the same shape as any other public chain — no SLA, no warranty, no cure.

Disclosures + user copy

These strings are copy-locked by tests in the codebase (apps/desktop/test/mode-2-pure.test.mjs::REQUIRED_DISCLOSURES — labels match the verbatim copy gate). Marketing, IR, and product surfaces all use the same wording.

Mode-selection screen (entry point)

MODE 2 — SOVEREIGN

Choose this if you want SPACE OS to never see your wallet keys.

You should know:

• SPACE OS cannot recover your wallet. We never have your keys.
• Lose your mnemonic backup → lose your funds. Permanently.
• Mode 2 wallets are not insured by SPACE OS. Other modes are.

[I understand and want to continue] [Take me back to Mode 1 (recommended)]

Mnemonic-display + three-checkbox gate

The 24-word BIP-39 mnemonic appears in a numbered grid. Below the grid:

Write this down. These 24 words ARE your wallet. Write them down in order, store them somewhere safe and offline. We won't show them to you again unless you unlock the app + ask in Settings.

Three required checkboxes (each individually required before "Continue" enables):

• I have written down my recovery phrase.
• I understand SPACE OS cannot recover my wallet.
• I understand losing my recovery phrase means losing my funds — permanently.

Verify-by-prompt (post-mnemonic)

After "Continue", the wizard picks 3 random word positions and prompts:

What were words #X, #Y and #Z?

If any are wrong, the wizard explicitly lists which positions didn't match. No lock-out — the user can retry as many times as needed (the design intent is "the user actually has the backup before proceeding", not "test their memory").

Restore-from-recovery-phrase

Restoring on a fresh device gets your master key back, but it does NOT recover individual wallet addresses from your old device — those keypairs only exist where you generated them. After restoring, you'll create a new wallet on this device. If your old device still has funds, sweep them off it before you stop using it.

This is the load-bearing UX caveat that distinguishes our restore from "import seed phrase" flows in other wallets — our wallets are random-per-wallet under the master, NOT BIP-44-HD-derived from it.

Phase 2.5 device-to-device migration

Open Aether on the device that holds your existing wallet. Go to Settings → Keys → "Migrate this wallet to a new device" and type the code below.

Only enter this code on your own Aether device that's open in front of you. Never enter codes received via email, chat, or support requests.

Mirror copy on Device A's claim modal:

Compare the wallet address below against the one shown on your OTHER Aether device. They should be identical. If they don't match, hit Cancel — the migration may have been intercepted.

The dual-device address-display is the load-bearing safety check (see Threat model summary). It defends against a network-level address-swap attack regardless of bridge trust.

Compliance verification — how to check our claims

For each load-bearing claim, the source-of-truth file lives in a public or T2 repo. Counsel + auditors can verify without reading the entire codebase.

Verify everything works — operator-runnable test plan: space-os-kis/docs/MODE_2_TEST_PLAN.md. Twelve sections, real commands, real expected outputs, sign-off criteria. The smoke run itself is the artefact that says "this works end-to-end".

Glossary

References