Dory/Datre 项目完整技术文档

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   前端应用      │    │   API服务层     │    │   子图索引      │
│   (Web/Mobile) │◄──►│   (FastAPI)     │◄──►│   (The Graph)   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │                       │
                                │                       │
                                ▼                       ▼
                       ┌─────────────────────────────────────┐
                       │         Arbitrum One               │
                       │      (智能合约层)                  │
                       │    ┌─────────────────────────────┐  │
                       │    │      DoryContract          │  │
                       │    │   (UUPS代理模式)           │  │
                       │    └─────────────────────────────┘  │
                       └─────────────────────────────────────┘

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

contracts/
├── datre-token/             # Datre Token 合约模块
│   ├── contracts/          # 智能合约源码
│   │   └── Datre.sol      # 主合约文件
│   ├── test/               # 测试文件
│   │   └── Datre.test.js  # 合约测试
│   ├── scripts/            # 部署脚本
│   │   └── deploy.js      # 部署脚本
│   ├── artifacts/          # 编译产物
│   ├── cache/             # 编译缓存
│   ├── hardhat.config.js   # Hardhat 配置
│   ├── package.json        # 合约依赖
│   └── README.md           # 项目说明
├── datre-hook/              # Uniswap v4 Hook 合约模块
│   ├── contracts/          # Hook 合约源码
│   ├── test/               # 测试用例
│   ├── scripts/            # 部署脚本
│   ├── hardhat.config.js   # Hardhat 配置
│   └── package.json        # Hook 依赖
└── datre-distributor/        # 代币分发合约模块
    ├── contracts/          # 分发合约源码
    ├── test/               # 测试用例
    ├── scripts/            # 部署脚本
    ├── hardhat.config.js   # Hardhat 配置
    └── package.json        # 分发合约依赖

1
2
3
4
5
6
7

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;

contract DoryContract is Initializable, ERC20Upgradeable, OwnableUpgradeable, UUPSUpgradeable {
    string public constant VERSION = "1.0.0";
    // ... 其他代码
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

contract SimpleDatreHook is Ownable {
    uint256 public constant BPS_DENOM = 10000;
    uint256 public feeBps = 500; // 5%

    address public immutable feeRecipient;
    address public immutable blackhole;
    address public immutable power;
    IERC20 public immutable datre;
    IERC20 public immutable usdc;

    function simulateSellDatre(uint256 datreAmount) external;
    function simulateBuyDatre(uint256 usdcAmount, address user) external;
    function setFeeBps(uint256 _feeBps) external onlyOwner;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

struct UserInfo {
    address referrer;      // 推荐人地址
    uint256 power;         // 算力值
    uint256 joinTime;      // 加入时间
    uint256 updateTime;    // 最后更新时间
    uint256 reserved1;     // 保留字段1
    uint256 reserved2;     // 保留字段2
    bytes32 reserved3;     // 保留字段3
    bool reserved4;        // 保留字段4
}

1
2
3
4
5
6

struct NodeConfig {
    uint256 price;         // 节点价格 (USDT, 6位小数)
    uint256 power;         // 节点算力
    uint256 remaining;     // 剩余数量
    bool isActive;         // 是否开放购买
}

1
2
3
4
5
6
7

struct FreezeRecord {
    uint256 amount;        // 冻结金额
    uint256 timestamp;     // 冻结时间
    uint256 expireTime;    // 到期时间 (0表示永久冻结)
    string reason;         // 冻结原因
    bool isActive;         // 是否激活状态
}

1
2
3

event ReferrerSet(address indexed account, address indexed referrer, uint256 timestamp);
event ReferrerModified(address indexed account, address indexed oldReferrer, address indexed newReferrer, uint256 timestamp);
event ReferralRelationshipEstablished(address indexed referrer, address indexed referee, uint256 timestamp);

1

event PowerUpdated(address indexed account, uint256 oldPower, uint256 newPower, uint256 timestamp);

1
2

event NodePurchased(address indexed buyer, NodeType indexed nodeType, uint256 usdtAmount, uint256 powerGained, uint256 timestamp);
event NodeConfigUpdated(NodeType indexed nodeType, uint256 price, uint256 power, uint256 remaining, bool isActive);

1
2
3

event FundsFreezed(address indexed account, uint256 indexed freezeId, uint256 amount, string reason);
event FundsUnfreezed(address indexed account, uint256 indexed freezeId, uint256 amount);
event FundsAutoUnfreezed(address indexed account, uint256 indexed freezeId, uint256 amount);

1
2
3
4
5
6
7
8

dataSources:
  - kind: ethereum
    name: DoryContract
    network: arbitrum-one
    source:
      address: "0x6174B1868c61c05Eb520E06ad312E8dd0Af8C553"
      abi: DoryContract
      startBlock: 362672657

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

type User @entity {
  id: ID!                    # 用户地址
  address: Bytes!            # 用户地址
  power: BigInt!             # 用户算力
  referreeCount: BigInt!     # 直接被推荐人数量
  bindingTime: BigInt!       # 绑定时间

  # 推荐关系
  referrees: [User!]! @derivedFrom(field: "referrer")
  referrer: User

  # 推荐关系记录
  referralRelationships: [ReferralRelationship!]! @derivedFrom(field: "referee")
  referrerRelationships: [ReferralRelationship!]! @derivedFrom(field: "referrer")
}

1
2
3
4
5
6
7

type ReferralRelationship @entity {
  id: ID!                    # 推荐关系ID
  referrer: User!            # 推荐人
  referee: User!             # 被推荐人
  timestamp: BigInt!         # 绑定时间
  isActive: Boolean!         # 是否活跃
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

export function handleReferrerSet(event: ReferrerSet): void {
  let user = getOrCreateUser(event.params.account);
  let referrer = getOrCreateUser(event.params.referrer);

  // 检查是否已经存在推荐关系，避免重复计算
  if (user.referrer == null) {
    // 设置推荐人和绑定时间
    user.referrer = referrer.id;
    user.bindingTime = event.params.timestamp;
    user.save();

    // 更新推荐人的直接推荐人数量
    updateReferreeCount(referrer, true);
  }

  // 创建推荐关系记录
  let relationship = new ReferralRelationship(
    event.transaction.hash.toHexString() + "-" + event.logIndex.toString()
  );
  relationship.referrer = referrer.id;
  relationship.referee = user.id;
  relationship.timestamp = event.params.timestamp;
  relationship.isActive = true;
  relationship.save();
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

export function handleReferrerModified(event: ReferrerModified): void {
  let user = getOrCreateUser(event.params.account);
  let oldReferrer: User | null = null;
  let newReferrer: User | null = null;

  // 获取旧推荐人
  if (user.referrer != null) {
    oldReferrer = User.load(user.referrer!);
  }

  // 设置新推荐人
  if (!event.params.newReferrer.equals(Address.zero())) {
    newReferrer = getOrCreateUser(event.params.newReferrer);
    user.referrer = newReferrer.id;
  } else {
    user.referrer = null;
  }

  user.save();

  // 创建新的推荐关系（如果新推荐人不为空）
  if (!event.params.newReferrer.equals(Address.zero())) {
    let relationship = new ReferralRelationship(
      event.transaction.hash.toHexString() + "-" + event.logIndex.toString()
    );
    relationship.referrer = newReferrer!.id;
    relationship.referee = user.id;
    relationship.timestamp = event.params.timestamp;
    relationship.isActive = true;
    relationship.save();
  }

  // 更新旧推荐人的直接推荐人数量
  if (oldReferrer) {
    updateReferreeCount(oldReferrer, false);
  }

  // 更新新推荐人的直接推荐人数量
  if (newReferrer) {
    updateReferreeCount(newReferrer, true);
  }
}

1
2
3
4
5

export function handlePowerUpdated(event: PowerUpdated): void {
  let user = getOrCreateUser(event.params.account);
  user.power = event.params.newPower;
  user.save();
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

function getOrCreateUser(address: Address): User {
  let user = User.load(address.toHexString());
  if (!user) {
    user = new User(address.toHexString());
    user.address = address;
    user.power = BigInt.fromI32(0);
    user.referreeCount = BigInt.fromI32(0);
    user.bindingTime = BigInt.fromI32(0);
    user.save();
  }
  return user;
}

1
2
3
4
5
6
7
8

function updateReferreeCount(user: User, increment: boolean): void {
  if (increment) {
    user.referreeCount = user.referreeCount.plus(BigInt.fromI32(1));
  } else {
    user.referreeCount = user.referreeCount.minus(BigInt.fromI32(1));
  }
  user.save();
}

1
2
3
4
5

function recalculateReferreeCount(user: User): void {
  // 重置计数
  user.referreeCount = BigInt.fromI32(0);
  user.save();
}

1
2
3
4
5

function validateReferreeCount(user: User): void {
  // 这里可以添加验证逻辑
  // 如果发现数量不匹配，可以重新计算
  user.save();
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

datre/
├── contracts/                    # 智能合约目录
│   ├── datre-token/             # Datre Token 合约
│   │   ├── Datre.sol           # 主合约文件 (ERC-20 + 推荐系统)
│   │   ├── artifacts/          # 编译产物
│   │   ├── hardhat.config.js   # Hardhat 配置
│   │   └── package.json        # 合约依赖
│   └── datre-hook/              # Uniswap v4 Hook 合约
│       ├── contracts/          # Hook 合约源码
│       ├── test/               # 测试用例
│       ├── scripts/            # 部署脚本
│       ├── hardhat.config.js   # Hardhat 配置
│       └── package.json        # Hook 依赖
├── ledger/                     # 数据同步服务
│   ├── program/                # 同步程序
│   │   ├── core/              # 核心模块
│   │   ├── sync/              # 同步模块
│   │   └── run.py             # 启动脚本
│   ├── config/                # 配置文件
│   └── database/              # 数据库初始化
├── service/                    # API 服务
│   ├── program/               # API 程序
│   │   ├── app.py            # FastAPI 应用
│   │   ├── db.py             # 数据库操作
│   │   └── run.py            # 启动脚本
│   └── config/               # 配置文件
├── subgraph/                   # 子图索引
│   ├── src/                  # 映射源码
│   ├── abis/                 # 合约 ABI
│   └── schema.graphql        # 数据模式
└── README.org                 # 项目文档

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

@app.get("/v1/user", response_model=UserResponse)
async def get_user(address: str = Query(..., description="钱包地址")):
    """
    获取用户信息

    Args:
        address: 钱包地址（需要小写）

    Returns:
        用户信息，包括推荐人列表和绑定时间
    """

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

class UserResponse(BaseModel):
    code: int = 0
    msg: str = "success"
    data: Optional[dict] = None

class User(BaseModel):
    id: str
    address: str
    power: float
    level: int = 0
    smallCommunityPower: float = 0.0      # 小区算力
    communityPower: float = 0.0           # 社区算力
    maxCommunityPower: float = 0.0        # 大区算力
    powerDecay: int = 0                   # 算力衰减
    expectedReward: float = 0.0           # 预计收益
    referreeCount: int
    referrees: List[Referree]

class Referree(BaseModel):
    id: str
    address: str
    power: float
    bindingTime: int
    communityPower: float  # 社区算力

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 处理地址格式
address = address.lower()

# 添加0x前缀（如果没有）
if not address.startswith('0x'):
    address = '0x' + address

# 验证地址格式
if not Web3.is_address(address):
    return UserResponse(code=0, msg="无效的钱包地址格式", data={})

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

query = """
{
  user(id: "%s") {
    id
    address
    power
    referreeCount
    referrees(first: 100) {
      id
      address
      power
      bindingTime
    }
  }
}
""" % address

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 转换数据格式
referrees = []
for ref in user_data.get("referrees", []):
    ref_power = float(ref["power"])
    referrees.append(Referree(
        id=Web3.to_checksum_address(ref["id"]),
        address=Web3.to_checksum_address(ref["address"]),
        power=ref_power,
        bindingTime=int(ref["bindingTime"]),
        communityPower=ref_power  # 社区算力等于本人算力
    ))

# 按照绑定时间倒序排列
referrees.sort(key=lambda x: x.bindingTime, reverse=True)

1
2
3
4
5
6

# 加载环境变量
load_dotenv()

# 配置
SUBGRAPH_URL = os.getenv("SUBGRAPH_URL", "https://api.studio.thegraph.com/query/117650/dory/version/latest")
API_KEY = os.getenv("API_KEY", "3775070ab8c4f893227a8b8e42f00818")

1
2
3
4
5
6
7
8

# 添加 CORS 中间件
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

1
2
3
4
5

if response.status_code != 200:
    raise HTTPException(
        status_code=500,
        detail=f"Subgraph request failed: {response.status_code}"
    )

1
2
3
4
5
6
7

# 检查是否有错误
if "errors" in data:
    error_msg = data["errors"][0]["message"] if data["errors"] else "Unknown error"
    raise HTTPException(
        status_code=400,
        detail=f"GraphQL error: {error_msg}"
    )

1
2
3
4
5
6
7

# 检查用户是否存在
if not data.get("data", {}).get("user"):
    return UserResponse(
        code=0,
        msg="error",
        data={}
    )

1
2
3

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8911)

1
2
3
4
5
6
7

# requirements.txt
fastapi
uvicorn
httpx
pydantic
python-dotenv
web3

1
2
3
4
5
6
7
8

用户操作 → 智能合约 → 事件触发 → 子图监听 → 数据索引 → API查询 → 前端展示
    │           │           │           │           │           │
    │           │           │           │           │           └── 用户界面
    │           │           │           │           └── 业务逻辑处理
    │           │           │           └── GraphQL查询
    │           │           └── 实体创建/更新
    │           └── 状态变更
    └── 交易提交

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 代码生成
graph codegen

# 构建子图
graph build

# 部署到 Graph Studio
graph deploy dory

# 本地测试
graph create --node http://localhost:8020 dory
graph deploy --node http://localhost:8020 --ipfs http://localhost:5001 dory

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 安装依赖
pip install -r requirements.txt

# 启动服务
python main.py

# 后台运行
nohup python main.py > app.log 2>&1 &

# 停止服务
pkill -f "python main.py"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 进入合约目录
cd contracts/datre-token

# 安装合约依赖
npm install

# 编译合约
npm run compile

# 运行测试
npm run test

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# 进入 Hook 合约目录
cd contracts/datre-hook

# 安装依赖
npm install

# 编译合约
npm run compile

# 运行测试
npm test

# 部署合约
npm run deploy

# 查找 CREATE2 盐（用于主网部署）
npm run find-salt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 创建新合约目录
mkdir contracts/new-contract

# 初始化新合约
cd contracts/new-contract
npm init -y

# 添加 Hardhat 依赖
npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox

# 创建 hardhat.config.js 配置文件
# 添加合约源码和测试文件

1
2
3
4
5
6
7
8

# 安装 Node.js 依赖
npm install -g @graphprotocol/graph-cli

# 安装 Python 依赖
pip install fastapi uvicorn httpx pydantic python-dotenv web3

# 安装 Solidity 编译器
npm install -g solc