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.