models

README

SPV Wallet: Models

Table of Contents

• About
• Installation
• Documentation
• Usage
  • Examples & Tests
  • Benchmarks
• Code Standards
• Contributing
• License

About

SPV Wallet internal models & structs

Installation

go-template requires a supported release of Go.

go get -u github.com/bitcoin-sv/spv-wallet-models

Documentation

View the generated documentation

Repository Features

This repository was created using MrZ's go-template

Built-in Features

• Continuous integration via GitHub Actions
• Build automation via Make
• Dependency management using Go Modules
• Code formatting using gofumpt and linting with golangci-lint and yamllint
• Unit testing with testify, race detector, code coverage HTML report and Codecov report
• Releasing using GoReleaser on new Tag
• Dependency scanning and updating thanks to Dependabot and Nancy
• Security code analysis using CodeQL Action
• Automatic syndication to pkg.go.dev on every release
• Generic templates for Issues and Pull Requests in GitHub
• All standard GitHub files such as LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md
• Code ownership configuration for GitHub
• All your ignore files for vs-code, docker and git
• Automatic sync for labels into GitHub using a predefined configuration
• Built-in powerful merging rules using Mergify
• Welcome new contributors on their first Pull-Request
• Follows the standard-readme specification
• Visual Studio Code configuration with Go
• (Optional) Slack, Discord or Twitter announcements on new GitHub Releases
• (Optional) Easily add contributors in any Issue or Pull-Request

Package Dependencies

• stretchr/testify

Library Deployment

Releases are automatically created when you create a new git tag!

If you want to manually make releases, please install GoReleaser:

goreleaser for easy binary or library deployment to GitHub and can be installed:

• using make: make install-releaser
• using brew: brew install goreleaser

The .goreleaser.yml file is used to configure goreleaser.

Automatic Releases on Tag Creation (recommended)

Automatic releases via GitHub Actions from creating a new tag:

make tag version=1.2.3

Manual Releases (optional)

Use make release-snap to create a snapshot version of the release, and finally make release to ship to production (manually).

Makefile Commands

View all makefile commands

make help

List of all current commands:

all                           Runs multiple commands
clean                         Remove previous builds and any cached data
clean-mods                    Remove all the Go mod cache
coverage                      Shows the test coverage
diff                          Show the git diff
generate                      Runs the go generate command in the base of the repo
godocs                        Sync the latest tag with GoDocs
help                          Show this help message
install                       Install the application
install-all-contributors      Installs all contributors locally
install-go                    Install the application (Using Native Go)
install-releaser              Install the GoReleaser application
lint                          Run the golangci-lint application (install if not found)
release                       Full production release (creates release in GitHub)
release                       Runs common.release then runs godocs
release-snap                  Test the full release (build binaries)
release-test                  Full production test release (everything except deploy)
replace-version               Replaces the version in HTML/JS (pre-deploy)
tag                           Generate a new tag and push (tag version=0.0.0)
tag-remove                    Remove a tag if found (tag-remove version=0.0.0)
tag-update                    Update an existing tag to current commit (tag-update version=0.0.0)
test                          Runs lint and ALL tests
test-ci                       Runs all tests via CI (exports coverage)
test-ci-no-race               Runs all tests via CI (no race) (exports coverage)
test-ci-short                 Runs unit tests via CI (exports coverage)
test-no-lint                  Runs just tests
test-short                    Runs vet, lint and tests (excludes integration tests)
test-unit                     Runs tests and outputs coverage
uninstall                     Uninstall the application (and remove files)
update-contributors           Regenerates the contributors html/list
update-linter                 Update the golangci-lint package (macOS only)
vet                           Run the Go vet application

Usage

Examples & Tests

All unit tests run via GitHub Actions and uses Go version 1.18.x. View the configuration file.

Run all tests (including integration tests)

make test

Run tests (excluding integration tests)

make test-short

Benchmarks

Run the Go benchmarks:

make bench

Code Standards

Read more about this Go project's code standards.

Contributing

All kinds of contributions are welcome!
To get started, take a look at code standards.
View the contributing guidelines and follow the code of conduct.

License

Documentation

Overview

Package models contains all models (contracts) between spv-wallet api and other spv-wallet solutions

Index

• Constants
• type AccessKey
• type AdminStats
• type AuthPayload
• type BlockHeader
• type Destination
• type DraftTransaction
• type FeeUnit
• type MapProtocol
• type Metadata
• type OpReturn
• type PaymailAddress
• type PaymailP4
• type ScriptOutput
• type SyncConfig
• type SyncResult
• type SyncResults
• type SyncTransaction
• type Transaction
• type TransactionConfig
• type TransactionInput
• type TransactionOutput
• type Utxo
• type UtxoPointer
• type Xpub
• type XpubMetadata

Examples

• AccessKey

Constants

const (
	// AuthHeader is the header to use for authentication (raw xPub)
	AuthHeader = "x-auth-xpub"

	// AuthAccessKey is the header to use for access key authentication (access public key)
	AuthAccessKey = "x-auth-key"

	// AuthSignature is the given signature (body + timestamp)
	AuthSignature = "x-auth-signature"

	// AuthHeaderHash hash of the body coming from the request
	AuthHeaderHash = "x-auth-hash"

	// AuthHeaderNonce random nonce for the request
	AuthHeaderNonce = "x-auth-nonce"

	// AuthHeaderTime the time of the request, only valid for 30 seconds
	AuthHeaderTime = "x-auth-time"

	// AuthSignatureTTL is the max TTL for a signature to be valid
	AuthSignatureTTL = 20 * time.Second
)

const (
	// DraftStatusDraft is when the transaction is a draft
	DraftStatusDraft string = "draft"

	// DraftStatusCanceled is when the draft is canceled
	DraftStatusCanceled string = "canceled"

	// DraftStatusExpired is when the draft has expired
	DraftStatusExpired string = "expired"

	// DraftStatusComplete is when the draft transaction is complete
	DraftStatusComplete string = "complete"
)

Types

type AccessKey

type AccessKey struct {
	// Model is a common model that contains common fields for all models.
	common.Model

	// ID is an access key id.
	ID string `json:"id"`
	// XpubID is an access key's xpub related id.
	XpubID string `json:"xpub_id"`
	// RevokedAt is a time when access key was revoked.
	RevokedAt *time.Time `json:"revoked_at,omitempty"`
	// Key is a string representation of an access key.
	Key string `json:"key,omitempty"`
}

AccessKey is a model that represents an access key.

Example

ExampleAccessKey is an example for AccessKey model.

ac := new(AccessKey)
ac.Model.UpdatedAt = time.Now().UTC()
ac.Model.CreatedAt = time.Now().UTC()
ac.Model.DeletedAt = time.Now().UTC()
ac.XpubID = "123"
ac.ID = "123"
fmt.Printf("%s", ac.ID)

Output:

123

type AdminStats

type AdminStats struct {
	// Balance is a total balance of all xpubs.
	Balance int64 `json:"balance"`
	// Destinations is a total number of destinations.
	Destinations int64 `json:"destinations"`
	// PaymailAddresses is a total number of paymail addresses.
	PaymailAddresses int64 `json:"paymail_addresses"`
	// Transactions is a total number of committed transactions.
	Transactions int64 `json:"transactions"`
	// TransactionsPerDay is a total number of committed transactions per day.
	TransactionsPerDay map[string]interface{} `json:"transactions_per_day"`
	// Utxos is a total number of utxos.
	Utxos int64 `json:"utxos"`
	// UtxosPerType are utxos grouped by type.
	UtxosPerType map[string]interface{} `json:"utxos_per_type"`
	// Xpubs is a total number of xpubs.
	XPubs int64 `json:"xpubs"`
}

AdminStats is a model that represents admin stats.

type AuthPayload

type AuthPayload struct {
	// AuthHash is the hash of the body contents
	AuthHash string `json:"auth_hash"`
	// AuthNonce is a random string
	AuthNonce string `json:"auth_nonce"`
	// AuthTime is the current time in milliseconds
	AuthTime int64 `json:"auth_time"`
	// BodyContents is the body of the request
	BodyContents string `json:"body_contents"`
	// Signature is the signature of the body contents
	Signature string `json:"signature"`
	// XPub is the xpub of the account
	XPub string `json:"xpub"`
	// AccessKey is the access key of the account
	AccessKey string `json:"access_key"`
}

AuthPayload is the struct that is used to create the signature for the API call

type BlockHeader

type BlockHeader struct {
	// Model is a common model that contains common fields for all models.
	common.Model

	// ID is a block header id (hash).
	ID string `json:"id"`
	// Height is a block header height.
	Height uint32 `json:"height"`
	// Time is a block header time (timestamp).
	Time uint32 `json:"time"`
	// Nonce is a block header nonce.
	Nonce uint32 `json:"nonce"`
	// Version is a block header version.
	Version uint32 `json:"version"`
	// HashPreviousBlock is a block header hash of previous block.
	HashPreviousBlock string `json:"hash_previous_block"`
	// HashMerkleRoot is a block header hash merkle tree root.
	HashMerkleRoot string `json:"hash_merkle_root"`
	// Bits contains BSV block header bits no.
	Bits string `json:"bits"`
	// Synec is a time when block header was synced.
	Synced time.Time `json:"synced"`
}

BlockHeader is a model that represents a BSV block header.

type Destination

type Destination struct {
	// Model is a common model that contains common fields for all models.
	common.Model

	// ID is a destination id.
	ID string `json:"id"`
	// XpubID is a destination's xpub related id used to register destination.
	XpubID string `json:"xpub_id"`
	// LockingScript is a destination's locking script.
	LockingScript string `json:"locking_script"`
	// Type is a destination's type.
	Type string `json:"type"`
	// Chain is a destination's chain representation.
	Chain uint32 `json:"chain"`
	// Num is a destination's num representation.
	Num uint32 `json:"num"`
	// Address is a destination's address.
	Address string `json:"address"`
	// DraftID is a destination's draft id.
	DraftID string `json:"draft_id"`
	// Monitor is a time when destination was monitored.
	Monitor time.Time `json:"monitor"`
}

Destination is a model that represents a destination - registered in a spv-wallet with xpub.

type DraftTransaction

type DraftTransaction struct {
	// Model is a common model that contains common fields for all models.
	common.Model

	// ID is a draft transaction id.
	ID string `json:"id"`
	// Hex is a draft transaction hex.
	Hex string `json:"hex"`
	// XpubID is a draft transaction's xpub used to sign transaction.
	XpubID string `json:"xpub_id"`
	// ExpiresAt is a time when draft transaction expired.
	ExpiresAt time.Time `json:"expires_at"`
	// Configuration contains draft transaction configuration.
	Configuration TransactionConfig `json:"configuration"`
	// Status is a draft transaction lastly monitored status.
	Status string `json:"status"`
	// FinalTxID is a final transaction id.
	FinalTxID string `json:"final_tx_id"`
}

DraftTransaction is a model that represents a draft transaction.

type FeeUnit

type FeeUnit struct {
	// Satoshis is a fee unit satoshis amount.
	Satoshis int `json:"satoshis"`
	// Bytes is a fee unit bytes representation.
	Bytes int `json:"bytes"`
}

FeeUnit is a model that represents a fee unit (simplified version of fee unit from go-bt).

type MapProtocol

type MapProtocol struct {
	// App is a map protocol app.
	App string `json:"app,omitempty"`
	// Keys is a map protocol keys.
	Keys map[string]interface{} `json:"keys,omitempty"`
	// Type is a map protocol type.
	Type string `json:"type,omitempty"`
}

MapProtocol is a model that represents a map protocol.

type Metadata

type Metadata map[string]interface{}

Metadata is a SPV Wallet ecosystem metadata model.

type OpReturn

type OpReturn struct {
	// Hex is a full hex of op return.
	Hex string `json:"hex,omitempty"`
	// HexParts is a slice of splitted hex parts.
	HexParts []string `json:"hex_parts,omitempty"`
	// Map is a pointer to a map protocol object.
	Map *MapProtocol `json:"map,omitempty"`
	// StringParts is a slice of string parts.
	StringParts []string `json:"string_parts,omitempty"`
}

OpReturn is a model that represents a op return.

type PaymailAddress

type PaymailAddress struct {
	// Model is a common model that contains common fields for all models.
	common.Model

	// ID is a paymail address id.
	ID string `json:"id"`
	// XpubID is a paymail address's xpub related id used to register paymail address.
	XpubID string `json:"xpub_id"`
	// Alias is a paymail address's alias (first part of paymail).
	Alias string `json:"alias"`
	// Domain is a paymail address's domain (second part of paymail).
	Domain string `json:"domain"`
	// PublicName is a paymail address's public name.
	PublicName string `json:"public_name"`
	// Avatar is a paymail address's avatar.
	Avatar string `json:"avatar"`
	// ExternalXpubKey is a paymail address's external xpub key.
	ExternalXpubKey string `json:"external_xpub_key"`
}

PaymailAddress is a model that represents a paymail address.

type PaymailP4

type PaymailP4 struct {
	// Alias is a paymail p4 alias.
	Alias string `json:"alias,omitempty"`
	// Domain is a paymail p4 domain.
	Domain string `json:"domain,omitempty"`
	// FromPaymail is a paymail p4 from paymail.
	FromPaymail string `json:"from_paymail,omitempty"`
	// Note is a paymail p4 note.
	Note string `json:"note,omitempty"`
	// PubKey is a paymail p4 pub key.
	PubKey string `json:"pub_key,omitempty"`
	// ReceiveEndpoint is a paymail p4 receive endpoint.
	ReceiveEndpoint string `json:"receive_endpoint,omitempty"`
	// ReferenceID is a paymail p4 reference id.
	ReferenceID string `json:"reference_id,omitempty"`
	// ResolutionType is a paymail p4 resolution type.
	ResolutionType string `json:"resolution_type,omitempty"`
}

PaymailP4 is a model that represents a paymail p4.

type ScriptOutput

type ScriptOutput struct {
	// Address is a script output address.
	Address string `json:"address,omitempty"`
	// Satoshis is a script output satoshis.
	Satoshis uint64 `json:"satoshis,omitempty"`
	// Script is a script output script.
	Script string `json:"script"`
	// ScriptType is a script output script type.
	ScriptType string `json:"script_type"`
}

ScriptOutput is a model that represents a script output.

type SyncConfig

type SyncConfig struct {
	// Broadcast is a flag that indicates whether to broadcast transaction or not.
	Broadcast bool `json:"broadcast"`
	// BroadcastInstant is a flag that indicates whether to broadcast transaction instantly or not.
	BroadcastInstant bool `json:"broadcast_instant"`
	// PaymailP2P is a flag that indicates whether to use paymail p2p or not.
	PaymailP2P bool `json:"paymail_p2p"`
	// SyncOnChain is a flag that indicates whether to sync transaction on chain or not.
	SyncOnChain bool `json:"sync_on_chain"`
}

SyncConfig contains sync configuration flags.

type SyncResult

type SyncResult struct {
	// Action type broadcast, sync etc
	Action string `json:"action"`
	// ExecutedAt contains time when action was executed.
	ExecutedAt time.Time `json:"executed_at"`
	// Provider field is used for attempts(s).
	Provider string `json:"provider,omitempty"`
	// StatusMessage contains success or failure messages.
	StatusMessage string `json:"status_message"`
}

SyncResult is a model that represents a single sync result.

type SyncResults

type SyncResults struct {
	// LastMessage is a last message received during sync.
	LastMessage string `json:"last_message"`
	// Results is a slice of sync results.
	Results []*SyncResult `json:"results"`
}

SyncResults is a model that represents a sync results.

type SyncTransaction

type SyncTransaction struct {
	// Model is a common model that contains common fields for all models.
	common.Model

	// ID is a sync transaction id.
	ID string `json:"id"`
	// Configuration contains sync transaction configuration.
	Configuration SyncConfig `json:"configuration"`
	// LastAttempt contains last attempt time.
	LastAttempt time.Time `json:"last_attempt"`
	// Results contains sync transaction results.
	Results SyncResults `json:"results"`
	// BroadcastStatus contains broadcast status.
	BroadcastStatus string `json:"broadcast_status"`
	// P2PStatus contains p2p status.
	P2PStatus string `json:"p2p_status"`
	// SyncStatus contains sync status.
	SyncStatus string `json:"sync_status"`
}

SyncTransaction is a model that represents a sync transaction specific fields.

type Transaction

type Transaction struct {
	// Model is a common model that contains common fields for all models.
	common.Model
	// ID is a transaction id.
	ID string `json:"id"`
	// Hex is a transaction hex.
	Hex string `json:"hex"`
	// XpubInIDs is a slice of xpub input ids.
	XpubInIDs []string `json:"xpub_in_ids"`
	// XpubOutIDs is a slice of xpub output ids.
	XpubOutIDs []string `json:"xpub_out_ids"`
	// BlockHash is a block hash that transaction is in.
	BlockHash string `json:"block_hash"`
	// BlockHeight is a block height that transaction is in.
	BlockHeight uint64 `json:"block_height"`
	// Fee is a transaction fee.
	Fee uint64 `json:"fee"`
	// NumberOfInputs is a number of transaction inputs.
	NumberOfInputs uint32 `json:"number_of_inputs"`
	// NumberOfOutputs is a number of transaction outputs.
	NumberOfOutputs uint32 `json:"number_of_outputs"`
	// DraftID is a transaction related draft id.
	DraftID string `json:"draft_id"`
	// TotalValue is a total input value.
	TotalValue uint64 `json:"total_value"`
	// OutputValue is a total output value.
	OutputValue int64 `json:"output_value,omitempty"`
	// Outputs represents all spv-wallet-transaction outputs. Will be shown only for admin.
	Outputs map[string]int64 `json:"outputs,omitempty"`
	// Status is a transaction status.
	Status string `json:"status"`
	// TransactionDirection is a transaction direction (inbound/outbound).
	TransactionDirection string `json:"direction"`
}

Transaction is a model that represents a transaction.

type TransactionConfig

type TransactionConfig struct {
	// ChangeDestinations is a slice of change destinations.
	ChangeDestinations []*Destination `json:"change_destinations"`
	// ChangeStrategy is a change strategy.
	ChangeStrategy string `json:"change_destinations_strategy"`
	// ChangeMinimumSatoshis is a minimum satoshis for change.
	ChangeMinimumSatoshis uint64 `json:"change_minimum_satoshis"`
	// ChangeNumberOfDestinations is a number of change destinations.
	ChangeNumberOfDestinations int `json:"change_number_of_destinations"`
	// ChangeSatoshis is a change satoshis.
	ChangeSatoshis uint64 `json:"change_satoshis"`
	// ExpiresAt is a time when transaction expires.
	ExpiresIn time.Duration `json:"expires_in"`
	// Fee is a fee amount.
	Fee uint64 `json:"fee"`
	// FeeUnit is a pointer to a fee unit object.
	FeeUnit *FeeUnit `json:"fee_unit"`
	// FromUtxos is a slice of from utxos used to build transaction.
	FromUtxos []*UtxoPointer `json:"from_utxos"`
	// IncludeUtxos is a slice of utxos to include in transaction.
	IncludeUtxos []*UtxoPointer `json:"include_utxos"`
	// Inputs is a slice of transaction inputs.
	Inputs []*TransactionInput `json:"inputs"`
	// Outputs is a slice of transaction outputs.
	Outputs []*TransactionOutput `json:"outputs"`
	// SendAllTo is a pointer to a transaction output object.
	SendAllTo *TransactionOutput `json:"send_all_to"`
	// Sync contains sync configuration.
	Sync *SyncConfig `json:"sync"`
}

TransactionConfig is a model that represents a transaction config.

type TransactionInput

type TransactionInput struct {
	// Utxo is a pointer to a utxo object.
	Utxo `json:",inline"`
	// Destination is a pointer to a destination object.
	Destination Destination `json:"destination"`
}

TransactionInput is a model that represents a transaction input.

type TransactionOutput

type TransactionOutput struct {
	// OpReturn is a pointer to a op return object.
	OpReturn *OpReturn `json:"op_return,omitempty"`
	// PaymailP4 is a pointer to a paymail p4 object.
	PaymailP4 *PaymailP4 `json:"paymail_p4,omitempty"`
	// Satoshis is a satoshis amount.
	Satoshis uint64 `json:"satoshis"`
	// Script is a transaction output string representation of script.
	Script string `json:"script"`
	// ScriptType is a transaction output script type.
	Scripts []*ScriptOutput `json:"scripts,omitempty"`
	// To is a transaction output destination address.
	To string `json:"to"`
	// UseForChange is a flag that indicates if this output should be used for change.
	UseForChange bool `json:"use_for_change"`
}

TransactionOutput is a model that represents a transaction output.

type Utxo

type Utxo struct {
	// Model is a common model that contains common fields for all models.
	common.Model
	// UtxoPointer is a pointer to a utxo object.
	UtxoPointer `json:",inline"`

	// ID is a utxo id.
	ID string `json:"id"`
	// XpubID is a utxo related xpub id.
	XpubID string `json:"xpub_id"`
	// Satoshis is a utxo satoshis amount.
	Satoshis uint64 `json:"satoshis"`
	// ScriptPubKey is a utxo script pub key.
	ScriptPubKey string `json:"script_pub_key"`
	// Type is a utxo type.
	Type string `json:"type"`
	// DraftID is a utxo transaction related draft id.
	DraftID string `json:"draft_id"`
	// ReservedAt is a time utxo was reserved at.
	ReservedAt time.Time `json:"reserved_at"`
	// SpendingTxID is a spending transaction id - null if not spent yet.
	SpendingTxID string `json:"spending_tx_id"`
	// Transaction is a transaction pointer that utxo points to.
	Transaction *Transaction `json:"transaction"`
}

Utxo is a model that represents a utxo.

type UtxoPointer

type UtxoPointer struct {
	// TransactionID is a transaction id that utxo points to.
	TransactionID string `json:"transaction_id"`
	// OutputIndex is a output index that utxo points to.
	OutputIndex uint32 `json:"output_index"`
}

UtxoPointer is a pointer model that represents a utxo.

type Xpub

type Xpub struct {
	// Model is a common model that contains common fields for all models.
	common.Model

	// ID is a xpub id.
	ID string `json:"id"`
	// CurrentBalance is a xpub's current balance.
	CurrentBalance uint64 `json:"current_balance"`
	// NextInternalNum is a next internal num.
	NextInternalNum uint32 `json:"next_internal_num"`
	// NextExternalNum is a next external num.
	NextExternalNum uint32 `json:"next_external_num"`
}

Xpub is a model that represents a xpub.

type XpubMetadata

type XpubMetadata map[string]Metadata

XpubMetadata is a SPV Wallet ecosystem xpub metadata model.