Skip to main content

​
Overview

Gearbox Protocol Core V3 can be installed in your project using npm for JavaScript/TypeScript projects, or directly via Foundry/Hardhat for Solidity development.
Package Name: @gearbox-protocol/core-v3Current Version: 1.0.1Repository: Gearbox-protocol/core-v3

​
Installation Methods

npm

For JavaScript/TypeScript projects

Foundry

For Foundry-based Solidity projects

Hardhat

For Hardhat-based Solidity projects

​
npm Installation

Install the package via npm or yarn: 
npm install @gearbox-protocol/core-v3
Then import interfaces in your TypeScript/JavaScript code: 
import { IPoolV3__factory } from '@gearbox-protocol/core-v3/types';
import { ICreditFacadeV3__factory } from '@gearbox-protocol/core-v3/types';

// Connect to contracts
const pool = IPoolV3__factory.connect(poolAddress, signer);
const creditFacade = ICreditFacadeV3__factory.connect(facadeAddress, signer);

​
Foundry Installation

For Foundry projects, install as a git submodule: 
forge install Gearbox-protocol/core-v3
Then add the remapping to your foundry.toml:
foundry.toml
[profile.default]
src = 'contracts'
out = 'out'
libs = ['lib']
remappings = [
    '@gearbox-protocol/core-v3/=lib/core-v3/contracts/'
]
Import contracts in your Solidity files: 
import "@gearbox-protocol/core-v3/interfaces/IPoolV3.sol";
import "@gearbox-protocol/core-v3/interfaces/ICreditFacadeV3.sol";
import "@gearbox-protocol/core-v3/interfaces/ICreditManagerV3.sol";

​
Hardhat Installation

First, install via npm: 
npm install @gearbox-protocol/core-v3
Then configure Hardhat to recognize the package:
hardhat.config.js
module.exports = {
  solidity: {
    version: "0.8.23",
    settings: {
      optimizer: {
        enabled: true,
        runs: 1000
      },
      evmVersion: "shanghai"
    }
  },
  paths: {
    sources: "./contracts",
    tests: "./test",
    cache: "./cache",
    artifacts: "./artifacts"
  }
};
Import in your Solidity contracts: 
import "@gearbox-protocol/core-v3/contracts/interfaces/IPoolV3.sol";
import "@gearbox-protocol/core-v3/contracts/interfaces/ICreditFacadeV3.sol";
import "@gearbox-protocol/core-v3/contracts/interfaces/ICreditManagerV3.sol";

​
Compiler Configuration

Gearbox Protocol Core V3 requires specific compiler settings for compatibility.

​
Solidity Version

Gearbox Protocol Core V3 contracts use Solidity ^0.8.17 and are compiled with version 0.8.23: 
pragma solidity ^0.8.17;
For Foundry, use these settings in foundry.toml:
foundry.toml
[profile.default]
solc_version = '0.8.23'
evm_version = 'shanghai'
optimizer = true
optimizer_runs = 1000
bytecode_hash = 'none'
For Hardhat, configure hardhat.config.js:
hardhat.config.js
module.exports = {
  solidity: {
    version: "0.8.23",
    settings: {
      optimizer: {
        enabled: true,
        runs: 1000
      },
      evmVersion: "shanghai",
      viaIR: false
    }
  }
};

​
Key Interfaces

After installation, you’ll have access to these core interfaces: 
import "@gearbox-protocol/core-v3/contracts/interfaces/IPoolV3.sol";

contract MyContract {
    IPoolV3 public pool;
    
    constructor(address poolAddress) {
        pool = IPoolV3(poolAddress);
    }
    
    function deposit(uint256 assets) external {
        // Deposit to pool
        pool.deposit(assets, msg.sender);
    }
}

​
Dependencies

Gearbox Protocol Core V3 depends on these external libraries:
1

OpenZeppelin Contracts

Standard library for ERC20, ERC4626, and utility contracts.
npm install @openzeppelin/contracts
2

1inch Solidity Utils

Utilities including SafeERC20 for secure token transfers.
npm install @1inch/solidity-utils
These dependencies are automatically installed when you install @gearbox-protocol/core-v3 via npm.

​
Project Structure

Once installed, the package contains: 
@gearbox-protocol/core-v3/
├── contracts/
│   ├── interfaces/          # Contract interfaces
│   │   ├── IPoolV3.sol
│   │   ├── ICreditFacadeV3.sol
│   │   ├── ICreditManagerV3.sol
│   │   ├── ICreditAccountV3.sol
│   │   └── base/            # Base interfaces
│   ├── pool/                # Pool implementations
│   │   ├── PoolV3.sol
│   │   ├── PoolV3_USDT.sol
│   │   ├── PoolQuotaKeeperV3.sol
│   │   └── GaugeV3.sol
│   ├── credit/              # Credit account implementations
│   │   ├── CreditFacadeV3.sol
│   │   ├── CreditManagerV3.sol
│   │   └── CreditAccountV3.sol
│   └── libraries/           # Utility libraries
│       ├── CreditLogic.sol
│       ├── CollateralLogic.sol
│       ├── BalancesLogic.sol
│       └── BitMask.sol
└── package.json

​
Verification

Verify your installation by compiling a simple contract:
TestInstallation.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.17;

import "@gearbox-protocol/core-v3/contracts/interfaces/IPoolV3.sol";
import "@gearbox-protocol/core-v3/contracts/interfaces/ICreditFacadeV3.sol";

contract TestInstallation {
    IPoolV3 public pool;
    ICreditFacadeV3 public creditFacade;
    
    constructor(
        address poolAddress,
        address facadeAddress
    ) {
        pool = IPoolV3(poolAddress);
        creditFacade = ICreditFacadeV3(facadeAddress);
    }
    
    function getPoolInfo() external view returns (
        address underlying,
        uint256 liquidity,
        uint256 borrowed
    ) {
        underlying = pool.underlyingToken();
        liquidity = pool.availableLiquidity();
        borrowed = pool.totalBorrowed();
    }
}
Compile with Foundry: 
forge build
Or with Hardhat: 
npx hardhat compile

​
License

The primary license for Gearbox Protocol Core V3 is the Business Source License 1.1 (BUSL-1.1).Files that are NOT licensed under the BUSL-1.1 have appropriate SPDX headers.
Before using Gearbox Protocol in production, review the license terms in the LICENSE file.

​
Troubleshooting

Ensure you’re using Solidity 0.8.23 or a compatible version ^0.8.17. Update your foundry.toml or hardhat.config.js accordingly.
Verify your remappings in foundry.toml or ensure the package is properly installed via npm. Try running forge remappings to see current mappings.
Gearbox contracts are optimized for 1000 runs. Using different optimizer settings may cause issues. Match the recommended settings above.
Ensure OpenZeppelin and 1inch utilities are installed:
npm install @openzeppelin/contracts @1inch/solidity-utils

​
Next Steps

Quickstart Guide

Learn how to interact with the contracts

API Reference

Explore the complete API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us