Account Abstraction (AA) Protocol

01 Account Architecture Overview 계정 구조 개요

When a user signs up via Google OAuth or email, the WebXcom platform automatically provisions the full blockchain identity stack — no seed phrases, no wallet extensions, no Web3 knowledge required from the user. 사용자가 Google OAuth 또는 이메일로 가입하면, WebXcom 플랫폼은 전체 블록체인 신원 스택을 자동으로 프로비저닝합니다 — 시드 구문, 지갑 확장 프로그램, Web3 지식이 사용자에게 일절 필요하지 않습니다.

The complete account hierarchy: 전체 계정 계층 구조:

Google / Email Account
    └── user_uuid (DB Primary Key)
         └── owner_eoa  (Platform-generated EOA, private key encrypted in DB)
              └── SimpleAccount  (AA Wallet, Counterfactual Address via CREATE2)
                   └── content_address  (Slot/Deck address)

Counterfactual Address (CREATE2) — The AA wallet address is computed deterministically from the factory address, the owner EOA address, and a salt value. This means the address is known before the contract is actually deployed on-chain. The first transaction that touches this wallet will trigger deployment automatically via the initCode field of the UserOperation. 카운터팩추얼 주소 (CREATE2) — AA 지갑 주소는 팩토리 주소, owner EOA 주소, salt 값으로 결정론적으로 계산됩니다. 즉 컨트랙트가 온체인에 실제 배포되기 전에 주소를 미리 알 수 있습니다. 이 지갑에 대한 첫 번째 트랜잭션이 UserOperation의 initCode 필드를 통해 자동으로 배포를 트리거합니다.

02 AA Wallet & Slot Address / Ownership AA 지갑과 Slot(Deck) 주소 및 소유권

In the WebXcom system, the AA wallet address is the user's canonical on-chain identity. When the SimpleAccount executes a call on any contract, msg.sender is the SimpleAccount's address — not the owner EOA. WebXcom 시스템에서 AA 지갑 주소는 사용자의 정규 온체인 신원입니다. SimpleAccount가 컨트랙트를 호출하면, msg.sender는 owner EOA가 아닌 SimpleAccount의 주소입니다.

Each slot (deck) also has its own dedicated AA wallet called content_address. This is computed with a different salt (C_SALT) using the same owner EOA, creating a separate SimpleAccount for content-level operations. 각 슬롯(덱)도 content_address라는 전용 AA 지갑을 가집니다. 동일한 owner EOA에 다른 salt(C_SALT)를 사용하여 계산되며, 콘텐츠 수준의 작업을 위한 별도의 SimpleAccount를 생성합니다.

Ownership assignment — When a slot is purchased or minted, the dex contract's buy_slot(aaAddress, slot, ...) function registers the user's AA wallet address as the slot owner. On-chain ownership is determined solely by what is recorded in the dex contract. 소유권 할당 — 슬롯이 구매 또는 민팅되면, dex 컨트랙트의 buy_slot(aaAddress, slot, ...) 함수가 사용자의 AA 지갑 주소를 슬롯 소유자로 등록합니다. 온체인 소유권은 dex 컨트랙트에 기록된 내용에 의해서만 결정됩니다.

// On-chain ownership check (Solidity)
// dex contract stores: mapping(uint256 => address) public slotOwner;

function buy_slot(address aaAddress, uint256 slot, ...) external {
    // ... payment logic ...
    slotOwner[slot] = aaAddress;  // User's SimpleAccount(W_SALT)
}

// When querying ownership:
// slotOwner[slot] == user's AA wallet address (SimpleAccount)

// Address computation (off-chain)
// Both addresses are derived from the SAME owner EOA but with different salts

const userAAAddress    = computeAddress(factory, ownerEoa, W_SALT);  // Main wallet
const contentAddress   = computeAddress(factory, ownerEoa, C_SALT);  // Slot/Deck wallet

// CREATE2: address = keccak256(0xff ++ factory ++ salt ++ keccak256(initCode))[12:]

03 Slot Transfer Slot 트랜스퍼

Slot ownership transfer is executed as an AA UserOperation. The platform handles the entire flow — the user simply initiates the request, and the platform signs and submits the on-chain transaction on their behalf. 슬롯 소유권 이전은 AA UserOperation으로 실행됩니다. 플랫폼이 전체 플로우를 처리하며 — 사용자는 요청만 시작하면, 플랫폼이 대신 서명하고 온체인 트랜잭션을 제출합니다.

Server-to-server flow — The request travels from A서버 (OAUTH/NestJS) via gRPC to B서버 (Oauth-blockchain), which constructs and submits the AA UserOperation. 서버 간 플로우 — 요청은 A서버(OAUTH/NestJS)에서 gRPC를 통해 B서버(Oauth-blockchain)로 전달되며, B서버가 AA UserOperation을 구성하고 제출합니다.

// Request body
POST /idex-platform/exchange_token_owner
{
  "state": "session-state-token",
  "cu_id": "content-unit-id",
  "from_uuid": "sender-user-uuid",
  "to_uuid": "receiver-user-uuid",
  "meta_idx": 42
}

The transfer flow end-to-end: 엔드투엔드 트랜스퍼 플로우:

User requests transfer (from_uuid → to_uuid)
    ↓
A서버: /idex-platform/exchange_token_owner
    ↓ gRPC
B서버: dapp_exchange_own_initPermissionSelf
    ↓
AA UserOperation: SimpleAccount.execute(dex.init_self(aaAddress, slot, newOwnerAAAddress))
    ↓ EntryPoint.handleOps
On-chain: Slot ownership changed

04 Gas Sponsorship — VerifyingPaymaster 가스비 대납 — VerifyingPaymaster

Users on the WebXcom platform never pay gas fees. Every on-chain operation — slot purchases, transfers, ownership changes — is sponsored by the platform's VerifyingPaymaster. This is a core design decision that enables a Web2-like user experience on Web3 infrastructure. WebXcom 플랫폼의 사용자는 가스비를 절대 부담하지 않습니다. 슬롯 구매, 트랜스퍼, 소유권 변경 등 모든 온체인 작업은 플랫폼의 VerifyingPaymaster가 대납합니다. 이는 Web3 인프라 위에서 Web2와 같은 사용자 경험을 제공하기 위한 핵심 설계 결정입니다.

The complete UserOperation lifecycle: UserOperation의 전체 라이프사이클:

executeViaAA()
  1. Build UserOperation
     ├── sender       = aaAddress (SimpleAccount)
     ├── initCode     = factory.createAccount(owner, salt)  // only if first tx
     ├── callData     = SimpleAccount.execute(target, value, data)
     ├── callGasLimit / verificationGasLimit / preVerificationGas
     └── paymasterAndData = (empty, filled in step 2)

  2. signPaymasterData()
     ├── Platform signs: hash(userOp, validUntil, validAfter)
     ├── validUntil   = now + 5 minutes
     ├── validAfter   = now
     └── paymasterAndData = paymaster + validUntil + validAfter + signature

  3. signUserOperation()
     ├── owner_eoa signs the full UserOp hash
     └── signature = owner_eoa.sign(entryPoint.getUserOpHash(userOp))

  4. submitUserOperation()
     └── EntryPoint.handleOps([userOp], beneficiary)
              ↓
         EntryPoint validates Paymaster signature  ✓
         EntryPoint validates owner signature       ✓
         SimpleAccount.execute() runs               ✓
         Gas deducted from Paymaster's EntryPoint deposit

// initCode construction (first tx only)
const initCode = ethers.utils.solidityPack(
  ['address', 'bytes'],
  [
    FACTORY_ADDRESS,
    factory.interface.encodeFunctionData('createAccount', [ownerEoa, salt])
  ]
);

// Subsequent transactions
const initCode = '0x';  // Contract already deployed

05 PIN & XOR 3-of-3 Key Architecture PIN과 XOR 3-of-3 키 분산 보관

The PIN is a user-facing security mechanism that bridges the gap between Web2 familiarity and Web3 key management. It is not the private key of the AA wallet. Rather, the PIN is one of three cryptographic shares required to reconstruct the owner EOA private key — using an XOR 3-of-3 threshold scheme. No single party ever holds the complete private key. PIN은 Web2의 친숙함과 Web3 키 관리 사이의 간극을 메우는 사용자 대면 보안 메커니즘입니다. AA 지갑의 프라이빗키가 아닙니다. PIN은 XOR 3-of-3 임계값 방식으로 owner EOA 프라이빗키를 복원하기 위해 필요한 세 개의 암호학적 조각 중 하나입니다. 어떤 단일 주체도 완전한 프라이빗키를 단독으로 보유하지 않습니다.

5-1. XOR 3-of-3 Key Splitting Overview 5-1. XOR 3-of-3 키 분할 개요

When a PIN wallet is created, the owner EOA private key is split into three shares via bitwise XOR. All three shares must be combined to recover the original key: PIN 지갑이 생성될 때, owner EOA 프라이빗키는 비트 XOR을 통해 세 개의 조각으로 분할됩니다. 원래 키를 복원하려면 세 조각 모두 필요합니다:

fullPrivateKey  =  share_pin  ⊕  share_server  ⊕  share_user

share_pin    :  PBKDF2-SHA256(pin_hash, 'webxcom-pin-salt', 100_000 iter, 32 bytes)
                — derived on-demand from user's PIN; never stored anywhere
share_server :  crypto.randomBytes(32)
                — stored in B서버 DB (Key table, b_key column)
share_user   :  fullPrivateKey ⊕ share_pin ⊕ share_server
                — returned to client; stored in Rails encrypted session cookie

5-2. PIN Registration Flow 5-2. PIN 등록 플로우

PIN registration happens during account signup. The platform creates the AA wallet and XOR-splits the private key in a single atomic operation. PIN 등록은 계정 가입 시 발생합니다. 플랫폼은 단일 원자적 연산으로 AA 지갑을 생성하고 프라이빗키를 XOR 분할합니다.

// webxcom → A서버
POST /v1/pin/register
{
  "user_uuid": 12345,
  "pin_hash":  "SHA-256(pin + pin_salt)",   // plaintext PIN never transmitted
  "pin_salt":  "<64-char hex>"
}

// A서버 → B서버 (gRPC)
CreateWalletWithPin({ account_idx, pin_hash })

// B서버 internal:
//   1. Ethers.Wallet.createRandom()  → mnemonic, privateKey, ownerEoaAddress
//   2. AAService.computeAAAddress()  → aaAddress (counterfactual, CREATE2)
//   3. splitKeyXor3(privateKey, pin_hash):
//        share_pin    = PBKDF2(pin_hash, 'webxcom-pin-salt', 100000, 32, sha256)
//        share_server = crypto.randomBytes(32)
//        share_user   = privateKey ⊕ share_pin ⊕ share_server
//   4. DB transaction (atomic):
//        Wallet.create({ account_idx, address: aaAddress, owner_eoa, wallet_type: 'AA' })
//        Key.create({ a_key: UUID(account_idx, U_SALT),       b_key: share_server })
//        Key.create({ a_key: UUID(account_idx, U_SALT)+'_MN', b_key: AES256(mnemonic) })
//   5. privateKey buffer wiped (Buffer.fill(0))

// A서버 response → webxcom
{
  "success": true,
  "data": [{
    "address":       "0xAA...",          // SimpleAccount address
    "mnemonic":      "<AES-256-CTR encrypted>",
    "key_share_user": "0x..."            // share_user — stored in Rails session
  }]
}

5-3. Transaction Signing Flow (PIN Verification) 5-3. 트랜잭션 서명 플로우 (PIN 검증)

Every sensitive operation (transfer, ownership change, etc.) requires the user to enter their PIN. The three shares are combined in-memory inside B서버 to reconstruct the private key for signing, then immediately wiped. 모든 민감한 작업(이체, 소유권 변경 등)은 사용자 PIN 입력이 필요합니다. 세 조각은 B서버 내부 메모리에서 합산되어 서명용 프라이빗키를 복원하며, 즉시 초기화됩니다.

// webxcom → A서버
POST /v1/pin/verify
{
  "user_uuid":     12345,
  "pin_hash":      "SHA-256(entered_pin + session[:pin_salt])",
  "pin_salt":      "session[:pin_salt]",
  "key_share_user": "session[:key_share_user]"
}

// A서버 → B서버 (gRPC)
ExecutePinTransaction({ account_idx, pin_hash, key_share_user, tx_data })

// B서버 internal:
//   1. share_server = Key.findOne({ a_key: UUID(account_idx, U_SALT) }).b_key
//   2. restoreKeyXor3(key_share_user, pin_hash, share_server):
//        share_pin  = PBKDF2(pin_hash, 'webxcom-pin-salt', 100000, 32, sha256)
//        fullKey    = share_user ⊕ share_pin ⊕ share_server
//   3. Sign UserOperation with fullKey
//   4. fullKey buffer wiped (Buffer.fill(0))
//   5. Submit via EntryPoint

5-4. PIN Reset via Mnemonic 5-4. 니모닉으로 PIN 재설정

If the user remembers their mnemonic (12-word recovery phrase) but forgets their PIN, they can reset the PIN without changing the owner EOA. The existing owner EOA private key is re-split with the new PIN hash. 사용자가 니모닉(12단어 복구 구문)을 기억하지만 PIN을 잊어버린 경우, owner EOA를 변경하지 않고 PIN을 재설정할 수 있습니다. 기존 owner EOA 프라이빗키가 새 PIN 해시로 재분할됩니다.

// POST /v1/pin/reset
{
  "user_uuid":    12345,
  "mnemonic":     "word1 word2 ... word12",  // user's recovery phrase
  "new_pin_hash": "SHA-256(new_pin + new_salt)",
  "new_pin_salt": "<64-char hex>"
}

// B서버 internal (verifyMnemonic):
//   1. Decrypt stored mnemonic (Key[UUID_MN]) → compare with user input
//   2. Derive privateKey from mnemonic (Ethers.fromMnemonic)
//   3. splitKeyXor3(privateKey, new_pin_hash) → new share_server, new share_user
//   4. Key[UUID].b_key ← new share_server
//   5. Return new key_share_user (owner EOA unchanged)

5-5. Why a PIN instead of seed phrases? 5-5. 왜 시드 구문 대신 PIN인가?

06 Private Key Rotation — Email Recovery Flow 프라이빗키 교체 — 이메일 복구 플로우

One of the most powerful properties of Account Abstraction is the ability to rotate the signing key without changing the wallet address. Since the AA wallet is a smart contract (SimpleAccount), its owner field can be updated to point to a new EOA — while the contract address (and thus the on-chain identity) remains permanent. 계정추상화의 가장 강력한 속성 중 하나는 지갑 주소를 변경하지 않고 서명 키를 교체할 수 있다는 것입니다. AA 지갑은 스마트 컨트랙트(SimpleAccount)이므로, owner 필드를 새 EOA를 가리키도록 업데이트할 수 있습니다 — 컨트랙트 주소(즉 온체인 신원)는 영구적으로 유지됩니다.

Key rotation is triggered when the user can no longer recover their PIN via mnemonic (lost both PIN and mnemonic, or suspects key compromise). The user verifies identity via email, and the platform generates a completely new owner EOA, rotates ownership on-chain, and XOR-re-splits the new key with the new PIN. 키 교체는 사용자가 니모닉으로도 PIN을 복구할 수 없는 경우(PIN과 니모닉 모두 분실, 또는 키 유출 의심)에 트리거됩니다. 사용자가 이메일로 신원 확인을 완료하면, 플랫폼은 완전히 새로운 owner EOA를 생성하고, 온체인 소유권을 교체하며, 새 PIN으로 새 키를 XOR 재분할합니다.

This calls the B서버 gRPC service: 이는 B서버 gRPC 서비스를 호출합니다:

// webxcom → A서버 (after email verification)
POST /v1/pin/recover
{
  "user_uuid":    12345,
  "pin_hash":     "SHA-256(new_pin + new_salt)",
  "pin_salt":     "<64-char hex>"
}

// A서버 → B서버 (gRPC)
RecoverWalletKeyWithPin({ account_idx, pin_hash })

Step-by-step breakdown inside B서버 (recover_wallet_key_with_pin): B서버 내부 단계별 상세 설명 (recover_wallet_key_with_pin):

The on-chain state before and after rotation: 교체 전후의 온체인 상태:

// Before rotation
SimpleAccount (0xAA11...):
  owner = 0xOLD_EOA_111...  (old signing key — reconstructed via old XOR shares)

// After rotation
SimpleAccount (0xAA11...):              ← ADDRESS UNCHANGED
  owner = 0xNEW_EOA_222...  (new signing key — new XOR 3-of-3 split)

// B서버 DB after rotation
Key[UUID].b_key        = new_share_server  (old share_server overwritten)
Key[UUID_MN].b_key     = AES256(new_mnemonic)
Wallet.owner_eoa       = 0xNEW_EOA_222...

// Browser session after rotation
session[:key_share_user] = new_share_user  (old share_user invalidated)
session[:pin_hash]        = new_pin_hash

// All on-chain references to 0xAA11... remain valid
// Slot ownership, token balances, approvals — all preserved

Recovery Options Summary 복구 옵션 요약