Cross-App Character Portability Through Wallet-Based Ownership Checks

Abstract

Portable character ownership is a practical lock-in barrier for product suites, and in Realbits it is a core design axis rather than a UX novelty. The proposed mechanism is straightforward: connect a wallet once, validate a signature-based ownership proof, and then use read-only contract state as the canonical entitlement source for character visibility across every app surface. This article argues that this is not only sufficient for first-order cross-app reuse, but operationally superior to per-app entitlement databases because it preserves a single source of truth and keeps creator inventory semantics stable across app distribution boundaries.

The analysis combines Realbits implementation details with protocol-level standards and external research. Token portability studies emphasize that portability is not automatic and depends on both interoperability and operational assumptions, especially around transfer paths and trust boundaries [S1]. ERC-721 and related signing standards define practical primitives for ownership and wallet identity, while Realbits already has on-chain and mobile-facing touchpoints suitable for this architecture [S5][S6][S11]. We assess the design as an engineering problem with three layers: identity establishment, entitlement verification, and cross-app propagation. We then list limits and the repository-specific work needed for robust production behavior.

Realbits Context

Realbits already aligns with a provider-first model: reusable assets (model packs and character cards) should be shared, while apps act as distribution surfaces. In that architecture, wallet-based ownership is the natural join key between creator-side asset publication and user-side runtime availability.

In the web package, the on-chain helper already performs a narrow but valuable check: it validates configured contract address, checks transaction receipt status when provided, queries ownerOf, and compares stored metadata URI against an expected pointer [S5]. That means the core idea is present: ownership entitlement is validated directly against chain state at lookup time, not inferred from external profile state. The same pattern is a strong foundation for cross-app portability because it can be reused by all surfaces with minimal contract assumptions.

The app stack also includes React Query hooks for wallet-oriented data concerns (balance and escrow workflows), indicating the project is already using a cache-keyed, query-first data flow in the web plane [S13][S14]. On the platform side, Flutter apps are split by vertical and distribution surface, making centralized entitlement resolution more important than ever. If portability is expressed as token ownership, the desktop/web/mobile surfaces can converge on one set of checks and one shared event schema, while retaining app-local UI.

From a systems perspective, the migration from app-specific entitlement to shared ownership checks is not a UI refactor, it is a state model change. A character card should be considered a portable object if it is associated with a transferable asset proof and a manifest that can be resolved in any authorized app context.

Related Work

The closest conceptual predecessor is token portability research, which frames portability as a property affected by transfer paths and ecosystem support, not merely token type [S1]. That research warns against treating chain portability as a binary property and helps justify Realbits’ first step: optimize for robust same-chain portability in phase one before speculative cross-chain abstractions.

Cross-chain token standards work introduces further caution. Comparative surveys show that even where inter-chain token models exist, they diverge in trust model, message passing model, and failure semantics [S2]. For Realbits this means an important design limit: ownership portability can be implemented safely within one chain configuration first, while cross-chain character roaming should be treated as a separate roadmap item. The repository’s current chain mapping around Polygon mainnet and testnet is consistent with this incremental stance.

Wallet identity literature and standards also inform sequencing. Self-sovereign identity research points out that portability and control are constrained by onboarding friction, governance, and the need for careful cryptographic UX [S4]. ERC-4361 directly addresses this by standardizing a nonceed, chain-scoped message format for off-chain session establishment, with explicit replay and verification considerations [S11]. This is stronger than a raw raw-signature prompt and reduces ambiguity about what a wallet signature proves.

NFT literature adds a hard requirement on metadata handling. The study on NFT-to-asset connection fragility reports that on-chain ownership does not always guarantee usable off-chain assets because pointers can fail or drift [S3]. For Realbits, this means token ownership alone is not enough for portability safety; tokenURI integrity and content resolution become part of entitlement. In practice this supports dual checks: ownerOf must match requested wallet, and metadata pointer should either resolve to expected schema or fail gracefully.

At implementation level, existing Ethereum tooling already gives us robust primitives. ERC-721 defines ownerOf and tokenURI semantics for chain-level proofs [S5]. EIP-1193 defines provider events like accountsChanged and chainChanged, which become critical for session updates when a wallet reconnects or switches networks [S6]. Ethers v6 provides contract and provider call semantics needed to implement these checks with low ceremony [S7][S8], and hashing utilities support signature recovery paths [S9]. On the delivery plane, Next.js route handlers are now the canonical route primitive for API endpoints in App Router contexts [S12], and React Query provides explicit caching semantics for per-address ownership data in a way that can be tuned by staleness and refetch policy [S13][S14].

Architecture Analysis

The architecture can be decomposed into four coordinated components.

1. Wallet session and identity proof The session starts with wallet connection and cryptographic proof of possession. The system should avoid trusting address strings alone and should instead verify a signed payload with explicit domain, chain, and nonce context [S11][S9]. Using a standardized payload reduces replay risk and reduces integration variance across wallet providers. For mobile, this is where WalletConnect-style wallet access is most relevant, because Flutter surfaces typically need a connector rather than direct browser provider injection [S15].

2. On-chain entitlement verification Once identity is established, entitlement checks should call ownerOf(tokenId) on the CharacterNFT contract and compare result with normalized wallet address. This gives deterministic proof for ownership at chain height when checked. A second check against tokenURI(tokenId) is advised to detect off-chain asset split-brain conditions where ownership moved without corresponding metadata continuity [S3]. Using ethers contract reads for these calls follows official contract call patterns and keeps logic deterministic [S8]. The current web helper already includes receipt checks when a tx hash is provided, which can be retained as a stricter path for mint verification workflows.

3. Shared ownership index and scope partitioning The central challenge is not query accuracy but serving shape and freshness across apps. A shared endpoint in packages/web can return a normalized list of owned characters and their status in one query. This endpoint can be represented by address + chainId, with optional fields for knownCharacterIds, ownedCharacterIds, and invalidProofs.

The data path should be explicit:

• Request: wallet address + chainId + appId
• Step A: validate session signature freshness and nonce; reject stale signatures
• Step B: enumerate owned character records from backend metadata store or manifest index
• Step C: for each candidate, run ownerOf/tokenURI checks for chain-confirmed mapping
• Step D: attach app-specific visibility metadata for that appId
• Step E: return deterministic response with TTL and proofVersion

Ethers provider calls used in this stage should be short-lived and network-aware. RPC call failures and chain congestion are expected operationally; the endpoint should degrade to cache-aware mode with explicit stale flag rather than hard fail user journeys.

1. App-level consumption and cache policy Mobile and web apps should treat ownership as query state with controlled staleness. React Query options make this easier because query keys already encode address inputs and cache invalidation is explicit [S13]. For example, queries for owned characters can use address-scoped keys and short default staleness windows so transfers are noticed quickly without overloading chains. Mutation paths (for wallet connect/disconnect events) should trigger cache invalidation or refresh.

Two lifecycle events from the wallet provider should be first-class in both web and mobile:

• accountsChanged: drop old cache state, re-derive ownership for the new account immediately [S6]
• chainChanged: invalidate all ownership data and force re-check because ownerOf semantics can change under chain mismatch [S6]

Without these event hooks, cross-app portability becomes brittle because session state can silently diverge from chain context. App surfaces should never assume “same account, same entitlement” across chain changes.

1. Character portability contract between apps For portability to be reliable, every app must interpret character records the same way. A shared contract is required in naming and filtering rules: what constitutes “available,” “owned,” “revoked,” and “cross-app candidate.” Because Realbits runs multiple apps with different themes, the shared layer should return a normalized visibility field and a per-app origin_app_id for analytics and onboarding nudges. This enables explicit behavior like “show your astrology character in chat-hub” without trusting each app to map ownership semantics independently.

2. Data integrity and abuse resistance The strongest anti-forgery posture combines wallet signatures for session proof and contract reads for entitlement. Signature checks should be limited to login and sensitive operations; long-lived sessions should rotate nonce/issuedAt and have short inactivity windows. On-chain checks should avoid trust in mutable metadata alone, because NFT metadata can be unreliable despite ownership proof [S3]. A safe default is to accept ownership with warning when metadata cannot be dereferenced, then hide unsafe content until a secondary sync restores confidence.

3. Operational path for Next.js and mobile parity Route handlers in the web layer can provide a shared /api/characters/owned-by/:address endpoint with deterministic response contracts. Next.js confirms route handlers are the app-native way to expose this in the App Router, with support for GET caching strategy control and clean parameterization [S12]. Mobile clients then consume that endpoint as a unified service boundary while preserving local runtime independence.

Limitations

First, ownership checks remain chain-specific unless explicitly extended. Cross-chain portability is a separate design axis with different security and trust assumptions, and forcing it early can increase blast radius [S2].

Second, metadata integrity is not guaranteed by ERC-721 ownership alone. The NFT-to-asset fragility literature shows that pointer drift and availability failures are material risks [S3]. This means Realbits must treat metadata validation as part of entitlement confidence, not a post-hoc feature.

Third, wallet UX remains a friction point. SSDI research notes broad deployment barriers in usability, key management, and governance context even when protocol designs are sound [S4]. In practice, onboarding failure for wallet login can block the portability value proposition even when chain checks are perfect.

Fourth, performance depends on RPC availability and index latency. Even with optimized calls, provider outages, rate limits, and finality windows can delay entitlement updates. Caching helps UX but can create short periods of stale visibility.

Finally, revocation semantics are tricky. If a character is transferred out and then into another wallet, any app-level cache must react quickly through event invalidation or short TTLs; stale “owned” state is a correctness bug and a trust risk.

Implications for This Repository

Realbits should implement portability as a shared entitlement service rather than app-specific behavior. A concrete roadmap is below.

1. Add a canonical ownership endpoint in packages/web Expose a server route for owned character lookup and enforce one query contract across all surfaces. Route handlers are the right primitive in the current Next stack [S12]. Use short TTLs and explicit freshness fields to avoid stale ownership assumptions.

2. Standardize session and challenge format Use SIWE-style fields such as chainId, nonce, issuedAt, and domain in the signing challenge [S11]. This turns wallet login into a reproducible protocol and avoids ad-hoc signature formats across native and web surfaces.

3. Expand on-chain service with failure-aware semantics Keep existing ownerOf/tokenURI checks [S5] but add structured failure categories: no ownership, metadata mismatch, unresolved URI, rpc timeout, chain mismatch. This is essential for deterministic debugging and for mobile reconciliation.

4. Unify wallet event propagation Consume provider account and chain change signals [S6] in web and route wallet events consistently in mobile. If either signal changes, invalidate cached ownership and trigger a re-check before showing “owned” sections.

5. Tune React Query usage for shared state Use address-chain scoped keys and controlled staleTime/garbage collection to balance correctness and battery/data usage [S13][S14]. For mobile, aggressive staleness can reduce load but must not hide ownership revocation.

6. Tie portability metrics to source-of-truth events Emit explicit events for wallet_sign_in, owned_character_used, and cross_app_install_with_shared_character with app_id and chain metadata. These events should rely on the shared endpoint outputs, not local heuristics.

7. Enforce metadata confidence policy If tokenURI resolution fails, show the character as owned for navigation context but mark runtime availability as restricted until resolution is revalidated. This balances continuity with safety and reflects the off-chain fragility findings [S3].

This architecture keeps Realbits’ mobile strategy intact: one core provider model, multiple surfaces, and ownership as a portable entitlement primitive rather than a per-app permission table. It is still strict ownership, still lightweight for users, and measurable enough to iterate with telemetry.

References

• S1: https://arxiv.org/abs/2005.07461
• S2: https://arxiv.org/abs/2603.06388
• S3: https://arxiv.org/abs/2212.11181
• S4: https://arxiv.org/abs/2603.06896
• S5: https://eips.ethereum.org/EIPS/eip-721
• S6: https://eips.ethereum.org/EIPS/eip-1193
• S7: https://docs.ethers.org/v6/api/providers/
• S8: https://docs.ethers.org/v6/api/contract/
• S9: https://docs.ethers.org/v6/api/hashing/
• S10: https://docs.openzeppelin.com/contracts/5.x/api/token/erc721
• S11: https://eips.ethereum.org/EIPS/eip-4361
• S12: https://nextjs.org/docs/app/getting-started/route-handlers
• S13: https://tanstack.com/query/latest/docs/framework/react/reference/useQuery
• S14: https://tanstack.com/query/latest/docs/framework/react/reference/useMutation
• S15: https://docs.walletconnect.network/wallet-sdk/overview

Source Ledger

• [S1] Factors in the Portability of Tokenized Assets on Distributed Ledgers (arxiv): https://arxiv.org/abs/2005.07461 - Defines portability as a multi-dimensional property of tokenized assets and links it to transferability, compatibility, and infrastructure assumptions.
• [S2] Comparative Analysis of Cross-Chain Token Standards (arxiv): https://arxiv.org/abs/2603.06388 - Maps tradeoffs among cross-chain token architectures, useful for separating portability goals from actual ownership-check design.
• [S3] Do NFTs' Owners Really Possess their Assets? A First Look at the NFT-to-Asset Connection Fragility (arxiv): https://arxiv.org/abs/2212.11181 - Shows practical fragility in NFT metadata availability and uniqueness, supporting explicit token URI integrity checks.
• [S4] SoK: Self-Sovereign Digital Identities (arxiv): https://arxiv.org/abs/2603.06896 - Frames self-sovereign identity as a spectrum and highlights adoption and usability constraints that matter for wallet-based authentication.
• [S5] ERC-721: Non-Fungible Token Standard (standards): https://eips.ethereum.org/EIPS/eip-721 - Specifies ownerOf, tokenURI, and transfer semantics that make on-chain ownership checks feasible for entitlement.
• [S6] EIP-1193: Ethereum Provider JavaScript API (standards): https://eips.ethereum.org/EIPS/eip-1193 - Defines provider request behavior and chain/account change events needed to keep wallet sessions synchronized.
• [S7] Ethers.js Provider API (v6) (official-doc): https://docs.ethers.org/v6/api/providers/ - Documents provider operations such as block lookup and balance queries used by server and client runtime checks.
• [S8] Ethers.js Contract API (v6) (official-doc): https://docs.ethers.org/v6/api/contract/ - Documents contract read methods and ABI-based call patterns for ownerOf/tokenURI lookup flows.
• [S9] Ethers.js Hashing Utilities (v6) (official-doc): https://docs.ethers.org/v6/api/hashing/ - Confirms message verification behavior used for off-chain signature-based wallet authentication.
• [S10] OpenZeppelin ERC721 Documentation (official-doc): https://docs.openzeppelin.com/contracts/5.x/api/token/erc721 - Confirms implemented IERC721 surface and ownership transfer patterns expected in common NFT contracts.
• [S11] ERC-4361: Sign-In with Ethereum (standards): https://eips.ethereum.org/EIPS/eip-4361 - Standardized session-based signing flow with nonce and chain-scoped message fields for wallet authentication.
• [S12] Next.js Route Handlers (official-doc): https://nextjs.org/docs/app/getting-started/route-handlers - Defines server-side route contracts for app-scoped API surfaces, directly relevant to a shared owned-character endpoint.