# architecture

## System Overview

{% @mermaid/diagram content="flowchart TB
subgraph Users\["User & Agent Actions"]
BUY\[Buy BGOLD]
SELL\[Sell BGOLD]
CLAIM\[Claim VNXAU]
PROTECT\[Buy Protection]
AGENT\[AI Agent X402]
end

```
subgraph Tax["5% Tax Distribution"]
    FEE[5% Fee Collected]
    REF[49.5% Reflections]
    MKT[49.5% Marketing]
    LIQ[1% Liquidity]
end

subgraph Rewards["Reward System"]
    VNXAU[VNXAU Pool]
    PROT[Protection Reserve]
end

subgraph AILayer["AI Agent Layer"]
    X402[X402 Protocol v2]
    SDK[Agent SDK]
    VERIFY[Payment Verification]
end

BUY --> FEE
SELL --> FEE
AGENT --> X402
X402 --> BUY

FEE --> REF
FEE --> MKT
FEE --> LIQ

REF --> VNXAU
CLAIM --> VNXAU
PROTECT --> PROT

X402 --> VERIFY
SDK --> X402" %}
```

***

## Smart Contract Design

### BaseGold Token Contract

{% code title="BaseGold.sol (summary)" %}

```solidity
// Key functions
- transfer() - Standard ERC-20 with reflection logic
- pan() - Claim accumulated VNXAU rewards
- checkPendingReflections() - View pending rewards
- setIsDividendExempt() - Admin function for exchanges
```

{% endcode %}

### BaseGold Distributor

* Tracks holder balances (shares)
* Calculates proportional rewards
* Executes VNXAU distribution via Slipstream
* Handles batch processing

### SwapReceiver Contract

* Receives WETH from token swaps
* Withdraws and forwards ETH to main contract
* Rescue function for stuck tokens

### Protection Contract (Coming Q3 2026)

* Policy purchases and tracking
* Claim verification
* Solvency management
* VNXAU payout execution

### X402 Payment Handler (Coming Q3 2026)

* Payment proof verification
* Rate limiting
* Multi-currency support
* Agent authentication

***

## Implementation Status

| Component                            | Status      | Contract/System           |
| ------------------------------------ | ----------- | ------------------------- |
| **Core Token**                       | ✅ Deployed  | `BaseGold.sol`            |
| **VNXAU Distributor**                | ✅ Deployed  | `BaseGoldDistributor.sol` |
| **SwapReceiver**                     | ✅ Deployed  | `SwapReceiver.sol`        |
| **Manual Claim (`pan()`)**           | ✅ Live      | Part of BaseGold          |
| **Batch Distribution (`process()`)** | ✅ Live      | Part of Distributor       |
| **GoldXBT Intelligence Engine**      | 🔄 Building | Backend AI system         |
| **GoldXBT API**                      | 🔄 Building | REST endpoints            |
| **GoldXBT Twitter**                  | 📋 Q2 2026  | Auto-posting bot          |
| **Holder Tier Verification**         | 📋 Q2 2026  | Backend + on-chain check  |
| **AI Auto-Distribution**             | 📋 Q2 2026  | Bot calling `process()`   |
| **X402 Gateway**                     | 📋 Q3 2026  | New contract needed       |
| **Gold-Backed Protection**           | 📋 Q3 2026  | New contract needed       |
| **Premium WebSocket**                | 📋 Q3 2026  | Backend service           |

***

## Security Features

{% hint style="warning" %}
Security measures apply across contracts and backend systems. Emergency mechanisms and access controls are in place to reduce attack surface and limit blast radius.
{% endhint %}

### Reentrancy Protection

All state-changing functions protected against reentrancy attacks using custom lock modifiers.

### Access Control

Owner-based permissions for admin functions with ownership transfer capability.

### Emergency Stop

Emergency pause mechanism to halt trading and distributions if vulnerabilities discovered.

### Rate Limiting

* Maximum deposit limits per swap (1.5 ETH)
* Maximum gas limits for batch processing
* Price impact caps on swaps (2% max)

### Slippage Protection

Built-in slippage tolerance (10%) for VNXAU swaps during reward distribution.

***

## Web3 Frontend

### Technology Stack

* React 18 + TypeScript
* Viem + Wagmi for blockchain interaction
* RainbowKit for wallet connections
* TanStack Query for data management

### Key Features

* Real-time balance tracking
* Live reward calculations
* Transaction history
* Price charts
* Protection status dashboard
* Mobile-responsive design

### User Experience

* One-click wallet connection
* Instant reward claiming
* Transaction notifications
* USD value calculations
* BaseScan integration


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://basegold.gitbook.io/basegold/technical/architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.