Skip to content

Commit fe9a520

Browse files
CarsonRoscoeCarsonRoscoe
committed
feat: added and implemented @x402/evm-contracts
1 parent 54db9d5 commit fe9a520

35 files changed

+20095
-1038
lines changed

‎e2e/pnpm-lock.yaml‎

Lines changed: 5420 additions & 366 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎e2e/pnpm-workspace.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,4 @@ packages:
1111
- "../typescript/packages/http/*"
1212
- "../typescript/packages/mechanisms/*"
1313
- "../typescript/packages/legacy/*"
14+
- "../typescript/packages/contracts/*"

‎examples/typescript/pnpm-lock.yaml‎

Lines changed: 3898 additions & 371 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎examples/typescript/pnpm-workspace.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,4 @@ packages:
1616
- "../../typescript/packages/http/*"
1717
- "../../typescript/packages/mechanisms/*"
1818
- "../../typescript/packages/legacy/*"
19+
- "../../typescript/packages/contracts/*"

‎typescript/packages/contracts/evm/.gitignore‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
node_modules
2+
.env
3+
4+
# Test coverage
5+
coverage
6+
coverage.json
7+
8+
# Hardhat build output (compile artifacts, cache, typechain)
9+
dist-hardhat/
10+
11+
# TypeScript/tsup build output (npm package)
12+
dist/
13+
14+
# Legacy Hardhat paths (in case they get generated)
15+
cache/
16+
artifacts/
17+
typechain-types/
18+
19+
# Deployment records (contain addresses, not secrets)
20+
# Uncomment to track deployments in git:
21+
# !deployments/*.json
22+
deployments/
23+
24+
# Generated ABI exports (auto-generated by build)
25+
src/abis/

‎typescript/packages/contracts/evm/.npmrc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
auto-install-peers=true
2+
strict-peer-dependencies=false

‎typescript/packages/contracts/evm/.prettierrc‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{
2+
"plugins": ["prettier-plugin-solidity"],
3+
"overrides": [
4+
{
5+
"files": "*.sol",
6+
"options": {
7+
"parser": "solidity-parse",
8+
"printWidth": 100,
9+
"tabWidth": 4,
10+
"useTabs": false,
11+
"singleQuote": false,
12+
"bracketSpacing": false
13+
}
14+
}
15+
]
16+
}

‎typescript/packages/contracts/evm/.solhint.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"extends": "solhint:recommended",
3+
"rules": {
4+
"compiler-version": ["error", "^0.8.0"],
5+
"func-visibility": ["warn", { "ignoreConstructors": true }],
6+
"max-line-length": ["warn", 150],
7+
"not-rely-on-time": "off",
8+
"no-empty-blocks": "off",
9+
"gas-custom-errors": "off",
10+
"contract-name-capwords": "off"
11+
}
12+
}

‎typescript/packages/contracts/evm/QUICKSTART.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# @x402/evm-contracts Quickstart
2+
3+
## ✅ Setup Complete!
4+
5+
Your Hardhat project is integrated into the pnpm monorepo at `typescript/packages/contracts/evm/`.
6+
7+
## 🚀 Quick Commands
8+
9+
All commands can be run from anywhere in the monorepo using `pnpm --filter`:
10+
11+
### Build Package
12+
```bash
13+
pnpm --filter @x402/evm-contracts build
14+
```
15+
16+
This runs:
17+
1. `hardhat compile` → `dist-hardhat/` (artifacts, typechain)
18+
2. `extract-abis.ts` → `src/abis/` (x402* ABIs only)
19+
3. `tsup` → `dist/` (ESM + CJS package)
20+
21+
### Run Tests
22+
```bash
23+
# All tests
24+
pnpm --filter @x402/evm-contracts test
25+
26+
# Unit tests only
27+
pnpm --filter @x402/evm-contracts test:unit
28+
29+
# Fork tests (real Permit2 on Base Sepolia)
30+
pnpm --filter @x402/evm-contracts test:fork
31+
32+
# With coverage
33+
pnpm --filter @x402/evm-contracts test:coverage
34+
```
35+
36+
### Local Development
37+
```bash
38+
# Start local Hardhat node
39+
pnpm --filter @x402/evm-contracts node
40+
41+
# Deploy to local network (in another terminal)
42+
pnpm --filter @x402/evm-contracts deploy:local
43+
```
44+
45+
### Deployment
46+
```bash
47+
# Compute deterministic address
48+
pnpm --filter @x402/evm-contracts compute-address
49+
50+
# Deploy to networks
51+
pnpm --filter @x402/evm-contracts deploy:base-sepolia
52+
pnpm --filter @x402/evm-contracts deploy:sepolia
53+
pnpm --filter @x402/evm-contracts deploy:base
54+
55+
# Verify on block explorer
56+
pnpm --filter @x402/evm-contracts verify:base-sepolia <address> <permit2-address>
57+
```
58+
59+
### Code Quality
60+
```bash
61+
# Lint Solidity
62+
pnpm --filter @x402/evm-contracts lint
63+
64+
# Format all code
65+
pnpm --filter @x402/evm-contracts format
66+
67+
# Clean build artifacts
68+
pnpm --filter @x402/evm-contracts clean
69+
```
70+
71+
## 📁 Project Structure
72+
73+
```
74+
packages/contracts/evm/
75+
├── contracts/ # Solidity contracts
76+
│ ├── x402Permit2Proxy.sol # Main protocol contract
77+
│ ├── interfaces/ # IPermit2, etc.
78+
│ └── mocks/ # Test mocks
79+
├── scripts/ # Build & deploy scripts
80+
│ ├── deploy-x402-proxy.ts # CREATE2 deployment
81+
│ ├── compute-address.ts # Address computation
82+
│ ├── extract-abis.ts # ABI extraction
83+
│ └── constants.ts # Internal constants
84+
├── test/ # Contract tests
85+
│ ├── x402Permit2Proxy.test.ts # Unit tests (118 passing)
86+
│ └── x402Permit2Proxy.fork.test.ts # Fork tests (9 passing)
87+
├── src/ # Package exports
88+
│ ├── index.ts # Main entry
89+
│ ├── constants.ts # Public constants
90+
│ └── abis/ # Auto-generated ABIs
91+
├── dist/ # Built package (gitignored)
92+
│ ├── cjs/ # CommonJS
93+
│ └── esm/ # ES Modules
94+
└── dist-hardhat/ # Hardhat output (gitignored)
95+
├── artifacts/
96+
├── cache/
97+
└── typechain-types/
98+
```
99+
100+
## 🔧 Environment Variables
101+
102+
Create a `.env` file for deployments:
103+
104+
```bash
105+
# Required for live deployments
106+
PRIVATE_KEY=your-private-key-here
107+
108+
# RPC URLs (optional, has defaults)
109+
BASE_SEPOLIA_RPC_URL=https://sepolia.base.org
110+
SEPOLIA_RPC_URL=https://rpc.sepolia.org
111+
112+
# For contract verification
113+
BASESCAN_API_KEY=your-basescan-api-key
114+
```
115+
116+
## 📦 Package Exports
117+
118+
When published, the package exports:
119+
120+
```typescript
121+
// Main entry
122+
import {
123+
x402Permit2ProxyAbi,
124+
PERMIT2_ADDRESS,
125+
X402_PERMIT2_PROXY_ADDRESS
126+
} from "@x402/evm-contracts";
127+
128+
// Just constants
129+
import { PERMIT2_ADDRESS } from "@x402/evm-contracts/constants";
130+
131+
// Just ABIs
132+
import { x402Permit2ProxyAbi } from "@x402/evm-contracts/abis";
133+
```
134+
135+
## 💡 Tips
136+
137+
- ABIs are exported with `as const` for full TypeScript inference with viem
138+
- The x402Permit2Proxy deploys to the same address on all chains (CREATE2)
139+
- Use `compute-address` to verify the address before deploying
140+
- Fork tests use real Permit2 on Base Sepolia for integration testing
141+
- Gas reports: `REPORT_GAS=true pnpm --filter @x402/evm-contracts test`
142+
143+
## 📚 Resources
144+
145+
- [Hardhat Docs](https://hardhat.org/docs)
146+
- [Permit2 Docs](https://docs.uniswap.org/contracts/permit2/overview)
147+
- [OpenZeppelin Contracts](https://docs.openzeppelin.com/contracts/)
148+
- [Viem Docs](https://viem.sh/)
149+
- [ABIType](https://abitype.dev/) - TypeScript types for ABIs

‎typescript/packages/contracts/evm/README.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# @x402/evm-contracts
2+
3+
Smart contracts and ABIs for the x402 EVM payment protocol.
4+
5+
## Installation
6+
7+
```bash
8+
npm install @x402/evm-contracts
9+
# or
10+
pnpm add @x402/evm-contracts
11+
```
12+
13+
## Usage
14+
15+
```typescript
16+
import {
17+
x402Permit2ProxyAbi,
18+
PERMIT2_ADDRESS,
19+
X402_PERMIT2_PROXY_ADDRESS
20+
} from "@x402/evm-contracts";
21+
import { getContract } from "viem";
22+
23+
// Use with viem - full type inference!
24+
const contract = getContract({
25+
address: X402_PERMIT2_PROXY_ADDRESS,
26+
abi: x402Permit2ProxyAbi,
27+
client,
28+
});
29+
30+
// TypeScript knows all function signatures
31+
await contract.read.PERMIT2();
32+
await contract.write.settle([permit, amount, owner, witness, signature]);
33+
```
34+
35+
## Exports
36+
37+
| Export | Description |
38+
|--------|-------------|
39+
| `x402Permit2ProxyAbi` | ABI for the x402Permit2Proxy contract |
40+
| `PERMIT2_ADDRESS` | Canonical Permit2 address (same on all chains) |
41+
| `X402_PERMIT2_PROXY_ADDRESS` | x402Permit2Proxy address (same on all chains via CREATE2) |
42+
43+
## Development
44+
45+
### Setup
46+
47+
From the monorepo root:
48+
49+
```bash
50+
cd typescript
51+
pnpm install
52+
```
53+
54+
### Commands
55+
56+
```bash
57+
# Build (compile contracts + extract ABIs + bundle)
58+
pnpm --filter @x402/evm-contracts build
59+
60+
# Run tests
61+
pnpm --filter @x402/evm-contracts test
62+
63+
# Run fork tests (against real Permit2 on Base Sepolia)
64+
pnpm --filter @x402/evm-contracts test:fork
65+
66+
# Run local Hardhat node
67+
pnpm --filter @x402/evm-contracts node
68+
69+
# Deploy to local network
70+
pnpm --filter @x402/evm-contracts deploy:local
71+
72+
# Deploy to Base Sepolia
73+
pnpm --filter @x402/evm-contracts deploy:base-sepolia
74+
75+
# Compute deterministic deployment address
76+
pnpm --filter @x402/evm-contracts compute-address
77+
78+
# Lint Solidity
79+
pnpm --filter @x402/evm-contracts lint
80+
81+
# Format code
82+
pnpm --filter @x402/evm-contracts format
83+
84+
# Clean build artifacts
85+
pnpm --filter @x402/evm-contracts clean
86+
```
87+
88+
## Project Structure
89+
90+
```
91+
packages/contracts/evm/
92+
├── contracts/ # Solidity smart contracts
93+
│ ├── x402Permit2Proxy.sol
94+
│ ├── interfaces/ # Contract interfaces
95+
│ └── mocks/ # Test mocks
96+
├── scripts/ # Deployment and utility scripts
97+
│ ├── deploy-x402-proxy.ts
98+
│ ├── compute-address.ts
99+
│ └── extract-abis.ts
100+
├── test/ # Contract tests
101+
│ ├── x402Permit2Proxy.test.ts
102+
│ └── x402Permit2Proxy.fork.test.ts
103+
├── src/ # TypeScript exports (auto-generated ABIs)
104+
│ ├── index.ts
105+
│ ├── constants.ts
106+
│ └── abis/
107+
├── dist/ # Built package (ESM + CJS)
108+
└── dist-hardhat/ # Hardhat artifacts (gitignored)
109+
```
110+
111+
## Deterministic Deployment
112+
113+
The x402Permit2Proxy contract is deployed to the same address on all EVM chains using CREATE2:
114+
115+
```
116+
x402Permit2Proxy: 0xcE4c4C3721A5234A63ba39760Eb4Be0b1021a90a
117+
```
118+
119+
Run `pnpm compute-address` to verify the address computation.
120+
121+
## Resources
122+
123+
- [Hardhat Documentation](https://hardhat.org/docs)
124+
- [Permit2 Documentation](https://docs.uniswap.org/contracts/permit2/overview)
125+
- [OpenZeppelin Contracts](https://docs.openzeppelin.com/contracts/)
126+
- [Viem Documentation](https://viem.sh/)

0 commit comments

Comments
 (0)