Wallet (blockchain)

Introduction

In order to avoid ambiguity, the terms "blockchain wallet" and "blockchain address" refers to the cryptocurrency for which is pool is tracking receipts. This differentiation is necessary to avoid confusion with OT wallets or nym addresses.

Responsibilities

The blockchain wallet tracks and manipulates cryptocurrencies balances on the appropriate blockchain. The wallet notifies the auditor of received deposits, constructs outgoing transactions, and monitors the state of all relevant incoming and outgoing transactions.

An auditor requires access to a wallet provider for every cryptocurrency its operator wishes to accept deposits for, and this wallet must support the Voting Pool Wallet API.

Wallets should understand both hierarchical determinism and multisig capability, and also output coloring.

Operations

Address Identification

All components of a voting pool, except for the blockchain wallet, must be currency-agnostic and do not have any inherent understanding of currency-specific parameters such as address formats.

Because of this, all addresses are passed as a set of index numbers. These numbers represent the parameters which can deterministically generate the underlying blockchain address from the voting pool asset contract.

The numbers are grouped into two identifiers based on the resolution needed for common operations.

Series Identifier

Since one wallet will need to handle multiple pools and series, a series identifier must include the pool for which it belongs.

A series identifier is defined as JSON object and is composed of two parts:

Pool

UUID for a specific voting pool. This UUID is persistent even as members are added or removed.

Series

An index number that starts at 1 and increases monotonically (from the Keyset Definition)

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Series identifier",
    "description": "A unique identifier for a series in a voting pool",
    "type": "object",
    "properties": {
        "pool": {
            "type": "string",
            "description": "the color definition of the pool's charter"
        },
        "series": {
            "type": "number",
            "description": "the series number of the given voting pool",
            "minimum": 1,
            "exclusiveMinimum": false
        }
    },
    "required": [ "pool","series" ]
}

Example

{
    "pool": "IFOC:a1075db55d416d3ca199f55b6084e2115b9345e16c5cf302fc80e9d5fbf5d48d:0:57043",
    "series": 42
}

Address Identifier

An address identifier is defined as a JSON object and is composed of three parts:

Series

The series identifier which contains the address

Branch

0 for change addresses, 1-through-n for deposit addresses.

Note the branch represents the position of a server’s xpub in the standard order for a given series. The auditor must reference the keyset definition to obtain the correct notary ID-to-branch mapping for a given series since the standard order will change between series.

Index

The index applied to the xpubs in a given series to obtain the desired multisig output script.

When the auditor needs to query a specific address from the blockchain wallet, will pass the address identifier instead of a raw blockchain address or script.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Address identifier",
    "description": "A unique identifier for a specific address in a voting pool",
    "type": "object",
    "properties": {
        "series": {
            "description": "the series identifier containing the address",
            "$ref": "https://raw.githubusercontent.com/Open-Transactions/rfc/master/json/schema/seriesid-01.json"
        },
        "branch": {
            "type": "number",
            "description": "the chain within the series containing the desired address",
            "minimum": 0,
            "exclusiveMinimum": false
        },
        "index": {
            "type": "number",
            "description": "the value used to derive the public keys used to create the multisig script",
            "minimum": 0,
            "exclusiveMinimum": false
        }
    },
    "required": [ "series","branch","index" ]
}

Example

{
    "series": { "pool": "IFOC:a1075db55d416d3ca199f55b6084e2115b9345e16c5cf302fc80e9d5fbf5d48d:0:57043", "series": 42 },
    "branch": 0,
    "index": 21
}

Wallet Creation

When an auditor first initializes a voting pool contract, it must create the appropriate cryptocurrency wallets via the Createseries call to a wallet provider of the appropriate coin type (Bitcoin, Litecoin, etc).

The auditor must call this function for every defined series in the keyset.

When the extended private keys for a series are brought online, the wallet must call Thawseries to load them into the blockchain wallet.

The wallet must find the correct extended public key when it adds the extended private key to the wallet and must return an error to the operator if he attempts to load and extended private key for an extended public key not defined in that series.