Security News
Highlights from the 2024 Rails Community Survey
A record 2,709 developers participated in the 2024 Ruby on Rails Community Survey, revealing key tools, practices, and trends shaping the Rails ecosystem.
@bananapus/buyback-hook
Advanced tools
The buyback hook allows a project to route incoming payments to a Uniswap pool for their project's token if doing so would yield more tokens for the payer.
The buyback hook allows a project to route incoming payments to a Uniswap pool for their project's token if doing so would yield more tokens for the payer.
If you're having trouble understanding this contract, take a look at the core protocol contracts and the documentation first. If you have questions, reach out on Discord.
How to install nana-buyback-hook
in another project.
For projects using npm
to manage dependencies (recommended):
npm install @bananapus/buyback-hook
For projects using forge
to manage dependencies (not recommended):
forge install Bananapus/nana-buyback-hook
If you're using forge
to manage dependencies, add @bananapus/buyback-hook/=lib/nana-buyback-hook/
to remappings.txt
. You'll also need to install nana-buyback-hook
's dependencies and add similar remappings for them.
nana-buyback-hook
uses npm (version >=20.0.0) for package management and the Foundry development toolchain for builds, tests, and deployments. To get set up, install Node.js and install Foundry:
curl -L https://foundry.paradigm.xyz | sh
You can download and install dependencies with:
npm ci && forge install
If you run into trouble with forge install
, try using git submodule update --init --recursive
to ensure that nested submodules have been properly initialized.
Some useful commands:
Command | Description |
---|---|
forge build | Compile the contracts and write artifacts to out . |
forge fmt | Lint. |
forge test | Run the tests. |
forge build --sizes | Get contract sizes. |
forge coverage | Generate a test coverage report. |
foundryup | Update foundry. Run this periodically. |
forge clean | Remove the build artifacts and cache directories. |
To learn more, visit the Foundry Book docs.
For convenience, several utility commands are available in package.json
.
Command | Description |
---|---|
npm test | Run local tests. |
npm run test:fork | Run fork tests (for use in CI). |
npm run coverage | Generate an LCOV test coverage report. |
npm run artifacts | Fetch Sphinx artifacts and write them to deployments/ |
nana-buyback-hook
manages deployments with Sphinx. To run the deployment scripts, install the npm devDependencies
with:
`npm ci --also=dev`
You'll also need to set up a .env
file based on .example.env
. Then run one of the following commands:
Command | Description |
---|---|
npm run deploy:mainnets | Propose mainnet deployments. |
npm run deploy:testnets | Propose testnet deployments. |
Your teammates can review and approve the proposed deployments in the Sphinx UI. Once approved, the deployments will be executed.
You can use the Sphinx CLI to run the deployment scripts without paying for Sphinx. First, install the npm devDependencies
with:
`npm ci --also=dev`
You can deploy the contracts like so:
PRIVATE_KEY="0x123…" RPC_ETHEREUM_SEPOLIA="https://rpc.ankr.com/eth_sepolia" npx sphinx deploy script/Deploy.s.sol --network ethereum_sepolia
This example deploys nana-buyback-hook
to the Sepolia testnet using the specified private key. You can configure new networks in foundry.toml
.
To view test coverage, run npm run coverage
to generate an LCOV test report. You can use an extension like Coverage Gutters to view coverage in your editor.
If you're using Nomic Foundation's Solidity extension in VSCode, you may run into LSP errors because the extension cannot find dependencies outside of lib
. You can often fix this by running:
forge remappings >> remappings.txt
This makes the extension aware of default remappings.
The root directory contains this README, an MIT license, and config files. The important source directories are:
nana-buyback-hook/
├── script/
│ ├── Deploy.s.sol - Deployment script.
│ └── helpers/ - Internal helpers for the deployment script.
├── src/
│ ├── JBBuybackHook.sol - The main buyback hook contract.
│ └── interfaces/
│ ├── IJBBuybackHook.sol - Buyback hook interface.
│ └── external/ - Contains WETH9 interface (do not modify).
└── test/
├── Fork.t.sol - Fork tests.
├── Unit.t.sol - Unit tests.
├── helpers/ - Contains helpers for Juicebox and Uniswap interactions.
└── mock/ - Contains a mock malicious split hook.
Other directories:
nana-buyback-hook/
├── .github/
│ └── workflows/ - CI/CD workflows.
└── deployments/ - Sphinx deployment logs.
When a Juicebox project that uses the buyback hook is paid, it checks whether buying tokens in a Uniswap pool or paying the project as usual would yield more tokens for the payer. If buying tokens in the pool would yield more tokens, the payment is routed there. Otherwise, the payment is sent to the project as usual. Either way, the project's reserved rate applies.
The buyback hook works with any Juicebox terminal and checks the Uniswap pool specified by the project's owner.
This contract is both a data hook and a pay hook. Data hooks receive information about a payment and put together a payload for the pay hook to execute.
Juicebox projects can specify a data hook in their JBRulesetMetadata
. When someone attempts to pay or redeem from the project, the project's terminal records the payment in the terminal store, passing information about the payment to the data hook in the process. The data hook responds with a list of payloads – each payload specifies the address of a pay hook, as well as some custom data and an amount of funds to send to that pay hook.
Each pay hook can then execute custom behavior based on the custom data (and funds) they receive.
At a high level:
sequenceDiagram
participant Project
participant Terminal
participant Buyback hook
participant Uniswap pool
Note right of Terminal: User calls pay(…) to pay the project
Terminal->>Project: Reads data hook from ruleset
Project->>Terminal: Returns buyback hook as data hook
Terminal->>Buyback hook: Calls beforePayRecordedWith(…) with payment data
Buyback hook->>Terminal: If buying from pool is better, return specification to use pay hook
Terminal->>Buyback hook: Calls afterPayRecordedWith(…) with returned specification
Buyback hook->>Uniswap pool: Executes swap
Note left of Buyback hook: After, burn and re-mint tokens to apply the reserved rate.
pay(…)
function. In the payment metadata, the client passes in a Uniswap quote, the amount of funds to use for the swap, and the minimum number of project tokens to receive in exchange from the Uniswap pool (accounting for slippage). These should be encoded using the delegate metadata library. If no quote is provided, the buyback hook will use a time-weighted average price.pay(…)
function calls the buyback hook (as a data hook) to determine whether the swap should be executed or not. It makes this determination by considering the information that was passed in, information about the pool, and the project's current rules.afterPayRecordedWith(…)
method, which will wrap the ETH (to wETH), execute the swap, burns the token it received, and mint them again (it also mints tokens for any funds which weren't used in the swap, if any). This burning/re-minting process allows the buyback hook to apply the reserved rate and respect the caller's preferClaimedTokens
preference.addToBalanceOf
to send the funds to the project.Tips for project owners using the buyback hook.
Every time the buyback hook chooses the swap route, a Uniswap trade will be executed, making payers vulnerable to MEV attacks. To mitigate MEV attacks, frontend clients should provide a reasonable minimum quote, and the TWAP parameters should be carefully set – these parameters are used to calculate a default minimum quote when the payer/client doesn't provide one.
You can also avoid MEV attacks by using the Flashbots Protect RPC for transactions which trigger the buyback hook. You can add this RPC to your wallet on protect.flashbots.net. If you're using a multisig wallet (like a Gnosis Safe), make sure that the last signer signs and executes at the same time while using the Flashbots Protect RPC. For more information on mitigating MEV from your Gnosis Safe, see this article.
As the project owner, you have two parameters at your disposal to protect payers: the TWAP window and the maximum slippage tolerance. See TWAP Basics for an explanation.
You'll also want to keep the pool's cardinality in mind. This is the number of recent transactions the Uniswap pool keeps track of for calculating the TWAP. If the cardinality is only 1 (the default), then the TWAP will only take the most recent trade into account for calculations. Anyone can increase the pool's cardinality by calling the pool's increaseObservationCardinalityNext(…)
function.
For an overview of TWAP risks, see this article. Some other helpful resources:
JBConstants.NATIVE_TOKEN
: 0x000000000000000000000000000000000000EEEe
.fee
is a uint24
with the same representation as in Uniswap's contracts (basis points with 2 decimals): a 0.01% fee is 100
, a 0.05% fee is 500
, a 0.3% fee is 3000
, and a 1% fee is 10000
.When you trade tokens on Uniswap, you must provide a minimum acceptable price for your trade to protect against excessive price movement (also called "slippage"). If the price moves unfavourably beyond this slippage tolerance, your trade will not be executed, protecting you from receiving a worse deal than you were expecting.
The buyback hook allows payers (or frontend clients) to provide a minimum acceptable return from their trade, and the hook will only execute the trade if it can provide that return – if it can't, the terminal's default behavior takes over. In most cases, this means the payment will go to the project that the hook is associated with.
But if the payer (or frontend client) does not provide a minimum acceptable return, the buyback hook must calculate a fair minimum on its own. On Uniswap, the current price is called a "spot price". This can be dangerous to rely on, because the price can move around quickly. To solve this problem, Uniswap v3 exposes a smoothed-out price called a TWAP, or a time-weighted average price. This is calculated by taking the geometric mean of the price over a window of time, which you can learn more about here.
The buyback hook allows each project to specify a time window (period of time) over which to calculate the TWAP. It also allows each project to specify a "TWAP slippage tolerance". This is the same as the minimum acceptable price above: with a 5% TWAP slippage tolerance, the transaction will revert to the terminal's default behavior if the expected return is more than 5% worse than the TWAP price over the window.
setPoolFor(…)
. If they migrate to a different exchange or a pool on a different version of Uniswap, this hook won't work. Projects looking to mitigate this risk should consider bootstrapping a Uniswap v3 pool by providing liquidity themselves.FAQs
The buyback hook allows a project to route incoming payments to a Uniswap pool for their project's token if doing so would yield more tokens for the payer.
The npm package @bananapus/buyback-hook receives a total of 92 weekly downloads. As such, @bananapus/buyback-hook popularity was classified as not popular.
We found that @bananapus/buyback-hook demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A record 2,709 developers participated in the 2024 Ruby on Rails Community Survey, revealing key tools, practices, and trends shaping the Rails ecosystem.
Security News
In 2023, data breaches surged 78% from zero-day and supply chain attacks, but developers are still buried under alerts that are unable to prevent these threats.
Security News
Solo open source maintainers face burnout and security challenges, with 60% unpaid and 60% considering quitting.