ERC-20 Content Token Protocol

💡 The Account Value Paradox 💡 계정 가치의 역설

DeOAuth's Content Token system works just like in-app purchases on the Google Play Store. Every time a user buys an item in-game, that spending record (used_balances) is accumulated on-chain — permanently, immutably, and publicly queryable by anyone. DeOAuth의 컨텐츠 토큰 시스템은 구글 플레이스토어의 인앱 결제와 동일한 개념입니다. 사용자가 게임에서 아이템을 구매할 때마다 그 소비 기록(used_balances)이 온체인에 누적됩니다. 이 누적값은 영구적이고 불변이며, 외부에서 누구나 조회할 수 있습니다.

STEP 1 Provider Registration — Verify Ownership (Developer AA Wallet) Provider 등록 — 소유권 인증 (개발자 AA 지갑)

To participate in the Content Token system, your application must first be tied to a verified owner. There is no public REST endpoint for provider registration. It is currently done in the Developer Center with Verify Ownership, which proves ownership with your developer AA wallet. 컨텐츠 토큰 시스템에 참여하려면 먼저 앱이 인증된 소유자와 연결되어 있어야 합니다. Provider 등록용 공개 REST 엔드포인트는 없습니다. 현재는 개발자센터의 Verify Ownership(소유권 인증)으로 처리하며, 개발자 AA 지갑으로 소유권을 증명합니다.

STEP 2 Buy Content Token — buy_content_token 컨텐츠 토큰 구매 — buy_content_token

When a user pays XOTN, the smart contract instantly distributes revenue to Platform and Provider, then issues content tokens to the slot. 사용자가 XOTN을 지불하면, 스마트 컨트랙트가 즉시 Platform과 Provider에게 수익을 분배하고, 슬롯에 컨텐츠 토큰을 발급합니다.

XOTN Revenue Distribution XOTN 분배 구조

// Buy content token — user pays 0.01 XOTN | 컨텐츠 토큰 구매 — 사용자가 0.01 XOTN 지불
const response = await fetch('/v1/development-api/user_buy_content_token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client_id: 'your-client-id',
    user_dbkey: 'user-uuid-12345',
    amount: '10000000000000000', // 0.01 XOTN (wei)
    cuid: 'game-rpg-2026'
  })
});

const data = await response.json();
// data.tx_hash       — purchase transaction hash | 구매 트랜잭션 해시
// data.token_amount  — content tokens issued | 지급된 컨텐츠 토큰 수량

curl -X POST /v1/development-api/user_buy_content_token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "user_dbkey": "user-uuid-12345",
    "amount": "10000000000000000",
    "cuid": "game-rpg-2026"
  }'

{
  "success": true,
  "tx_hash": "0x1a2b3c4d5e6f...",
  "token_amount": "100",
  "xotn_paid": "10000000000000000",
  "platform_fee": "1500000000000000",
  "provider_received": "8500000000000000"
}

STEP 3 Record Spending — increaseUsedBal 소비 기록 — increaseUsedBal

Called from the Provider's server when a user consumes in-game items. Deducts from the content token balance while permanently accumulating the same amount in used_balances. 사용자가 게임 내 아이템을 소비할 때 Provider 서버에서 호출합니다. 컨텐츠 토큰 잔액에서 차감되며, 동시에 used_balances에 같은 금액이 영구 누적됩니다.

Slot State After increaseUsedBal increaseUsedBal 호출 후 슬롯 상태 변화

// Record spending — user consumes 100 tokens on item (called from Provider server)
// 소비 기록 — 사용자가 아이템 100토큰 소비 (Provider 서버에서 호출)
import crypto from 'crypto';

function encryptPayload(payload, key, iv) {
  // AES-256-CTR encryption | AES-256-CTR 암호화
  const cipher = crypto.createCipheriv('aes-256-ctr',
    Buffer.from(key, 'hex'),
    Buffer.from(iv, 'hex')
  );
  let encrypted = cipher.update(JSON.stringify(payload), 'utf8', 'hex');
  encrypted += cipher.final('hex');
  return encrypted;
}

const payload = {
  client_id: 'your-client-id',
  user_dbkey: 'user-uuid-12345',
  amount: '100',      // token amount to consume | 소비할 토큰 수량
  cuid: 'game-rpg-2026'
};

const response = await fetch('/v1/development-api/increase_used_content_token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    encrypted_message: encryptPayload(payload,
      process.env.DEAUTH_KEY,
      process.env.DEAUTH_IV
    )
  })
});

// After this call: slot's used_balances += 100 (permanently recorded on-chain)
// 이 호출 후 슬롯의 used_balances += 100 (온체인에 영구 기록)

STEP 4 Account Value Query — balanceAdex 계정 가치 조회 — balanceAdex

When trading accounts on a marketplace, buyers can verify a slot's investment history through balanceAdex — no login required. 마켓플레이스에서 계정을 거래할 때, 구매자는 balanceAdex를 통해 로그인 없이도 계정의 투자 내역을 검증할 수 있습니다.

// Public query — no auth required, anyone can call | 공개 조회 — 인증 불필요, 누구나 호출 가능
const slotAddress = '0xUserSlotAddress...';
const response = await fetch(
  `/v1/development-api/balance_adex/${slotAddress}`
);

const data = await response.json();
// data.balance       — current content token balance | 현재 컨텐츠 토큰 잔액
// data.used_balances — total spent (= account investment history) | 총 소비 누적값 (= 계정 투자 내역)

console.log(`Balance: ${data.balance} tokens`);       // 잔액
console.log(`Total invested: ${data.used_balances} tokens spent`); // 총 투자

{
  "success": true,
  "slot": "0xUserSlotAddress...",
  "balance": "900",
  "used_balances": "3200",
  "cuid": "game-rpg-2026"
}

// Marketplace — auto-estimate account price | 마켓플레이스 — 계정 가격 자동 산정
async function estimateAccountValue(slotAddress, pricePerToken = 0.001) {
  const { used_balances } = await fetchBalanceAdex(slotAddress);
  
  // Minimum guaranteed value based on spending history | 소비 기록 기반 최소 보증 가치 산정
  const minGuaranteedValue = Number(used_balances) * pricePerToken;
  
  return {
    used_balances,
    min_value_xotn: minGuaranteedValue,
    verified: true,       // on-chain verified | 온체인 검증 완료
    requires_login: false // no login needed | 로그인 불필요
  };
}

STEP 5 Provider Settlement — releaseUsedBal Provider 정산 — releaseUsedBal

Providers can receive additional settlement through releaseUsedBal, based on the slot's used_balances. This is a separate settlement mechanism from the 85% revenue share at purchase time. Provider는 releaseUsedBal을 통해 슬롯의 used_balances를 기반으로 추가 정산을 받을 수 있습니다. 이는 구매 시점의 수익 분배(85%)와는 별도의 정산 메커니즘입니다.

// Provider settlement call | Provider 정산 호출
const response = await fetch('/v1/development-api/release_used_balance', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client_id: 'your-client-id',
    cuid: 'game-rpg-2026',
    slot: '0xUserSlotAddress...'
  })
});

const data = await response.json();
// data.released_amount — settled token amount | 정산된 토큰 수량
// data.tx_hash         — settlement transaction hash | 정산 트랜잭션 해시

🔄 Full Lifecycle 🔄 전체 라이프사이클

The complete flow from content token issuance to account value verification. 컨텐츠 토큰의 발급부터 계정 가치 검증까지 전체 흐름입니다.

🔒 AES-256-CTR Encryption Reference 🔒 AES-256-CTR 암호화 레퍼런스

Sensitive API calls like increaseUsedBal require AES-256-CTR encryption. Use the DEAUTH_KEY (32 bytes) and DEAUTH_IV (16 bytes) issued at Provider registration. increaseUsedBal 등 민감한 API 호출에는 AES-256-CTR 암호화가 필요합니다. Provider 등록 시 발급되는 DEAUTH_KEY(32바이트)와 DEAUTH_IV(16바이트)를 사용합니다.

// Node.js — AES-256-CTR Encryption | AES-256-CTR 암호화
import crypto from 'crypto';

/**
 * Encrypts a JSON payload with AES-256-CTR.
 * AES-256-CTR로 JSON 페이로드를 암호화합니다.
 * @param {object} payload  - object to encrypt | 암호화할 객체
 * @param {string} key      - 32-byte hex key (DEAUTH_KEY) | 32바이트 hex 키
 * @param {string} iv       - 16-byte hex IV (DEAUTH_IV) | 16바이트 hex IV
 * @returns {string} hex-encoded encrypted string | hex 인코딩된 암호화 문자열
 */
function encryptPayload(payload, key, iv) {
  const cipher = crypto.createCipheriv('aes-256-ctr',
    Buffer.from(key, 'hex'),
    Buffer.from(iv, 'hex')
  );
  let encrypted = cipher.update(JSON.stringify(payload), 'utf8', 'hex');
  encrypted += cipher.final('hex');
  return encrypted;
}

// Usage example | 사용 예시
const encrypted = encryptPayload(
  { client_id: 'xxx', user_dbkey: 'yyy', amount: '100', cuid: 'game-rpg-2026' },
  process.env.DEAUTH_KEY,
  process.env.DEAUTH_IV
);

# Python — AES-256-CTR Encryption | AES-256-CTR 암호화
# pip install pycryptodome
import json
from Crypto.Cipher import AES
import binascii

def encrypt_payload(payload: dict, key: str, iv: str) -> str:
    """
    Encrypts a dict payload with AES-256-CTR.
    AES-256-CTR로 dict 페이로드를 암호화합니다.
    key: 32-byte hex string | 32바이트 hex 문자열
    iv:  16-byte hex string | 16바이트 hex 문자열
    """
    key_bytes = bytes.fromhex(key)
    iv_bytes  = bytes.fromhex(iv)
    
    cipher = AES.new(key_bytes, AES.MODE_CTR,
                     nonce=iv_bytes[:8],         # CTR nonce (8 bytes)
                     initial_value=iv_bytes[8:])  # counter initial value | 카운터 초기값
    
    plaintext = json.dumps(payload).encode('utf-8')
    encrypted = cipher.encrypt(plaintext)
    return binascii.hexlify(encrypted).decode('ascii')

# Usage example | 사용 예시
encrypted = encrypt_payload(
    {'client_id': 'xxx', 'user_dbkey': 'yyy', 'amount': '100', 'cuid': 'game-rpg-2026'},
    os.environ['DEAUTH_KEY'],
    os.environ['DEAUTH_IV']
)

// Verify encryption implementation against server result | 암호화 구현 검증 — 서버의 암호화 결과와 비교
async function verifyEncryption(testString) {
  // 1. Encrypt on server | 서버에서 암호화
  const serverRes = await fetch('/v1/development-api/test_encryption', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_id: 'your-client-id',
      test_string: testString
    })
  });
  const { encrypted_string: serverEncrypted } = await serverRes.json();

  // 2. Encrypt locally | 로컬에서 암호화
  const localEncrypted = encryptPayload(
    testString,
    process.env.DEAUTH_KEY,
    process.env.DEAUTH_IV
  );

  // 3. Compare | 비교
  const matches = localEncrypted === serverEncrypted;
  console.log('Verify:', matches ? '✅ Match' : '❌ Mismatch'); // 암호화 검증
  return matches;
}

await verifyEncryption('Hello DeOAuth');