#MetaQuantum Platform Architecture & Delivery Plan

Last updated: {{DATE}}

#Execution Status

#1. Vision Overview

• Objective: Evolve the MetaQuantum network from a secure identity layer into a production-ready infrastructure platform comparable to Arbitrum, Alchemy, AltLayer, Ankr, Caldera, Conduit, Gelato, and Zeeve.
• Guiding Principles:
• Unified cryptographic identity across every surface.
• Deterministic Layer2 execution with auditable data availability.
• Developer-first experience: documented APIs, SDKs, usage insights, and responsive support.
• Operational excellence: observability, automation, and repeatable delivery pipelines.

#2. Service Fabric Overview

Status: Ownership across all domains has been defined and the majority of core services are live. Layer2 now submits batches on-chain, persists DA payloads, and tracks forced inclusion queues, while the developer API key lifecycle and telemetry endpoints are exposed. Remaining gaps: enforce signature verification, finalize documentation, and wire dashboards/alerts to the new metrics.

#Integration Map

1. Identity → Layer2: Newly registered users receive deterministic smart contracts. SessionManager::register_user calls CONTRACT_REGISTRY and seeds WASM artefacts.
2. Layer2 → Gateway: Sequencer updates, forced inclusion queue state, and batch metadata exposed via service.rs (/layer2/status, /layer2/metrics, /layer2/batches, /layer2/data/{hash}) for UI/API consumption.
3. Layer2 ↔ Financial: MQPY ledger operations invoked from smart contracts (apply_user_smart_contract). Rewards and burns feed into Layer2 state deltas.
4. Gateway → Frontend Consoles: Static consoles (discover/devhub/consensus/contracts) consume the shared dashboard bundle (dashboard.bundle.js) plus the new developer usage APIs to render API key metrics and Layer2 health.
5. Observability → Ops: Prometheus registry in telemetry.rs exports Layer2/bridge counters and health snapshots; dashboards/Alertmanager wiring remains pending. Logs still slated for structured JSON (future). Health checks consumed by CI/CD smoke tests.

#External Integrations

• Stripe (fiat onboarding) — webhook handling, signature verification (stripewebhook).
• IPFS/Hypercore/Tor — data transport and content storage for identity proofs.
• Planned: Ethereum L1 via ethers-rs for rollup commit & forced inclusion transactions.

#Recent Platform Updates

• Layer2 batches (src/layer2.rs): commits now submit to L1 when sequencer secrets are present, persist data-availability snapshots (DATA_AVAILABILITY_DIR), and queue forced inclusion requests with ready timestamps.
• Developer + Layer2 APIs (src/service.rs): Actix scope exposes /layer2/status, /layer2/metrics, /layer2/batches, /layer2/data/{hash}, and /developer/api-keys, /developer/usage endpoints for dashboards and tooling.
• Persistent API keys (src/accounts_db.rs): user records store API key metadata (ApiKeyMetadata) for issuance, revocation, and usage tracking used by the new endpoints.
• Secret bootstrap (src/secret_store.rs): SecretManager now loads sequencer RPC/private key/inbox data, enabling on-chain batch submission with helpful warnings when unset.
• Telemetry registry (src/telemetry.rs): Prometheus counters/gauges track Layer2 commits, forced inclusion requests, bridge health, and health snapshots for /metrics exposure.
• Developer consoles (static/js/dashboard.bundle.js): UI needs to surface the new API key metrics and Layer2 telemetry cards in the usage view (in progress).

#3. Success Metrics

Status: Baseline targets are defined and Prometheus metrics are emitting; the remaining gap is wiring Grafana dashboards and scrape configs (Prometheus/Alertmanager) to surface them.

| Track | Metric | Target (Pilot) | Target (GA) | | --- | --- | --- | --- | | Service Availability | RPC uptime | ≥ 99.5% | ≥ 99.9% | | Sequencer Performance | Batch finality SLA | ≤ 2 min average | ≤ 60 sec average | | Data Availability | Batch DA retrieval success | ≥ 99% | ≥ 99.9% | | Developer Adoption | Active API keys (monthly) | 25 | 150+ | | Developer Experience | Time-to-first successful tx (guided flow) | ≤ 30 min | ≤ 10 min | | Security | PQ signature validation coverage | 100% new sessions | 100% all sessions | | CI/CD Health | Pipeline success rate | ≥ 90% | ≥ 95% |

Telemetry Note: Metrics already flow from telemetry.rs across Layer2, bridge, and developer usage. Next step is publishing Grafana dashboards, alerts, and per-team ownership around the emitted series.

#4. Layer2 + Developer Portal Sprint (2 Weeks)

Status: Sprint backlog drafted; execution partially underway (Layer2 endpoints + telemetry live, signature enforcement and UI wiring still pending).

#Sprint Goals

1. Stabilize Layer2 execution with authenticated APIs.
2. Ship Developer Portal prototype integrated with live metrics and batch explorer feeds.

#Workstreams & Tasks

#A. Layer2 Stabilization

• Harden batch ingestion & commit flow:
  • [x] Implement signature bypass guard (ALLOW_INSECURE_LAYER2) with clear error messaging.
  • [x] Persist forced inclusion requests with ready timestamps and expose /layer2/forced_inclusion; integration tests still pending.
  • [x] Persist DA payload snapshots (keccak + JSON) and expose /layer2/data/{hash}.
  • [ ] Define retention/rotation policy for DA files and add checksum validation jobs.
• RPC Enhancements:
  • [x] Ship /layer2/status, /layer2/metrics, and /layer2/batches endpoints (JSON + explorer metadata).
  • [ ] Add authentication middleware (API keys) and per-route rate limiting.
• Reliability:
  • [ ] Bench tests for WASM execution (gauge average latency, mem usage).
  • [x] Add Prometheus metrics: batch queue length, DA write failure count, proof lag.

#B. Developer Portal Prototype

• UI:
  • [x] Extend dashboard.bundle.js with tab navigation & copy helpers.
  • [ ] Wire the new API usage and Layer2 telemetry cards into the developer console.
• API Adapter Layer:
  • [x] Expose /developer/api-keys (list/create/delete) and /developer/usage endpoints in service.rs.
  • [ ] Hook API key issuance into quota + rotation policy (post-auth middleware).
  • [ ] Implement anonymized logging for key operations (to feed usage dashboards).
• Documentation:
  • [ ] Auto-generate API reference (OpenAPI) and serve via Developer Portal.
  • [ ] Publish onboarding guide (registration → contract execution → analytics).
• Testing:
  • [ ] Playwright smoke tests covering sheet open, tab navigation, API fetch.

#Deliverables

• Layer2 API spec & Postman collection.
• Developer Portal prototype hosted at /discover.html sheet (integrated).
• Sprint summary covering metrics, issues, next steps.

#5. CI/CD & Staging Strategy

Status: Automated via .github/workflows/ci.yml — sequential jobs lint, test, build, and run the staging bundler (scripts/deploystaging.sh).

#Pipeline Stages

1. Lint & Format: cargo fmt --check, cargo clippy -- -D warnings, frontend lint (ESLint).
2. Unit Tests: cargo test --all, JS unit tests (Jest/Vitest where applicable).
3. Integration Tests:
   • Spin up ephemeral environment (Docker Compose or cargo test harness) for Layer2 & API.
   • Run e2e scenarios: user registration → contract execution → Layer2 batch retrieval.
4. Security Gates:
   • cargo audit, npm audit --production.
   • Optional: Trivy scan for container images.
5. Build & Artifact:
   • Produce Rust binary tarballs, WASM bundles, static assets.
   • Attach version metadata (git SHA, build time).
6. Deploy:
   • Staging: handled by the CI workflow (staging job) which packages artifacts through scripts/deploy_staging.sh and publishes them as staging bundles.
   • Production: manual approval, blue/green or canary rollout with health checks.

#Environments

| Env | Purpose | Data | Deployment cadence | | --- | --- | --- | --- | | Dev | Local development | Mocked | On-demand | | Staging (Preview) | Integration & QA | Synthetic + scrubbed | On every merge to main | | Production | Live traffic | Real | Manual promotion |

#Staging Features

• Simulated Layer2 chain with deterministic seeds.
• Replayable fixtures for Layer2 batches and ledger events.
• Toggle to enable API key authentication and throttling.
• Observability parity: metrics, logs, alerts configured identical to prod.
• CI job uploads staging bundles under staging/ to simulate deployment hand-off.

#Tooling & Infrastructure

• CI Engine: GitHub Actions/GitLab CI with caching for Cargo & npm.
• Secrets Management: GitHub OIDC + HashiCorp Vault (or AWS Secrets Manager).
• Container Registry: GHCR with signed images (cosign).
• Infrastructure as Code: Terraform or Pulumi modules for staging/prod resources.
• Monitoring: Prometheus + Grafana dashboards, Alertmanager/PagerDuty integration.

#Rollback & Incident Response

• Automated rollback trigger on failed health checks.
• Runbook outlining how to revert to previous deployment, invalidate caches, and notify stakeholders.
• Post-incident review template stored in /docs/ops/runbooks.

#6. Immediate Next Steps

Status: Architecture document sign-off pending; subsequent actions depend on the consolidated execution status table.

1. Sign-off on architecture document with Domain Leads (Identity, Layer2, Platform, SRE).
2. Allocate sprint teams and create Jira/Linear tickets per task above.
3. Bootstrap CI/CD pipeline: create pipeline config, integrate with repo, set up secret management.
4. Wire developer portal UI to /developer/usage and /layer2/* endpoints, including API key issuance & revocation flows.
5. Build staging cluster: provision infrastructure, configure environment variables, seed baseline data.
6. Schedule check-ins: Daily standup for sprint, weekly platform sync, dedicated SRE handoff session.

#7. Risks & Mitigations

Status: Risk register recorded; mitigation tasks require owner assignment and tracking on the delivery board.

#8. References

• docs/layer1_integration_plan.md
• src/layer2.rs, src/service.rs, src/accounts_db.rs, src/secret_store.rs, src/telemetry.rs, src/session.rs
• static/discover.html, static/js/dashboard.bundle.js, static/js/home_portal.js

---

Prepared by: MetaQuantum Platform Team

---

#9. Module Inventory (Living)

> Scope This section is maintained as a living inventory and updated each release. Starting with the foundational groups helps track ownership and work streams before covering the remaining modules.

#9.1 Core Processing & Protocols

Status: Ownership identified for every module; consolidation work scheduled for Hypercore and MQN bridge components.

#9.2 Layered Architecture

Status: Layer0 is fully wired; Layer1 scaffolding exists; Layer2 needs the consolidation tasks tracked in the sprint.

The remaining module groups (Ledger & ZK, Data Access, Sessions & Security, etc.) will be documented in upcoming revisions. Use these tables as the authoritative reference when triaging work or assigning owners.

#9.3 Developer & Surface APIs

Status: Public-facing endpoints now expose Layer2 status and developer API key lifecycle; quotas, dashboards, and UI integration still on the roadmap.

#MetaQuantum Consensus Wiring (Draft)

#PubSub Topics

• mqconsensusproposal: broadcasts full block proposals as JSON-encoded ConsensusMessage::Proposal.
• mqconsensusvote: carries quorum votes with validator id, block hash، والارتفاع المستهدف.

#Runtime Hooks (حاليًا)

1. runswarm يشترك في مواضيع الإجماع ويحوّل أي رسالة يتم استلامها إلى ConsensusState::handlemessage.
2. ConsensusState::handlemessage يقوم فقط بتسجيل الحدث وتخزين الكتل المقترحة في Hypercore لأغراض الرصد.
3. دالة publishconsensusmessage متاحة لإرسال الرسائل عبر Gossipsub، ويجري استدعاؤها حاليًا عندما يكون متغير البيئة VALIDATORID مساويًا للمقترح المتوقع فتقوم العقدة ببث كتلة موقعة بمفاتيح config/validatorkeys.toml.

• ✅ بناء جدولة للمقترحين تربط بين expectedproposer وهوية العقدة المحليّة عبر مخزن دوري للحصص والارتفاعات القادمة.
• ✅ فرض توقيع كل من المقترحات والأصوات مع رفض الرسائل الخالية من التوقيع أو غير المتطابقة.
• ✅ إدارة أصوات الإجماع عبر registervote مع طابور للرسائل المتأخرة بدل المسار القديم المباشر.
• ✅ استخدام lastlocalproposal لإعادة تهيئة المقترحات بعد إعادة التشغيل وإطلاق محاولات إعادة التصويت عند الحاجة.
• ✅ إضافة اختبارات تكامل بثلاث عقد للتحقق من نشر المقترح وتحصيل الأصوات والوصول إلى النصاب.

| المرحلة | الرسالة | المرسل | المستلمون | السلوك الحالي | |---------|---------|--------|------------|----------------| | 1 | ConsensusMessage::Proposal | المقترح المتوقع | جميع العقد عبر mqconsensusproposal | تخزين الكتلة في Hypercore وتحديث lastlocalproposal. | | 2 | ConsensusMessage::Vote | كل عقدة تتحقق من المقترح | جميع العقد عبر mqconsensusvote | يتم التحقق من التوقيع، ثم تمرير التصويت إلى registervote. | | 3 | Commit (قيد التنفيذ) | عقدة تصل للنصاب | طبقة التخزين / Layer2 | جارٍ تصميم تدفق الالتزام، حالياً يجري فقط التسجيل في السجلات. |

المراحل 1 و2 مستقرة، بينما المرحلة 3 تحتاج ترجمة واضحة إلى تحديث جذور الحالة ونشر الكتل إلى الـ ledger.

#خطة الإتمام

1. Commit Hook: تنفيذ دالة finalize_block التي تُحدِّث حالة ConsensusState وتكتب بيانات الكتلة النهائية إلى التخزين.
2. إعادة المحاولة: توثيق سياسة إعادة إرسال المقترحات/الأصوات عند الانقطاعات وفترات الانتظار.
3. الرصد: إضافة عدادات Prometheus//metrics/performance لعدد المقترحات والفشل في النصاب.
4. التوثيق: تحديث هذا المستند عند اكتمال كل خطوة وإضافة رسم تسلسلي يوضح حالة العقدة (Idle → Proposal → Voting → Commit).

#Layer1 Deployment & Testing Guide

This guide documents compiling, testing, and deploying the contract suite (SequencerInbox, ChallengeOutbox, BridgeEscrow) using the Hardhat workspace bundled with the repository.

#1. Prerequisites

1. Dependency installation in qdeepproject/hardhat:

   cd hardhat
   npm install
   

   cp ../.env.example ../.env
   

• MQPYTOKENADDRESS – ERC20 backing the bridge (e.g., deployed MQPYToken).
• SEQUENCERRPCURL, SEQUENCERPRIVATEKEY, SEQUENCERINBOXADDRESS, etc.
• BRIDGEESCROWADDRESS / BRIDGEESCROWRPCURL for the watcher.

#2. Compile & Test

Contract compilation: (sources are taken from ../contracts):

npm run compile

Unit tests (Hardhat network by default):

npm test

Test scope:

• Batch submission / forced inclusion workflow (SequencerInbox).
• Queueing, challenging, and resolving withdrawals (ChallengeOutbox).
• Deposit / withdrawal events (BridgeEscrow).

#3. Deploy to a Network

Ensure the deployer account has sufficient funds on the target network (e.g., Sepolia). Execute:

npm run deploy:sepolia

Deployment script summary:

1. Deploys SequencerInbox with challenge/forced inclusion parameters.
2. Deploys ChallengeOutbox, linked to the inbox.
3. Deploys BridgeEscrow, linked to MQPYToken and the outbox.
4. Writes a summary JSON file to hardhat/artifacts/layer1-deployment.json.

For alternative networks, add the configuration to hardhat.config.js (network section) and create a matching npm script.

#4. Wiring Back Into Rust

Post-deployment steps:

1. Update .env with the live addresses (SEQUENCERINBOXADDRESS, BRIDGEESCROWADDRESS, etc.).
2. Restart the Rust node so Layer2State and bridgewatcher pick up the new configuration.
3. Visit /layer2/batches and the developer hub (static/devhub.html) to confirm batches are published and DA payloads are accessible.
4. Trigger a sample deposit on BridgeEscrow and verify bridgereserve.rs reflects the event.

This flow validates the Layer1 contracts are verified end-to-end before moving on to validity/fraud proof integration.

#Layer1 Integration Plan

This plan defines the high-level wiring required to connect the new Layer1 contracts to the existing Rust services.

#Rust Modules To Touch

1. src/layer2.rs

• Extend the AggregatedProof struct with:

batchid (matches SequencerInbox ID).

Optional proofcommitment.

1. src/bridgereserve.rs

• Map the existing ledger events to on-chain deposits/withdrawals:

Emit BridgeEscrow.deposit when Layer2 records a user deposit.

• Maintain a bijection between on-chain IDs (depositId / withdrawalId) and current reserve entries.

1. src/service.rs / RPC layer

• Expose endpoints to:

Request forced inclusion (calls SequencerInbox.requestForcedInclusion).

• Subscribe to contract events via WebSocket (e.g., ethers-rs or alloy) to update local state.

1. src/quantummask.rs and user-facing logic

ethers = { version = "2", default-features = false, features = ["abigen", "contract", "ethers-solc"] }

| Variable | Description | | --- | --- | | SEQUENCERRPCURL | HTTPS endpoint of the Ethereum JSON-RPC provider (Sepolia recommended for testing). | | SEQUENCERPRIVATEKEY | Hex-encoded private key of the sequencer signer (without 0x). | | SEQUENCERCHAINID | Numeric chain ID (optional, defaults to 11155111 for Sepolia). | | SEQUENCERINBOXADDRESS | Deployed address of SequencerInbox. | | SEQUENCERCHALLENGEWINDOWSECS | Challenge period for batches (optional). | | SEQUENCERFORCEDELAYSECS | Minimum delay before forced inclusion can be executed (optional). |

1. Serialize the Layer2 frame (transactions + per-user contract state changes).
2. Store the blob under DATAAVAILABILITYDIR (default data/availability).
3. Compute keccak256 of the blob and pass as dataAvailabilityHash to submitBatch.
4. Persist the mapping {batchid -> datastore pointer} for auditors and expose through /layer2/batches + /layer2/data/{hash}.

#Challenge Flow Stub

Until fraud/validity proofs land:

• Implement a guardian service that can call flagBatch manually when inconsistencies are detected.
• Add metrics to detect not-yet-finalized batches that exceed challengeWindow + grace.
• Bridge watchers can be enabled by setting BRIDGEESCROWADDRESS (and optional BRIDGEESCROWRPCURL) to sync on-chain deposits with bridgereserve.rs.

This integration plan should be executed after writing deployment & ABI scripts for the Solidity contracts above.

#Per-User Smart Contract Migration

1. Solidity Template: أنشئ عقداً أساسياً (UserProfileContract) يجسّد المنطق الحالي للحرق والتوجيه وحدود التداول. يجب أن يدعم إعدادات JSON المشابهة لـ SmartUserContract.
2. تهيئة آلية النشر: استخدم مصنعاً (Factory) أو عقود قابلة للاستنساخ لضمان نشر عقد جديد عند تسجيل كل مستخدم مع ربط العنوان بحساباته الحالية.
3. تدفق Rust: عدِّل SessionManager::registeruser وapplyusersmartcontract ليقوما بتهيئة العقد على Layer1 واستدعاء واجهاته بدلاً من تنفيذ المنطق محلياً.
4. الحوكمة والأمان: أضف اختبارات Solidity، وتحقق من ضبط الأذونات (مالك/حوكمة) بحيث لا يمكن تعديل قواعد المستخدم دون موافقته.
5. التدقيق والتوثيق: بعد اكتمال النقل، حدّث خانة الوثائق الأمامية والخلفية لتوضيح أن المنطق أصبح على السلسلة مع توفير ABI وروابط التحقق.

#Security Checks

Use scripts/runsecuritychecks.sh to run static linting and dependency audits before publishing new builds or Testnet releases.

scripts/run_security_checks.sh

The script runs:

1. cargo clippy --all-targets --all-features -- -D warnings

• Requires the Clippy component. Install once via:

     rustup component add clippy
     

1. cargo fmt --all -- --check
2. cargo audit

• Install with cargo install cargo-audit if missing.

1. cargo deny check

• Install with cargo install cargo-deny if missing.

All steps must pass without warnings before approving Testnet deployments.

#عناصر التحكم المكمّلة

• تم تعطيل مسار استرجاع مفاتيح الطوارئ المباشر (/getemergencykeyvalueendpoint) ويجب الاعتماد على تدفقات الاسترداد المصادقة فقط.
• خدمة معاينة الصفحات الآن ترفض أي نطاقات محلية أو خاصة افتراضياً؛ عدّل RENDERALLOWEDHOSTS بحذر وراجع docs/renderpreview.md.
• عميل الجلب الخارجي في Rust (RequestManager::fetchquic) يعتمد على reqwest مع مهلة 15 ثانية وحد أقصى للاستجابة 2MB، ما يقلل مخاطر الاستنزاف أو الحجب.

أضف هذه النقاط لقائمة التحقق قبل أي إطلاق: تأكد من أن إعدادات البيئة تعكس السياسات الجديدة وأن سجلات الوصول تُراجع عند تمكين نطاقات إضافية.

#Performance Metrics API

#Overview

The MQPYChain node now exposes runtime performance statistics that are collected directly from the ledger-backed transaction pipeline and consensus commit path.

• Endpoint: GET /metrics/performance
• Format: JSON
• Source: PerformanceMetrics aggregator shared by Layer1, ConsensusState, and the HTTP layer.

#Fields

| Field | Description | |-------|-------------| | totaltransactions | Cumulative count of processed Layer1 transactions. | | totalblocks | Total finalized blocks persisted through consensus or standalone mode. | | totalvolumemqpy | Sum of transferred MQPY volume (tokens) recorded in ledger micro-units. | | totalfeesmqpy | Total MQPY fees collected since startup. | | avgtxlatencyms | Moving average latency (milliseconds) from transaction intake to confirmation. | | maxtxlatencyms | Peak observed latency for any individual transaction. | | avgblocktimems | Average inter-block interval derived from recent consensus commits. | | rollingtps | Rolling transactions-per-second computed from the recent block sample window. | | rollingblocktimems | Rolling block time calculated across the same sample window. | | lasttxtimestamp | Wall-clock timestamp of the last confirmed transaction. | | lastblocktimestamp | Wall-clock timestamp of the most recent finalized block. | | lastblockheight | Height of the last finalized block. | | storagereadops | Total ledger read operations captured since startup. | | storagewriteops | Total ledger write operations captured since startup. | | storagereadmb | Aggregate volume of data read from ledger storage (megabytes). | | storagewritemb | Aggregate volume of data written to ledger storage (megabytes). | | avgstoragereadms | Average latency per ledger read operation. | | avgstoragewritems | Average latency per ledger write operation. |

curl -s http://localhost:8787/metrics/performance | jq

• Use rollingtps for short-term throughput monitoring.
• avgtxlatencyms helps catch congestion and ledger backpressure.
• Combine totalvolumemqpy and totalfeesmqpy with explorer data for economic dashboards.

• Metrics are stored in-memory only; restart resets the counters.
• Increase the block sample window in metrics.rs (MAXBLOCK_SAMPLES) if you need longer smoothing.
• The endpoint is lightweight and safe to poll frequently for dashboards or alerting systems.

#mQUSDT Bridge Ledger & Messaging

#Ledger Overview

• Source: src/mqusdtledger.rs
• Storage layout: data/accounts/mqpy/mqusdtbalances/<user>.acc (u128 micro units) and mqusdttotalsupply.json.
• API surface:
• MqusdtLedger::balanceof(user) → read balance.
• credit/debit → increase or decrease balance with supply tracking.
• transfer → convenience helper built on credit/debit.
• Metrics: read/write calls report byte counts and latency to PerformanceMetrics (see /metrics/performance).

• OverledgerBridge::sendmqusdtevent wraps sendtransaction with structured payloads.
• Envelope format (BridgeEnvelope):

  {
    "asset": "MQUSDT",
    "action": "Deposit|WithdrawRequest|WithdrawConfirm|WithdrawReject",
    "user_id": "<id>",
    "amount_micro": 1000000,
    "from_chain": "mq.mainnet",
    "to_chain": "external.eth",
    "external_tx": "0x...",
    "metadata": { ... },
    "timestamp": 1730000000,
    "reserve_id": "92b0c35f-...",
    "contract_id": "user123_default"
  }
  

• Helper payload (MqusdtBridgePayload) ensures all fields are captured before serialisation.
• Actions are validated, and the message is serialized via serdejson to reuse existing Kademlia transport.

• Global tracker: src/bridgereserve.rs maintains data/bridgereserves.json with totals per asset (deposited, withdrawn, pending, external outstanding).
• The tracker deduplicates reserveid values to prevent reprocessing and feeds the /api/bridge/reserves endpoint for Proof-of-Reserves reporting.
• Withdrawals increase externaloutstandingmicro, while deposits decrease it and clear pending amounts, keeping wrapped supply aligned with internal balances.
• External relayers update reserves by calling POST /api/bridge/relayer (see src/relayer.rs), passing the reserveid, optional contractid, amount, and event type (withdrawconfirm, withdrawreject, or burn).
• src/contractregistry.rs persists UserContractMetadata (user → contract id/internal address) so every bridge event can be attributed to the correct per-user smart contract.