Difference between revisions of "Wallet (blockchain)"

From Open Transactions
Jump to navigation Jump to search
(Schema: fix errors)
(Deposits)
 
(9 intermediate revisions by 2 users not shown)
Line 5: Line 5:
 
==Responsibilities==
 
==Responsibilities==
  
The blockchain wallet tracks and manipulates cryptocurrencies balances on the appropriate blockchain. The wallet notifies the audit server of received deposits, constructs outgoing transactions, and monitors the state of all relevant incoming and outgoing transactions.
+
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 audit server requires access to a wallet provider for every cryptocurrency its operator wishes to accept deposits for, and this wallet must support the [[Cryptocurrency wallet API|Voting Pool Wallet API]].
+
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.
 
Wallets should understand both hierarchical determinism and multisig capability, and also output coloring.
  
==Address Identification==
+
==Operations==
  
===Series Identifier===
+
===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.
 
Since one wallet will need to handle multiple pools and series, a series identifier must include the pool for which it belongs.
  
A wallet identifier is defined as JSON object and is composed of two parts:
+
A series identifier is defined as JSON object and is composed of two parts:
  
 
;Pool
 
;Pool
Line 25: Line 33:
 
:An index number that starts at 1 and increases monotonically (from the [[Keyset (voting pools)|Keyset Definition]])
 
:An index number that starts at 1 and increases monotonically (from the [[Keyset (voting pools)|Keyset Definition]])
  
====Schema====
+
=====Schema=====
  
<code><pre>
+
<include src="https://raw.githubusercontent.com/Open-Transactions/rfc/master/json/schema/seriesid-01.json" />
{
 
    "$schema": "http://json-schema.org/draft-04/schema#",
 
    "title": "Wallet 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" ]
 
}
 
</pre></code>
 
  
====Example====
+
=====Example=====
  
<code><pre>
+
<include src="https://raw.githubusercontent.com/Open-Transactions/rfc/master/json/data/seriesid-01.json" />
{
 
    "pool": "IFOC:a1075db55d416d3ca199f55b6084e2115b9345e16c5cf302fc80e9d5fbf5d48d:0:57043",
 
    "series": 42
 
}
 
</pre></code>
 
  
===Address Identifier===
+
====Address Identifier====
  
 
An address identifier is defined as a JSON object and is composed of three parts:
 
An address identifier is defined as a JSON object and is composed of three parts:
Line 68: Line 51:
 
:0 for change addresses, 1-through-n for deposit addresses.
 
: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 audit server must reference the [[Keyset (voting pools)|keyset definition]] to obtain the correct transaction server ID-to-branch mapping for a given series since the standard order will change between series.
+
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 (voting pools)|keyset definition]] to obtain the correct notary ID-to-branch mapping for a given series since the standard order will change between series.
  
 
;Index
 
;Index
 
:The index applied to the [[xpub|xpubs]] in a given series to obtain the desired multisig output script.
 
:The index applied to the [[xpub|xpubs]] in a given series to obtain the desired multisig output script.
  
When the audit server needs to query a specific address from the blockchain wallet, will pass the address identifier instead of a raw blockchain address or 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=====
  
<code><pre>
+
<include src="https://raw.githubusercontent.com/Open-Transactions/rfc/master/json/schema/addressid-01.json" />
{
 
    "$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": "http://TBD"
 
        },
 
        "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" ]
 
}
 
</pre></code>
 
  
====Example====
+
=====Example=====
  
<code><pre>
+
<include src="https://raw.githubusercontent.com/Open-Transactions/rfc/master/json/data/addressid-01.json" />
{
 
    "series": { "pool": "IFOC:a1075db55d416d3ca199f55b6084e2115b9345e16c5cf302fc80e9d5fbf5d48d:0:57043", "series": 42 },
 
    "branch": 0,
 
    "index": 21
 
}
 
</pre></code>
 
  
==Wallet Creation==
+
===Wallet Creation===
  
When an audit server first initializes a voting pool contract, it must create the appropriate cryptocurrency wallets via the [[Voting Pool Wallet API#createseries|createseries]] call to a wallet provider of the appropriate coin type (Bitcoin, Litecoin, etc).
+
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 audit server must call this function for every defined series in the keyset.
+
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 [[Voting Pool Wallet API#updateseries|updateseries]] to load them into the blockchain wallet.
+
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.
 
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.
 +
 +
===Deposits===
 +
 +
The wallet provides a deposit scripts for an address when requested via the [[getdepositscript]] call which may be wrapped a [[Payment Protocol (voting pools)|PaymentRequest]] and passed to the depositor.
 +
 +
When a deposit is received, or if the confirmation status of the incoming transaction changes unexpectedly, the wallet will inform the caller via push notifications.
  
 
[[Category:Voting Pool Components]]
 
[[Category:Voting Pool Components]]

Latest revision as of 13:00, 12 November 2014

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": "Wallet 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.

Deposits

The wallet provides a deposit scripts for an address when requested via the getdepositscript call which may be wrapped a PaymentRequest and passed to the depositor.

When a deposit is received, or if the confirmation status of the incoming transaction changes unexpectedly, the wallet will inform the caller via push notifications.