Paycrest Contracts

Description

Paycrest contracts are multi-chain EVM-based smart contracts that facilitate the on-chain lifecycle of a payment order. They empower a sender to create a payment order, enable a liquidity provider to receive cryptocurrency in escrow, and much more.

Deployment

Deployment is done using Hardhat Ignition

Deploy upgradeable proxy contract

npx hardhat ignition deploy ./ignition/modules/Gateway.ts --network <network>

Redeploy (reset previous deployment state)

npx hardhat ignition deploy ./ignition/modules/Gateway.ts --network <network> --reset

Verify contract

npx hardhat verify --network <network> <contract_address>

Tron network

# deploy
tronbox migrate -f 1 --to 1 --network <network>

# upgrade
tronbox migrate -f 2 --to 2 --network <network>

Upgrade all EVM gateways (recommended)

Uses the same DEPLOYER_PRIVATE_KEY on every chain. Proxy addresses stay the same; only the implementation is replaced.

# Preview targets (no transactions)
npx hardhat upgrade-all-evm --dry-run

# Upgrade all EVM mainnets
npx hardhat upgrade-all-evm

# Re-apply unified fee settings after each upgrade
npx hardhat upgrade-all-evm --set-fees --update-config

# Subset of networks
npx hardhat upgrade-all-evm --networks base,arbitrum,8453

# npm shortcuts
npm run upgrade:all-evm:dry-run
npm run upgrade:all-evm

Flags: --dry-run, --set-fees, --update-config, --networks, --fail-fast, --yes (skip prompt).

Tron is not included — use tronbox migrate -f 2 --to 2 separately.

RPC: scripts/config.ts uses Shield3 URLs (SHIELD3_API_KEY). If rpc.shield3.com is unreachable, the upgrade task falls back to public RPCs automatically. Override per chain with RPC_URL_<chainId> in .env (e.g. RPC_URL_8453=https://mainnet.base.org).

Upgrade single network (legacy)

npx hardhat run scripts/upgrade.ts --network <network>

Owner configurations

Update network settings in scripts/config.ts

npx hardhat run scripts/setSupportedTokens.ts --network <network>

npx hardhat run scripts/updateProtocolAddresses.ts --network <network>

npx hardhat run scripts/setTokenFeeSettings.ts --network <network>

# for Tron network,
npx hardhat run scripts/tron/setSupportedTokens.ts

npx hardhat run scripts/tron/updateProtocolAddresses.ts

npx hardhat run scripts/tron/setTokenFeeSettings.ts

Testnet Contracts

Network	Contracts	Address
Ethereum Sepolia	Gateway Proxy	0xCAD53Ff499155Cc2fAA2082A85716322906886c2
	Gateway Implementation	0xafbf71A72d30f81eb66baaF904ea537fD35dd106
Polygon Amoy	Gateway Proxy	0xCAD53Ff499155Cc2fAA2082A85716322906886c2
	Gateway Implementation	0xd2d97002ec87ba57fcf3f6b510f20d5a80a6c33a
Arbitrum Sepolia	Gateway Proxy	0x87B321fc77A0fDD0ca1fEe7Ab791131157B9841A
	Gateway Implementation	0xd2d97002Ec87ba57FCf3f6b510f20d5A80A6C33a
Base Sepolia	Gateway Proxy	0x847dfdAa218F9137229CF8424378871A1DA8f625
	Gateway Implementation	0xd2d97002Ec87ba57FCf3f6b510f20d5A80A6C33a
Asset Chain Testnet	Gateway Proxy	0xBe6dE889795677736919A7880324A71Dc7dFa162
	Gateway Implementation	0x9519D63fbF9717Fa3419846eBA92B01Cd1d1D131
Tron Shasta	Gateway Proxy	TYA8urq7nkN2yU7rJqAgwDShCusDZrrsxZ
	Gateway Implementation	TSGr6Ri7NZ7FxN1gCiWkn8cPA2qtF6ctdF
	Gateway Admin	TNcogTDoWxpuv77WtsiNTRhqjRbZmmDLTR

Mainnet Contracts

Network	Contracts	Address
Ethereum	Gateway Proxy	0x8d2C0D398832b814e3814802FF2dC8b8eF4381e5
	Gateway Implementation	0x0BC10d31B96838aD5783a0dd994fb16e14609e6E
	Gateway Admin	0xfe12e3afaa5e3702eafb5929781441fc63d30381
Polygon	Gateway Proxy	0xfB411Cc6385Af50A562aFCb441864E9d541CDA67
	Gateway Implementation	0xd2d97002ec87ba57fcf3f6b510f20d5a80a6c33a
Base	Gateway Proxy	0x30F6A8457F8E42371E204a9c103f2Bd42341dD0F
	Gateway Implementation	0xd28da2E11FCd2A9F44D5a4952430CE8b4f3Ee05f
BNB Smart Chain	Gateway Proxy	0x1FA0EE7F9410F6fa49B7AD5Da72Cf01647090028
	Gateway Implementation	0xd2d97002ec87ba57fcf3f6b510f20d5a80a6c33a
Arbitrum One	Gateway Proxy	0xE8bc3B607CfE68F47000E3d200310D49041148Fc
	Gateway Implementation	0x8fd1f78d88dd008e557273b5cd517487c2a9a7de
Optimism (defunct)	Gateway Proxy	0xD293fCd3dBc025603911853d893A4724CF9f70a0
	Gateway Implementation	0xd2d97002Ec87ba57FCf3f6b510f20d5A80A6C33a
	Gateway Admin	0xb9B5280AB99E48a9662D4740B1e1398abdf87b6D
Scroll (defunct)	Gateway Proxy	0x663C5BfE7d44bA946C2dd4b2D1Cf9580319F9338
	Gateway Implementation	0xd2d97002ec87ba57fcf3f6b510f20d5a80a6c33a
	Gateway Admin	0x16c9C78Dbb224889E3e2ADef991C8c4438ea797B
Celo	Gateway Proxy	0xF418217E3f81092eF44b81C5C8336e6A6fDB0E4b
	Gateway Implementation	0x8508c1C9f29BD1e73B5A9bD8FB87720927c681FA
	Gateway Admin	0xc38D6817F736b1cb44785e14A8cb7152385d3210
Lisk (defunct)	Gateway Proxy	0xff0E00E0110C1FBb5315D276243497b66D3a4d8a
	Gateway Implementation	0x3Dc80272cE93cBFF3351913bB089B59C4a9141DE
	Gateway Admin	0x8FD1f78d88Dd008E557273b5Cd517487C2A9A7de
Asset Chain	Gateway Proxy	0xff0E00E0110C1FBb5315D276243497b66D3a4d8a
	Gateway Implementation	0x3Dc80272cE93cBFF3351913bB089B59C4a9141DE
Tron	Gateway Proxy	THyFP5ST9YyLZn6EzjKjFhZti6aKPgEXNU
	Gateway Implementation	TDhBvHbnF8nN7YctokpdZAVPcmBx2Jrn2d
	Gateway Admin	TLw6AW9khfwLVq5gq9uV71wTVZEPxKjoiZ

Testing

Contract tests are defined under the test/ directory. To run all tests, run:

npx hardhat test

Commits and PRs

This project uses Conventional Commits to generate release notes and to determine versioning. Commit messages should adhere to this standard and be of the form:

$ git commit -m "feat: Add new feature x"
$ git commit -m "fix: Fix bug in feature x"
$ git commit -m "docs: Add documentation for feature x"
$ git commit -m "test: Add test suite for feature x"

Further details on conventional commits can be found here

Contributing

We welcome contributions to the Paycrest gateway contract! To get started, follow these steps:

Important: Before you begin contributing, please ensure you've read and understood these important documents:

• Contribution Guide - Critical information about development process, standards, and guidelines.

• Code of Conduct - Our community standards and expectations.

Our team will review your pull request and work with you to get it merged into the main branch of the repository.

If you encounter any issues or have questions, feel free to open an issue on the repository or leave a message in our developer community on Telegram

Contributors ✨

Prosperity 💻	chibie 💻
Add your contributions

This project follows the all-contributors specification. Contributions of any kind welcome!

License

Affero General Public License v3.0

Formal verification

Contracts that hold or move funds ship behind a verification gate: unit, fuzz and invariant tests (Foundry), bounded symbolic checks (Halmos), static analysis (Slither), a 100% line and branch coverage gate, and a property-to-test traceability check against the contract's spec in docs/. Each gate is a make target defined in its own <name>-verify.mk and run by its own CI workflow; make help lists them.

make verify-tools  # one-time: forge on PATH, forge-std submodule, .venv with halmos + slither
make help          # every gate and its steps

Halmos and Slither are pinned in requirements-verify.txt, because a tool upgrade can change what a gate proves; bump them in their own PR with every gate re-run. requirements-verify.lock is the fully resolved, hash-pinned expansion of that file, and CI installs it with --require-hashes so the tools that decide the result, and all their transitive dependencies, are reproducible. That guarantee covers the verifier packages; pip itself and the runner image are not pinned. Foundry is pinned to a specific release in each workflow for the same reason. Regenerate the lock with:

uv pip compile --universal --generate-hashes -o requirements-verify.lock requirements-verify.txt

make verify-tools deliberately installs the loose file instead, so local setup works on whatever interpreter you have. CI is the authority; if a local run ever disagrees with it, compare the two environments.

Foundry lives alongside Hardhat: Hardhat keeps ignition/typechain artifacts and test/**/*.js; Foundry owns test/foundry/*.sol (Hardhat's Solidity test runner is pointed at test/hardhat-solidity). Foundry output goes to out/ and cache_forge/, never to Hardhat's artifacts/ or cache/.