SDK v3

[alex-connolly]

@imtbl/contracts v3.0.0

Breaking Changes

This is a major version upgrade with significant breaking changes to modernize the package.

Package Structure

• ESM-first with CJS compatibility
• Removed TypeChain-generated types (use ABIs directly with viem/wagmi)
• Consolidated exports into single entry point

Removed Contracts

Contract	Reason
GuardedMulticaller (v1)	Deprecated - use GuardedMulticaller2
ImmutableSignedZone (v1)	Deprecated - use ImmutableSignedZoneV2
Conduit shims	Unnecessary - import directly from seaport libraries
Validator shims	Unnecessary - import directly from seaport libraries

Removed Dependencies

Dependency	Reason
@limitbreak/creator-token-standards	ITransferValidator interface inlined
solidity-bits	Never used
solidity-bytes-utils	Replaced with inline assembly
ethers	Migrated to viem
@nomiclabs/hardhat-ethers	Replaced with @nomicfoundation/hardhat-viem
typechain	Types removed - use ABIs directly
prettier / prettier-plugin-solidity	Use forge fmt
Various testing packages	Consolidated

API Changes

• Removed guardedMulticallerAbi export (use guardedMulticaller2Abi)
• Address exports now use chain IDs: IMMUTABLE_SEAPORT[CHAIN_ID.IMMUTABLE_MAINNET]

---

Security Improvements

Vulnerability Reduction

Metric	Before	After	Change
Total Vulnerabilities	327	160	-51%
Packages Audited	1,525	710	-53%
Critical	76	48	-37%
High	64	23	-64%
Moderate	41	7	-83%
Low	146	82	-44%

Dependency Cleanup

• Removed 815 transitive packages
• Eliminated deprecated/unmaintained libraries
• Upgraded all maintained dependencies to latest versions

---

Package Changes

Upgraded

Package	From	To
hardhat	2.x	3.0.15
@openzeppelin/contracts	4.9.3	4.9.6 + 5.5.0
typescript	4.x	5.8.3
solhint	3.x	6.0.1
viem	-	2.40.2 (new)

Tooling Migration

• Ethers → Viem: Modern, type-safe Ethereum library
• Hardhat 2 → Hardhat 3: Built-in Foundry support, native TypeScript
• Prettier → Forge fmt: Native Solidity formatting

---

Contract Changes

Staking Contracts

• Merged V1 and V2 implementations
• V2 stakeFor functionality now in base contracts
• Removed separate V1 files

ERC721 Contracts

• Renamed V2 contracts to drop suffix (V1 removed)
• ImmutableERC721V2 → ImmutableERC721
• ERC721PsiV2 → ERC721Psi

Permit Contracts

• Replaced BytesLib.slice() with inline assembly
• More gas efficient signature parsing

Seaport/Trading

• Removed conduit controller shims
• Removed validator shims
• Removed SignedZone V1
• Tests updated to use V2 zone

---

New Usage

Installation

npm install @imtbl/contracts
# or
yarn add @imtbl/contracts

TypeScript/JavaScript

import {
  // ABIs
  immutableErc721Abi,
  guardedMulticaller2Abi,
  
  // Chain IDs
  CHAIN_ID,
  
  // Deployed addresses
  IMMUTABLE_SEAPORT,
  OPERATOR_ALLOWLIST,
} from '@imtbl/contracts';

// Get address for mainnet
const seaport = IMMUTABLE_SEAPORT[CHAIN_ID.IMMUTABLE_MAINNET];
// '0x6c12aD6F0bD274191075Eb2E78D7dA5ba6453424'

// Use with viem
import { getContract } from 'viem';

const contract = getContract({
  address: IMMUTABLE_SEAPORT[CHAIN_ID.IMMUTABLE_MAINNET],
  abi: immutableErc721Abi,
  client,
});

Solidity

import "@imtbl/contracts/contracts/token/erc721/preset/ImmutableERC721.sol";

---

Migration Guide

From v2.x

1. Update imports:

   // Before
   import { GuardedMulticaller__factory } from '@imtbl/contracts/typechain';
   
   // After
   import { guardedMulticaller2Abi, CHAIN_ID } from '@imtbl/contracts';

2. Update address access:

   // Before
   import addresses from '@imtbl/contracts/addresses.json';
   const addr = addresses['ImmutableSeaport']['Mainnet Address'];
   
   // After
   import { IMMUTABLE_SEAPORT, CHAIN_ID } from '@imtbl/contracts';
   const addr = IMMUTABLE_SEAPORT[CHAIN_ID.IMMUTABLE_MAINNET];

3. Update contract references:

   • GuardedMulticaller → GuardedMulticaller2
   • ImmutableSignedZone → ImmutableSignedZoneV2
   • ImmutableERC721V2 → ImmutableERC721

4. Peer dependencies:

   {
     "peerDependencies": {
       "@openzeppelin/contracts": "^4.9.3 || ^5.0.0"
     }
   }

---

Full Changelog

Removed

• GuardedMulticaller.sol (v1)
• ImmutableSignedZone.sol (v1) + tests
• Conduit/Validator shim files
• contracts/random/ (empty)
• TypeChain types and generation
• Ethers.js dependency
• 10+ unused dev dependencies

Changed

• Hardhat 2 → Hardhat 3
• Ethers → Viem
• Prettier → Forge fmt
• Address format: network names → chain IDs
• ERC721 V2 contracts renamed (dropped suffix)
• Staking V1/V2 merged

Added

• CHAIN_ID constants for Immutable zkEVM
• Type-safe address exports
• ESM build output
• Inline assembly for permit signature parsing

[drinkcoffee]

We can't remove this file: it is the authoritative source of this information, referenced from here: https://docs.immutable.com/learn/products/contracts/