Merge pull request #20 from symbioticfi/specs

Specs

specs/Collateral.md

@@ -1,10 +1,16 @@
 ## Collateral
 
-### General Overview
+Collateral is a concept introduced by Symbiotic that brings capital efficiency and scale by enabling assets used to secure Symbiotic networks to be held outside of the Symbiotic protocol itself - e.g. in DeFi positions on networks other than Ethereum itself.
 
-Any operator wishing to operate in a Proof of Stake (POS) system must have a stake. This stake must be locked in some manner, somewhere. There are solutions that make such a stake liquid, yet the original funds remain locked, and in exchange, depositors/delegators receive LST tokens. They can then operate with these LST tokens. The reasons for locking the original funds include the need for immediate slashing if an operator misbehaves. This requirement for instant action necessitates having the stake locked, a limitation imposed by the current design of POS systems.
+Symbiotic achieves this by separating the ability to slash assets from the underlying asset itself, similar to how liquid staking tokens create tokenized representations of underlying staked positions. Technically, collateral positions in Symbiotic are ERC-20 tokens with extended functionality to handle slashing incidents if applicable. In other words, if the collateral token aims to support slashing, it should be possible to create a `Burner` responsible for proper burning of the asset.
 
-Collateral introduces a new type of asset that allows stakeholders to hold onto their funds and earn yield from them without needing to lock these funds in direct manner or convert them to another type of asset. Collateral represents an asset but does not require physically holding or locking this asset. The securities backing the Collateral can be in various forms, such as a liquidity pool position, some real-world asset, or generally any type of asset. Depending on the implementation of Collateral, this securing asset can be held within the Collateral itself or elsewhere.
+For example, if asset is ETH LST it can be used as a collateral if it's possible to create `Burner` contract that withdraw ETH from beaconchain and burn it, if asset is native e.g. governance token it also can be used as collateral since burner might be implemented as "black-hole" contract or address.
+
+Symbiotic allows collateral tokens to be deposited into vaults, which delegate collateral to operators across Symbiotic networks. Vaults define acceptable collateral and it's `Burner` _(if vault supports slashing)_ and networks need to accept these and other vault terms such as slashing limits to receive rewards _(these processes are described in detail in Vault section)_.
+
+---
+
+We do not specify the exact implementation of the Collateral, however, it must satisfy all the following requirement:
 
 - Collateral token must support ERC-20 interface
 - [**OPTIONAL**] Collateral token should be slashable i.e. native token or derivative that supports redeeming the underlying native token. _(Only if collateral is used in slashable vaults)_.

specs/Network.md

@@ -1,13 +1,54 @@
 ## Network
 
-In Symbiotic, we define networks as any protocol that requires a decentralized infrastructure network to deliver a service in the crypto economy, e.g. enabling developers to launch decentralized applications by taking care of validating and ordering transactions, providing off-chain data to applications in the crypto economy, or providing users with guarantees about cross-network interactions, etc.
+In Symbiotic, networks are represented through a network address (either an EOA or a contract) and a middleware contract, which can incorporate custom logic and is required to include slashing logic. The core protocol's fundamental functionalities encompass slashing operators and rewarding both stakers and operators.
 
 ---
 
-Networks are represented through a network address (either an EOA or a contract) and a middleware contract, which can incorporate custom logic and is required to include slashing logic.
+A network epoch (let's name it $`\text{NETWORK\_EPOCH}`$) is a period while a certain operator set, obtained given the captured stake, operates for the good of the network. The epoch plus the vault's veto and execute phases' durations should not exceed the duration of the vault's epoch to **ensure that withdrawals do not impact the captured stake** (however, the conditions can be softer in practice).
 
 ---
 
+The vault allocates stakes by setting limits for networks and operators.
+
+Let the vault be $V$, the delegator module of the vault is $D$ and slasher module is $S$.
+
+Given the current $\text{active}$ balance of the vault and the limits, we can **capture the stake for the subsequent network epoch**:
+
+$networkOperatorStake = D.stake(network, operator)$
+
+---
+
+The limits are set in the vault, and the network cannot control this process (unless the vault is managed by the network). However, the **implementation prevents** the vault **from removing the previously given slashing guarantees**.
+
+Moreover, the network **can limit the maximum amount of stake** it wants to use via the `D.setMaxNetworkLimit()` method.
+
+---
+
+The network has the flexibility to configure the operator set within the middleware or network contract.
+
+The following functions could be useful:
+
+- `D.stakeAt(network, operator, timestamp, hints)`: Determines minimum stake eligibility. Note that the sum of operators' stakes may exceed the network's total stake, depending on the network's and operators' limits in the delegator module.
+- `OperatorOptInService.isOptedInAt(operator, network, timestamp, hint)`: Checks the opt-in status.
+
+---
+
+For each operator, the network can obtain its stake which will be valid during $d = vaultEpoch$. It can slash the whole stake of the operator. Note, that the stake itself is given according to the limits and other conditions.
+
+Note that **the actual slashed amount may be less than the requested one**. This is influenced by the cross-slashing or veto process of the Slasher module.
+
+The network can slash the operator within the vault only if
+
+1. The operator is opted into the vault
+2. The operator is opted into the network
+
+To initiate a slashing process, a network should call:
+
+1. `slash(network, operator, amount, captureTimestamp, hints)` for the Slasher module.
+2. `requestSlash(network, operator, amount, captureTimestamp, hints)` for the VetoSlasher module.
+
+The module will check the provided guarantees at the $captureTimestamp$, denoted as $G$. It also calculates cumulative slashings from the $captureTimestamp$ to the current moment, denoted as $C$. It is guaranteed that for every correct $captureTimestamp$, $C \leq G$. The module will allow slashing no more than $G - C$ to justify the given guarantees.
+
 ### Deploy
 
 ```shell

specs/Operator.md

@@ -12,11 +12,17 @@ In Symbiotic, the operator can be either an EOA or a contract registered in the
 
 ---
 
-The operator opts into the network to join it. Each network independently decides whether to include the operator in its active operator set based on various factors, such as reputation, stake amount, and other relevant criteria.
+Let the vault be $V$, the delegator module of the vault is $D$ and slasher module is $S$.
+
+To raise the stake, the operator must opt into networks and vaults by calling the `optIn()` method in the `OperatorNetworkOptInService` and `OperatorVaultOptInService` accordingly. The `OPERATOR_NETWORK_LIMIT_SET_ROLE` then allocates the stake to the operator by calling `D.setOperatorNetworkLimit()`.
+
+---
+
+The operator opts into the network to validate it. Based on various factors, such as reputation, stake amount, and other relevant criteria each network independently decides whether to include the operator in the active operator set or not.
 
 ---
 
-The entire amount of stake is subject to slashing. The operator's stake becomes active and subject to slashing after the conclusion of the vault's epoch that follows the opt-in processes to both the network and the vault.
+The operator's stake becomes active and subject to slashing immediately after the opt-in process to both the network and the vault. However, the corresponding role in the vault can apply the timelock for allocating a stake for additional guarantees for operators. The slashing process is implemented in the $S$ module.
 
 ### Deploy
 

specs/Resolver.md

@@ -4,4 +4,4 @@ Symbiotic supports various modes of handling slashing incidents through the intr
 
 ---
 
-A resolver is an address that can veto a particular slashing request in the vault. It listens to the slashing requests and when it finds the request it has some time to veto the request or agree with the slashing. Note, that a resolver does not veto the request, such a request will be considered approved for slashing by the resolver. Each slashing request has its own veto deadline defined by the vault.
+A resolver is an address that can veto a particular slashing request in the slasher module of the vault. It listens to the slashing requests and when it finds the request it has some time to veto the request or agree with the slashing. Note, that if a resolver does not veto the request, such a request will be considered approved for slashing by the resolver. Each slashing request has its own veto deadline defined by the vault.