Skip to content

chore: pc20-documentation #1233

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mohammeds1992 wants to merge 7 commits into
base: main
Choose a base branch
from
Open

chore: pc20-documentation #1233

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
17b04a3
chore: pc20-documentation
mohammeds1992 Aug 3, 2026
41e2dd2
fix: minor fix
mohammeds1992 Aug 3, 2026
e693cad
chore(settings): expand Claude tool allowlist for git/gh/browser work…
HarshRajat Aug 11, 2026
08fe252
docs(chain): clarify PRC20 vs PC20 distinction and improve token reso…
HarshRajat Aug 11, 2026
15f1f74
docs(chain): rewrite PC20 examples as self-contained round-trip flows…
HarshRajat Aug 19, 2026
613b767
docs(chain): consolidate PC20 funds docs and add token-type distinction
HarshRajat Aug 19, 2026
8b48c54
docs(chain): standardize PC-20 and PRC-20 hyphenation across all docu…
HarshRajat Aug 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 27 additions & 1 deletion .claude/settings.local.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,33 @@
"mcp__acp__Write",
"mcp__acp__Edit",
"Bash(node:*)",
"Read(//Users/Prodigy/.claude/**)"
"Read(//Users/Prodigy/.claude/**)",
"Bash(git fetch *)",
"Bash(git checkout *)",
"Bash(git ls-remote *)",
"mcp__95f498ec-a312-4638-979c-64a5024e71a9__notion-fetch",
"Bash(ls -la /Users/Prodigy/Desktop/Inhouse/PUSH/push-website/.claude/worktrees/weekly-lfpush-refresh-06bae9/ 2>&1 | head; echo \"=== any tracker in worktree? ===\"; find /Users/Prodigy/Desktop/Inhouse -iname '*tracker*' -maxdepth 6 2>/dev/null | head)",
"mcp__claude-in-chrome__tabs_context_mcp",
"mcp__claude-in-chrome__browser_batch",
"mcp__claude-in-chrome__javascript_tool",
"Bash(git add *)",
"Bash(git commit -S --no-verify -m ' *)",
"Bash(git log *)",
"Bash(git push *)",
"Bash(gh pr *)",
"Bash(find /opt/homebrew /usr/local /Applications /Users/Prodigy/.local -maxdepth 4 -name gh -type f 2>/dev/null | head -5; echo \"--- brew? ---\"; which brew 2>&1; echo \"--- git remote ---\"; git remote -v | head -2)",
"Bash(/opt/homebrew/bin/brew list *)",
"Bash(sed -E 's/\\(oauth_token:\\).*/\\\\1 <REDACTED>/' ~/.config/gh/hosts.yml)",
"Bash(/opt/homebrew/bin/brew install *)",
"Bash(/opt/homebrew/bin/gh auth *)",
"Bash(/opt/homebrew/bin/gh api *)",
"Bash(/opt/homebrew/bin/gh repo *)",
"Bash(echo \"--- exit: $? ---\")",
"Bash(curl -s -A \"Mozilla/5.0 \\(Macintosh; Intel Mac OS X 10_15_7\\) AppleWebKit/537.36 \\(KHTML, like Gecko\\) Chrome/120.0 Safari/537.36\" \"https://cdn.syndication.twimg.com/tweet-result?id=2082672823462416656&token=a&lang=en\")",
"Bash(python3 -c \"import json,sys; d=json.load\\(sys.stdin\\); print\\(d.get\\('created_at'\\), '|', d.get\\('user',{}\\).get\\('screen_name'\\), '|', d.get\\('favorite_count'\\)\\)\")",
"Bash(git worktree *)",
"Bash(ln -sfn /Users/Prodigy/Desktop/Inhouse/PUSH/push-website/node_modules .claude/worktrees/lfpush-2026-08-08/node_modules)",
"mcp__claude-in-chrome__navigate"
]
}
}
36 changes: 26 additions & 10 deletions build.agents.examples.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,13 +47,14 @@ const SDK_METHODS = [
'PushChain.utils.account.toUniversalFromKeypair',
'PushChain.utils.account.deriveExecutorAccount',
'PushChain.utils.account.resolveControllerAccount',
'PushChain.utils.chain.getChainNamespace',
'PushChain.utils.chain.getChainName',
'PushChain.utils.chain.getSupportedChains',
'PushChain.utils.tx.encodeTxData',
'PushChain.utils.token.getMoveableTokens',
'PushChain.utils.token.getPayableTokens',
'PushChain.utils.token.getPRC20Address',
'PushChain.utils.chains.getChainNamespace',
'PushChain.utils.chains.getChainName',
'PushChain.utils.chains.getSupportedChains',
'PushChain.utils.helpers.encodeTxData',
'PushChain.utils.tokens.getMoveableTokens',
'PushChain.utils.tokens.getPayableTokens',
'PushChain.utils.tokens.getPRC20Address',
'PushChain.utils.tokens.getPC20Address',
'PushChain.utils.conversion.originToExecutor',
'PushChain.utils.conversion.executorToOrigin',
];
Expand Down Expand Up @@ -389,11 +390,23 @@ export const buildAgentsExamples = async () => {

await fs.mkdir(AGENTS_EXAMPLES_DIR, { recursive: true });

// Load existing index so we can skip already-registered IDs
// Load existing index so we can skip already-registered IDs.
//
// The index was migrated from a bare array to an object wrapper
// (`{ schema_version, …, examples: [] }`) — see its own `migration_note`.
// Both shapes are accepted, and whichever one was read is the one written
// back, so the wrapper's metadata survives a regeneration.
let existingIndex = [];
let indexWrapper = null;
try {
const raw = await fs.readFile(INDEX_PATH, 'utf-8');
existingIndex = JSON.parse(raw);
const parsed = JSON.parse(raw);
if (Array.isArray(parsed)) {
existingIndex = parsed;
} else if (parsed && Array.isArray(parsed.examples)) {
existingIndex = parsed.examples;
indexWrapper = parsed;
}
} catch {
// No existing index — start fresh
}
Expand Down Expand Up @@ -500,7 +513,10 @@ export const buildAgentsExamples = async () => {
// Persist updated index
if (newEntries.length > 0) {
const merged = [...existingIndex, ...newEntries];
await fs.writeFile(INDEX_PATH, JSON.stringify(merged, null, 2), 'utf-8');
const payload = indexWrapper
? { ...indexWrapper, examples: merged }
: merged;
await fs.writeFile(INDEX_PATH, JSON.stringify(payload, null, 2), 'utf-8');
console.log(
chalk.cyan(
`\n📖 Updated examples/index.json → ${merged.length} total entries`
Expand Down
17 changes: 10 additions & 7 deletions docs/chain/02-setup/02-Smart-Contract-Address-Book.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,9 @@ Custom precompiles deployed on Push Chain for universal transaction verification

### PRC-20 Supported Tokens (on Push Chain)

Push-native representations of tokens bridged from external chains. Each PRC-20 token is minted on Push Chain when its source token is deposited via the respective chain's gateway.
Push Chain representations of tokens that live natively on an external chain. Each PRC-20 token is minted on Push Chain when its source token is deposited via the respective chain's gateway.

> See [Token Types on Push Chain](/docs/chain/important-concepts#token-types-on-push-chain) for how PRC-20 differs from PC-20.

| Token Name | Symbol | Source Chain | Token Address on Push Chain |
| ---------- | --------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -91,7 +93,8 @@ Push-native representations of tokens bridged from external chains. Each PRC-20
| USDC.bsc | USDC.bsc | BNB_Testnet | [0x120EBf25Dad7D6a09Ad2316f23f9Be95DBb90639](https://donut.push.network/address/0x120EBf25Dad7D6a09Ad2316f23f9Be95DBb90639?tab=contract) |
| USDT.bnb | USDT.bnb | BNB_Testnet | [0x731aF1Da5365259d27528557EE4aFBA4baC90ef2](https://donut.push.network/address/0x731aF1Da5365259d27528557EE4aFBA4baC90ef2?tab=contract) |

---
> **PC-20 wrappers are not listed here.** A PRC-20 is created by Push Chain, so it can be published as a fixed table. A PC-20 wrapper is deployed on the external chain the first time its token is exported there, so the set changes over time and lives in UniversalCore's on-chain registry instead. Resolve one with [`getPC20Address`](/docs/chain/build/utility-functions/#get-pc-20-address).


### Core AMM & Helpers

Expand Down Expand Up @@ -165,7 +168,7 @@ Vault contract custodies user funds deposited via the gateway and coordinates wi

Tokens accepted by the Ethereum Sepolia gateway and their corresponding PRC-20 representations on Push Chain.

| Token Name | Source Address | PRC20 Address (on Push Chain) |
| Token Name | Source Address | PRC-20 Address (on Push Chain) |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Native ETH | 0x0000000000000000000000000000000000000000 | [0x2971824Db68229D087931155C2b8bB820B275809](https://donut.push.network/address/0x2971824Db68229D087931155C2b8bB820B275809?tab=contract) `pETH` |
| USDC | [0x97F477B7f970D47a87B42869ceeace218106152a](https://sepolia.etherscan.io/address/0x97F477B7f970D47a87B42869ceeace218106152a#code) | [0x7A58048036206bB898008b5bBDA85697DB1e5d66](https://donut.push.network/address/0x7A58048036206bB898008b5bBDA85697DB1e5d66?tab=contract) `USDC.eth` |
Expand Down Expand Up @@ -206,7 +209,7 @@ Vault contract on Arbitrum Sepolia that custodies deposited funds and coordinate

Tokens accepted by the Arbitrum Sepolia gateway and their corresponding PRC-20 representations on Push Chain.

| Token Name | Source Address | PRC20 Address (on Push Chain) |
| Token Name | Source Address | PRC-20 Address (on Push Chain) |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Native ETH | 0x0000000000000000000000000000000000000000 | [0xc0a821a1AfEd1322c5e15f1F4586C0B8cE65400e](https://donut.push.network/address/0xc0a821a1AfEd1322c5e15f1F4586C0B8cE65400e?tab=contract) `pETH.arb` |
| USDC | [0x5dd39b0b3610F666F631a6506b7713EF83e1Ac5C](https://sepolia.arbiscan.io/address/0x5dd39b0b3610F666F631a6506b7713EF83e1Ac5C#code) | [0x1091cCBA2FF8d2A131AE4B35e34cf3308C48572C](https://donut.push.network/address/0x1091cCBA2FF8d2A131AE4B35e34cf3308C48572C?tab=contract) `USDC.arb` |
Expand Down Expand Up @@ -246,7 +249,7 @@ Vault contract on Base Sepolia that custodies deposited funds and coordinates cr

Tokens accepted by the Base Sepolia gateway and their corresponding PRC-20 representations on Push Chain.

| Token Name | Source Address | PRC20 Address (on Push Chain) |
| Token Name | Source Address | PRC-20 Address (on Push Chain) |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Native ETH | 0x0000000000000000000000000000000000000000 | [0xc7007af2B24D4eb963fc9633B0c66e1d2D90Fc21](https://donut.push.network/address/0xc7007af2B24D4eb963fc9633B0c66e1d2D90Fc21?tab=contract) `pETH.base` |
| USDC | [0x5c3504F0E3bA28FDc1F74234fE936518276AaBB8](https://sepolia.basescan.org/address/0x5c3504F0E3bA28FDc1F74234fE936518276AaBB8#code) | [0xD7C6cA1e2c0CE260BE0c0AD39C1540de460e3Be1](https://donut.push.network/address/0xD7C6cA1e2c0CE260BE0c0AD39C1540de460e3Be1?tab=contract) `USDC.base` |
Expand Down Expand Up @@ -286,7 +289,7 @@ Vault contract on BNB Testnet that custodies deposited funds and coordinates cro

Tokens accepted by the BNB Testnet gateway and their corresponding PRC-20 representations on Push Chain.

| Token Name | Source Address | PRC20 Address (on Push Chain) |
| Token Name | Source Address | PRC-20 Address (on Push Chain) |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Native BNB | 0x0000000000000000000000000000000000000000 | [0x7a9082dA308f3fa005beA7dB0d203b3b86664E36](https://donut.push.network/address/0x7a9082dA308f3fa005beA7dB0d203b3b86664E36?tab=contract) `pBNB` |
| USDC | [0xA8802F96cAd0d45343d9bc660B6f7d80050A660b](https://testnet.bscscan.com/address/0xA8802F96cAd0d45343d9bc660B6f7d80050A660b#code) | [0x120EBf25Dad7D6a09Ad2316f23f9Be95DBb90639](https://donut.push.network/address/0x120EBf25Dad7D6a09Ad2316f23f9Be95DBb90639?tab=contract) `USDC.bsc` |
Expand All @@ -309,7 +312,7 @@ Contracts deployed on Solana Devnet. The Solana gateway is a native Solana progr

Tokens accepted by the Solana Devnet gateway and their corresponding PRC-20 representations on Push Chain.

| Token Name | Source Address | PRC20 Address (on Push Chain) |
| Token Name | Source Address | PRC-20 Address (on Push Chain) |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Native SOL | — | [0x5D525Df2bD99a6e7ec58b76aF2fd95F39874EBed](https://donut.push.network/address/0x5D525Df2bD99a6e7ec58b76aF2fd95F39874EBed?tab=contract) `pSOL` |
| USDC | [4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU](https://explorer.solana.com/address/4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU?cluster=devnet) | [0x04B8F634ABC7C879763F623e0f0550a4b5c4426F](https://donut.push.network/address/0x04B8F634ABC7C879763F623e0f0550a4b5c4426F?tab=contract) `USDC.sol` |
Expand Down
25 changes: 25 additions & 0 deletions docs/chain/03-Important-Concepts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -202,6 +202,31 @@ Every external chain is represented as a particular constant on Push Chain. Ment

> The namespaces are inspired from [caip-10](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-10.md 'Link to caip-10 proposal') format.

## Token Types on Push Chain

Push Chain represents tokens in two directions. Which standard a token uses tells you which direction it came from.

| Standard | Native to | Represented as |
| --------- | ----------------- | ---------------------------------------------------- |
| **PRC-20** | An external chain | A synthetic token on Push Chain (`USDC.eth`, `pETH`) |
| **PC-20** | Push Chain | A wrapper deployed on the external chain |

- **PRC-20 → foreign tokens, mirrored inward**<br />
Synthetic Push Chain representations of tokens that live natively on an external chain.

For instance, USDC on Ethereum Sepolia becomes **USDC.eth** on Push Chain; native ETH becomes **pETH**.

Push Chain creates one PRC-20 per source token, per origin chain. See the [Address Book](/docs/chain/setup/smart-contract-address-book) for every PRC-20 and its source token.

- **PC-20 → Push-native tokens, mirrored outward**<br />
Tokens whose canonical version lives on Push Chain and which can be exported to external chains, where a wrapper is deployed to represent them.

The canonical token stays on Push Chain; the wrapper is what travels.

> **Mental model**
> PRC-20 = a foreign token, wearing a Push jacket.
> PC-20 = a Push token, wearing a foreign jacket.

## Next Steps

- Setup your [Environment and Tooling](/docs/chain/setup/)
Expand Down
17 changes: 17 additions & 0 deletions docs/chain/03-build/01-Recommended-Practices.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,23 @@ To understand where your users are coming from—whether directly on Push Chain

These helpers are already deployed and maintained, so you can easily integrate them into your logic with minimal effort.

## Moving Tokens Across Chains

Push Chain has two token standards:

- **PRC-20** for tokens that come in from an external chain, and
- **PC-20** for Push-native tokens that go out to one.

See [Token Types on Push Chain](/docs/chain/important-concepts#token-types-on-push-chain) for the distinction. Two habits will save you most of the debugging:

- **Resolve decimals, never hardcode them.**<br />
`parseUnits('1', 6)` is only correct for six-decimal tokens such as USDC and USDT. Both **getPRC20Address()** and **getPC20Address()** return the token's decimals.

Resolve the token first, then pass what it reports. Hardcoding the wrong exponent does not throw; it silently moves the wrong amount.

- **When naming a token's chain, name where it *is*.**<br />
In `funds.token`, `chain` is the chain the tokens are sitting on right now, not the chain they are headed to. The destination is a separate field. Getting this backwards is rejected before anything is signed, so it fails loudly, but it is the single most common first mistake.

## Speed run

<NodeJSVirtualIDE repo={{title: "Open in Github", url: "https://github.com/pushchain/push-chain-examples/tree/main/core-sdk-functions/initialize-push-chain-client"}}>
Expand Down
2 changes: 1 addition & 1 deletion ...03-build/02-contract-initiated-examples/02-Example-Outbound-From-Push-Chain.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ This is the smallest contract-initiated outbound that runs end to end on Donut.
| **Direction** | Push Chain to BNB Testnet. One-way. No back-leg. |
| **Trigger** | A regular EOA calls `dispatchOutbound(...)` on the Push contract. |
| **Identity on BNB** | The destination contract sees `msg.sender` equal to the Push contract's deterministic CEA on BNB. |
| **Funds movement** | None. The example dispatches a payload only. The same surface supports bridging PRC20 (`token` + `amount`); see the [Advanced Patterns](/docs/chain/build/contract-initiated-examples/advanced-patterns) for funds variants. |
| **Funds movement** | None. The example dispatches a payload only. The same surface supports bridging PRC-20 (`token` + `amount`); see the [Advanced Patterns](/docs/chain/build/contract-initiated-examples/advanced-patterns) for funds variants. |
| **Verified on** | Donut Testnet. |

## Identity model
Expand Down
Loading