wallet

README

wallet-interface

Interfaces for the openbazaar-go wallet

Any coin that wishes to integrate with openbazaar-go must implement this interface.

Documentation

Index

• Constants
• Variables
• type Coin
• type CoinType
  • func (c *CoinType) CurrencyCode() string
  • func (c *CoinType) String() string
• type Datastore
• type FeeLevel
• type KeyPath
• type KeyPurpose
• type Keys
• type Signature
• type StatusCode
• type Stxo
  • func (stxo *Stxo) IsEqual(alt *Stxo) bool
• type Stxos
• type TransactionCallback
• type TransactionInput
• type TransactionOutput
• type TransactionRecord
• type Txn
• type Txns
• type Utxo
  • func (utxo *Utxo) IsEqual(alt *Utxo) bool
• type Utxos
• type Wallet
• type WalletMustManuallyAssociateTransactionToOrder
• type WatchedScripts

Constants

const (
	Bitcoin     CoinType = 0
	Litecoin             = 1
	Zcash                = 133
	BitcoinCash          = 145
	Ethereum             = 60

	TestnetBitcoin     = 1000000
	TestnetLitecoin    = 1000001
	TestnetZcash       = 1000133
	TestnetBitcoinCash = 1000145
	TestnetEthereum    = 1000060
)

const (
	StatusUnconfirmed StatusCode = "UNCONFIRMED"
	StatusPending                = "PENDING"
	StatusConfirmed              = "CONFIRMED"
	StatusStuck                  = "STUCK"
	StatusDead                   = "DEAD"
	StatusError                  = "ERROR"
)

const (
	PRIOIRTY FeeLevel = 0
	NORMAL            = 1
	ECONOMIC          = 2
	FEE_BUMP          = 3
)

Variables

var (
	ErrorInsuffientFunds error = errors.New("Insuffient funds")
	ErrorDustAmount      error = errors.New("Amount is below network dust treshold")
)

Errors

Types

type Coin

type Coin interface {
	String() string
	CurrencyCode() string
}

type CoinType

type CoinType uint32

func (*CoinType) CurrencyCode

func (c *CoinType) CurrencyCode() string

func (*CoinType) String

func (c *CoinType) String() string

type Datastore

type Datastore interface {
	Utxos() Utxos
	Stxos() Stxos
	Txns() Txns
	WatchedScripts() WatchedScripts
}

type FeeLevel

type FeeLevel int

type KeyPath

type KeyPath struct {
	Purpose KeyPurpose
	Index   int
}

type KeyPurpose

type KeyPurpose int

The end leaves on the HD wallet have only two possible values. External keys are those given to other people for the purpose of receiving transactions. These may include keys used for refund addresses. Internal keys are used only by the wallet, primarily for change addresses but could also be used for shuffling around UTXOs.

const (
	EXTERNAL KeyPurpose = 0
	INTERNAL            = 1
)

type Keys

type Keys interface {
	// Put a bip32 key to the database
	Put(hash160 []byte, keyPath KeyPath) error

	// Import a loose private key not part of the keychain
	ImportKey(scriptAddress []byte, key *btcec.PrivateKey) error

	// Mark the script as used
	MarkKeyAsUsed(scriptAddress []byte) error

	// Fetch the last index for the given key purpose
	// The bool should state whether the key has been used or not
	GetLastKeyIndex(purpose KeyPurpose) (int, bool, error)

	// Returns the first unused path for the given purpose
	GetPathForKey(scriptAddress []byte) (KeyPath, error)

	// Returns an imported private key given a script address
	GetKey(scriptAddress []byte) (*btcec.PrivateKey, error)

	// Returns all imported keys
	GetImported() ([]*btcec.PrivateKey, error)

	// Get a list of unused key indexes for the given purpose
	GetUnused(purpose KeyPurpose) ([]int, error)

	// Fetch all key paths
	GetAll() ([]KeyPath, error)

	// Get the number of unused keys following the last used key
	// for each key purpose.
	GetLookaheadWindows() map[KeyPurpose]int
}

Keys provides a database interface for the wallet to save key material, track used keys, and manage the look ahead window.

type Signature

type Signature struct {
	InputIndex uint32
	Signature  []byte
}

This object contains a single signature for a multisig transaction. InputIndex specifies the index for which this signature applies.

type StatusCode

type StatusCode string

type Stxo

type Stxo struct {
	// When it used to be a UTXO
	Utxo Utxo

	// The height at which it met its demise
	SpendHeight int32

	// The tx that consumed it
	SpendTxid chainhash.Hash
}

func (*Stxo) IsEqual

func (stxo *Stxo) IsEqual(alt *Stxo) bool

type Stxos

type Stxos interface {
	// Put a stxo to the database
	Put(stxo Stxo) error

	// Fetch all stxos from the db
	GetAll() ([]Stxo, error)

	// Delete a stxo from the db
	Delete(stxo Stxo) error
}

type TransactionCallback

type TransactionCallback struct {
	Txid      string
	Outputs   []TransactionOutput
	Inputs    []TransactionInput
	Height    int32
	Timestamp time.Time
	Value     int64
	WatchOnly bool
	BlockTime time.Time
}

This callback is passed to any registered transaction listeners when a transaction is detected for the wallet.

type TransactionInput

type TransactionInput struct {
	OutpointHash  []byte
	OutpointIndex uint32
	LinkedAddress btc.Address
	Value         int64
	OrderID       string
}

type TransactionOutput

type TransactionOutput struct {
	Address btc.Address
	Value   int64
	Index   uint32
	OrderID string
}

type TransactionRecord

type TransactionRecord struct {
	Txid      string
	Index     uint32
	Value     int64
	Address   string
	Spent     bool
	Timestamp time.Time
}

OpenBazaar uses p2sh addresses for escrow. This object can be used to store a record of a transaction going into or out of such an address. Incoming transactions should have a positive value and be market as spent when the UXTO is spent. Outgoing transactions should have a negative value. The spent field isn't relevant for outgoing transactions.

type Txn

type Txn struct {
	// Transaction ID
	Txid string

	// The value relevant to the wallet
	Value int64

	// The height at which it was mined
	Height int32

	// The time the transaction was first seen
	Timestamp time.Time

	// This transaction only involves a watch only address
	WatchOnly bool

	// The number of confirmations on a transaction. This does not need to be saved in
	// the database but should be calculated when the Transactions() method is called.
	Confirmations int64

	// The state of the transaction (confirmed, unconfirmed, dead, etc). Implementations
	// have some flexibility in describing their transactions. Like confirmations, this
	// is best calculated when the Transactions() method is called.
	Status StatusCode

	// If the Status is Error the ErrorMessage should describe the problem
	ErrorMessage string

	// Raw transaction bytes
	Bytes []byte
}

type Txns

type Txns interface {
	// Put a new transaction to the database
	Put(raw []byte, txid string, value, height int, timestamp time.Time, watchOnly bool) error

	// Fetch a tx and it's metadata given a hash
	Get(txid chainhash.Hash) (Txn, error)

	// Fetch all transactions from the db
	GetAll(includeWatchOnly bool) ([]Txn, error)

	// Update the height of a transaction
	UpdateHeight(txid chainhash.Hash, height int, timestamp time.Time) error

	// Delete a transactions from the db
	Delete(txid *chainhash.Hash) error
}

type Utxo

type Utxo struct {
	// Previous txid and output index
	Op wire.OutPoint

	// Block height where this tx was confirmed, 0 for unconfirmed
	AtHeight int32

	// The higher the better
	Value int64

	// Output script
	ScriptPubkey []byte

	// If true this utxo will not be selected for spending. The primary
	// purpose is track multisig UTXOs which must have separate handling
	// to spend.
	WatchOnly bool

	// add by zou
	Lock bool
}

func (*Utxo) IsEqual

func (utxo *Utxo) IsEqual(alt *Utxo) bool

type Utxos

type Utxos interface {
	// Put a utxo to the database
	Put(utxo Utxo) error

	// Fetch all utxos from the db
	GetAll() ([]Utxo, error)

	// Make a utxo unspendable
	SetWatchOnly(utxo Utxo) error

	// Delete a utxo from the db
	Delete(utxo Utxo) error

	// add by zou
	Lock(utxo Utxo) error

	// add by zou
	Unlock(op wire.OutPoint) error
}

type Wallet

type Wallet interface {
	// contains filtered or unexported methods
}

1) The buyer clicks a button to place an order with a vendor. In addition to populating the order with all the relevant information, the buyer's node calls the `GenerateMultisigScript` interface method to generate an address and redeem script that is unique for the order. The order is then sent over to the vendor for evaluation.

2) The vendor receives the order, takes his public key as well as the key provided by the buyer and moderator and likewise calls `GenerateMultisigScript` and compares the returned address and redeem script to those provide by the buyer in the order to make sure the buyer provided valid information. He then sends a message to the buyer notifying that he has accepted the order.

3) The buyer can then either send funds into the multisig address using an external wallet or if he wishes to use the built-in wallet, he calls the `Spend` interface method and provides the multisig address as the destination.

4) After the buyer receives the goods he clicks the complete order button in the UI to leave a review and release the funds to the vendor. His node calls the `CreateMultisigSignature` interface method to generate a signature for the transaction releasing the funds. The signature is sent over to the vendor along with his review.

5) The vendor receives the review and the signature then calls `CreateMultisigSignature` himself to generate his signature on the transaction. We now have the two signatures necessary to release the funds. The vendor then calls the `Multisign` interface method and includes both signatures. The multisign function combines all the signatures into one valid transaction then broadcasts it to the network.

The above example is only one possible order flow. There are other variants based on whether or not the vendor is online or offline and whether or not the buyer is doing a direct payment or escrowed payment.

type WalletMustManuallyAssociateTransactionToOrder

type WalletMustManuallyAssociateTransactionToOrder interface {
	// AssociateOrderToTransaction must be called for wallets which implement it to support
	// wallet implementations which are not able to generate unique Addresses on a per-Order
	// basis. It should be called as soon as the wallet transaction and referenceID are both
	// known by the openbazaar-go node (which should be reported from the buyer to the vendor).
	AssociateTransactionToOrder(txid chainhash.Hash, referenceID string) error
}

WalletMustManuallyAssociateTransactionToOrder MUST be checked for by openbazaar-go to ensure that wallets which require manual association between transactions and orders are properly associated. If the interface is supported, AssociateTransactionToOrder must be called as early as is reasonable to ensure proper reporting of payment.

type WatchedScripts

type WatchedScripts interface {
	// Add a script to watch
	Put(scriptPubKey []byte) error

	// Return all watched scripts
	GetAll() ([][]byte, error)

	// Delete a watched script
	Delete(scriptPubKey []byte) error
}