v4-periphery: the Solidity building blocks around Uniswap v4 pools

Periphery sits on top of the core pool, not inside it

The clearest way to read this repository is as a boundary. Uniswap v4 is the protocol itself, the automated market maker with its core pool logic, and v4-periphery is the layer that builds on that logic. It names the pieces: hook contracts, position managers, and possibly libraries needed for integrations. That means the repository is not a complete trading interface and not a deployment of the protocol. It is the pieces a developer would normally write themselves, provided in a form that others can fork, extend and audit. Anyone expecting an off-the-shelf exchange frontend will find nothing of the sort here. Anyone who wants to implement a bespoke pool behaviour, such as a hook that changes how liquidity is added or removed, is looking at exactly the right repository, since the whole point of v4 is framed as extensibility and customizability to pools, and the periphery as where that extensibility becomes code.

Hooks are callback contracts, and BaseHook shows the shape

The mechanism that makes v4 pools extensible is the hook. Hook authors are pointed at BaseHook from the separate v4-hooks-public repository, with a short example of a contract that inherits from it. The example overrides a single callback, _beforeAddLiquidity, with the key, the ModifyLiquidityParams and the hookData, and returns BaseHook.beforeAddLiquidity.selector so the pool knows which callback the contract implements. The selector return is the detail worth pausing on: a hook advertises which callbacks it supports, and returning the selector is how that contract registers itself. A hook that overrides nothing is inert, and one that returns the wrong value will not be called as intended. Because the example is short, it is easy to mistake the shape for the whole API, and it is not. The repository is described as still in development, with further periphery contracts not yet built, so the set of callbacks and helper types you can rely on is a moving target and should be read from the contracts themselves rather than from the example.

forge install is the whole documented setup path

There is no install command for the package manager. Getting the contracts into a local repository takes one line, and it uses Foundry's installer rather than npm, even though the repository also carries a package.json:

forge install https://github.com/Uniswap/v4-periphery

That single command is the entirety of the local deployment and usage guidance, and it is aimed at deploying the contracts to a local testnet. Everything else in the repository root suggests the shape of a Foundry project rather than a JavaScript one: foundry.toml, remappings.txt, foundry.lock, a lib/ directory and a .gitmodules file all point at Solidity compilation with dependency remapping rather than at a JavaScript build. No build, test or deploy command is given beyond the install line, so a reader cannot learn the test invocation or the deployment script from it. The scripts/ and script/ directories and the broadcast/ directory exist in the repository, and broadcast/ is where Foundry records the results of a deployment, but the commands that produce those artefacts are not written down in the documentation.

The package.json and the documentation disagree about the licence

This is the one place where a reader has to look twice. The licence field on the repository says MIT, and the package.json published under the name @uniswap/v4-periphery at version 1.0.4 also carries an MIT licence field, with the description reading that it hosts peripheral smart contracts for interacting with Uniswap v4. Its licence section states that the license for Uniswap V4 Periphery is the GNU General Public License (GPL 2.0), pointing to the LICENSE file in the repository root. MIT and GPL 2.0 are very different terms, particularly for a Solidity library that other contracts import, so the disagreement is not cosmetic. This review offers no view on which term governs; that is a question for the LICENSE file and for whoever owns the repository. What is clear is that a team planning to depend on these contracts has two conflicting statements to reconcile before shipping, and the version 1.0.4 in package.json is a published package version rather than a GitHub release, since the repository has no GitHub releases at all.

Audits, snapshots and a foundry lock are what you actually inherit

The repository root carries an audits/ directory, a snapshots/ directory, a foundry.lock file and a .pre-commit style of contributor tooling, along with a CONTRIBUTING.md linked for people who want to contribute. The presence of audits/ and snapshots/ tells you what kind of artifact this repository is: Solidity that gets reviewed and checked against recorded outputs, not a script collection. snapshots/ in a Foundry project holds recorded values such as storage or gas snapshots, and a foundry.lock pins the dependency versions the project was built against. Together with remappings.txt, those are the files that make the build reproducible, and they are also the files a new integrator should read first, because they tell you which versions of the core and its libraries the contracts here expect. The bug tracker link in package.json points at a bug bounty address, which is the right channel for reporting a problem in the contracts rather than opening an issue.

Building a hook locally, step by step and within the documented limits

A first local use is short. Install the dependencies into a Foundry repository, then create a contract that inherits from BaseHook and overrides the callbacks you want. The example given in the README is the shape to copy:

contract CoolHook is BaseHook {
    // Override the hook callbacks you want on your hook
    function _beforeAddLiquidity(
        address,
        PoolKey calldata key,
        ModifyLiquidityParams calldata params,
        bytes calldata hookData
    ) internal override returns (bytes4) {
        // hook logic
        return BaseHook.beforeAddLiquidity.selector;
    }
}

The unnamed first parameter is the sender address, deliberately left out because the example does not use it. The two repositories are separate, so BaseHook itself is not in this repository, it comes from v4-hooks-public, which means a hook that inherits from it has a dependency on two codebases at once. What the reader should expect to see is a contract that compiles against the pool types, with the selector returned from each callback the hook wants to receive. What the reader should not expect is a worked deploy: a local testnet is named as the target, but no deployment command, private key configuration or fork URL is given, so the last mile of the tutorial is yours to build from the Foundry tooling already present in the repository.

Editorial conclusion

v4-periphery is the right dependency for a team shipping a custom hook, a position manager or an integration library against Uniswap v4, and for a Solidity developer who wants a working local testnet deployment rather than a paper design. It is not the place to look for a production-ready contract set, since the contracts are described as still in development and further periphery contracts as not yet built, and it is not the Uniswap v4 core pool implementation. Before you build on it, settle the licence question first, because the licence field on the repository says MIT while the README states the licences for Uniswap V4 Periphery is the GNU General Public License (GPL 2.0), then read the audits/ directory and confirm your Solidity and Foundry versions against foundry.toml and remappings.txt.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. Uniswap/v4-periphery on GitHub