Events & confirmations

Every write on YouthChain is asynchronous: an endpoint hands you a transaction hash, and the result exists a few blocks later. This page is the contract for the other half — how your UI learns that the thing actually happened.

Blocks are produced every ~5 seconds. Every cadence on this page derives from that. A UI that polls every second just burns four requests waiting for a round that has not happened yet.

Pick the right mechanism

You need	Use
”Did my transaction land?”	Poll `eth_getTransactionReceipt` for that hash
”Tell me when the chain moves”	Subscribe to `newHeads` over WebSocket
”Did the faucet fund this address?”	Poll `GET /api/faucet/status/:address`
”Did this engagement register?”	Poll `GET /api/mobile/actions/:address` or `/rewards/:address`

1. WebSocket — `newHeads`

wss://rpc.chain.youthapp.io/ws

const ws = new WebSocket("wss://rpc.chain.youthapp.io/ws");

ws.onopen = () => ws.send(JSON.stringify({
  jsonrpc: "2.0", id: 1, method: "eth_subscribe", params: ["newHeads"],
}));

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.id === 1) return;                       // {"result":"0x1"} — the subscription id
  if (msg.method === "eth_subscription") {
    const head = msg.params.result;               // a block header
    console.log("block", parseInt(head.number, 16));
  }
};

Each notification carries a standard Ethereum header — number, hash, parentHash, timestamp, stateRoot, gasUsed, baseFeePerGas, miner, transactions, plus a YouthChain extra, ycCommitSigners (the validator indices whose signatures committed the block).

newHeads is the only subscription that exists. Any other value — logs, newPendingTransactions — is refused with only newHeads subscription is supported (-32601). To react to a contract event, watch heads and then call eth_getLogs for the range you care about.

Unsubscribe with eth_unsubscribe and the id you were given. Reconnect on close: a dropped socket loses every subscription, and the app must re-subscribe and backfill the blocks it missed via eth_getBlockByNumber.

Debugging with curl? Force HTTP/1.1 — curl --http1.1 -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" .... Over HTTP/2 the upgrade is refused with 400, which looks like a broken endpoint and is not. Browser and Node clients negotiate this correctly on their own.

2. Polling a receipt

For “did my transaction land”, polling the receipt is simpler than a subscription and costs one request per block:

async function waitForReceipt(hash: string, timeoutMs = 60_000) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const receipt = await provider.getTransactionReceipt(hash);
    if (receipt) return receipt;          // receipt.status === 1 → success, 0 → reverted
    await new Promise(r => setTimeout(r, 5_000));   // one block
  }
  throw new Error(`no receipt for ${hash} after ${timeoutMs}ms`);
}

A receipt normally appears within one or two blocks — budget 60 s before declaring failure, and never below 15 s.

The public RPC is served by an archive node that syncs from the validators, so a receipt can appear a beat after the block that contains it. If you poll a receipt in a tight loop and get null for a transaction you just sent, that is the lag, not a failure.

3. Async REST endpoints

Some REST endpoints do several transactions and answer before they settle. They return 202 Accepted with the hashes and a pollUrl.

Faucet

POST /api/faucet → 202
{
  "ok": true,
  "pending": true,
  "nativeTxHash": "0x...",
  "txHash": "0x...",
  "ycrTxHash": "0x...",
  "pollUrl": "/api/faucet/status/0x..."
}

The three transfers (native gas, YCE, YCR) are submitted immediately and land within a few blocks. Poll the pollUrl until nativeBalance is non-zero:

const res = await fetch(`${API}/api/faucet`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ address }),
});
const { pollUrl } = await res.json();

for (let i = 0; i < 12; i++) {
  await new Promise(r => setTimeout(r, 5_000));
  const status = await fetch(`${API}${pollUrl}`).then(r => r.json());
  if (status.nativeBalance !== "0") break;        // funded
}

Measured on the live testnet: the POST answers in under a second, and the balance is visible ~15 s later.

The faucet used to hold the connection until all three receipts existed, which took ~40 s and exceeded the default timeout of most HTTP clients — a working faucet looked broken. If you have an older client that treats a slow response as failure, it can be simplified: the answer is immediate now.

Engagement

POST /api/mobile/engagement returns a txHash right away with status: "pending". The reward is visible once the block is committed:

await fetch(`${API}/api/mobile/engagement`, { /* ... */ });
// a block later:
const rewards = await fetch(`${API}/api/mobile/rewards/${address}`).then(r => r.json());
// rewards.pendingYcrTokens → "5.0000"

Send an Idempotency-Key header so a network retry replays the original response instead of recording the action twice — mobile networks retry on their own, and a double like is a double mint.

Cadence cheat sheet

What	Interval	Give up after
Transaction receipt	5 s	60 s
Faucet status	5 s	60 s
Rewards / profile after an action	5 s	30 s
Chain height (no subscription)	5–10 s	—
Anything while the screen is hidden	stop polling	—

Prefer one newHeads subscription per app over N polling loops: one socket tells every screen that the chain moved, and each screen refetches only what it shows.

​Pick the right mechanism

​1. WebSocket — newHeads

​2. Polling a receipt

​3. Async REST endpoints

​Faucet

​Engagement

​Cadence cheat sheet

Pick the right mechanism

1. WebSocket — `newHeads`

2. Polling a receipt

3. Async REST endpoints

Faucet

Engagement

Cadence cheat sheet