Wallet Architecture Specification

1. Non-Custodial Design Principles

The JIL wallet is built on a single foundational principle: the user controls their assets at all times. JIL cannot unilaterally move, freeze, or seize any user funds. This is not a policy choice - it is an architectural constraint enforced by cryptographic key distribution and on-chain policy rules.

Non-Custodial Control Test

A wallet is non-custodial if and only if: (1) the operator cannot produce a valid transaction signature without the user's active participation, and (2) the user can independently recover and transfer assets without the operator's cooperation. The JIL wallet satisfies both conditions across all three custody lanes.

2. Three MPC Wallet Lanes

The JIL wallet offers three distinct custody configurations ("lanes"), each designed for a different risk profile and regulatory context. Users choose their lane at wallet creation and can upgrade between lanes as their needs evolve.

Lane Selection Logic

Lane selection is explicit and informed. During wallet creation, users are presented with a clear comparison of trade-offs. The default recommendation is Lane B for most users, as it balances sovereignty with recovery options and protection coverage. Users can change lanes at any time - upgrading from A to B requires adding the JIL co-sign shard; downgrading from B to A requires removing it (with a 48-hour cooldown for security).

3. Wrapper Token Model

When users deposit external assets (BTC, ETH, USDC) into the JIL ecosystem, they receive wrapper tokens - jBTC, jETH, jUSDC - that represent a 1:1 claim on the underlying asset held in segregated reserves. Wrapper tokens are the native asset format within the JIL ledger.

Design Principles

• 1:1 backing, always: Every jBTC in circulation is backed by exactly 1 BTC in segregated reserves. No fractional reserves. No rehypothecation. No lending of reserves.
• Segregated reserves: Reserve assets are held in dedicated, single-purpose addresses that are distinct from JIL operational wallets. Reserve addresses are published and independently verifiable.
• Proof-of-reserves: On-chain attestations published at regular intervals (and available on-demand) that prove the reserve balance equals or exceeds the wrapper token supply.
• Not synthetic: Wrapper tokens derive their value from actual underlying assets, not from algorithmic pegs, collateral ratios, or market-making mechanisms.
• Instant unwrap: Users can burn wrapper tokens and receive the underlying asset at any time. No lock-ups. No queues. No exit fees. The only delay is the underlying chain's confirmation time.

Supported Wrapper Tokens

4. Wrapper Lifecycle

The wrapper token lifecycle follows a five-step flow from deposit to exit. Each step is deterministic, auditable, and requires no human intervention beyond the user's initial action.

Mint Process (Detailed)

1. User requests a deposit address from the bridge contract, specifying the asset type (BTC/ETH/USDC).
2. Bridge generates a unique, single-use deposit address linked to the user's JIL wallet address.
3. User sends the underlying asset to the deposit address on the source chain.
4. Bridge monitors the source chain for the deposit transaction and waits for finality (configurable confirmation threshold).
5. Once finality is reached, 14-of-20 validators independently verify the deposit and sign a mint attestation.
6. When the quorum threshold is met, the JIL ledger mints the corresponding wrapper tokens to the user's wallet.
7. A proof-of-reserves update is triggered, reflecting the new reserve balance.

Burn Process (Detailed)

1. User initiates a burn transaction, specifying the wrapper token amount and the destination address on the external chain.
2. Wrapper tokens are burned (destroyed) on the JIL ledger immediately.
3. 14-of-20 validators sign a release attestation authorizing the transfer of underlying assets.
4. Bridge releases the underlying asset from the reserve address to the user's specified destination.
5. Proof-of-reserves is updated to reflect the reduced reserve balance.

5. Liquidity Design

The JIL wallet does not require users to convert between assets or use wrapper tokens for basic operations. Users can hold and transact in native JIL tokens without ever interacting with the wrapper system. Wrapping is optional and is only needed when users want to bring external assets into the JIL ecosystem.

No Forced Conversion

• Users are never required to swap, convert, or wrap assets as a prerequisite for using the wallet.
• JIL tokens can be sent, received, and used for all platform operations without wrapping.
• Wrapper tokens (jBTC, jETH, jUSDC) are an opt-in feature for users who want to bring external assets on-chain.

Optional RFQ Routing

For users who want to trade between assets (e.g., jBTC to jUSDC), the wallet integrates with the JIL RFQ (Request for Quote) system. RFQ routes orders to external liquidity providers who compete to offer the best price. This is entirely optional - no market-making obligation falls on the user or on JIL.

6. Authentication & Passkeys

The JIL wallet replaces traditional password-based authentication with WebAuthn passkeys - hardware-bound, phishing-resistant credentials that use biometric verification (Face ID, fingerprint, Windows Hello) or security keys.

WebAuthn Ceremony

1. Registration: User creates a passkey on their device. The device generates a public-private keypair in a secure enclave (TPM, Secure Enclave, or equivalent). The private key never leaves the device.
2. Authentication: To sign a transaction, the user performs a biometric challenge (face scan, fingerprint). The device signs a challenge with the private key and returns the signature to the wallet.
3. Verification: The wallet verifies the signature against the registered public key. No password, no OTP, no SMS - just a biometric gesture on the user's own device.

Security Properties

Transaction Signing Flow

Every transaction requires explicit user approval via biometric passkey. The flow is: Review transaction details (amount, recipient, fees) - Biometric challenge (Face ID / fingerprint) - MPC co-sign (Lane B: JIL policy engine auto-co-signs if policy rules pass; Lane C: custodian co-signs per SLA) - Submit to ledger.

7. Guardian Recovery

If a user loses access to their device or passkey, the JIL wallet provides a guardian recovery mechanism that restores access without requiring JIL to hold or use any key material on the user's behalf.

How Guardian Recovery Works

1. Setup (before loss): User designates 3-5 trusted guardians (family members, colleagues, or institutional guardians). Each guardian receives a recovery shard encrypted to their own wallet.
2. Initiation (after loss): User contacts guardians and requests recovery. A majority of guardians (e.g., 3-of-5) must independently approve the recovery request from their own wallets.
3. Timelock (24 hours): Once the guardian quorum is reached, a mandatory 24-hour timelock begins. During this period, the original wallet holder can cancel the recovery if it was unauthorized. Notifications are sent to all registered devices and email addresses.
4. Key rotation: After the timelock expires, a new MPC key shard is generated and bound to the user's new device/passkey. The old shard is cryptographically invalidated.

Recovery Guarantees

8. Protection Coverage

Lane B and Lane C wallets include up to $250,000 in per-incident protection coverage, underwritten by a licensed third-party protection coverage provider. This is not government-backed deposit insurance - it is a commercial protection coverage product specifically designed for digital asset custody.

Coverage Scope

Important Disclaimers

Claims Process

1. Incident detection: Automated monitoring detects unauthorized activity or platform compromise. User can also report directly.
2. Investigation: On-chain forensics determine whether the incident falls within coverage scope. All evidence is cryptographically verifiable.
3. Claim submission: Verified claims are submitted to the protection coverage underwriter with on-chain evidence package.
4. Payout: Approved claims are paid directly to the affected user's wallet, up to the $250K+ per-incident limit.

9. Compliance Zones

The JIL wallet integrates with the platform's 13-zone compliance framework, ensuring that every transaction passes a pre-transaction compliance preflight before execution. This allows users to transact freely within their jurisdictional boundaries while maintaining full regulatory compliance.

13 Compliance Zones

Pre-Transaction Compliance Preflight

Before any transaction is submitted to the ledger, the wallet performs a compliance preflight that checks:

• Sanctions screening: Sender and recipient addresses checked against OFAC, EU, UN, and jurisdiction-specific sanctions lists.
• Transaction limits: Per-transaction and velocity limits enforced per zone (e.g., US_FINCEN: $10K CTR threshold).
• Travel rule: For transactions above threshold amounts, originator and beneficiary information is collected and transmitted per FATF Recommendation 16.
• Asset restrictions: Certain assets may be restricted in specific zones (enforced per zone policy).
• Corridor restrictions: Cross-border transfer rules enforced based on sender and recipient zones.

Zero-Knowledge Compliance Proofs

For privacy-sensitive compliance checks, the wallet generates ZK proofs that demonstrate compliance without revealing underlying data. For example: "this transaction is below the $10K CTR threshold" without revealing the exact amount. ZK proofs are generated client-side and verified by validators.

10. Cross-Chain Bridge

The JIL wallet connects to external blockchains through a 14-of-20 validator bridge - the same infrastructure used for wrapper token minting and burning. The bridge is the gateway between the JIL L1 ledger and external chains (Bitcoin, Ethereum, and future integrations).

Bridge Architecture

• 14-of-20 quorum: Any bridge operation (mint, burn, transfer) requires signatures from at least 14 of 20 validators distributed across 13 jurisdictions. This provides Byzantine fault tolerance up to 6 compromised validators.
• Multi-chain support: Bitcoin (native SegWit), Ethereum (ERC-20), and future chains via adapter modules.
• Finality guarantees: Bridge operations wait for source-chain finality (6 confirmations BTC, 32 confirmations ETH) before minting wrapper tokens.
• Reserve segregation: Each asset type has a dedicated reserve address. Reserve addresses are multisig-controlled by the validator set.

Bridge Risk Disclosure

11. Secure Document Vault (SDV)

The JIL wallet includes a Secure Document Vault (SDV) - encrypted, content-addressable document storage that allows users to upload, manage, and selectively share sensitive documents directly from their wallet. SDV is built on Hetzner S3-compatible object storage with client-side encryption and SHA-256 content hashing.

Design Principles

• Client-side encryption: Documents are encrypted on the user's device before upload. The encryption key is derived from the user's MPC key shard. JIL never has access to plaintext document content.
• Content-addressable storage: Each document is stored under its SHA-256 content hash (docs/{sha256}). This ensures deduplication, integrity verification, and tamper detection.
• Zero-knowledge metadata: Document metadata (name, type, size) is stored in the wallet database, encrypted at rest. The storage backend only sees opaque content hashes.
• User sovereignty: Users own and control their documents at all times. Documents can be permanently deleted by the owner. JIL cannot access, read, or share user documents without explicit user authorization.

Supported Document Types

Document Lifecycle

1. Upload: User selects a file from their device. The wallet encrypts the file client-side, computes the SHA-256 hash, and uploads the encrypted blob to SDV.
2. Index: Document metadata (name, type, size, hash) is stored in the wallet database, linked to the user's wallet ID.
3. Share (optional): User can share documents with other users via handle-based access grants (see Section 12).
4. Verify: Any party with access can verify document integrity by comparing the content hash against the stored SHA-256. Tampered documents fail verification.
5. Delete: Owner can permanently delete a document. The encrypted blob is removed from SDV, all access grants are revoked, and metadata is purged.

12. Handle-Based Document Sharing

The JIL wallet uses @handle-based addressing for document sharing. Instead of sharing via wallet addresses or email, users share documents by entering the recipient's JIL handle (e.g., @alice). The handle system resolves to the recipient's wallet, and access is granted with configurable permissions and expiration.

Sharing Flow

1. Select document: Owner chooses a document from their vault to share.
2. Enter handle: Owner enters the recipient's @handle. The system resolves the handle to a verified user account.
3. Set access type: Owner chooses between View (read-only, no download) and Download (full access to retrieve the decrypted file).
4. Set expiration: Owner configures the access duration:
   • 1 hour - for time-sensitive verifications
   • 24 hours - for standard document review
   • 7 days - for due diligence periods
   • 30 days - for ongoing business relationships
   • Unlimited - permanent access until explicitly revoked
5. Grant access: A share record is created. The recipient sees the document in their "Shared With Me" tab with the granted permissions.

Access Control

Use Cases

• KYC document sharing: Share identity documents with a compliance officer's @handle for verification, with 24-hour expiration.
• Institutional due diligence: Share fund documentation with a counterparty's @handle for 7-day review period.
• Regulatory filing: Share compliance attestations with a regulator's @handle with unlimited access for ongoing oversight.
• Proof of reserves: Share audit reports with investors' @handles with 30-day access windows.

13. Document API

The wallet exposes a RESTful API for programmatic document management. All endpoints require JWT authentication and operate within the user's own document scope.

Upload Request

POST /documents/upload
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "filename": "passport_scan.pdf",
  "mimeType": "application/pdf",
  "content": "<base64-encoded-data>"
}

Response:
{
  "id": "doc_a1b2c3d4",
  "sha256": "e3b0c44298fc1c149afb...",
  "filename": "passport_scan.pdf",
  "size": 245760,
  "createdAt": "2026-03-02T10:30:00Z"
}

Share Request

POST /documents/doc_a1b2c3d4/share
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "handle": "@alice",
  "accessType": "view",
  "expiresIn": "24h"
}

Response:
{
  "shareId": "share_x1y2z3",
  "handle": "@alice",
  "accessType": "view",
  "expiresAt": "2026-03-03T10:30:00Z"
}

14. Implementation Roadmap

15. Connected Ecosystem

The JIL Wallet integrates seamlessly with every component of the JIL Sovereign platform.