Intuition V2 Periphery Smart Contracts

npm alpha package

This branch prepares @0xintuition/[email protected] for the alpha tag. It ships the TrustSwapAndBridgeRouter Solidity source and required interfaces, ABI and creation bytecode, ESM/CommonJS exports, TypeScript declarations, and artifact-manifest.json. Other periphery contracts remain repository-only in this release. No Solidity business logic is changed by the packaging work.

After publication:

import { TrustSwapAndBridgeRouterAbi } from "@0xintuition/contracts-v2-periphery/abis";
import { TrustSwapAndBridgeRouterBytecode } from "@0xintuition/contracts-v2-periphery/bytecodes";

Foundry source consumers need these remappings:

@0xintuition/contracts-v2-periphery/=node_modules/@0xintuition/contracts-v2-periphery/
node_modules/@0xintuition/contracts-v2-periphery/:contracts/=node_modules/@0xintuition/contracts-v2-periphery/contracts/
@openzeppelin/contracts/=node_modules/@openzeppelin/contracts/

Run bun install --frozen-lockfile, bun run release:check, and bun run test:router. Release checks build and test the package, install its tarball in an isolated JS/TS consumer, and reproduce the Solidity ABI/bytecode using only npm dependencies. npm pack and npm publish run these checks through prepack. With a permitted npm login and an unused version, publish using npm publish --access public --tag alpha; leave latest unchanged. This publishes artifacts only and does not deploy contracts. Check the registry integrity and record the final git revision after publication.

The package build uses the pinned OpenZeppelin v5.4.0 submodule; consumers install the matching exact npm version. The legacy core submodule's v4 dependencies remain development-only aliases for repository tests. The router is pinned to Base mainnet protocol addresses; publishing its bytecode does not establish compatibility with other chains or deployed revisions.

A set of periphery smart contracts for the Intuition protocol, built using Foundry.

What's Inside

• Forge: compile, test, fuzz, format, and deploy smart contracts
• [Bun]: Foundry defaults to git submodules, but this template also uses Node.js packages for managing dependencies
• Forge Std: collection of helpful contracts and utilities for testing
• Prettier: code formatter for non-Solidity files
• Solhint: linter for Solidity code

Usage

This is a list of the most frequently needed commands.

Build

Build the contracts:

$ forge build

Clean

Delete the build artifacts and cache directories:

$ forge clean

Deploy

Deploy to Anvil:

$ forge script script/Deploy.s.sol --broadcast --fork-url http://localhost:8545

For this script to work, you need to have a MNEMONIC environment variable set to a valid BIP39 mnemonic.

For instructions on how to deploy to a testnet or mainnet, check out the Solidity Scripting tutorial.

Format

Format the contracts:

$ forge fmt

Gas Usage

Get a gas report:

$ forge test --gas-report

Lint

Lint the contracts:

$ bun run lint

Test

Run the tests:

$ forge test

Test Coverage

Generate test coverage and output result to the terminal:

$ bun run test:coverage

Test Coverage Report

Generate test coverage with lcov report (you'll have to open the ./coverage/index.html file in your browser, to do so simply copy paste the path):

$ bun run test:coverage:report

[!NOTE]

This command requires you to have lcov installed on your machine. On macOS, you can install it with Homebrew: brew install lcov.

Claude Slash Commands (Shared)

This repo includes team-shared Claude slash commands in .claude/commands.

Use /help in Claude Code to see them, then run:

• /audit-solidity [codebase-path] [spec-document-optional]
• /audit-context [codebase-path] [--focus <module>]
• /audit-entry-points [directory-path]
• /audit-static-analysis [codebase-path]
• /audit-spec-compliance <spec-document> [codebase-path]
• /audit-variants [vulnerability-description]

Generated reports are written to audits/automated-reports/.

License

This project is licensed under BUSL-1.1

Deployed Contracts

Mainnet

Base Mainnet

| Contract Name | Address | ProxyAdmin | | -------------------------- | ------------------------------------------ | ---------- | | EmissionsAutomationAdapter | 0xb1ce9Ac324B5C3928736Ec33b5Fd741cb04a2F2d | / | | TrustSwapAndBridgeRouter | 0xA1EC6f95A88Bfc7A8Fd35f1296b64ebaf91C93fb | / |

Intuition Mainnet

| Contract Name | Address | ProxyAdmin | | -------------------- | ------------------------------------------ | ---------- | | Multicall3 | 0xcA11bde05977b3631167028862bE2a173976CA11 | / | | EntryPoint | 0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108 | / | | SafeSingletonFactory | 0x914d7Fec6aaC8cd542e72Bca78B30650d45643d7 | / |

Testnet

Base Sepolia

| Contract Name | Address | ProxyAdmin | | ------------- | ------------------------------------------ | ---------- | | TestTrust | 0xA54b4E6e356b963Ee00d1C947f478d9194a1a210 | / |

Intuition Testnet

| Contract Name | Address | ProxyAdmin | | ------------- | ------------------------------------------ | ---------- | | Multicall3 | 0xcA11bde05977b3631167028862bE2a173976CA11 | / | | EntryPoint | 0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108 | / |