Baskets

Basket is a share of a fixed set of up to eight Stock Tokens, minted and redeemed in kind. One ERC-20 holds a portfolio, and the margin engine margins it as that portfolio. You can mint shares by depositing the tokens, redeem them for the tokens, and read the target the owner has set.

Source: contracts/src/Basket.sol. The registry key is the basket's name under .tapehouse.Baskets, and the SDK takes that key as basket.

Mint and redeem#

Read what a mint takes, approve each Stock Token to the basket, then mint with a cap per token.

import { baskets } from '@tapehouse/sdk'

const shares = 10n ** 18n
const { tokens } = await baskets.components(publicClient, deployments, 'PAIR')
const amounts = await baskets.previewMint(publicClient, deployments, 'PAIR', shares)

await wallet.writeContract(
  baskets.mint(deployments, { basket: 'PAIR', shares, receiver: wallet.account.address, maxAssets: amounts }),
)

components lists the symbols and tokens, and every list of amounts follows that order. maxAssets is one limit per token, in raw units. Passing previewMint's result as the limit fails if the basket's holdings move against you before the transaction lands, so add a margin of your own where that matters.

Redeem the same way:

await wallet.writeContract(
  baskets.redeem(deployments, { basket: 'PAIR', shares, receiver: wallet.account.address, owner: wallet.account.address }),
)

Functions#

Reads#

The SDK has baskets.components, baskets.previewMint, baskets.previewRedeem, baskets.target and baskets.pendingTarget, plus the mint and redeem call builders.

How shares work#

• In kind. A share is a claim on its part of every token the basket holds. Minting rounds each token's part up and redeeming rounds it down, as ERC-4626 does, so neither takes from other holders. A share is asked for, never priced, so no donation can make a mint cost more than one raw unit of each token above its part. The first mint, and the first after every share is gone, pays the target.
• Raw units. The basket counts each token in its raw units, so dividends and splits, which move only the token's ERC-8056 multiplier, pass through, and mints and redemptions stay open over a multiplier change. A burn by the issuer from the basket falls at once on every holder in proportion, and a token sent to it is every holder's.
• The issuer's controls. A share moves only as its tokens could. There is no transfer, mint or redemption while any token is paused (ComponentPaused), and none to, from or by an address the issuer has blocklisted in any of the tokens' registries (Blocked). A paused token, or a blocklisted basket, stops every redemption: shares are never redeemed in part.
• Margin. The margin accounts take the shares of the baskets their owner adds, and margin them as the Stock Tokens they redeem for. When a margin position falls short, the liquidator redeems its baskets into those tokens and sells them as any other.

The target and rebalancing#

The owner proposes a new target, in raw units of each token per share, and it takes effect NOTICE (seven days) later, so a holder who disagrees can redeem in kind first. The set of tokens never changes: a target can weigh them anew or leave one out. A proposal replaces an earlier one that has not yet taken effect.

Anyone may call rebalance to move the basket toward the target in effect. Each token either comes in or goes out, never both, and none passes its target. What comes in, valued at each band's low edge, must be worth at least what goes out, valued at each band's high edge. So at every price the band allows, the basket is worth no less afterward, and whoever rebalances pays the bands' width. Each token that moves needs a band with a price, no multiplier change pending, and a settled L2 sequencer.

Parameters and limits#

A target holds a nonzero amount of at least one token, and the first target holds a nonzero amount of every token. A basket holds from one to eight distinct tokens, each with a Stock Token in the band.

Roles#

The owner proposes targets and does nothing else. It cannot touch holdings, mint or pause the basket. Ownership moves in two steps and cannot be renounced.

Events#

Errors#

Next#

• Margin accounts
• Short and baskets
• Portfolio margin