Skip to content

Delegator calls reference

Jump to bottom
Egor Lysenko edited this page Jan 18, 2021 · 12 revisions

Delegation calls

Create delegation

Delegate a certain amount of FTM to a staker.

Delegation is applied in next epoch.

Minimum delegation amount is 1.0 FTM.

sfcc.createDelegation(stakerID, {from: "0xAddress", value: web3.toWei("amount", "ftm")})

Checks

  • Staker must exist
  • Staker is active: staker isn't a cheater, isn't pruned for being offline, didn't prepare to withdraw
  • Delegated amount is greater or equal to sfcc.minDelegation()
  • No more than one delegation per address
  • This address isn't a staker
  • Total amount of delegations to staker is less or equal to 15.0 * staker's stake amount

Increase delegation stake

Not availible since sfc2.0.2-rc2.

Request to fully withdraw delegated stake

Put in a request to withdraw delegated stake. After a number of seconds and epochs have passed since calling the function below, you will be able to call withdrawDelegation() successfully.

After calling this function, you won't be able to claim rewards anymore. Claim all the rewards before calling this function.

The validator's stake will be decreased in next epoch by amount of delegation.

sfcc.prepareToWithdrawDelegation(stakerID, {from: "0xAddress"})

Checks

  • Delegation must exist
  • All delegation rewards are claimed
  • Delegation isn't deactivated (i.e. didn't prepare to withdraw)

Request to partially withdraw delegated stake

Put in a request to partially withdraw delegated stake. This function can be called after all the rewards are claimed. After a number of seconds and epochs have passed since calling the function below, you will be able to call partialWithdrawByRequest() successfully.

requestID is any number which wasn't used by delegator before. Remember this number, it'll be needed to finalize withdrawal. Use 0 if not sure.

Delegator cannot prepare to withdraw the whole stake with this call. Use prepareToWithdrawDelegation for this case.

The validator's stake will be decreased in next epoch by amountToWithdraw.

sfcc.prepareToWithdrawDelegationPartial(requestID, stakerID, web3.toWei("amountToWithdraw", "ftm"), {from: "0xAddress"})

Checks

  • Delegation must exist
  • All delegation rewards are claimed
  • Delegation isn't deactivated (i.e. didn't prepare to withdraw)
  • requestID isn't occupied by another request
  • amountToWithdraw >= minDelegationDecrease()
  • left amount >= minDelegation()

Fully withdraw delegated stake

Withdraw delegated stake. Erases delegation object and withdraws delegated stake.

Note that a number of seconds and epochs must elapse since prepareToWithdrawDelegation call.

If staker is a cheater (i.e. double-signed), then delegation will be erased, but delegated stake won't be withdrawn (i.e. will be slashed).

sfcc.withdrawDelegation(stakerID, {from: "0xAddress"})

Checks

  • Either passed at least sfcc.delegationLockPeriodTime() seconds since prepareToWithdrawDelegation was called, or validator has withdrawn already
  • Either passed at least sfcc.delegationLockPeriodEpochs() epochs since prepareToWithdrawDelegation was called, or validator has withdrawn already

Partially withdraw delegated stake

Finalize withdrawal request. Erases request object and withdraws requested stake, transfers requested stake to account address.

Note that a number of seconds and epochs must elapse since prepareToWithdrawDelegationPartial call.

If staker is a cheater (i.e. double-signed), then object will be erased, but stake won't be withdrawn (i.e. will be slashed).

sfcc.partialWithdrawByRequest(requestID, {from: "0xAddress"})

Checks

  • Either passed at least sfcc.delegationLockPeriodTime() seconds since prepareToWithdrawDelegationPartial was called, or validator has withdrawn already
  • Either passed at least sfcc.delegationLockPeriodEpochs() epochs since prepareToWithdrawDelegationPartial was called, or validator has withdrawn already

Lock up delegation

Reward for a non-locked stake is 30% (base rate) of the full reward for a locked stake. If withdrawal is to be made before lockup period expired, the following penalty will be withheld from the withdrawn amount:

  • 85% of rewards received for epochs during the lockup period. On partial withdrawal, the penalty is multiplied by a ratio of withdrawn stake (in a case of withdrawing a half of stake, 85%/2=42.5% penalty is applied). 85% is the penalty calculated as (base rate = 30%)/2 + lockup rate = 70%.

Note that validator's stake must be locked up before validator's delegations can lock their stake. The specified lockup period of a delegation must not exceed the validator's current lockup period.

sfcc.lockUpDelegation(lockupDuration, stakerID, {from: "0xAddress"})

lockupDuration is lockup duration in seconds. Must be >= 14 days, <= 365 days.

Checks

  • Previous lockup period (if any) must end before the new period starts.
  • lockupDuration >= 14 days
  • lockupDuration <= 365 days
  • Validator's lockup period must end after delegation's lockup period will expire.
  • Validator is active: validator isn't a cheater, isn't pruned for being offline, didn't prepare to withdraw
  • All the lockup rewards are claimed (including the last epoch of lockup period).
Clone this wiki locally