WalletConnect v2 Infrastructure in the xolosArmy Ecosystem

1. Overview: Why WalletConnect v2 for xolosArmy

The xolosArmy ecosystem is built on eCash (XEC), leveraging fast, low-fee transactions and a modern token/NFT experience via eCash-compatible standards (including ALP eTokens). To connect sovereign, non-custodial custody with rich dApp interactions, xolosArmy adopts WalletConnect v2 as the canonical transport and session layer between Xolo Legend and RMZWallet / Tonalli.

WCv2 upgrades the interaction model from ad-hoc connections into a session-based protocol with robust permission negotiation, persistence, granular capabilities, and a standards-driven identity model through CAIP (Chain Agnostic Improvement Proposals). This enables a secure and chain-agnostic integration without inheriting EVM-centric assumptions.

2. eCash Foundation and the Role of RMZWallet (Tonalli)

RMZWallet (Tonalli) is the custodial boundary for users in xolosArmy. It is a modern web wallet (PWA-friendly) designed to keep the user’s seed phrase and private keys local, encrypted, and never exposed to external applications or relays.

2.1 Tokens and NFTs

The ecosystem token $RMZ operates as an ALP eToken. RMZWallet also supports xolosArmy NFTs, including metadata retrieval (e.g., via IPFS/Pinning infrastructure) and user-level asset visualization. WalletConnect sessions can authorize dApps like Xolo Legend to request account visibility and transaction signing for these assets without ever obtaining custody.

3. CAIP-25 Sessions: Namespace Negotiation as the Core Contract

The security contract between Xolo Legend and RMZWallet is expressed through CAIP-25 session negotiation. The dApp sends a session proposal describing required capabilities. The wallet validates that proposal, prompts the user for consent, and returns the approved session namespaces with CAIP-10 formatted accounts.

3.1 Structure of a Session Proposal

WCv2 organizes permissions into namespaces. Each namespace specifies: chains, methods, and events. The proposal is split into: requiredNamespaces and optionalNamespaces.

3.2 Approval and Session Creation

After validation and explicit user consent, RMZWallet returns the session namespaces confirming exactly what is approved. Accounts are expressed using CAIP-10.

{
  "namespaces": {
    "ecash": {
      "accounts": [
        "ecash:<chain-id>:<address-or-account-identifier>"
      ],
      "methods": [
        "ecash_signTransaction",
        "ecash_signMessage"
      ],
      "events": [
        "accountsChanged",
        "chainChanged"
      ]
    }
  }
}

Note: chain identifiers and method naming should reflect the canonical choices in xolosArmy’s implementation. The example above illustrates the structure, not a mandated naming convention.

3.3 wallet_* Methods and Chain-Optional Requests

Some requests (notably methods prefixed with wallet_) can be defined as chain-optional in WCv2. This enables future expansion—such as adding chains or environments—without forcing a chain target at request time. For xolosArmy, this creates a forward-compatible path for additional layers and ecosystem growth.

4. Implementation in RMZWallet (Tonalli)

RMZWallet is built with a modern web stack (TypeScript + Vite) and integrates WCv2 through dedicated components responsible for pairing, session lifecycle, request routing, and user consent.

4.1 Chain Data: Chronik + ecash-lib

As a WalletConnect controller, RMZWallet must maintain reliable chain state visibility: balances, UTXOs, token ownership, and transaction confirmation. This is achieved through:

• Chronik for index-backed chain queries and real-time balance/UTXO tracking.
• ecash-lib for local transaction construction and signing.

4.2 Core Components: Lifecycle and Request Queueing

In a typical controller architecture, WCv2 responsibilities are split into:

5. Xolo Legend dApp: Bridge, Persistence, and Events

On the dApp side, Xolo Legend initiates pairing and manages session persistence via its WalletConnect bridge modules (for example: WcBridge.tsx and walletconnect.ts). The dApp typically generates a QR code or a deep link that the user opens with RMZWallet.

5.1 Session Persistence

One of WCv2’s strongest UX benefits is persistent sessions. Xolo Legend can reconnect using a session identifier stored locally, reducing repeated QR scans while keeping the permission scope explicit and auditable.

5.2 Event Tunnels: Reactive UX

The dApp subscribes to wallet events (e.g., accountsChanged) so that account switching within Tonalli is reflected instantly in Xolo Legend’s UI. This enables real-time reactivity without polling or insecure custom transports.

6. Signing Flow and Cryptographic Security

When a user triggers an on-chain action in Xolo Legend (e.g., purchasing an item, interacting with a token module, or publishing a cultural on-chain message), the dApp sends a JSON-RPC request through WCv2. RMZWallet validates, prompts the user, then signs locally and returns the signed transaction for broadcast.

7. Validation and Error Handling

WCv2 defines standardized error codes that both wallet and dApp should handle to preserve reliability and user trust. Errors can originate from technical failures, malformed requests, unsupported capabilities, or explicit user rejection.

8. Observability and Origin Verification

8.1 Telemetry (Non-sensitive)

WCv2 SDKs can expose telemetry signals about runtime behavior and error codes. Properly configured, telemetry can help identify bottlenecks in session approval flows without collecting sensitive user data such as balances, addresses, or holdings.

8.2 VerifyContext: Preventing Phishing

The VerifyContext feature allows RMZWallet to assess the origin of a session request and classify it as valid, invalid, or unknown. This helps prevent phishing attempts where a malicious site imitates Xolo Legend to capture permissions.

9. Tokens, NFTs, and On-Chain Culture via WalletConnect

The integration is not limited to XEC transfers. xolosArmy leverages on-chain primitives to support:

• ALP eTokens such as $RMZ for community economics and incentives.
• NFT collections that represent identity, access, culture, and digital artifacts.
• OP_RETURN messages to anchor proposals, events, and cultural signals on-chain.

9.1 Storage and Visualization

RMZWallet can integrate NFT metadata retrieval (e.g., IPFS + pinning), enabling Xolo Legend to request permission to view and incorporate user-owned NFTs into gameplay, social layers, or access modules—without compromising custody.

10. Evolution and Roadmap: Extensible Sessions

WalletConnect v2 is intentionally modular. This allows xolosArmy to expand supported namespaces, methods, and session patterns as new modules arrive—without redesigning the communication layer.

Near-term growth areas may include crowdfunding modules, native payment flows for ecosystem services, and richer transaction intents exposed as wallet-approved JSON-RPC methods—while keeping the wallet’s security boundary intact.

11. Conclusion: Secure Interoperability as the Ecosystem Backbone

The WCv2 integration between Xolo Legend and RMZWallet (Tonalli) is a cornerstone of xolosArmy engineering: it balances security, interoperability, and user sovereignty through CAIP-based session negotiation and local signing.

With strict namespace validation, standardized error handling, origin verification, and a chain-aware state layer (Chronik + ecash-lib), the ecosystem achieves a durable and scalable communication fabric—capable of supporting tokens, NFTs, and the broader cultural/utility vision of xolosArmy on eCash.