Collateral

Overview

The Collateral module is the central storage for collateral provided by users and vaults of the system. It allows to (i) lock, (ii) release, and (iii) slash collateral of either users or vaults. It can only be accessed by other modules and not directly through external transactions.

Step-by-Step

The protocol has three different “sub-protocols”.

Lock: Store a certain amount of collateral from a single entity (user or vault).
Release: Transfer a certain amount of collateral back to the entity that paid it.
Slash: Transfer a certain amount of collateral to a party that was damaged by the actions of another party.

Data Model

Maps

Accounts

Mapping from accounts to the Account struct.

Structs

Account

Stores the balances of a single account.

Parameter	Type	Description
`free`	Balance	Free and may be transferred without restriction.
`reserved`	Balance	Reserved and may not be used by holder until unlocked.

Functions

lockCollateral

A user or a vault locks some amount of collateral.

Specification

Function Signature

lockCollateral(account, amount)

Parameters

account: The account locking collateral.
amount: The amount of collateral.

Events

LockCollateral

Preconditions

The account MUST have sufficient free balance.

Postconditions

The account’s free balance MUST decrease by amount.
The account’s reserved balance MUST increase by amount.

releaseCollateral

When a protocol has completed successfully, we unlock the account’s collateral.

Specification

Function Signature

releaseCollateral(account, amount)

Parameters

account: The account unlocking collateral.
amount: The amount of collateral.

Events

ReleaseCollateral

Preconditions

The account MUST have sufficient reserved balance.

Postconditions

The account’s reserved balance MUST decrease by amount.
The account’s free balance MUST increase by amount.

slashCollateral

When a protocol has not completed successfully, the origin account (sender) is slashed and the collateral is transferred to another party (receiver).

Specification

Function Signature

slashCollateral(sender, receiver, amount)

Parameters

sender: The sender that to slash.
receiver: The receiver of the collateral.
amount: The amount of collateral.

Events

SlashCollateral

Preconditions

The sender MUST have sufficient reserved balance.

Postconditions

The sender’s reserved balance MUST decrease by amount.
The receiver’s free balance MUST increase by amount.

Events

LockCollateral

Emit a LockCollateral event when a sender locks collateral.

Event Signature

LockCollateral(sender, amount)

Parameters

sender: The sender that provides the collateral.
amount: The amount of collateral.

Function

lockCollateral

ReleaseCollateral

Emit a ReleaseCollateral event when a sender releases collateral.

Event Signature

ReleaseCollateral(sender, amount)

Parameters

sender: The sender that initially provided the collateral.
amount: The amount of collateral.

Function

releaseCollateral

SlashCollateral

Emit a SlashCollateral event when a sender’s collateral is slashed and transferred to the receiver.

Event Signature

SlashCollateral(sender, receiver, amount)

Parameters

sender: The sender that initially provided the collateral.
receiver: The receiver of the collateral.
amount: The amount of collateral.

Function

slashCollateral

Errors

ERR_INSUFFICIENT_BALANCE`

Message: “The sender’s balance is below the requested amount.”
Function: lockCollateral | releaseCollateral | slashCollateral
Cause: the sender has less collateral stored than the requested amount.