# Clusters

A cluster is a decentralized index that tracks a programmable allocation of assets. Each cluster is implemented as a smart contract that incentivizes users to execute rebalancing deposits / withdrawals in amounts that maintain its token balances in line with cluster's target allocation.

A cluster issues tradable shares of its inventory called cluster tokens (CT), which are minted when users deposit assets into the cluster, and can be later returned and burned for a portion of the cluster's managed holdings in the original underlying assets.

Nebula allows users to "invest in stories" through holding and trading various cluster tokens. Clusters express tradable narratives through their dynamic allocation of assets and, when combined, allow users to construct expressive portfolios with a richer vocabulary of investment theses and strategies.

# Advantages of Clusters

  1. Maximizes Flexibility: Nebula is designed to impose as few restrictions on the potential designs of clusters as possible. This includes both the assets that are included in clusters themselves, as well as the logic and algorithm that defines how the cluster composition are rebalanced and managed.
  2. Minimizes Centralized Control: Traditional financial products rely on various middlemen to dictate how they are designed, managed, and adjusted. With Nebula, we aim to give those decision-making powers back to those that are actually using the protocol; the community. They will be the one who decides.
  3. Increases Index Maintenance/Adjustment Efficiency: Instead of relying on centralized parties to intermittently rebalance and adjust clusters, Nebula implements various incentive and other mechanisms to encourage the community to actively take part in maintaining the health of the protocol.

# Definition

A cluster is an instance of a smart contract, an account-like entity that commands a balance and can invoke a restricted set of operations on the Terra chain. A cluster can be described through the following attributes:

  • name, a short moniker identifying the cluster
  • description, an explanation of the cluster's strategy
  • target, the cluster's goal asset and weight allocation
  • penalty function, a mathematical model to score rebalancing operations
  • inventory, the cluster's balance of various Terra native assets or CW20 tokens
  • cluster token, the associated token representing inventory shares
  • pricing oracle, an account or contract with permissions to update asset pricing
  • target oracle, an account or contract with permissions to update cluster target

# Cluster Lifecycle

# Ideation

Every cluster starts out as just an idea. The following is a typical scenario:

  • A member of the community finds a unique opportunity or interesting use case for a Nebula cluster and makes a post on the Nebula Forum (opens new window) outlining their concept, soliciting critical feedback from the community.
  • Once the idea for the potential cluster has been refined through debate, a governance poll for the creation of the cluster is submitted.

# Voting

The community votes on whether to approve the creation of the proposed cluster. If the poll gains enough voter support and passes, the cluster is automatically instantiated once the poll is executed, and initialized with the following procedure:

  1. Set the new cluster's configuration according to the poll's specifications.
  2. Instantiate a new CW20 token as the cluster token, mintable only by the new cluster.
  3. Instantiate a new Astroport pair for the new cluster's cluster token and UST.
  4. Register the new cluster with the protocol so it can begin to receive staking rewards.

# Active

After a cluster passes its voting stage and has been initialized, it enters its active stage during which it is fully operational.

  • Users may begin minting/burning, trading, and performing rebalancing operations against the cluster, meaning cluster token supply and cluster inventory can be changed from deposits and withdrawals.
  • The cluster can perform target updates via its recomposition oracle.

# End-of-Life

A cluster can be decommissioned through a governance poll, which effectively marks its end-of-life and delisting from Nebula protocol. This operation is irreversible, and the only way to "restart" a decommissioned cluster is to start over and propose a brand new cluster using its cluster configuration.

Once a cluster has been disabled:

  • CREATE operations against the cluster are disabled. This means no more of the cluster's token can be minted
  • REDEEM operations may only be performed as a pro-rata withdrawal.
  • No further updates from the pricing oracle or recomposition oracles can be made.
  • The cluster is delisted from any LP pools and arbitrage incentive campaigns and no logner earns any associated rewards.

As no new cluster tokens can be minted and only pro-rata withdrawal redemptions can be made, the decommissioned cluster's asset composition (weight allocation) is considered frozen. Users still holding cluster tokens should trade them back for underlying assets to avoid stale capital.

# Target Updates

Clusters are able to update their target to direct rebalancing toward a new inventory composition and asset weight allocation to maintain a consistent narrative through evolving market conditions.

# Target Oracle

Each cluster designates an account as its registered target oracle. The target oracle is a privileged account that is permitted to update the cluster's target asset composition. If a target oracle is not necessary for the cluster, this value should be set as the contract address for Nebula governance, in which case target updates can only be performed through a governance poll.

Otherwise, a cluster's target oracle can either be a trusted user account or a smart contract. If a cluster needs to change its target oracle for any reason, it must be reassigned through a governance poll.

# Recomposition

A target update can change not only the target weights of the existing asset allocation, but also introduce new assets to the cluster. This, alongside setting an existing component asset's target weight to 0 (removing it from the target), is referred to as target recomposition.

# Procedures

A couple of notes regarding procedure:

  • If the asset already exists in the target allocation, but with a weight of 0, then it is an asset that was previously within the cluster's active target allocation.

  • If removing an asset from the target, the asset to be removed should be weighed at 0, and must remain inside the list of recognized assets for its whole life.

  • If an asset is specified target with weight 0, the cluster will reject any CREATE operations that involve the asset

# Rebalancing

For a cluster to remain in sync with its advertised target asset allocation, it must regularly re-adjust, or rebalance its inventory in response to price changes of its component assets.

Unlike traditional basket instruments, Nebula uses a decentralized procedure to rebalance its clusters. At any moment that a cluster drifts from its target, any user may issue a rebalancing operation against the cluster.

# Operations

There are two rebalancing operations that can be used: "CREATE" and "REDEEM", which correspond to minting and burning cluster tokens. Users are incentivized to mint or burn to deposit or remove assets in amounts that reduce the cluster's divergence from the target with both a discount and NEB token rewards.


Due to the asymmetry introduced by the penalty function, the CREATE and REDEEM operations are not necessarily direct inverse operations.

Symbol Definition
I\vec{I} current inventory, in number of tokens
w\vec{w} target weights, in numbers of tokens
P\vec{P} prices of component tokens, in UST
YY penalty function
XX notional imbalance
  • \odot - denotes the element-wise product
  • \cdot - denotes a regular dot-product.
Design Notes

There are several desired properties of penalty functions:

  • Penalty should grow sharper as imbalance increases.
  • Penalty should scale with the size of the cluster. Creating $1,000 worth of imbalance on a balanced cluster worth $10,000 should incur a greater penalty than on a balanced cluster worth $10,000,000.
  • Breaking a rebalancing operation into several smaller ones should result in the same or greater penalty.
  • There should be a minimum threshold amount of corrected imbalance required to be eligible to receive a reward (CREATE) or discount (REDEEM), as these dilute the value of cluster tokens for existing token holders.
  • Intentionally increasing the imbalance to collect rebalancing rewards should always result in a net loss.
Capital Allocation

The capital allocation A\vec{A} of a cluster is defined as its inventory of tokens in notional terms (units in UST). For a given cluster, its capital allocation is A=IP\vec{A} = \vec{I} \odot \vec{P}.

Notional Imbalance

The notional imbalance XX of a cluster is defined as twice the amount of UST that must be reallocated (swapped from one underlying component asset to another) to make the cluster fully balanced, i.e. when

II=ww\frac{\vec{I}}{\|\vec{I}\|} = \frac{\vec{w}}{\|\vec{w}\|}

In order to compute XX, first determine the capital allocation Atarget\vec{A_\text{target}} of a perfectly balanced cluster with the same total value.

Compute the target weight vector u\vec{u} in notional space.

u=wPwP\vec{u} = \frac{\vec{w} \odot \vec{P}}{\vec{w} \cdot \vec{P}}

Then, multiply it with the total notional value of the cluster:

Atarget=(IP)u\vec{A_\text{target}} = (\vec{I} \cdot \vec{P})\vec{u}

Now, compute XX by adding up the cluster's difference from the target capital allocation for each component asset in the inventory:

X=iAtargetAiX = \sum_i |\vec{A_\text{target}} - \vec{A}|_i

For convenience, within the context of a rebalancing operation, X0X_0 and X1X_1 will refer to the notional imbalance of the cluster prior to and after rebalancing, respectively.


The penalty (pp) and reward (rr) functions (abbreviated as the penalty function YY) are modified by an input EE, the exponential moving average (EMA) of the cluster's total value. The EMA is used as a lagging indicator to guard against some forms of manipulation and modifies the cutoff parameters.

c^=Ec\hat{c} = E * c

The notation c^\hat{c} is used to denote a modified cutoff parameter, which has been multiplied by the value of EE provided within the context.

# CREATE / Mint

In a CREATE operation, the user deposits assets into the cluster and receives newly minted cluster tokens back from the cluster. The amount of minted cluster tokens depends on the quality of the CREATE operation, which corresponds to how much imbalance was corrected.

A CREATE operation is parameterized by two arguments:

  • asset_amounts: C\vec{C}, list of amounts of assets to deposit
  • min_tokens: tokensmin\text{tokens}_\text{min}, (optional) minimum cluster tokens to receive

The user specifies how much of each asset to use in the operation with asset_amounts, and the cluster will determine the amount of new cluster token to return. The operation is aborted if this amount is below min_tokens.

If min_tokens is not provided, the CREATE operation will execute without any protection on lower bound on amount of cluster tokens received.

The number of tokens returned is:

tokensminted=tokenssupplyY(X0,X1,E)+CPIP\text{tokens}_{\text{minted}} = \text{tokens}_{\text{supply}} * \frac{Y(X_0, X_1, E) + \vec{C} \cdot \vec{P}}{\vec{I} \cdot \vec{P}}

Example CREATE:

# REDEEM / Burn

In a REDEEM operation, the user burns their cluster tokens (removes from global supply) and withdraws assets from the cluster. The amount of cluster tokens burned depends on the quality of the REDEEM operation, which corresponds to how much imbalance was corrected.

A REDEEM operation is parametrized by two arguments:

  • asset_amounts - R\vec{R}, (optional) list of amounts of assets to withdraw
  • max_tokens: tokensmax\text{tokens}_\text{max}, maximum cluster tokens to burn

The user may specify his desired amount of each asset to withdraw inside asset_amounts, and the cluster will compute the number of cluster tokens to consume in the operation. The operation is aborted if this amount exceeds max_tokens.

If asset_amounts is not provided, the REDEEM operation is considered a pro-rata withdrawal of the cluster's current inventory and the following default value is used:

Rdefault=tokensmaxIPtokensupplywwP\vec{R}_\text{default} = \text{tokens}_\text{max} * \frac{\vec{I} \cdot \vec{P}}{\text{token}_\text{supply}}*\frac{\vec{w}}{\vec{w} \cdot \vec{P}}

The number of tokens burned is:

tokensburned=tokenssupplyRPY(X0,X1,E)IP\text{tokens}_{\text{burned}} = \text{tokens}_{\text{supply}} * \frac{\vec{R} \cdot \vec{P} - Y(X_0, X_1, E)}{\vec{I} \cdot \vec{P}}

Example REDEEM:

# Penalty Function


This section describes the default penalty function which ships with Nebula. Clusters can be configured to use an alternative penalty function if needed.

y={pX0X1rX0>X1Y(X0,X1,E)=X1X0 ⁣y(X,E)dX\begin{align*} y & = \begin{cases} p & X_0 \le X_1\\ r & X_0 > X_1 \end{cases} \\ Y(X_0, X_1, E) & = \int_{X_1}^{X_0} \! y(X, E) \, \mathrm{d}X \end{align*}

The penalty function YY provides a model for scoring a rebalancing operation, and incentivizes CREATE deposits and REDEEM withdrawals to be executed using amounts that bring the cluster's inventory closer to its target. It maps the change in notional imbalance of the cluster's inventory post-rebalance to a penalty (or reward) incurred.

The yy function selects between two separate curves for penalty and reward, depending on whether the final notional balance has increased. If the operation increases the notional imbalance, i.e. X0<X1X_0 < X_1 then a penalty is calculated using the pp function. Otherwise, the rr function is used to determine a reward. These functions map a given imbalance XX to the rate of penalty or reward per unit of imbalance.

We compute YY, the notional penalty / reward (amount in UST) incurred by the operation by calculating the area under the yy curve, taking its definite integral with respect to notional imbalance between the cluster's initial and final imbalances.

Note: YY < 0 means penalty (since the imbalance increases X1>X0X_1 > X_0) while YY > 0 means rewards. This is valid as the yy function (i.e., pp function and rr function) is a non-negative function showed below.

Y Graph

# p-function

p(X,E)={alX<cl^al+(ahal)(Xcl^)/(ch^cl^)cl^Xch^ahX>ch^\begin{align*} p(X, E) & = \begin{cases} a_l & X < \hat{c_l} \\ a_l + (a_h - a_l) * (X - \hat{c_l}) / (\hat{c_h} - \hat{c_l}) & \hat{c_l} \le X \le \hat{c_h} \\ a_h & X > \hat{c_h} \\ \end{cases} \end{align*}

If the imbalance of the cluster after rebalancing is greater, we compute the notional penalty YY by taking the area under the pp curve between the two imbalances (shaded), as illustrated below.

Graph 2


Parameter Definition
ala_l Penalty amount (low)
aha_h Penalty amount (high)
clc_l Penalty cutoff (low)
chc_h Penalty cutoff (high)

# r-function

r(X,E)={0Xc^aX>c^\begin{align*} r(X, E) & = \begin{cases} 0 & X \le \hat{c} \\ a & X > \hat{c} \end{cases} \end{align*}

If the imbalance of the cluster after rebalancing is reduced, we compute the notional reward YY by taking the area under the rr curve between the two imbalances (shaded), as illustrated below.

R Function


Parameter Definition
aa Reward amount
cc Reward cutoff
Updated on: 4/28/2022, 7:21:28 AM