PrestaShop 8.x Crypto Payments with OURTOKEN (BSC): Order‑Unique Addresses, On‑Chain Auto‑Confirmation, Wallet Linking (MetaMask + Trust Wallet/WalletConnect v2), Non‑Custodial Refunds, and MiCA Tracker

Scope (Everything We Want)

- New _sdf PrestaShop module(s) in a sanitized repo (we do not touch production modules).
- OURTOKEN (BEP‑20 on BSC) fully operational with discount; USDC (ERC‑20) operational.
- Order‑unique deposit address per order/network with QR + EVM deep link, expiry window, and amount tolerance.
- Reliable watchers that auto‑confirm orders after N confirmations (configurable), verifying destination and amount; record
tx hash, block, ts, asset/EUR values, and price source.
- Customer wallet linking (MetaMask + Trust Wallet via WalletConnect v2) stored with explicit consent; selectable “default
for refunds/cashback”.
- Non‑custodial refunds: BO button launches Trust Wallet deep link from corporate hot wallet; operator signs in wallet;
refund tx hash recorded. Server never signs payouts to customers.
- MiCA hook: append eligible events to CSV and compute rolling 12‑month EUR totals (operational stop hint at €950k; cap €1M).
- Security hardening: HMAC‑protected backend/cron, strict sanitization, TLS verification, secret masking, timeouts/retries,
rate limiting.
- Docs & Testnet: Operator + developer docs, OpenAPI for backend, testnet demo (BSC + Sepolia), packaged zips.

Functional Details

- Checkout
- OURTOKEN/USDC shown with EUR→asset conversion (price source configurable), QR & deep link, countdown/expiry, risk notice
and refund consent text.
- Cancel/return handling; display over/under‑payment instructions (configurable tolerance).
- Order‑Unique Addresses
- Deterministic per order/network; mapping stored and displayed; path schema versioned in config.
- Watchers (Idempotent + Resilient)
- Confirm N blocks; verify token/decimals and destination equals derived order address; amount ≥ required within
tolerance; reorg handling; RPC + explorer corroboration; idempotent key {chain}:{order_id}:{tx_hash}; backoff with jitter;
metrics/health.
- Wallet Linking
- MetaMask + WalletConnect v2 (Trust Wallet) linking; store address(es) per user with consent; set default for refunds/
cashback. Optionally verify address ownership through signed message (EIP‑4361 flow) if required.
- Refunds (Non‑Custodial)
- BO action composes Trust Wallet deep link (customer address, asset, amount); operator signs in wallet; admin records
tx hash; stored on order. Flow: Keystone (treasury multisig) → Trust Wallet (hot) → Customer. Server never signs customer
payouts.
- Admin & BO
- Networks: RPC/WS/explorer endpoints, chainId, token contracts/decimals; confirmations; expiry minutes; tolerance; OURTOKEN
discount %; cashback toggle + max %; geo‑restrictions; health panel (RPC height, explorer status, last watcher run).
- MiCA Tracker
- Admin action/hook writes eligible rows (venta, lp_exit) with ISO time, EUR values, tx hash, price source; rolling
12‑month computation and baked‑in stop hints; CSV lives in repo/var per your directory policy.

Architecture

- PrestaShop Module
- PHP 8.1/8.2; hooks: paymentOptions, paymentReturn, displayAdminOrder, displayBackOfficeHeader, displayHeader.
- Frontend: ethers.js v6, WalletConnect v2 sign‑client, QR code lib, secure AJAX for prices/state (server validates).
- Admin: Symfony forms; masked sensitive fields; server‑side validation; connectivity and watcher status UI.
- Backend Service (Deterministic Addresses)
- Node.js 20 LTS + Trust Wallet Core JS/WASM (official bindings). No custom Rust→WASM.
- Endpoints (HMAC signed; server signs sweeps only, and that endpoint ships disabled by default):
- `POST /wallet/generate {order_id, chain, asset}` → `{address, derivation_path}`
- `GET /tx/status?chain&address` → `{confirmed, confs, last_block, txs[]}`
- `POST /tx/sweep {from_path|from_address, to_address, asset, max_fee}` → `{txid}` [disabled by default; never used for
customer payouts]
- Blockchain Service Layer abstraction: providers (RPC/explorer), unit conversions, retries/backoff, and error taxonomy.
- Logging: JSON, correlation IDs, no PII/secrets; redaction in place; health endpoint.

Security & Custody (Embedded Clarifications)

- Non‑custody guaranteed: server never signs payouts to customers; refunds happen with Trust Wallet (corporate hot) signed by
an operator.
- Backend HMAC headers: X‑Request‑Timestamp (epoch s), X‑Request‑Signature (sha256=hex over canonical string:
ts.method.path.body). ±300s skew; replay‑safe; rate‑limited; optional IP allowlist.
- Sanitization: cast/validate all IDs/addresses; parameterized DB queries; bound timeouts; TLS verification for HTTP(S); SSRF
and IDOR guarded.
- Keys & Secrets: No keys in code or logs; secrets in env/PS configuration (masked). MVP seed stored in Vaultwarden with
rotation runbook; future upgrade path to AWS KMS or HashiCorp Vault is planned.
- Multi‑sig/HSM now? Not required for this phase; endpoints are prepared for later enforcement.

Networks & Providers

- Required: BNB Chain (OURTOKEN BEP‑20) with discount; Ethereum (USDC ERC‑20).
- Optional toggles in BO (ship disabled by default): Polygon, TRON (TRC‑20 USDT), BTC (confirm‑only), Solana (SPL USDC), XRP.
- Confirmations (defaults, editable): BSC 5–12; ETH 12; Polygon 6; TRX 20–30; BTC 1–3; SOL slot‑based; XRP per best practice.
- Connectivity (embedded answers):
- Use self‑hosted nodes for BTC/ETH/BNB when available; other networks via third‑party providers with failover
(QuickNode/Chainstack; Helius for Solana; TronGrid for TRON; Ankr/Moralis/Blockchair as fallback).

Compliance, Privacy, Geo

- MiCA Exemption: CSV hook for eligible events; rolling 12‑month sum; stop hints at €950k and cap €1M; admin‑visible policy
text.
- Risk Notice & Consent: CNMV risk notice in checkout; explicit consent text for OURTOKEN refunds; document retention and lawful
basis in Privacy Policy.
- Wallets = personal data: ask consent on link; allow unlink; store minimal info; document security.
- Geo‑restrictions: block US/UK (and others configured) on token pages and flows.

Configuration

- Admin keys/fields:
- OURTOKEN_CONTRACT, OURTOKEN_DECIMALS, OURTOKEN_DISCOUNT_PERCENT, OURTOKEN_RECEIVE_ADDRESS
- USDC_CONTRACT, USDC_DECIMALS (ETH)
- RPC_URL_*, EXPLORER_API_URL_*, EXPLORER_API_KEY_*
- CONFIRMATIONS_*, EXPIRY_MIN, AMOUNT_TOLERANCE_PCT
- PRICE_SOURCE (e.g., on‑chain quote or approved API), RISK_NOTICE_TEXT, REFUND_CONSENT_TEXT
- CASHBACK_ENABLED, CASHBACK_MAX_PERCENT, GEO_RESTRICTED
- Backend env:
- HMAC_SECRET, TWC_SEED_REF, RPC_URL_*, EXPLORER_API_*, REQUEST_TIMEOUT_MS, RETRY_*, TLS_CA (if custom), LOG_LEVEL

Data Model (minimal)

- ps_crypto_order_addr:
- id, order_id, chain, asset, address, derivation_path, expected_amt_asset, expected_amt_eur, price_source, expires_at,
status, created_at
- ps_crypto_tx:
- id, order_id, type [payment|sweep|refund], tx_hash, block_height, block_time, amount_asset, amount_eur, price_source,
meta_json, created_at
- ps_crypto_wallet_link:
- id, customer_id, chain_family, address, default_for_refunds (bool), consent_ts
- MiCA CSV:
-
fecha_iso,tipo,tx_hash,par,token_entregado,monto_token_entregado,token_recibido,monto_token_recibido,precio_referencia_eur,contravalor_eur,fuente_precio,computable,nota

Price & Evidence Capture

- Price locking: capture at confirmation time with source (API name/endpoint, timestamp); store EUR value and asset amount;
render on order admin and for CSV.
- Evidence: keep explorer links; record block/ts; logs show criteria met for “Paid”.

Observability & Health

- Health page: last watcher run, RPC height per chain, explorer availability, last error snippet.
- Logs: structured, redacted; correlation id per order; decision reasons (e.g., insufficient confs, addr mismatch).

Performance

- Watcher interval tunable; typical BSC auto‑confirmation under 90s at N=5–12.
- Backoff and retry strategy on API limits; fallback to alternate providers where configured.

Compatibility

- PS 8.x (PHP ≥8.1), MySQL 5.7+/8, OpenSSL; Node.js 20 LTS for backend; ethers.js v6 and WC v2 on FE.

Assumptions (explicit)

- KYC/AML integration not part of this phase; proportional controls only (sanctions/jurisdictions, manual review threshold).
- Keys: Vaultwarden + rotation acceptable for MVP; migration to AWS KMS/HashiCorp Vault planned without code changes in
business logic.
- Hosting: On‑prem or your preferred environment; we deliver containerized artifacts.

Acceptance Criteria

- Checkout: OURTOKEN and USDC shown; order‑unique address & QR/deep link; expiry/tolerance enforced; notices rendered.
- Watchers: flip to Paid only when destination matches derived address, amount ≥ required (±tolerance), and N confirmations
reached; tx hash, block, ts, EUR value, price source recorded; reorgs handled; idempotent behavior.
- Wallet linking: MetaMask + WC v2 link stored with consent; default for refunds selectable.
- Refunds: BO deep link launches Trust Wallet with correct params; refund tx hash stored on order.
- MiCA: CSV hook appends eligible rows; rolling 12‑month totals correct; stop hints visible.
- Security: HMAC enforced on backend/cron; inputs validated; TLS verification & timeouts; secrets masked; no secrets in logs.
- Testnet demo: one full BSC test, one ETH USDC test; screenshots or GIF + steps; docs complete.