Security

The Security module is responsible for (1) tracking the status of the BTC Bridge, (2) the “active” blocks of the BTC Bridge, and (3) generating secure identifiers.

  1. BTC Bridge Status: The BTC Bridge has three distinct states: Running, Error, and Shutdown which determine which functions can be used.
  2. Active Blocks: When the BTC Bridge is not in the Running state, certain operations are restricted. In order to prevent impact on the users and vaults for the core issue, redeem, and replace operations, the BTC Bridge only considers Active Blocks for the Issue, Redeem, and Replace Periods.
  3. Secure Identifiers: As part of the OP_RETURN scheme to prevent replay attacks, the security module generates unique identifiers that are used to identify transactions.

Overview

Failure Modes

The BTC Bridge can enter into an ERROR and SHUTDOWN state, depending on the occurred error. An overview is provided in the figure below.

State machine showing BTC Bridge failure modes

Fig. 10 (Informal) State machine showing the operational and failure modes and how to recover from or flag failures.

Failure handling methods calls are restricted, i.e., can only be called by pre-determined roles.

Oracle Offline

The Exchange Rate Oracle experienced a liveness failure (no up-to-date exchange rate available). The frequency of the oracle updates is defined in the Oracle module.

Error code: ORACLE_OFFLINE

BTC-Relay Offline

The BTC-Relay has less blocks stored than defined as the STABLE_BITCOIN_CONFIRMATIONS.

This is the initial state of the BTC-Bridge. After more than the STABLE_BITCOIN_CONFIRMATIONS BTC blocks have been stored in BTC-Relay, the BTC Bridge cannot decide if or not it is behind in terms of Bitcoin blocks since we make no assumption about the frequency of BTC blocks being produced.

Error code: BTC_RELAY_OFFLINE

Data Model

Enums

StatusCode

Indicates ths status of the BTC Bridge.

  • RUNNING: 0 - BTC Bridge fully operational
  • ERROR: 1- an error was detected in the BTC Bridge. See Errors for more details, i.e., the specific error codes (these determine how to react).
  • SHUTDOWN: 2 - BTC Bridge operation fully suspended. This can only be achieved via manual intervention by the Governance Mechanism.

ErrorCode

Enum specifying error codes tracked in Errors.

  • NONE: 0
  • ORACLE_OFFLINE: 1
  • BTC_RELAY_OFFLINE: 2

Data Storage

Scalars

BridgeStatus

Integer/Enum (see StatusCode below). Defines the current state of the BTC Bridge.

Errors

Set of error codes (ErrorCode enums), indicating the reason for the error. The ErrorCode entries included in this set specify how to react to the failure.

Nonce

Integer increment-only counter, used to prevent collisions when generating identifiers for e.g., redeem or replace requests (for OP_RETURN field in Bitcoin).

ActiveBlockCount

A counter variable that increments every block where the shard status is RUNNING:0. This variable is used to keep track of durations, such as issue/redeem/replace expiry. This is used instead of the block number because if the shard status is not RUNNING:0, no payment proofs can be submitted, so it would not be fair towards users and vaults to continue counting down the (expiry) periods.

Functions

generateSecureId

Generates a unique ID using an account identifier, the Nonce and a random seed.

Specification

Function Signature

generateSecureId(account)

Parameters

  • account: Bridge account identifier (links this identifier to the AccountId associated with the process where this secure id is to be used, e.g., the user calling requestIssue).

Returns

  • hash: a cryptographic hash generated via a secure hash function.

Function Sequence

  1. Increment the Nonce.
  2. Concatenate account, Nonce, and parent_hash().
  3. SHA256 hash the result of step 1.
  4. Return the resulting hash.

Note

The funtion parent_hash() is assumed to return the hash of the shard’s parent block - which precedes the block this function is called in.

hasExpired

Checks if the given period has expired since the given starting point. This calculation is based on the ActiveBlockCount.

Specification

Function Signature

has_expired(opentime, period)

Parameters

  • opentime: the ActiveBlockCount at the time the issue/redeem/replace was opened.
  • period: the number of blocks the user or vault has to complete the action.

Returns

  • true if the period has expired

Function Sequence

  1. Add the opentime and period.
  2. Compare this against ActiveBlockCount.

setBridgeStatus

Governance sets a status code for the BTC Bridge manually.

Specification

Function Signature

setBridgeStatus(StatusCode)

Parameters

  • StatusCode: the new StatusCode of the BTC-Bridge.

insertBridgeError

Governance inserts an error for the BTC Bridge manually.

Specification

Function Signature

insertBridgeError(ErrorCode)

Parameters

  • ErrorCode: the ErrorCode to be added to the set of errors of the BTC-Bridge.

removeBridgeError

Governance removes an error for the BTC Bridge manually.

Specification

Function Signature

removeBridgeError(ErrorCode)

Parameters

  • ErrorCode: the ErrorCode to be removed from the set of errors of the BTC-Bridge.

Events

RecoverFromErrors

Event Signature

RecoverFromErrors(StatusCode, ErrorCode[])

Parameters

  • StatusCode: the new StatusCode of the BTC Bridge
  • ErrorCode[]: the list of current errors