Mobile App Integration — Full Walkthrough

This is the canonical guide for engineers integrating YouthChain into a mobile app. It covers the full happy path: wallet creation, faucet, on-chain identity, engagement actions, rewards claim, AMM swap, and validator attestations. By the end you’ll have:

A wallet for the user
The user appearing on-chain
Each social action minting verifiable YCR
The user able to swap YCR ↔ YCE via AMM
The user’s phone signing blocks (counted on the dashboard)

Network basics


Chain ID	`7717`
RPC URL	`https://rpc.54-237-170-237.sslip.io`
Indexer REST	`https://api.54-237-170-237.sslip.io/api`
Block time	~5 s
Gas token	YCE (native)
Currency symbol	YCE

To add the network programmatically (MetaMask Mobile, WalletConnect, etc.):

await window.ethereum.request({
  method: "wallet_addEthereumChain",
  params: [{
    chainId: "0x1e25",
    chainName: "YouthChain Testnet",
    nativeCurrency: { name: "YCE", symbol: "YCE", decimals: 18 },
    rpcUrls: ["https://rpc.54-237-170-237.sslip.io"],
    blockExplorerUrls: ["https://explorer.54-237-170-237.sslip.io/explorer/"]
  }]
});

Step 1 — wallet

Two options: A. Bring your own (MetaMask, WalletConnect, etc.) — standard Ethereum wallets work. Sign with secp256k1, EIP-155 transactions are required (ethers v6 default). B. Build the wallet into your app — BIP-39 phrase, BIP-44 path m/44'/60'/0'/0/0, phrase in the platform secure store, key re-derived per signature.

import { ethers } from "ethers";
const wallet = ethers.Wallet.createRandom(); // throwaway, for a spike only

createRandom() is fine for a throwaway test address and wrong for a product: it produces a key with no recovery path and no derivation standard, so the user can never restore the account anywhere else. For anything a user will hold value in, follow Wallet Integration — derivation, secure storage, EIP-155 signing and the backup flow, with the shipped reference implementation.

Step 2 — faucet

Fund the wallet before any other call. Faucet drops 0.1 native YCE + 11K YCE token + 1K YCR in a single request.

const r = await fetch("https://api.54-237-170-237.sslip.io/api/faucet", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ address: wallet.address.toLowerCase() })
});
const { txHash, nativeTxHash, ycrTxHash } = await r.json();

The call answers with 202 Accepted in under a second — the transfers are submitted, not yet settled. Balances appear ~15 s later (three blocks). Poll the pollUrl in the response, or eth_getBalance, every 5 s; do not treat the first empty balance as a failure. See Events & confirmations. Full faucet docs →

Step 3 — identity (optional but recommended)

If your app shows a user profile, register the device so the indexer tracks it:

await fetch("https://api.54-237-170-237.sslip.io/api/mobile/register", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    address: wallet.address.toLowerCase(),
    deviceInfo: {
      os: "iOS", model: "iPhone 14", appVersion: "1.0.0",
      networkType: "wifi", region: "BR-SP", timezone: "America/Sao_Paulo"
    }
  })
});

Step 4 — engagement actions

Every social action in the app — Post, Like, Share, Comment, Watch, NftCreate, Tip — should call the engagement endpoint to mint YCR for the user. No private key required — the indexer signs via the oracle wallet and attributes the action to the user inside the calldata.

await fetch("https://api.54-237-170-237.sslip.io/api/mobile/engagement-onbehalf", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    address: wallet.address.toLowerCase(),
    actionType: "post",          // post|like|share|comment|watch|nft_create|tip
    targetId: "post_123abc",     // your app's ID for the content
    deviceInfo: { os: "iOS", model: "iPhone 14", appVersion: "1.0.0" },
    clientTimestamp: Math.floor(Date.now() / 1000)
  })
});

This calls EngagementOracle.recordAction(user, actionType, weight, targetId) on-chain and accumulates pending YCR for the user. The mint rate per action is governed by setYCRMintRate(ActionType, rate), set by the foundation.

Step 5 — display rewards

Show the user how much YCR they’ve earned:

const profile = await fetch(
  `https://api.54-237-170-237.sslip.io/api/mobile/profile/${wallet.address.toLowerCase()}`
).then(r => r.json());

console.log(profile);
// {
//   address, level, engagementScore, actionsCount,
//   yceBalance, ycrBalance, ycrPending,
//   distinctActionTypes
// }

Or read directly from the contract:

const ycr = new ethers.Contract(YCR_ADDR, [
  "function balanceOf(address) view returns (uint256)",
  "function previewClaim(address, uint8) view returns (uint256)"
], provider);

const balance = await ycr.balanceOf(wallet.address);
const pending = await ycr.previewClaim(wallet.address, 0xff); // all action types

Step 6 — claim YCR

When the user wants to convert pending YCR into actual ERC-20 balance:

const ycr = new ethers.Contract(YCR_ADDR, [
  "function claim(uint8) returns (uint256)"
], wallet.connect(provider));

const tx = await ycr.claim(0xff, { gasLimit: 300_000n, type: 0 });
await tx.wait();

After claim, the YCR is real ERC-20 balance — the user can transfer, swap, etc.

Step 7 — AMM swap

YCR → YCE conversion through the on-chain pool. Swap rate floats with reserves; 2% of input is burned.

const POOL = "0xb7646654d1fd946e8a8bc32b5786a571be5925f2";
const ycrContract = new ethers.Contract(YCR_ADDR, ERC20_ABI, signer);
const pool = new ethers.Contract(POOL, [
  "function swapYCRForYCE(uint256, uint256) returns (uint256)"
], signer);

await (await ycrContract.approve(POOL, amountIn)).wait();
await (await pool.swapYCRForYCE(amountIn, minOut, { gasLimit: 250_000n, type: 0 })).wait();

Full AMM docs →

Step 8 — register in the ValidatorRegistry (optional)

Bonding 10K YCE registers the address in ValidatorRegistry. register takes four arguments and is not payable — the stake is pulled with transferFrom, so approve first. Registering also requires a 48-byte BLS public key and a 32-byte ed25519 public key, which is why this step only makes sense for someone who is actually running a candidate node.

const REGISTRY = "0x286b9783b3245a253c3350c60d91cd50cc5e4c5c";

const yce = new ethers.Contract(YCE_ADDR, ERC20_ABI, signer);
const reg = new ethers.Contract(REGISTRY, [
  "function register(uint256 stakeAmount, bytes blsPublicKey, bytes edPublicKey, string p2pEndpoint)"
], signer);

const stake = ethers.parseEther("10000");
await (await yce.approve(REGISTRY, stake)).wait();
await (await reg.register(stake, blsPublicKey, edPublicKey, "http://my-node:9000", {
  gasLimit: 300_000n, type: 0
})).wait();

Full registry docs →

Step 9 — block endorsements (off-chain participation signal)

The app can sign each new block hash and submit it. Be precise about what this is: the signature is verified by the indexer and stored in an off-chain table, over a block that was already finalised. It is not recorded on-chain, it is not checked against the bond, and it carries no consensus weight.

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("https://api.54-237-170-237.sslip.io/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, 5000); // poll every 5s

Full endorsement docs →

Voting in the DAO

The DAO is the new contract at 0xa5851461a5cff6f8277917f2a691d3c6ef5bef9e with a 5-minute voting period (testnet only — mainnet is 7 days).

const DAO = "0xa5851461a5cff6f8277917f2a691d3c6ef5bef9e";
const dao = new ethers.Contract(DAO, [
  "function createProposal(string,string) returns (uint256)",
  "function vote(uint256, uint256, bool)",
  "function execute(uint256) returns (bool)",
  "function status(uint256) view returns (bool active, bool passed, uint256 votesFor, uint256 votesAgainst, uint256 totalBurned, uint64 endsAt)"
], signer);

// 1 YCE proposal cost (burned)
await (await yce.approve(DAO, ethers.parseEther("100"))).wait();
const cr = await dao.createProposal("My proposal", "details...");
await cr.wait();

// vote with N power costs sqrt(N) YCE (burned)
await (await dao.vote(proposalId, 16n, true, { gasLimit: 250_000n, type: 0 })).wait();

Address book

Contract	Address
YCEToken	`0x6a2247af143536d3ce0b9bf86a27c9b366e2f9ed`
YCR (rewards)	`0x6afd8143a2d213067a31abe5adf0d458a0df532b`
AMM (EngagementDrivenConverter)	`0xb7646654d1fd946e8a8bc32b5786a571be5925f2`
BurnManager	`0x27cb5d2d2cedaf1274730edd348ad0c6eb003fdb`
StakingJars	`0xb11688e8ab9f2f32ece6ac663655ce7d7603a482`
QuadraticVoting (DAO)	`0xa5851461a5cff6f8277917f2a691d3c6ef5bef9e`
ValidatorRegistry	`0x286b9783b3245a253c3350c60d91cd50cc5e4c5c`
EngagementOracle	`0x06df136b8fbdbf93be1271dbd1b7a52854d7c6a9`
YouthNameService (`.yc`)	`0xcc79b3ecae6f9928ddcf764c28789a8a9a572805`
EngagementRollup v2	`0xefca508817f94af9d348250471046a0bcd476aef`
YCE721 (NFT)	`0x82f89f43f91eb0eb9df5867c5aa49402bc947643`
StYCE (liquid staking)	`0x197d9cd2268cfc20840c6a7ca9113b641b7b901d`

Source of truth lives at contracts/script/deployed.json in the repo. Read it at build time if your app needs to survive testnet wipes without a code change.

Signing model — important for the wallet team

YouthChain has two transaction-signing surfaces. Pick the right one per use case.

1. `eth_sendRawTransaction` — for user-signed txs (production path)

Standard Ethereum: the user’s secp256k1 key signs a serialized RLP tx (EIP-155 / EIP-1559 / legacy), the node ecrecovers the sender. Works with MetaMask, WalletConnect, ethers, viem, hardware wallets — anything that speaks the Ethereum spec. Use this for: swap, stake, vote, claim-by-self, transfer, register validator, mint NFT, register .yc handle. Anything the user initiates.

const provider = new ethers.JsonRpcProvider("https://rpc.54-237-170-237.sslip.io",
  { chainId: 7717, name: "youthchain" }, { batchMaxCount: 1, staticNetwork: true });
const wallet = new ethers.Wallet(privateKey, provider);
const tx = await wallet.sendTransaction({ to, value, data, gasLimit: 250_000n, type: 0 });

2. `/api/mobile/engagement-onbehalf` + `/api/mobile/claim` — for relayed txs (no user gas)

The indexer signs on behalf of the user using the authorized oracle wallet. The user’s address is carried inside the calldata, attribution stays correct, but the user does not pay gas and does not need to sign. This is testnet UX scaffolding. Use this for: engagement actions (HOT path — would be terrible UX to ask MetaMask on every like), gasless claim fallback.

There is also a low-level RPC yc_sendTransaction({ from, to, privateKey, ... }) used internally by the indexer and dev scripts. Do not call this from a mobile app. It takes a private key in plaintext and is a testnet convenience only — there is no signature-vs-from validation. Production wallets use eth_sendRawTransaction.

Common gotchas

Always pass type: 0 to ethers transaction options for now. The chain accepts EIP-1559 (type: 2) but legacy is most reliable across mobile wallets.
Use batchMaxCount: 1 on JsonRpcProvider. Older builds did not support JSON-RPC batching; explicit override avoids surprises.
Don’t skip the faucet for new wallets — without 0.1 native YCE, the wallet can’t pay gas for any user-signed tx.
EngagementOracle is onlyOracle — clients cannot call recordAction directly. Always go through /api/mobile/engagement-onbehalf.
YCRRewards.claim(uint8) costs gas — show a “claim now” button, don’t auto-claim. Fall back to /api/mobile/claim if the user has no gas.
MetaMask AccountTracker quirk: after adding YouthChain Testnet, open the MetaMask popup once on the new network so its balance cache populates. Without this, eth_getBalance returns 0x0 and writes show “insufficient funds” even when the chain has the balance.

Help

Issues with the testnet, RPC, or this guide → contact the YouthChain dev team
Test wallet pre-funded with everything: see Test Accounts
Live troubleshooting steps: Troubleshooting

​Network basics

​Step 1 — wallet

​Step 2 — faucet

​Step 3 — identity (optional but recommended)

​Step 4 — engagement actions

​Step 5 — display rewards

​Step 6 — claim YCR

​Step 7 — AMM swap

​Step 8 — register in the ValidatorRegistry (optional)

​Step 9 — block endorsements (off-chain participation signal)

​Voting in the DAO

​Address book

​Signing model — important for the wallet team

​1. eth_sendRawTransaction — for user-signed txs (production path)

​2. /api/mobile/engagement-onbehalf + /api/mobile/claim — for relayed txs (no user gas)

​Common gotchas

​Help

Network basics

Step 1 — wallet

Step 2 — faucet

Step 3 — identity (optional but recommended)

Step 4 — engagement actions

Step 5 — display rewards

Step 6 — claim YCR

Step 7 — AMM swap

Step 8 — register in the ValidatorRegistry (optional)

Step 9 — block endorsements (off-chain participation signal)

Voting in the DAO

Address book

Signing model — important for the wallet team

1. `eth_sendRawTransaction` — for user-signed txs (production path)

2. `/api/mobile/engagement-onbehalf` + `/api/mobile/claim` — for relayed txs (no user gas)

Common gotchas

Help