Web3 Integration & Provider Configuration
Relevant source files
The following files were used as context for generating this wiki page:
- src/app/[locale]/(platform)/_components/WalletFlow.tsx/_components/WalletFlow.tsx)
- src/app/[locale]/(platform)/event/[slug]/_components/DirectResolutionButton.tsx/event/[slug]/_components/DirectResolutionButton.tsx)
- src/app/[locale]/admin/integrations/_components/AdminIntegrationsForm.tsx
- package.json
- src/app/[locale]/admin/(general)/_actions/update-general-settings.ts/_actions/update-general-settings.ts)
- tests/unit/adminCreateEventFormUtils.test.ts
The Web3 integration system provides the core infrastructure for interacting with blockchain networks, managing user wallets, and executing decentralized market operations. It encompasses a multi-layered architecture that includes External Owned Account (EOA) connections via Reown AppKit, non-custodial smart contract "Deposit Wallets," and specialized integrations for cross-chain liquidity and prediction market protocols.
This system ensures secure transaction signing, automated winning redemptions, and administrative controls for market creation and resolution. By abstracting complex blockchain interactions into a unified provider configuration, the platform supports seamless onboarding through both traditional and Web3-native wallet providers.
Core Architecture and Wallet Management
The platform utilizes a hybrid wallet architecture. Users connect an EOA (Externally Owned Account) which acts as a signer for a non-custodial smart contract wallet, referred to as the "Deposit Wallet."
Wallet Flow and Lifecycle
The WalletFlow component manages the primary user interface for funding, withdrawing, and deploying these wallets. It tracks the deposit_wallet_status, which can transition to deployed once the on-chain contract is initialized.
The diagram shows the lifecycle of a user's wallet from initial EOA connection to executing on-chain actions through a deployed smart contract wallet.
Sources: src/app/[locale]/(platform)/_components/WalletFlow.tsx:44-53, src/app/[locale]/(platform)/_components/WalletFlow.tsx:132-154
Key Wallet Utilities
| Feature | Description | File Reference |
|---|---|---|
| Deposit Wallet | A smart contract wallet that holds user funds (USDC) and executes trades. | src/app/[locale]/(platform)/_components/WalletFlow.tsx |
| EOA Signer | The connected wallet (e.g., MetaMask, Reown) used to authorize Deposit Wallet calls. | src/app/[locale]/(platform)/_components/WalletFlow.tsx:32-35 |
| Auto-Redeem | A setting allowing winnings to hit the balance automatically via one-time approval. | src/i18n/messages/en.json:115-121 |
| Multi-Wallet | Support for connecting different wallets for mirrored markets (e.g., Polymarket). | src/app/[locale]/admin/integrations/_components/AdminIntegrationsForm.tsx:130-132 |
Provider Configuration and Integrations
The platform integrates with several third-party Web3 providers and protocols to enhance functionality, managed through the AdminIntegrationsForm.
Integration Matrix
| Provider | Purpose | Configuration Key |
|---|---|---|
| Reown (AppKit) | Wallet connection and EIP-712 signing infrastructure. | package.json |
| LI.FI | Cross-chain swaps and deposit routing. | lifi_api_key, lifi_integrator |
| Polymarket | Mirroring markets and enabling arbitrage trading. | arbitrage_enabled |
| UMA | Optimistic oracle for decentralized market resolution. | resolution_mode |
Sources: src/app/[locale]/admin/integrations/_components/AdminIntegrationsForm.tsx:120-135, package.json:49-51, src/app/[locale]/admin/(general)/_actions/update-general-settings.ts:805-820
Transaction Fee Configuration
Administrators configure fee recipients and shares to sustain platform operations. These settings are encrypted before storage.
The flow demonstrates how fee settings are validated, encrypted, and eventually used in the frontend for real-time cost estimation.
Sources: src/app/[locale]/admin/(general)/_actions/update-general-settings.ts:880-900, src/app/[locale]/admin/affiliate/_components/AdminAffiliateContentClient.tsx:43-55
Market Resolution and Oracle Integration
Resolution of markets involves specific Web3 interactions depending on whether "Direct" or "UMA" (Universal Market Access) mode is selected.
Resolution Logic
- Direct Resolution: Requires the actor to be on the
proposer_whitelist. Authorized wallets callproposeAndResolveorproposeAndResolveNegRiskon theDirectResolutionOracle. - UMA Resolution: Involves a bonding mechanism where proposers lock USDC to suggest an outcome, earning rewards if confirmed.
The sequence shows the optimistic resolution process where a proposer submits a result and receives a reward after the dispute window expires.
Sources: src/app/[locale]/(platform)/event/[slug]/_components/DirectResolutionButton.tsx:645-680, src/app/[locale]/(platform)/event/[slug]/_components/DirectResolutionButton.tsx:755-780
Administrative Pre-sign Checks
Before deploying new markets, the system performs several "Pre-sign" checks to ensure the creator wallet is ready for blockchain interaction:
- EOA USDC Check: Validates that the creator has enough USDC for rewards.
- POL Gas Check: Ensures sufficient native tokens for
initializeandapprovetransactions. - Whitelist Check: Verifies the creator is registered in the
proposer_whitelistcontract. - Slug Uniqueness: A final check against the database to prevent collision before on-chain registration.
Sources: tests/unit/adminCreateEventFormUtils.test.ts:250-265, src/app/[locale]/admin/(general)/_actions/update-general-settings.ts:985-1000
Implementation Details
BigInt Serialization and RPC Requests
Web3 interactions often involve large numbers. The system handles BigInt serialization by converting values to hex strings for eth_sendTransaction calls to avoid provider-specific parsing failures.
// Example of RPC Transaction Request Construction
const request = buildRpcTransactionRequest({
from: '0x...',
to: '0x...',
data: '0x...',
value: 0n,
maxFeePerGas: 78000000075n,
});
// Result: maxFeePerGas is serialized as '0x1229298c4b'
Sources: tests/unit/adminCreateEventFormUtils.test.ts:115-135
Security and Encryption
Sensitive configuration, such as API keys for LI.FI or OpenRouter, is never stored in plain text. The update-general-settings action uses encryptSecret to wrap keys before they are persisted via the SettingsRepository.
Sources: src/app/[locale]/admin/(general)/_actions/update-general-settings.ts:882-895
Summary
The Web3 Integration & Provider Configuration system centralizes the management of decentralized identities and blockchain protocols. By combining EOA-signed smart contract wallets with a robust administrative suite for oracle management and cross-chain integrations, the platform maintains security while providing the high-speed execution required for prediction markets.