xtoken

Imported from xmoneyx/xtoken (AGENTS.md). Install upstream with npx skills add xmoneyx/xtoken. Copyright stays with the author.

AGENTS.md instructions for /home/baron/corecoin/cueswapV3

Project context

This repo is for smart contracts on a custom Core-like blockchain using the Ylem compiler. Use the custom framework spart (a clone of Foundry/Forge). Build with spark build, and run tests with spark test.

1) Blockchain Parameters (Project-Independent)

Compiler and execution model:

• Pragmas should always be pragma solidity ^1.1.2.
• Addresses are 22 bytes.
• keccak256 is implemented as SHA3-256 under the hood.
• As a result, all function selectors and hash-derived constants differ from Ethereum and must be recomputed for Core.

Cryptography differences vs Ethereum:

• ecrecover takes two arguments: ecrecover(bytes32 hash, bytes signature).
• Failed recovery hard reverts (burns 63/64 gas), instead of returning address(0) or a random address.
• Signature length is fixed to 171 bytes; reject any other length.
• No exposed (v, r, s) tuple at Solidity level; signatures are passed as one blob.
• Signed-message prefix is "\x19Core Signed Message:\n32".
• Typed-data hashing keeps EIP-712 framing: keccak256("\x19\x01" || domainSeparator || structHash).

Address derivation model:

• A 32-byte secp256k1 private key derives a raw 20-byte EVM-style address.
• Core addresses are 22-byte ICAN addresses: network prefix + BCD checksum + raw address.
• Network prefixes used by Checksum.toIcan: mainnet 0xcb, devin 0xab.

RPC model:

• Core RPC uses xcb_* methods (example: xcb_getBalance), not eth_*.

2) Core OpenZeppelin Compatibility (Project-Independent)

Core naming and library compatibility:

• OpenZeppelin ECDSA corresponds to EDDSA in this ecosystem.
• ERC standards are named CRC*:
  • CRC20 / CRC20Upgradeable
  • CRC721 / CRC721Upgradeable
  • CRC1155 / CRC1155Upgradeable
• Use Core naming in file names, contract names, and revert reasons.

Core OpenZeppelin repositories (current):

• Non-upgradeable: https://github.com/bchainhub/openzeppelin-contracts
• Upgradeable: https://github.com/bchainhub/openzeppelin-contracts-upgradeable

Zero-address policy:

• Two zero-like values exist: address(0) and Checksum.zeroAddress().
• For mint/burn style events with no real transfer, emit real zero: address(0).
• Any non-zero address validation must reject both address(0) and Checksum.zeroAddress().

ERC1967 slot constants (SHA3-256 minus 1):

• implementation: 0x169aa7877a62aec264f92a4c78812101abc42f65cbb20781a5cb4084c2d639d7
• admin: 0x5846d050da0e75d43b6055ae3cd6c2c65e1941ccb45afff84b891ff0c7a8e50e
• beacon: 0x79d0e26f0ed6a26bf96d37944c615e11aedbfafe56e064339e13dad9525cda31
• rollback: 0x9918ff29762f88fdc924c0a0ba5589b288a6baef366b4981f9a6f4309baada55

Common selector differences (SHA3-256 based):

• admin() selector: 0xeb8325fb
• implementation() selector: 0xf5d97006
• ERC1271 isValidSignature(bytes32,bytes) selector: 0x95f9a59b
• ERC165 supportsInterface(bytes4) selector: 0x80ada41b

3) Foxar / Spart Tooling (Project-Independent)

Tooling mapping:

• forge -> spark
• cast -> probe
• anvil -> shuttle
• chisel -> pilot
• foundryup -> foxarup

Foxar source of truth (for local debugging instead of web search):

• Repo: https://github.com/bchainhub/foxar
• Nonce-fix sequence to check first: cba86ce (fix: nonce on simulation), d980b35 (fix: deploy nonce), 4f6db45 (fix: nonce).

Network profiles (recommended explicit config):

• Do not rely on implicit defaults; select a profile and pass explicit flags/env.
• Devin:
  • address prefix: ab...
  • rpc: https://xcbapi.corecoin.cc/
  • network id: 3
• Mainnet:
  • address prefix: cb...
  • rpc: mainnet RPC endpoint for your environment
  • network id: query via probe network-id --rpc-url <mainnet-rpc>

Address prefix validation:

• All addresses in one run must match selected network prefix.
• Devin runs use ab...; mainnet runs use cb....
• Prefix mismatch should be treated as configuration error first.

Devin faucet flow (native XCB):

• Generate Devin-compatible keypair: probe wallet new --network devin.
• Faucet endpoint: POST https://api.devin.energy/api/claim as multipart form.
• Field: address (Devin-prefixed, no 0x).
• Verify funds: probe rpc --rpc-url https://xcbapi.corecoin.cc/ xcb_getBalance ab<address> latest.

Spark deploy/script guidance:

• Build: spark build
• Create deployment:
  • spark create src/<YourContract>.sol:<YourContract> --rpc-url <rpc> --network-id <id> --private-key "$PK"
• Script (read-only):
  • spark script script/<Script>.s.sol:<Script> --rpc-url <rpc> --network-id <id>
• Script (broadcast):
  • spark script script/<Script>.s.sol:<Script> --rpc-url <rpc> --network-id <id> --private-key "$PK" --broadcast
• If startup/simulation shows address-prefix errors, pin origin:
  • --sender "0x$ADDRESS" --tx-origin "0x$ADDRESS"

Energy price policy:

• For broadcast deploy/script flows, set energy price explicitly.
• Preflight check:
  • probe rpc --rpc-url <rpc-url> xcb_energyPrice
• Use explicit flag:
  • --energy-price <value> (or --with-energy-price <value> where applicable)