JIL Token Acquisition Flows
Three methods for users to acquire JIL tokens: MetaMask holder claim, email invite claim, and v1/v2 token swap. Each method leads to full platform access on JIL L1.
Holder Claim (MetaMask Self-Claim)
User proves Ethereum address ownership via MetaMask signature to claim pre-allocated JIL tokens. Services: web-wallet (nginx:3003), wallet-api (:8002), ledger-service (:8001). Kafka topic: HOLDER_CLAIMED.
MetaMask Connect
User connects MetaMask wallet via eth_requestAccounts. Frontend (web-wallet ClaimPage) sends request to wallet-api.
POST /claim/challenge - wallet-api :8002 returns nonce + message for signing.MetaMask personal_sign
User signs challenge message (EIP-191 signature). wallet-api verifies via ethers.verifyMessage() and looks up the claim in wallet_claims.
POST /claim/verify - Recovers signer address, matches against claim record in PostgreSQL.L1 Registration
Creates user and account records in wallet_users and wallet_accounts. Registers account on JIL L1 ledger via ledger-service :8001.
HOLDER_CLAIMED published. Notifies downstream services.JWT Session Issued
wallet-api issues JWT session and sets jil_session cookie. User redirected to dashboard with balance visible and claim complete.
Note: The wallet_claims table must be pre-seeded with eligible Ethereum addresses and their allocated JIL amounts before users can claim. The ethers.verifyMessage() call recovers the signer address from the EIP-191 signature and matches it against the claim record.
Email Invite Claim
Admin seeds claim allocations and sends email invites. Recipients claim tokens via a unique link. Services: web-wallet (nginx:3003), wallet-api (:8002). Endpoints: POST /claim/seed, POST /claim/send-invites, POST /claim/email.
Seed Claim Allocations
Admin calls POST /claim/seed with addresses and amounts. wallet-api generates claim_token UUIDs and stores them in wallet_claims with status pending.
Email Dispatch
Admin triggers POST /claim/send-invites. wallet-api sends invite emails containing unique claim links: /claim?claim_token=xxx. User receives email with invite link.
Holder Claims via Link
User clicks invite link, opens web-wallet ClaimPage with ?claim_token=xxx. Fills email + password form. Submits POST /claim/email with claim_token, email, password.
Verify Token and Create Account
PostgreSQL verifies claim_token (SELECT WHERE status = 'pending'). Creates user and account records. Updates claim status to claimed. Issues JWT session + cookie.
Dashboard Access
User redirected to web-wallet dashboard with balance visible and email-based auth active. No MetaMask required for this method.
Note: Email invite claims do not require MetaMask. The user creates a password-based account. The claim_token is a one-time-use UUID that becomes invalid after claiming. Admin endpoints (/claim/seed, /claim/send-invites) require the JIL_ADMIN_KEY header.
Token Swap (v1/v2 to v3)
Holders of deprecated JIL v1 (JIL.ai) or v2 tokens swap 1:1 for the current v3 JIL token on Ethereum mainnet. v1 to v3 swap: 0xfCAa...dcC1. v2 to v3 swap: 0x26D9...CA25. Deadline: May 1, 2026.
Connect Wallet and Detect Holdings
User visits /token-swap and connects MetaMask. Frontend auto-detects balances by calling balanceOf() on v1 (0xFa71...8dD4) and v2 (0x291C...58) contracts. Selects correct swap path.
Approve Spending
MetaMask popup for approve(swapContract, amount). Old token contract grants the swap contract transferFrom allowance.
JILTokenSwap.swap()
User confirms swap TX in MetaMask. Swap contract calls transferFrom on old tokens (held by swap contract) and transfers v3 JIL (0x9347...71e8) to user.
Bridge to L1
v3 JIL ERC-20 in user wallet on Ethereum. User can optionally bridge via JILBridge.sol - lock ERC-20 on Ethereum, mint jJIL on L1 via 14-of-20 validator bridge. Full platform access on jil-mainnet-1.
Note: The swap contracts hold a finite pool of v3 JIL tokens (100M each, funded at deploy). Old tokens are not burned - they are transferred to and held by the swap contract. The swap deadline is May 1, 2026. After that date, the swap() function reverts. The deployer can top up swap contracts anytime by transferring additional v3 JIL directly.
Method Comparison
| Method | Requires MetaMask | Auth Method | Pre-Requisite | Result |
|---|---|---|---|---|
| Holder Claim | Yes | personal_sign |
ETH address in wallet_claims | L1 account + JWT session |
| Email Invite | No | email + password |
Valid claim_token from invite | L1 account + JWT session |
| Token Swap | Yes | ERC-20 approve + swap |
v1 or v2 JIL token balance | v3 JIL ERC-20 (bridgeable) |
Three paths to JIL. One platform.
Whether you are a MetaMask holder, an email invite recipient, or a v1/v2 token holder - every path leads to full access on the JIL Sovereign platform.