This document serves as a comprehensive guide to understanding the underlying design and structure of MilkyWay. It is intended to provide a clear and detailed description of the various components, systems, and technologies that make up our solution. This document will be an essential resource for developers, operators, and anyone involved in the project, offering insight into the MilkyWay's architecture and how all the pieces fit together. Please feel free to reach out to the team if you have any questions or concerns.
MilkyWay offers a liquid staking solution for the Celestia ecosystem, and it will initially be deployed and operated on Osmosis due to technical constraints that cannot be immediately addressed. When users stake their TIA coins with MilkyWay, they receive an on-chain representation of their TIA staking position, known as milkTIA
. This empowers Celestia token holders to access liquidity for their staked assets, enabling trading or their use as collateral in various DeFi products.
At its core, MilkyWay uses CosmWasm contracts and a multisig custody system. It also leverages the Cosmos SDK authz module to introduce liquid staking derivative for Celestia ecosystem.
Before diving into the technical architecture of MilkyWay, let's get comfortable with a few terms that will pop up:
TIA
is the native coin on CelestiaosmoTIA
is IBC denomination for TIA sent to Osmosis blockchainmilkTIA
is minted through thetokenfactory
module on Osmosis when users stakeosmoTIA
. It is reward-bearing token meaning it increases linearly againstosmoTIA
over time.- Operators are trusted entities entrusted with the operation of the MilkyWay protocol, with each operator holding keys for all the multisigs used within the protocol.
- Validators are established Celestia validators who receive delegations from MilkyWay protocol.
The following diagrams for each process provide a visual representation of MilkyWay's data flow, These visual aids are designed to enhance the understanding of MilkyWay's technical architecture by simplifying complex concepts and illustrating how it works at its core.
At launch, MilkyWay begins with 7 operators. Every operator needs to generate 3 accounts on Celestia and share their public keys. This information will be used to set up the following multi-signature accounts. It is essential that the generated accounts are securely stored in a vault with as low risk of compromise as possible.
-
Staker multisig
- This account is configured as a 5-of-7 multisig, utilizing the public keys of the operators. It serves its purpose solely by granting full authorization to the
Staker Controller
multisig account. The full authorization means to grant privileges to grant to theStaker Controller
multisig account on behalf of the staker.
- This account is configured as a 5-of-7 multisig, utilizing the public keys of the operators. It serves its purpose solely by granting full authorization to the
-
Staker controller multisig
- This account is configured as a 5-of-7 multisig, utilizing the public keys of the operators. It receives a full authorization from the
Staker
multisig account and performs actions on behalf of the staker multisig account.
- This account is configured as a 5-of-7 multisig, utilizing the public keys of the operators. It receives a full authorization from the
-
Rewards collector multisig
- This account is configured as a 5-of-7 multisig, utilizing the public keys of the operators. It is primarily responsible for receiving staking rewards on behalf of the staker multisig account and is instrumental in enhancing accounting management.
There is an account called Grantee
, which will receive a limited authorization of the Staker
multisig and will be run by coordinator. The limited authorization prevents the Grantee
from taking any actions that could have a detrimental impact on the protocol.
- Limited authorization includes:
MsgDelegate
- This grant is needed for the
Grantee
to delegate on behalf of theStaker
multisig. It is important to note that the grant is setup with an allow list of validators selected by the MilkyWay protocol. With this constraint, theGrantee
is only permitted to delegate among the validators listed in the allow list.
- This grant is needed for the
MsgUndelegate
- This grant is needed for the Grantee to undelegate on behalf of the Staker multisig. It is important to note that the grant is setup with an allow list of validators selected by the MilkyWay protocol. With this constraint, the grantee is only permitted to undelegate among the validators listed in the allow list.
MsgBeginRedelegate
- This grant is needed for the Grantee to redelegate delegations from the Staker multisig account in case validator set is changed. It is important to note that the grant is setup with an allow list of validators selected by the MilkyWay protocol. With this constraint, the grantee is only permitted to redelegate among the validators listed in the allow list.
MsgWithdrawDelegatorReward
- This grant is needed to allow the
Grantee
to withdraw staking rewards from theStaker
multisig account.
- This grant is needed to allow the
MsgTransfer
- This grant is needed for the
Grantee
to IBC transfer. It is important to note that the grant is setup with the specific source port, channel and an allow list of the MilkyWay’s staking contract address. With this constraint, theGrantee
is only permitted to IBC transfer to the contract address.
- This grant is needed for the
We anticipate that TIA holders transfer their TIA from Celestia to Osmosis if they wish to use MilkyWay’s liquid staking derivative service. Our front-end application will facilitate the IBC transfer from Celestia to Osmosis.
-
Let’s assume that a user initiates a request to liquid stake their
osmosTIA
into the CW staking contract on Osmosis. -
The contract calculates how much
milkTIA
to provide based on the exchange rate ofTIA
. Then it mintsmilkTIA
using thetokenfactory
module of Osmosis and gives the usermilkTIA
(staked TIA) as a tokenized representation of the staked TIA coin. -
The contract constructs an IBC transfer transaction to the staker multisig account on Celestia and broadcast it.
-
The coordinator monitors the IBC transfer transactions from Osmosis on Celestia.
-
The coordinator generates
MsgDelegate
messages in a transaction to delegate uniformly across all MilkyWay validators using a private key of the grantee account (limited authorization) and broadcast it to Celestia.
-
Let’s assume that a user initiates a request to liquid unstake their
milkTIA
into the CW staking contract on Osmosis. -
The contract groups the unbonding request into a batch, which is then delivered to Celestia at the end of each batch period. By default, the batch period is 3 days.
-
The coordinator sends
MsgExecuteContract
transaction to execute thesubmit_batch
in the staking contract to process awaiting undelegation requests in the current batch. -
The coordinator generates
MsgUndelegate
messages in a transaction to undelegate uniformly across all MilkyWay validators and sign it with the grantee’s account. Then it broadcasts the signed transaction to Celestia. -
Wait for an unbonding period of 21 days
-
Unbonded amount is unlocked from the staking pool
-
The coordinator monitors undelegation events and construct an IBC transfer transaction from Celestia to Osmosis with the unbonded amounts and sign it. Then the coordinator broadcasts it to Celestia.
-
After a successful IBC transfer on Osmosis, unbonded
osmoTIA
is expected to arrive on the staking contract. Users who submitted unbonding requests can now claim theirosmoTIA
with the accrued staking rewards.
During the delegation process, the deposited osmoTIA is transferred to Celestia to stake on behalf of the MilkyWay users. Once it is staked, Celestia protocol begins to accrue staking rewards every block. To update the exchange rate on the staking contract on Osmosis, it's the responsibility of operators to regularly claim rewards and send them back to the staking contract, thereby updating the exchange rate. In MilkyWay, it leverages the authz module to grant limited authorization to withdraw staking rewards to the grantee account from the staker multisig account and the grantee account has limited authorization to IBC transfer from the rewards collector multisig account.
-
The coordinator periodically monitors the accrued staking rewards of the delegations from the Staker multisig account and signs
WithdrawDelegatorReward
andMsgTransfer
in a transaction and broadcast it to Celestia. -
IBC transfer the withdrawn staking rewards to the staking contract on Osmosis
-
Upon the staking rewards arriving on Osmosis, the staking contract updates the exchange rate. This increases the value of
milkTIA
over time.
It is important that you understand the difference between operators and validators in MilkyWay. Reference the “Definition” section to understand the difference between them.
The CW staking contract on Osmosis has exec entry points called AddValidator
and RemoveValidator
to add or remove validator from the current validator set.
-
The coordinator monitors the staking contract and parse add/remove validators events.
-
The coordinator performs the following depending on validator addition / removal
- Validator Addition Process
- There will be selection process for new validator(s)
- Request operators to sign
MsgGrant
(StakeAuthorization
) to updateAllowList
that includes the new validator(s). The coordinator aggregates signatures and broadcast it to Celestia - Request operators to sign
MsgExecuteContract
to callAddValidator
exec entry point in the staking contract on Osmosis. The coordinator aggregates signatures and broadcast it to Celestia - The coordinator rebalances the existing delegations by sending
MsgBeginRedelegate
messages in a transaction to allocate equal amounts to the newly added validator.
- Validator Removal Process
- Validators must provide at least one month's advance notice to the community if they wish to exit from the validator set. It is crucial that they remain within the active validator set and uphold uptime. If they become inactive and are removed from the validator set, the community will decide whether to exclude them from the MilkyWay validator set
- Execute
RemoveValidator
exec entry point in the staking contract on Osmosis - The coordinator sends
MsgBeginRedelegate
messages in a transaction to redelegate all delegations to our remaining validators. - Request operators to sign
MsgGrant
(StakeAuthorization
) to updateAllowList
that removes the validator(s). - We aggregate signatures and broadcast it to Celestia
- Validator Addition Process
In MilkyWay, we've designed a system that leverages the authz module to manage the process of changing the operator set.
- As long as we have 5 out of 7 signatures from operators, we can still generate the multi-signed transaction to change the staker controller multisig account.
In the event of slashing, the following process is expected to be processed.
-
The coordinator detects slashing events every block.
-
Operators sign
MsgExecuteContract
to activate the circuit breaker and temporarily pause the system. -
Investigate the slashing incident and take required measures including making an announcement, collaborating with other operators and partners, and putting up a vote to hear the community feedback and voice on the possibility of removing the validator from the MilkyWay validator set.
-
Operators sign
MsgExecuteContract
to update the total amount of native TIA to update the exchange rate and resume the protocol in the staking contract on Osmosis.
-
The coordinator periodically monitors the accrued staking rewards of the delegations from the staker multisig account periodically and signs
WithdrawDelegatorReward
and MsgTransfer in a transaction and broadcast it to Celestia. -
IBC transfer the withdrawn staking rewards to the staking contract on Osmosis
-
IBC transfer back to the staker multisig
-
The coordinator monitors the IBC transfer transactions from Osmosis on Celestia.
-
The coordinator generates
MsgDelegate
messages in a transaction to delegate uniformly across all MilkyWay validators using a private key of the grantee account (limited authorization) and broadcast it to Celestia.
The MilkyWay's core contracts that will be deployed and operated on Osmosis and the source code can be found in here.
The MilkyWay daemon is an off-chain program written in Go that provides convenient functionalities for operators to use. Also, it contains coordinator program to coordinate between the Osmosis and Celestia.