d-bis/proxmox
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fa5de3ba0110f8f6c19d43df484a805dc1d857f0
proxmox/docs/04-configuration/THIRDWEB_WALLETS_INTEGRATION.md
defiQUG e4c9dda0fd
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
Details
chore: update submodule references and documentation 
- Marked submodules ai-mcp-pmm-controller, explorer-monorepo, and smom-dbis-138 as dirty to reflect recent changes.
- Updated documentation to clarify operator script usage, including dotenv loading and task execution instructions.
- Enhanced the README and various index files to provide clearer navigation and task completion guidance.

Made-with: Cursor
2026-03-04 02:03:08 -08:00

144 lines
8.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Thirdweb Wallets – Documentation Review and Integration
**Purpose:** Review [thirdweb Wallets portal](https://portal.thirdweb.com/wallets) and document how we use or can fully integrate user/embedded wallets (email, phone, social, passkey, external) across the repo.
**References:** [thirdweb Wallets – Get Started](https://portal.thirdweb.com/wallets), [User Wallets](https://portal.thirdweb.com/wallets/users), [External Wallets](https://portal.thirdweb.com/wallets/external-wallets), [Quickstart (TypeScript/React)](https://portal.thirdweb.com/wallets/quickstart), [Connect SDK v5](https://portal.thirdweb.com/react/v5).
---
## 1. Portal overview
The thirdweb Wallets section covers:
- **User wallets (embedded/in-app):** Email, phone, social OAuth (Google, Apple, Facebook, Discord, X, etc.), passkey, guest, custom JWT.
- **External wallets:** 500+ wallets, EIP-6963; MetaMask, WalletConnect, Coinbase Wallet, etc.
- **Server wallets:** Backend-controlled wallets (send tx, monitor).
- **Gas sponsorship / session keys:** Optional.
For each user, thirdweb can create a **non-custodial wallet** and expose it via SDK or HTTP API.
---
## 2. HTTP API (Wallets)
Relevant for backend or headless flows:
| Endpoint | Purpose |
|----------|--------|
| `POST /v1/auth/initiate` | Start auth (email, phone, passkey, SIWE); get challenge. |
| `POST /v1/auth/complete` | Verify and complete auth; returns `token`, `userId`, `walletAddress`. |
| `GET /v1/auth/social` | Redirect to OAuth provider (`provider`, `redirectUrl`). |
| `GET /v1/wallets/me` | Get authenticated user wallet (use token from complete). |
**Headers:**
- **Frontend:** `x-client-id` (project Client ID).
- **Backend:** `x-secret-key` (Dashboard → Settings → API Keys); never in frontend.
**Auth flow (e.g. email):**
1. `POST /v1/auth/initiate` with `{ "type": "email", "email": "user@example.com" }`.
2. User receives code; then `POST /v1/auth/complete` with `{ "type": "email", "email": "...", "code": "123456" }`.
3. Response includes `token`, `walletAddress`; use `token` for `GET /v1/wallets/me` or other authenticated calls.
**Custom auth:** If you already have an auth system, you can attach thirdweb wallets via [Custom Authentication](https://portal.thirdweb.com/wallets/custom-auth).
---
## 3. Current usage in this repo
| Area | What we use | Notes |
|------|-------------|--------|
| **smom-dbis-138/frontend-dapp** | `ThirdwebProvider` (v4), `useAddress` / `useBalance` / `useContract` from `@thirdweb-dev/react`; bridge UI uses thirdweb v4 hooks. | Connect UI is **wagmi** (MetaMask, WalletConnect, Coinbase) in `WalletConnect.tsx`; no embedded wallet (email/social) yet. |
| **x402-api** | `thirdweb` v5: `createThirdwebClient`, `facilitator`, `settlePayment` from `thirdweb/x402`; custom Chain 138. | Server-side only; no user wallets. |
| **explorer-monorepo** | Raw ethers + MetaMask + custom `/api/v1/auth/nonce` and `/api/v1/auth/wallet`. | No thirdweb SDK. |
**Secrets / env:**
- **frontend-dapp:** `VITE_THIRDWEB_CLIENT_ID`, `VITE_WALLETCONNECT_PROJECT_ID` (see [MASTER_SECRETS.md](MASTER_SECRETS.md), [DAPP_LXC_DEPLOYMENT.md](../03-deployment/DAPP_LXC_DEPLOYMENT.md)).
- **x402-api:** `THIRDWEB_SECRET_KEY` (backend only), `SERVER_WALLET_ADDRESS` (treasury for x402). When `X402_USE_ALLTRA=true`, local verification does not require `THIRDWEB_SECRET_KEY`.
---
## 3.1 Server wallet (admin signer) — usage policy
Use the **server wallet** (e.g. the key backing `SERVER_WALLET_ADDRESS` or an Engine backend wallet) only for:
- **Contract admin actions:** roles, pausing, upgrades.
- **Allowlist / signature minting** (if your contracts support it).
- **Indexer repair jobs** (rare, e.g. backfill or reconciliation).
- **Operational controls:** key rotation, emergency ops.
**Do not** use it for user flows (no user impersonation). Keep keys in **KMS, HSM, or secure custody**. See [ALLTRA_X402_OPERATOR_GUIDE.md](ALLTRA_X402_OPERATOR_GUIDE.md) for Alltra/x402 operator context.
**User wallets vs server wallet:**
- **External connect:** power users (MetaMask, WalletConnect, etc.).
- **Embedded:** email/social/passkeys for smooth onboarding; both are user-controlled.
- **Server wallet:** backend-only; never exposed to or used on behalf of end users.
---
## 4. Full integration options
### 4.1 Frontend: one connect experience (embedded + external)
**Goal:** Single “Connect” that supports both **in-app wallets** (email, phone, social) and **external wallets** (MetaMask, WalletConnect, etc.) as in the [portal Get Started](https://portal.thirdweb.com/wallets) and [Quickstart](https://portal.thirdweb.com/wallets/quickstart).
**Recommended path: thirdweb SDK v5**
- Portal and Quickstart use **v5** (`thirdweb` package, `thirdweb/react`).
- v5 provides `ConnectButton` / `ConnectEmbed`, `inAppWallet({ auth: { options: ["email", "google", "passkey", ...] } })`, and 500+ external wallets with smaller bundle and better perf than v4.
- v4 (`@thirdweb-dev/react`) is still in use in the dapp for contract hooks; v5 can run [alongside v4](https://portal.thirdweb.com/react/v5/migrate) for a gradual move.
**Steps:**
1. **Add v5 and a dedicated wallets flow (e.g. demo page)**
- Install: `npm i thirdweb`.
- Use `createThirdwebClient({ clientId })`, `ThirdwebProvider`, `ConnectButton` from `thirdweb/react`.
- Configure `ConnectButton` with `inAppWallet({ auth: { options: ["email", "google", "apple", "passkey"] } })` so users can sign in with email/social or connect MetaMask/WalletConnect.
- **Done:** The frontend-dapp has a **Wallets** page (`/wallets`, `src/pages/WalletsDemoPage.tsx`) that uses only v5: `ConnectButton` with in-app wallet + external wallets, `useActiveAccount`, `useWalletBalance` on Chain 138. Use it to try email/social/external connect without changing the rest of the app.
2. **Unify connect UI (full integration)**
- Replace the current wagmi-only connect modal in `Layout` / `WalletConnect.tsx` with thirdweb v5’s `ConnectButton` (or `ConnectEmbed`) so the same button offers embedded + external.
- Migrate bridge and other features from v4 hooks to v5: e.g. `useAddress` → `useActiveAccount`, `useContract`/`useContractWrite` → v5 contract extensions + `useSendTransaction` (see [v5 migrate](https://portal.thirdweb.com/react/v5/migrate)).
- Keep Chain 138 in v5 (e.g. `defineChain` or use a chain list that includes 138) so the same RPC and chain are used.
3. **Env**
- Use the same `VITE_THIRDWEB_CLIENT_ID` (and optional `VITE_WALLETCONNECT_PROJECT_ID` if needed by v5). No backend secret in frontend.
### 4.2 Backend: optional use of Wallets API
- If you need to **resolve or manage user wallets server-side** (e.g. after a custom auth), call `GET /v1/wallets/me` with the thirdweb token, or use the HTTP auth flow (`/v1/auth/initiate`, `/v1/auth/complete`) with `x-secret-key` from a secure backend.
- **x402-api** already uses `THIRDWEB_SECRET_KEY` for x402; the same key can be used for server-side Wallets API calls if you add them.
### 4.3 Explorer (Blockscout frontend)
- The explorer uses ethers + MetaMask and custom auth endpoints; it does not use thirdweb.
- Full thirdweb Wallets integration there would mean adding the thirdweb SDK and either replacing or complementing the current connect flow with `ConnectButton` + in-app wallet; that’s a separate, optional project.
---
## 5. Checklist for “fully integrated” thirdweb Wallets
- [x] **Documentation:** This file + links to portal (Get Started, Users, Quickstart, v5 migrate).
- [x] **Client ID:** `VITE_THIRDWEB_CLIENT_ID` set in frontend-dapp (and any other app that uses thirdweb).
- [x] **Connect UI (demo):** `/wallets` page with v5 `ConnectButton` + `inAppWallet` (email, google, apple, passkey) + external wallets; Chain 138 balance shown.
- [ ] **Chain 138:** Supported in the thirdweb client/chains config used by the dapp.
- [ ] **Migration (optional):** Bridge and other components moved from v4 hooks to v5 extensions/hooks so one account source is used everywhere.
- [ ] **Backend (optional):** Use of `/v1/wallets/me` or auth endpoints from a secure service when needed.
---
## 6. Quick links
- [Wallets – Get Started](https://portal.thirdweb.com/wallets)
- [User Wallets (auth methods)](https://portal.thirdweb.com/wallets/users)
- [External Wallets](https://portal.thirdweb.com/wallets/external-wallets)
- [Quickstart (TypeScript/React)](https://portal.thirdweb.com/wallets/quickstart)
- [React v5 ConnectButton / ConnectEmbed](https://portal.thirdweb.com/react/v5/components/ConnectButton)
- [In-App Wallet (v5)](https://portal.thirdweb.com/react/v5/in-app-wallet/get-started)
- [Migrate from v4 to v5](https://portal.thirdweb.com/react/v5/migrate)
- [API Reference – Authentication](https://portal.thirdweb.com/reference#tag/authentication)
- [Custom auth](https://portal.thirdweb.com/wallets/custom-auth)
Reference in New Issue View Git Blame Copy Permalink