Step-by-Step Integration

This is the canonical “from zero to running” guide for an engineer integrating YouthChain into a mobile app. Every step has copy-paste code that runs as-is. By the end of step 7 your app is minting verifiable YCR rewards on-chain when users perform actions.

Before you start, make sure you have Node.js 20+ installed and a code editor open. No private keys to manage yet — we’ll generate test wallets in step 2.

What you’ll build

A wallet for the user (generated locally or imported from MetaMask)
The wallet funded with test tokens via the faucet
Each like / post / share in the app firing an on-chain action that mints YCR
Real-time balance display
An AMM swap (YCR → YCE) so the user converts rewards into the native token

Estimated time: 30 minutes.

Step 0 — Network basics

Bookmark these — you’ll use them in every call.

const NETWORK = {
  chainId: 7717,
  rpc: "https://rpc.chain.youthapp.io",
  api: "https://api.chain.youthapp.io/api",
  explorer: "https://explorer.chain.youthapp.io/explorer/",
};

const CONTRACTS = {
  YCE: "0x6a2247af143536d3ce0b9bf86a27c9b366e2f9ed",       // native + ERC-20
  YCR: "0x6afd8143a2d213067a31abe5adf0d458a0df532b",       // rewards
  AMM: "0xb7646654d1fd946e8a8bc32b5786a571be5925f2",       // YCR<->YCE pool
  ENGAGEMENT_ORACLE: "0x06df136b8fbdbf93be1271dbd1b7a52854d7c6a9",
  VALIDATOR_REGISTRY: "0x286b9783b3245a253c3350c60d91cd50cc5e4c5c",
  DAO: "0xa5851461a5cff6f8277917f2a691d3c6ef5bef9e",       // 5min voting on testnet
};

Step 1 — Install ethers

npm install ethers@^6

Or yarn add ethers@^6 / pnpm add ethers@^6. Works the same in React Native (npm install ethers @ethersproject/shims react-native-get-random-values).

Step 2 — Create or import a wallet

Option A — generate a fresh test wallet (easiest for development)

import { ethers } from "ethers";

// Generates a random wallet. Persist privateKey securely:
// - iOS: Keychain
// - Android: Keystore / EncryptedSharedPreferences
// - Web: never localStorage in production; use IndexedDB + Web Crypto subtle-key
const wallet = ethers.Wallet.createRandom();

console.log("Address:", wallet.address);
console.log("Private key:", wallet.privateKey);

Option B — connect MetaMask (web/mobile WebView)

import { ethers } from "ethers";

if (!window.ethereum) throw new Error("Install MetaMask");

await window.ethereum.request({
  method: "wallet_addEthereumChain",
  params: [{
    chainId: "0x1e25", // 7717
    chainName: "YouthChain Testnet",
    nativeCurrency: { name: "YCE", symbol: "YCE", decimals: 18 },
    rpcUrls: [NETWORK.rpc],
    blockExplorerUrls: [NETWORK.explorer],
  }],
});

await window.ethereum.request({ method: "eth_requestAccounts" });
const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();
console.log("Connected:", await signer.getAddress());

Step 3 — Fund the wallet via faucet

The faucet drops 0.1 native YCE + 11,000 YCE token + 1,000 YCR token in a single call. 24h cooldown per address.

async function getFaucet(address: string) {
  const r = await fetch(`${NETWORK.api}/faucet`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ address: address.toLowerCase() }),
  });

  if (r.status === 429) throw new Error("Faucet cooldown — try again in 24h");
  if (!r.ok) throw new Error(`Faucet failed: ${(await r.json()).error?.message}`);

  const { txHash, nativeTxHash, ycrTxHash } = await r.json();
  console.log("Faucet sent:", { txHash, nativeTxHash, ycrTxHash });

  // Wait ~5 seconds for the txs to land
  await new Promise(r => setTimeout(r, 5000));
}

await getFaucet(wallet.address);

Verify the wallet was funded:

const provider = new ethers.JsonRpcProvider(
  NETWORK.rpc,
  { chainId: NETWORK.chainId, name: "youthchain" },
  { batchMaxCount: 1, staticNetwork: true }
);

const native = await provider.getBalance(wallet.address);
console.log("Native YCE:", ethers.formatEther(native));
// → "0.1"

Step 4 — Load contract ABIs

ABIs are served as static JSON, CORS-enabled. Your app fetches them at startup.

async function loadAbi(name: string) {
  const r = await fetch(`/abis/${name}.json`);
  const { abi } = await r.json();
  return abi;
}

const yceAbi = await loadAbi("YCEToken");
const ycrAbi = await loadAbi("YCRRewards");
const ammAbi = await loadAbi("YCEYCRPool");
const oracleAbi = await loadAbi("EngagementOracle");

In production, bundle the ABIs into your app instead of fetching at runtime — they rarely change and you avoid the network hop on cold-start. curl -O + import works.

Step 5 — Read user balances

const yce = new ethers.Contract(CONTRACTS.YCE, yceAbi, provider);
const ycr = new ethers.Contract(CONTRACTS.YCR, ycrAbi, provider);

async function getBalances(address: string) {
  const [native, yceBal, ycrBal, ycrPending] = await Promise.all([
    provider.getBalance(address),
    yce.balanceOf(address),
    ycr.balanceOf(address),
    ycr.previewClaim(address, 0xff), // bitmask: include all 7 action types
  ]);

  return {
    native: ethers.formatEther(native),
    yce: ethers.formatEther(yceBal),
    ycr: ethers.formatEther(ycrBal),
    ycrPending: ethers.formatEther(ycrPending),
  };
}

console.log(await getBalances(wallet.address));
// {
//   native: "0.1",
//   yce: "11000.0",
//   ycr: "1000.0",
//   ycrPending: "0.0"
// }

Display these in your app’s wallet/profile screen.

Step 6 — Record an engagement action

Every social action in your app — post, like, share, comment, watch, NFT mint, tip — should call this endpoint. The indexer signs and submits an on-chain transaction to EngagementOracle.recordAction(), which accumulates pending YCR for the user.

async function recordAction(params: {
  address: string;
  privateKey: string;          // testnet convenience; gateway-signed in prod
  actionType: "post" | "like" | "share" | "comment" | "watch" | "nftCreate" | "tip";
  targetId: string;            // your app's content ID
  deviceInfo?: {
    os: string;
    model: string;
    appVersion: string;
    networkType?: string;
    region?: string;
  };
}) {
  const r = await fetch(`${NETWORK.api}/mobile/engagement`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      address: params.address.toLowerCase(),
      actionType: params.actionType,
      targetId: params.targetId,
      privateKey: params.privateKey,
      deviceInfo: params.deviceInfo,
      clientTimestamp: Math.floor(Date.now() / 1000),
    }),
  });

  if (!r.ok) throw new Error((await r.json()).error?.message ?? "engagement failed");

  const { txHash, actionType, weight, status } = await r.json();
  return { txHash, actionType, weight };
}

// Example — user liked a post
await recordAction({
  address: wallet.address,
  privateKey: wallet.privateKey,
  actionType: "like",
  targetId: "post_abc123",
  deviceInfo: { os: "iOS", model: "iPhone 14", appVersion: "1.0.0" },
});

// Wait ~5s, then re-check balances
await new Promise(r => setTimeout(r, 5000));
console.log(await getBalances(wallet.address));
// → ycrPending grew by the action's weight

Action weights (whitepaper §9)

Action	Default weight	Use case
`post`	1.0 YCR	Creating original content
`like`	0.2 YCR	Reaction
`share`	0.5 YCR	Amplifying reach
`comment`	0.3 YCR	Engagement
`watch`	0.15 YCR	Passive consumption
`nftCreate`	2.0 YCR	High-value content
`tip`	0.8 YCR	Direct creator support

Weights are governed on-chain via setYCRMintRate(ActionType, rate) and may change.

Step 7 — Claim pending YCR

Pending YCR is per-user accumulator. The user converts pending → real ERC-20 balance with one transaction:

const ycrSigner = new ethers.Contract(CONTRACTS.YCR, ycrAbi, wallet.connect(provider));

async function claimRewards() {
  const allActions = 0xff; // bitmask: all 7 types
  const tx = await ycrSigner.claim(allActions, { gasLimit: 300_000n, type: 0 });
  console.log("Claim tx:", tx.hash);
  const receipt = await tx.wait();
  return receipt.status === 1;
}

await claimRewards();
// pending → real balance

Show this as a “Claim now” button. Don’t auto-claim on every page load — it costs gas.

Step 8 — AMM swap (YCR → YCE)

Convert reward tokens into the native staking token via the on-chain pool. 2% of input is burned (deflationary).

const ycrWritable = new ethers.Contract(CONTRACTS.YCR, ycrAbi, wallet.connect(provider));
const amm = new ethers.Contract(CONTRACTS.AMM, ammAbi, wallet.connect(provider));

async function swapYcrForYce(amountIn: bigint) {
  // 1. Approve the pool to pull YCR
  const approveTx = await ycrWritable.approve(CONTRACTS.AMM, amountIn, {
    gasLimit: 120_000n,
    type: 0,
  });
  await approveTx.wait();

  // 2. Quote with 1% slippage protection
  const [rYCE, rYCR] = await Promise.all([amm.reservesYCE(), amm.reservesYCR()]);
  const expectedOut = (amountIn * rYCE) / (rYCR + amountIn);
  const minOut = (expectedOut * 99n) / 100n; // 1% slippage

  // 3. Swap
  const swapTx = await amm.swapYCRForYCE(amountIn, minOut, {
    gasLimit: 250_000n,
    type: 0,
  });
  console.log("Swap tx:", swapTx.hash);
  const receipt = await swapTx.wait();
  return receipt.status === 1;
}

await swapYcrForYce(ethers.parseEther("100"));
// 100 YCR → ~1.4 YCE (at current pool ratio)

Step 9 — Real-time updates

For live balance/leaderboard updates without polling, set up a 5-second poll on a single endpoint that returns everything you need:

async function getProfile(address: string) {
  const r = await fetch(`${NETWORK.api}/mobile/profile/${address.toLowerCase()}`);
  return r.json();
  // { address, level, engagementScore, actionsCount,
  //   yceBalance, ycrBalance, ycrPending, distinctActionTypes }
}

// In your app — use SWR / React Query / Riverpod / etc.
setInterval(async () => {
  const profile = await getProfile(wallet.address);
  setProfileState(profile); // update UI
}, 5000);

The /api/mobile/profile/:address endpoint is the single source of truth for everything you’d display in the user’s profile screen.

Step 10 — (Optional) Become a validator

If you want to demo the “phone validating” pattern, the user can bond 10K YCE and have the app sign each block:

const yceWritable = new ethers.Contract(CONTRACTS.YCE, yceAbi, wallet.connect(provider));
const registry = new ethers.Contract(CONTRACTS.VALIDATOR_REGISTRY,
  await loadAbi("ValidatorRegistry"), wallet.connect(provider));

const stake = ethers.parseEther("10000");
await (await yceWritable.approve(CONTRACTS.VALIDATOR_REGISTRY, stake)).wait();
await (await registry.register(stake, { gasLimit: 300_000n, type: 0 })).wait();
console.log("Registered as validator");

let lastSigned = 0;

async function attestLatest() {
  const blockNumber = await provider.getBlockNumber();
  if (blockNumber <= lastSigned) return;

  const block = await provider.getBlock(blockNumber);
  if (!block?.hash) return;

  const signature = await wallet.signMessage(block.hash);

  const r = await fetch(`${NETWORK.api}/validator-attest`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      blockNumber,
      blockHash: block.hash,
      signature,
      signerAddress: wallet.address.toLowerCase(),
    }),
  });

  if (r.ok) lastSigned = blockNumber;
}

setInterval(() => attestLatest().catch(console.warn), 5000);

Common gotchas

Always pass type: 0 to gasLimit in transaction options. EIP-1559 (type: 2) works too but legacy is most reliable across mobile wallets.
Never skip the faucet for new wallets. Without 0.1 native YCE, the wallet can’t pay gas to do anything.
batchMaxCount: 1 on JsonRpcProvider — the chain accepts JSON-RPC batching but explicit override avoids surprises across versions.
Don’t auto-claim YCR. It costs gas every call. Show a button instead.
Engagement actions are deduplicated by (user, actionType, targetId) per block. Same like on post_abc123 won’t double-count if fired twice in the same second.

Full working example (single file)

import { ethers } from "ethers";

const NETWORK = {
  chainId: 7717,
  rpc: "https://rpc.chain.youthapp.io",
  api: "https://api.chain.youthapp.io/api",
};
const CONTRACTS = {
  YCE: "0x6a2247af143536d3ce0b9bf86a27c9b366e2f9ed",
  YCR: "0x6afd8143a2d213067a31abe5adf0d458a0df532b",
};

async function main() {
  const provider = new ethers.JsonRpcProvider(
    NETWORK.rpc,
    { chainId: NETWORK.chainId, name: "yc" },
    { batchMaxCount: 1, staticNetwork: true }
  );

  // 1. Wallet
  const wallet = ethers.Wallet.createRandom().connect(provider);
  console.log("Wallet:", wallet.address);

  // 2. Faucet
  await fetch(`${NETWORK.api}/faucet`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ address: wallet.address.toLowerCase() }),
  });
  await new Promise(r => setTimeout(r, 5000));

  // 3. Engagement (e.g. user liked something)
  await fetch(`${NETWORK.api}/mobile/engagement`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      address: wallet.address.toLowerCase(),
      actionType: "post",
      targetId: "first_post",
      privateKey: wallet.privateKey,
      deviceInfo: { os: "node", model: "demo", appVersion: "1.0.0" },
      clientTimestamp: Math.floor(Date.now() / 1000),
    }),
  });
  await new Promise(r => setTimeout(r, 5000));

  // 4. Read balances
  const r = await fetch(`${NETWORK.api}/mobile/profile/${wallet.address.toLowerCase()}`);
  const profile = await r.json();
  console.log("Profile:", profile);
}

main();

Run with node --experimental-fetch demo.mjs (Node 20+ has fetch native). Expected output after ~10 seconds:

Wallet: 0xAbCd...1234
Profile: {
  address: '0xabcd...1234',
  level: 1,
  engagementScore: 1.0,
  actionsCount: 1,
  yceBalance: '11000000000000000000000',
  ycrBalance: '1000000000000000000000',
  ycrPending: '1000000000000000000', // 1 YCR for the post
  distinctActionTypes: 1
}

Next steps

Mobile Integration Guide — full reference with all endpoints
API Reference — Mobile REST — every endpoint documented individually
ABIs — direct download links for all 8 contracts
Test Accounts — pre-funded wallets for development
Troubleshooting — common errors and fixes

Issues or questions: contact the YouthChain dev team. Include your wallet address and the tx hash that’s misbehaving — we trace it from there.

​What you’ll build

​Step 0 — Network basics

​Step 1 — Install ethers

​Step 2 — Create or import a wallet

​Option A — generate a fresh test wallet (easiest for development)

​Option B — connect MetaMask (web/mobile WebView)

​Step 3 — Fund the wallet via faucet

​Step 4 — Load contract ABIs

​Step 5 — Read user balances

​Step 6 — Record an engagement action

​Action weights (whitepaper §9)

​Step 7 — Claim pending YCR

​Step 8 — AMM swap (YCR → YCE)

​Step 9 — Real-time updates

​Step 10 — (Optional) Become a validator

​Common gotchas

​Full working example (single file)

​Next steps

What you’ll build

Step 0 — Network basics

Step 1 — Install ethers

Step 2 — Create or import a wallet

Option A — generate a fresh test wallet (easiest for development)

Option B — connect MetaMask (web/mobile WebView)

Step 3 — Fund the wallet via faucet

Step 4 — Load contract ABIs

Step 5 — Read user balances

Step 6 — Record an engagement action

Action weights (whitepaper §9)

Step 7 — Claim pending YCR

Step 8 — AMM swap (YCR → YCE)

Step 9 — Real-time updates

Step 10 — (Optional) Become a validator

Common gotchas

Full working example (single file)

Next steps