# 获取 MCD 余额
curl -X GET "https://api.microcosm.money/v1/mcd/balance" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json"

{
  "data": {
    "type": "mcd_balance",
    "id": "user_123",
    "attributes": {
      "total_balance": "1250.50",
      "available_balance": "1200.00",
      "frozen_balance": "50.50",
      "updated_at": "2026-01-08T10:30:00Z"
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "api_version": "v1"
  }
}

{
  "type": "https://api.microcosm.money/errors/insufficient-scope",
  "title": "Insufficient Scope",
  "status": 403,
  "detail": "The access token does not have the 'mcd:read' scope required for this endpoint.",
  "instance": "/v1/mcd/balance"
}

{
  "type": "https://api.microcosm.money/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded the rate limit of 1000 requests per minute.",
  "retry_after": 45
}

# open-api-service 部署
apiVersion: apps/v1
kind: Deployment
metadata:
  name: open-api-service
  namespace: microcosm
spec:
  replicas: 2  # HA 部署
  template:
    spec:
      containers:
      - name: open-api-service
        image: asia-northeast1-docker.pkg.dev/microcosm/microcosm/open-api-service:v1.0.0
        resources:
          requests:
            cpu: 200m
            memory: 256Mi
          limits:
            cpu: 500m
            memory: 512Mi

// frontend-service/lib/api/services.ts

const MICROCOSM_API_BASE = 'https://api.microcosm.money/v1'

export async function getMCDBalance(): Promise<APIResponse<MCDBalanceType>> {
  const token = getAccessToken()
  const response = await fetch(`${MICROCOSM_API_BASE}/mcd/balance`, {
    headers: {
      'Authorization': `Bearer ${token}`,
      'Accept': 'application/json'
    }
  })
  return response.json()
}

export async function getMCDTransactions(params?: MCDHistoryParams): Promise<APIResponse<MCDTransaction[]>> {
  const token = getAccessToken()
  const queryString = new URLSearchParams(params as any).toString()
  const response = await fetch(`${MICROCOSM_API_BASE}/mcd/transactions?${queryString}`, {
    headers: {
      'Authorization': `Bearer ${token}`,
      'Accept': 'application/json'
    }
  })
  return response.json()
}

# open-api-service CORS 配置
ALLOWED_ORIGINS = [
    "https://doublehelix.money",
    "https://www.doublehelix.money",
    "https://poly.microcosm.money",
    "https://microcosm.money",
    # 开发环境
    "http://localhost:3000",
    "http://localhost:3001",
]

openapi: 3.1.0
info:
  title: Microcosm Open API
  version: 1.0.0
  description: Public API for Microcosm ecosystem

servers:
  - url: https://api.microcosm.money/v1
    description: Production

security:
  - oauth2: []

paths:
  /mcd/balance:
    get:
      summary: Get MCD Balance
      operationId: getMCDBalance
      security:
        - oauth2: [mcd:read]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCDBalanceResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.microcosm.money/oauth/authorize
          tokenUrl: https://auth.microcosm.money/oauth/token
          scopes:
            mcd:read: Read MCD balance and transactions
            mcc:read: Read MCC balance and transactions
            user:read: Read user profile
            org:read: Read organization information
            mining:read: Read mining records and stats

# 1. 部署 Redis
kubectl apply -f services/open-api-service/k8s/redis.yaml

# 2. 构建并部署 open-api-service
cd services/open-api-service
gcloud builds submit --config=cloudbuild.yaml --region=asia-northeast1 \
  --substitutions=_IMAGE_URI=<registry>/<project>/open-api-service:<version> .

# 3. 更新部署
kubectl set image deploy/open-api-service \
  open-api-service=<registry>/<project>/open-api-service:<version> \
  -n microcosm

POST /v1/mining/submit-activity
Authorization: Bearer {project_access_token}
X-Project-ID: double_helix

{
  "user_uid": "Drt0n1i6y1UVF8wqydT3ckQewM22",
  "activity_type": "trading",
  "activity_data": {
    "trade_volume_usdc": 10000,
    "trade_count": 15,
    "profit_usdc": 250
  },
  "proof": {
    "type": "signed_hash",
    "hash": "0x...",
    "signature": "...",
    "timestamp": "2026-01-10T12:00:00Z"
  },
  "idempotency_key": "dh-2026-01-10-user123-batch1"
}

{
  "data": {
    "type": "mining_activity",
    "id": "act_abc123",
    "attributes": {
      "status": "pending_verification",
      "mcd_estimated": "50.00",
      "created_at": "2026-01-10T12:00:01Z"
    }
  },
  "meta": {
    "webhook_url": "Will notify when confirmed"
  }
}

POST /v1/funds/lock
Authorization: Bearer {project_access_token}
X-Project-ID: event_horizon

{
  "user_uid": "user123",
  "currency": "MCC",
  "amount": "100.00",
  "reason": "auction_bid",
  "reference_id": "auction_456",
  "expires_at": "2026-01-11T00:00:00Z",
  "idempotency_key": "eh-auction-456-bid-user123"
}

{
  "data": {
    "type": "fund_lock",
    "id": "lock_xyz789",
    "attributes": {
      "status": "locked",
      "user_uid": "user123",
      "currency": "MCC",
      "amount": "100.00",
      "available_balance": "900.00",
      "locked_until": "2026-01-11T00:00:00Z"
    }
  }
}

POST /v1/transfer/request
Authorization: Bearer {project_access_token}
X-Project-ID: event_horizon

{
  "transfer_type": "auction_settlement",
  "from_uid": "bidder_user",
  "to_uid": "seller_user",
  "currency": "MCC",
  "amount": "100.00",
  "reference": {
    "auction_id": "auction_456",
    "item_id": "item_789"
  },
  "requires_onchain": true,
  "idempotency_key": "eh-auction-456-settlement"
}

POST /v1/webhooks/register
Authorization: Bearer {project_access_token}

{
  "url": "https://doublehelix.money/api/webhooks/microcosm",
  "events": ["mining.reward.confirmed", "transfer.completed"],
  "secret": "whsec_xxx..."
}

POST https://doublehelix.money/api/webhooks/microcosm
X-Microcosm-Signature: sha256=xxx...
X-Microcosm-Event: mining.reward.confirmed
X-Microcosm-Delivery: evt_123

{
  "id": "evt_abc123",
  "type": "mining.reward.confirmed",
  "created_at": "2026-01-10T12:05:00Z",
  "data": {
    "activity_id": "act_abc123",
    "user_uid": "Drt0n1i6y1UVF8wqydT3ckQewM22",
    "mcd_amount": "50.00",
    "tx_signature": "5xyz...abc",
    "block_height": 12345678
  }
}

import hmac
import hashlib

def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

POST /v1/projects/register
Authorization: Bearer {admin_token}

{
  "project_id": "double_helix",
  "name": "Double Helix Trading",
  "description": "Quantitative trading platform",
  "webhook_url": "https://doublehelix.money/api/webhooks/microcosm",
  "allowed_scopes": [
    "mining:write",
    "mining:read",
    "funds:read"
  ],
  "rate_limit_tier": "standard"
}

import hmac
import hashlib
import json
import time

def generate_signature(api_secret: str, method: str, path: str, body: dict, timestamp: int) -> str:
    """
    生成 API 请求签名

    签名格式: HMAC-SHA256(secret, method + path + timestamp + body_json)
    """
    body_json = json.dumps(body, separators=(',', ':'), sort_keys=True)
    payload = f"{method}\n{path}\n{timestamp}\n{body_json}"
    signature = hmac.new(
        api_secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return f"sha256={signature}"


# 使用示例
signature = generate_signature(
    api_secret="whsec_xxx...",
    method="POST",
    path="/v1/mining/submit-activity",
    body={"user_uid": "user123", "activity_type": "trading", ...},
    timestamp=int(time.time())
)

def verify_signature(request) -> bool:
    project_id = request.headers.get("X-Project-ID")
    timestamp = int(request.headers.get("X-Timestamp", 0))
    signature = request.headers.get("X-Signature", "")

    # 1. 时间戳验证 (5分钟窗口)
    if abs(time.time() - timestamp) > 300:
        return False

    # 2. 获取项目密钥
    api_secret = get_project_secret(project_id)
    if not api_secret:
        return False

    # 3. 重新计算签名
    expected = generate_signature(
        api_secret=api_secret,
        method=request.method,
        path=request.path,
        body=request.json(),
        timestamp=timestamp
    )

    # 4. 常量时间比较
    return hmac.compare_digest(expected, signature)

# Redis 存储已使用的 idempotency_key
def check_idempotency(key: str) -> bool:
    """返回 True 表示该 key 首次使用，False 表示重复"""
    result = redis.set(f"idempotency:{key}", "1", nx=True, ex=86400)  # 24小时过期
    return result is not None

-- 所有交易类操作记录
CREATE TABLE transaction_audit_log (
    id SERIAL PRIMARY KEY,
    project_id VARCHAR(50) NOT NULL,
    operation_type VARCHAR(50) NOT NULL,  -- 'mining_submit', 'funds_lock', 'transfer'
    user_uid VARCHAR(100) NOT NULL,
    request_body JSONB NOT NULL,
    response_body JSONB,
    status VARCHAR(20) NOT NULL,  -- 'success', 'failed', 'pending'
    idempotency_key VARCHAR(100) UNIQUE,
    ip_address INET,
    created_at TIMESTAMP DEFAULT NOW()
);

-- 用户项目属性表
CREATE TABLE user_project_attributes (
    id SERIAL PRIMARY KEY,
    uid VARCHAR(100) NOT NULL,                    -- 用户 UID
    project_id VARCHAR(50) NOT NULL,              -- 项目 ID
    attribute_key VARCHAR(100) NOT NULL,          -- 属性键
    attribute_value JSONB NOT NULL,               -- 属性值 (支持复杂结构)
    visibility VARCHAR(20) DEFAULT 'private',     -- public/private/authorized
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    UNIQUE(uid, project_id, attribute_key)
);

-- 项目状态历史表
CREATE TABLE project_status_history (
    id SERIAL PRIMARY KEY,
    project_id VARCHAR(50) NOT NULL,
    status VARCHAR(20) NOT NULL,                  -- active/maintenance/testing/discontinued/deleted
    reason TEXT,
    changed_by VARCHAR(100),                      -- 操作者 UID
    created_at TIMESTAMP DEFAULT NOW()
);

-- 索引
CREATE INDEX idx_user_project_attrs_uid ON user_project_attributes(uid);
CREATE INDEX idx_user_project_attrs_project ON user_project_attributes(project_id);
CREATE INDEX idx_project_status_history ON project_status_history(project_id, created_at DESC);

class RequireScope:
    # OpenID Connect 标准 scope 到 Microcosm scope 的映射
    SCOPE_ALIASES = {
        "profile": {"user:read"},  # OIDC profile scope 等同于 user:read
    }

    async def __call__(self, request: Request) -> UserInfo:
        user = await verify_oauth_token(request)
        user_scopes = set(user.scopes)

        # 展开 scope 别名 (OpenID Connect 兼容)
        expanded_scopes = set(user_scopes)
        for scope in user_scopes:
            if scope in self.SCOPE_ALIASES:
                expanded_scopes.update(self.SCOPE_ALIASES[scope])

        # 管理员角色自动拥有所有权限
        if user.role == "admin":
            return user

        # 检查是否拥有所需的 scope
        missing_scopes = self.required_scopes - expanded_scopes
        ...

def get_user_by_uid(uid: str) -> Optional[Dict[str, Any]]:
    ...
    return {
        'uid': user['uid'],
        'email': user.get('email'),
        'wallet_address': user.get('wallet_address'),
        'role': user.get('role', 'user'),
        'api_keys_configured': user.get('api_keys_configured', False),
        'display_name': user.get('display_name'),    # 新增
        'avatar_url': user.get('avatar_url'),        # 新增
        'created_at': user.get('created_at'),
        'updated_at': user.get('updated_at')
    }

// 修复前 ❌
authManager.setUser({
  uid: userData.uid,
  email: userData.email || "",
  role: finalRole as any,
  apiKeysConfigured: userData.api_keys_configured || false,
})

// 修复后 ✅
authManager.setUser({
  uid: userData.uid,
  email: userData.email || "",
  role: finalRole as any,
  displayName: userData.display_name || null,   // 新增
  avatarUrl: userData.avatar_url || null,       // 新增
  apiKeysConfigured: userData.api_keys_configured || false,
})

{
  "data": {
    "type": "mcc_price",
    "attributes": {
      "price_usdc": "10.50",
      "source": "admin",
      "updated_at": "2026-01-19T10:00:00Z"
    }
  }
}

{
  "price_usdc": "10.50"
}

{
  "data": {
    "type": "mcc_price",
    "attributes": {
      "price_usdc": "10.50",
      "source": "admin",
      "updated_at": "2026-01-19T10:00:00Z"
    }
  }
}

CREATE TABLE project_applications (
    id SERIAL PRIMARY KEY,
    application_id VARCHAR(36) NOT NULL UNIQUE,    -- UUID
    project_name VARCHAR(100) NOT NULL,            -- 项目名称
    project_description TEXT,                       -- 项目描述
    developer_uid VARCHAR(100) NOT NULL,           -- 申请人 Firebase UID
    developer_email VARCHAR(255) NOT NULL,         -- 申请人邮箱
    company_name VARCHAR(100),                     -- 公司名称
    website_url VARCHAR(255),                      -- 项目官网

    -- 钱包地址
    mcc_wallet_address VARCHAR(64),                -- MCC 收款钱包地址
    mcd_wallet_address VARCHAR(64) NOT NULL,       -- MCD 收款钱包地址 (必填)

    -- 审核信息
    status VARCHAR(20) NOT NULL DEFAULT 'pending', -- pending/approved/rejected/suspended
    reviewed_by VARCHAR(100),                      -- 审核人 UID
    reviewed_at TIMESTAMP,                         -- 审核时间
    rejection_reason TEXT,                         -- 拒绝原因

    -- 批准后生成
    project_id INTEGER,                            -- 数据库自增 ID (审批后生成)
    api_key VARCHAR(64),                           -- API Key (审批后生成)
    api_secret_hash VARCHAR(128),                  -- API Secret Hash

    -- 链上信息
    whitelist_pda VARCHAR(64),                     -- 链上白名单 PDA 地址
    whitelist_bump INTEGER,                        -- PDA bump
    whitelist_tx VARCHAR(128),                     -- 上链交易签名

    -- 时间戳
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_project_apps_status ON project_applications(status);
CREATE INDEX idx_project_apps_developer ON project_applications(developer_uid);
CREATE INDEX idx_project_apps_project_id ON project_applications(project_id);

-- 此表已存在于 organization-service
-- 参考 CLAUDE.md 中的 MCD 白名单机制说明
CREATE TABLE mcd_wallet_whitelist (
    id SERIAL PRIMARY KEY,
    project_id INTEGER NOT NULL UNIQUE,
    project_name VARCHAR(100) NOT NULL,
    wallet_address VARCHAR(64) NOT NULL,
    pda_address VARCHAR(64),                       -- 链上 PDA 地址
    pda_bump INTEGER,
    status VARCHAR(20) NOT NULL DEFAULT 'active',  -- active/suspended/removed
    created_by VARCHAR(100) NOT NULL,              -- 创建人 UID
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_whitelist_wallet ON mcd_wallet_whitelist(wallet_address);
CREATE INDEX idx_whitelist_status ON mcd_wallet_whitelist(status);

{
  "project_name": "My DApp",
  "project_description": "A decentralized application for...",
  "company_name": "My Company Ltd.",
  "website_url": "https://mydapp.com",
  "mcc_wallet_address": "5uo1HYjQXokE9UAd8UYiwAKomL5WACqpQMbV2Ftk7pXx",
  "mcd_wallet_address": "GaQdEfHjJar2X3Kqo8ptAgyretc6hakX8ZqeLW1cmRuS"  // 官方开发者项目备用钱包地址
}

{
  "data": {
    "type": "project_application",
    "id": "app-uuid-12345",
    "attributes": {
      "project_name": "My DApp",
      "status": "pending",
      "mcd_wallet_address": "GaQdEfHjJar2X3Kqo8ptAgyretc6hakX8ZqeLW1cmRuS"  // 官方开发者项目备用钱包地址,
      "created_at": "2026-01-26T10:00:00Z"
    }
  }
}

{
  "data": [
    {
      "type": "project_application",
      "id": "app-uuid-12345",
      "attributes": {
        "project_name": "My DApp",
        "status": "approved",
        "project_id": 2,
        "api_key": "mc_live_abc123...",
        "created_at": "2026-01-26T10:00:00Z",
        "reviewed_at": "2026-01-26T12:00:00Z"
      }
    }
  ]
}

{
  "data": [
    {
      "type": "project_application",
      "id": "app-uuid-12345",
      "attributes": {
        "project_name": "My DApp",
        "developer_email": "dev@example.com",
        "company_name": "My Company Ltd.",
        "mcd_wallet_address": "GaQdEfHjJar2X3Kqo8ptAgyretc6hakX8ZqeLW1cmRuS"  // 官方开发者项目备用钱包地址,
        "status": "pending",
        "created_at": "2026-01-26T10:00:00Z"
      }
    }
  ],
  "meta": {
    "total": 15,
    "page": 1,
    "per_page": 20
  }
}

{
  "data": {
    "type": "project_application",
    "id": "app-uuid-12345",
    "attributes": {
      "status": "approved",
      "project_id": 2,
      "api_key": "mc_live_xxxxxxxxxxxxxxxx",
      "api_secret": "mc_secret_yyyyyyyyyyyy",
      "whitelist_pda": "2sKFrgbgekkhw3jZgJiskP1YVhwKYrMkfLRTjHgD1Kio",
      "whitelist_tx": "5ScZLQTuFqw3..."
    }
  }
}

{
  "reason": "项目描述不符合接入标准"
}

{
  "data": [
    {
      "type": "mcd_whitelist_entry",
      "id": "1",
      "attributes": {
        "project_id": 2,
        "project_name": "Double Helix",
        "wallet_address": "4E4qsLLG2P88vLGTE4n39ayjaRAExbZRUdhJkrPCiBEA",
        "pda_address": "4Ch4RXdjUf5Mjw2L9R9zemCTRwTk1iE8rySrYq8rnnB7",
        "status": "active",
        "created_at": "2026-01-26T00:00:00Z"
      }
    }
  ]
}

{
  "status": "suspended"
}

{
  "data": {
    "type": "mcd_whitelist_entry",
    "id": "1",
    "attributes": {
      "status": "suspended",
      "updated_at": "2026-01-26T15:00:00Z"
    }
  }
}

{
  "data": {
    "message": "Project removed from whitelist",
    "remove_tx": "3kSVduyRZjYZAB2..."
  }
}

# Python 实现 (blockchain-service)
from solders.pubkey import Pubkey

MCD_PROGRAM_ID = Pubkey.from_string("J9UwVmFEr7ujLcp19T8nqpDnpBLcDzpL4cpwh5TMSd36")
MCD_WHITELIST_SEED = b"mcd_whitelist"

def get_whitelist_pda(project_id: int) -> tuple[Pubkey, int]:
    """计算白名单 PDA 地址"""
    project_id_bytes = project_id.to_bytes(8, 'little')
    pda, bump = Pubkey.find_program_address(
        [MCD_WHITELIST_SEED, project_id_bytes],
        MCD_PROGRAM_ID
    )
    return pda, bump

async def add_to_whitelist(
    project_id: int,
    project_name: str,
    wallet_address: str
) -> str:
    """
    调用 MCD 合约 add_to_whitelist 指令
    返回交易签名
    """
    # 1. 计算 PDA
    whitelist_pda, bump = get_whitelist_pda(project_id)

    # 2. 构造指令
    discriminator = get_instruction_discriminator("add_to_whitelist")
    # [8 bytes discriminator] + [8 bytes project_id] + [4 bytes name_len] + [name bytes]

    # 3. 发送交易
    tx_sig = await send_transaction(...)
    return tx_sig

// app/(dashboard)/developer/apply/page.tsx
export default function ProjectApplicationPage() {
  return (
    <div className="container mx-auto py-8">
      <h1>申请项目接入</h1>
      <ProjectApplicationForm />
    </div>
  )
}

// app/(dashboard)/admin/project-applications/page.tsx
export default function ProjectApplicationsAdminPage() {
  return (
    <div className="container mx-auto py-8">
      <h1>项目申请管理</h1>
      <Tabs defaultValue="pending">
        <TabsList>
          <TabsTrigger value="pending">待审核</TabsTrigger>
          <TabsTrigger value="approved">已批准</TabsTrigger>
          <TabsTrigger value="rejected">已拒绝</TabsTrigger>
        </TabsList>
        <TabsContent value="pending">
          <ApplicationList status="pending" />
        </TabsContent>
        {/* ... */}
      </Tabs>
    </div>
  )
}

// app/(dashboard)/admin/mcd-whitelist/page.tsx
export default function McdWhitelistAdminPage() {
  return (
    <div className="container mx-auto py-8">
      <h1>MCD 白名单管理</h1>
      <WhitelistTable />
    </div>
  )
}