This repository contains the core smart contracts powering Push Chain's universal interoperability protocol. The system enables users and applications from any supported chain to interact with Push Chain through deterministic smart accounts, a protocol coordinator, and synthetic token primitives — all without requiring a native Push Chain wallet.
- Foundry
- Solidity 0.8.26 (auto-pinned via
foundry.toml)
forge buildforge test # all tests
forge test -vvv # verbose output
forge test --match-test testName # single test by name
forge test --match-contract ContractTest # single contract
forge test --match-path test/tests_uea_and_factory/UEA_EVM.t.sol # single file
forge test --gas-report # with gas reportCoverage requires lcov for HTML report generation (optional):
# Ubuntu
sudo apt install lcov
# macOS
brew install lcovforge coverage --ir-minimum --no-match-coverage "(PRC20V0\.sol|UniversalCoreV0\.sol|ReceiverExample\.sol|src/(libraries|[Ii]nterfaces|mocks)/|test/)"Note: The
--ir-minimumflag is required because the codebase usesvia_ir = true. Without it,forge coveragedisables the optimizer and hits "Stack too deep" errors in some fuzz tests. The--ir-minimumflag re-enablesviaIRwith minimal optimization, producing accurate coverage without stack issues.
- Push Chain Overview — what Push Chain is and how cross-chain flows work
- Universal Executor Accounts (UEA) — UEA architecture, execution model, and migration
- Chain Executor Accounts (CEA) — CEA architecture, outbound flows, and migration
- UniversalCore — protocol coordinator, fee model, and role breakdown
- CEA + UEA Migration Flow — step-by-step proxy migration diagrams
- Threat Model — STRIDE threat tables, invariants, and trust boundaries
RPC: https://rpc.push.org/testnet
Push Chain Docs: https://push.org/docs/
MIT