SPV Wallet: Go Client

Table of Contents

1. Requirements and Compatibility
2. Quick start
3. Documentation
4. Testing and Development Standards
5. Examples
6. License

Requirements and Compatibility

Instalation:

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

Requirements

• Go Version: The spv-wallet-go-client requires Go version 1.22.5 or a later supported release of Go. Ensure your Go environment meets this requirement before using the client.

Compatibility and Support

Deprecation Notice

The client does not support the following:

• Admin and non-admin old endpoints of the SPV Wallet API based on the /v1/ prefix.
• Deprecated methods for building query parameters for HTTP requests.

Current Compatibility

The client is designed for full compatibility with the newer /api/v1/ endpoints exposed by the SPV Wallet API. It focuses on aligning with the latest standards and structure provided by the API.

API Admin Endpoints Compatibility

Access Keys API

HTTP Method	Endpoint	Action	Support Status	API Code	Pagination
GET	/api/v1/admin/users/keys	Search access keys	✅	API	✅

Contacts API

HTTP Method	Endpoint	Action	Support Status	API Code	Pagination
GET	/api/v1/admin/contacts	Search contacts	✅	API	✅
POST	/api/v1/admin/contacts/confirmations	Confirm contact	✅	API	❌
PUT	/api/v1/admin/contacts/{id}	Update contact	✅	API	❌
DELETE	/api/v1/admin/contacts/{id}	Delete contact	✅	API	❌
POST	/api/v1/admin/contacts/{paymail}	Create contact	✅	API	❌

Invitations API

HTTP Method	Endpoint	Action	Support Status	API Code	Pagination
POST	/api/v1/admin/invitations/{id}	Accept invitation	✅	API	❌
DELETE	/api/v1/admin/invitations/{id}	Reject invitation	✅	API	❌

Paymails API

HTTP Method	Endpoint	Action	Support Status	API Code	Pagination
GET	/api/v1/admin/paymails	Search paymails	✅	API	✅
POST	/api/v1/admin/paymails	Create paymail	✅	API	❌
GET	/api/v1/admin/paymails/{id}	Retrieve paymail	✅	API	❌
DELETE	/api/v1/admin/paymails/{id}	Delete paymail	✅	API	❌

Stats API

HTTP Method	Endpoint	Action	Support Status	API Code	Pagination
GET	/api/v1/admin/stats	Retrieve stats	✅	API	✅

Status API

HTTP Method	Endpoint	Action	Support Status	API Code	Pagination
GET	/api/v1/admin/status	Retrieve status	✅	API	❌

Transactions API

HTTP Method	Endpoint	Action	Support Status	API Code	Pagination
GET	/api/v1/admin/transactions	Search transactions	✅	API	✅
GET	/api/v1/admin/transactions/{id}	Retrieve transaction	✅	API	❌

UTXOs API

HTTP Method	Endpoint	Action	Support Status	API Code	Pagination
GET	/api/v1/admin/utxos	Search UTXOs	✅	API	✅

Webhooks API

HTTP Method	Endpoint	Action	Support Status	API Code	Pagination
GET	/api/v1/admin/webhooks/subscriptions	Subscribe to webhook	✅	API	❌
DELETE	/api/v1/admin/webhooks/subscriptions	Unsubscribe webhook	✅	API	❌

XPubs API

HTTP Method	Endpoint	Action	Support Status	API Code	Pagination
GET	/api/v1/admin/users	Search XPubs	✅	API	✅
POST	/api/v1/admin/users	Create XPub	✅	API	❌

API Non-Admin Endpoints Compatibility

Access Keys API

HTTP Method	Endpoint	Action	Support Status	API Code	Pagination
GET	/api/v1/users/current/keys	Search access keys	✅	API	✅
POST	/api/v1/users/current/keys	Create access key	✅	API	❌
GET	/api/v1/users/current/keys/{id}	Retrieve access key	✅	API	❌
DELETE	/api/v1/users/current/keys/{id}	Revoke access key	✅	API	❌

Contacts API

HTTP Method	Endpoint	Action	Support Status	API Code	Pagination
GET	/api/v1/contacts	Search contacts	✅	API	✅
GET	/api/v1/contacts/{paymail}	Retrieve contact	✅	API	❌
PUT	/api/v1/contacts/{paymail}	Upsert contact	✅	API	❌
DELETE	/api/v1/contacts/{paymail}	Remove contact	✅	API	❌
POST	/api/v1/contacts/{paymail}	Confirm contact	✅	API	❌
DELETE	/api/v1/contacts/{paymail}	Unconfirm contact	✅	API	❌

Invitations API

HTTP Method	Endpoint	Action	Support Status	API Code	Pagination
POST	/api/v1/invitations/{paymail}/contacts	Accept invitation	✅	API	❌
DELETE	/api/v1/invitations/{paymail}	Reject invitation	✅	API	❌

Merkle Roots API

HTTP Method	Endpoint	Action	Support Status	API Code	Pagination
GET	/api/v1/merkleroots	Search Merkle roots	✅	API	❌

Paymails API

HTTP Method	Endpoint	Action	Support Status	API Code	Pagination
GET	/api/v1/paymails	Search paymails	✅	API	✅

Transactions API

HTTP Method	Endpoint	Action	Support Status	API Code	Pagination
GET	/api/v1/transactions	Search transactions	✅	API	✅
POST	/api/v1/transactions	Record transaction	✅	API	❌
POST	/api/v1/transactions/drafts	Draft transaction	✅	API	❌
GET	/api/v1/transactions/{id}	Retrieve transaction	✅	API	❌
PATCH	/api/v1/transactions/{id}	Update transaction	✅	API	❌

UTXOs API

HTTP Method	Endpoint	Action	Support Status	API Code	Pagination
GET	/api/v1/utxos	Search UTXOs	✅	API	❌

XPubs API

HTTP Method	Endpoint	Action	Support Status	API Code	Pagination
GET	/api/v1/users/current	Retrieve current user info	✅	API	❌
PATCH	/api/v1/users/current	Update current user info	✅	API	❌

Feature Updates

While the client strives to support the latest API features, there may be a delay in fully integrating new functionalities. If you encounter any issues or have questions:

• Refer to the official documentation.
• Reach out for support to ensure a smooth development experience.

Quick start

The implementation enforces separation of concerns by isolating admin and non-admin APIs, requiring separate initialization for their respective clients. This ensures clarity and modularity when utilizing the exposed functionality.

UserAPI Initialization Methods:

1. NewUserAPIWithAccessKey

• Description: Initializes a UserAPI instance using an access key for authentication.
• Note: Requests made with this instance will be securely signed, ensuring integrity and authenticity.

2. NewUserAPIWithXPriv

• Description: Initializes a UserAPI instance using an extended private key (xPriv) for authentication.
• Note: Requests made with this instance will also be securely signed.
• Recommendation: This option offers a high level of security, making it a preferred choice alongside the access key option.

3. NewUserAPIWithXPub

• Description: Initializes a UserAPI instance using an extended public key (xPub).
• Note: Requests made with this instance will not be signed.
• Security Advisory: For enhanced security, it is strongly recommended to use either NewUserAPIWithAccessKey or NewUserAPIWithXPriv instead, as unsigned requests may be less secure.

AdminAPI Initialization Methods:

1. NewAdminAPIWithXPriv

• Description: Initializes a AdminAPI instance using an extended private key (xPriv) for authentication.
• Note: Requests made with this instance will be securely signed, ensuring integrity and authenticity.

2. NewAdminAPIWithXPub

• Description: Initializes a AdminAPI instance using an extended public key (xPub).
• Note: Requests made with this instance will not be signed.
• Security Advisory: For enhanced security, it is strongly recommended to use either NewAdminAPIWithXPrivinstead, as unsigned requests may be less secure.

Code snippets:

• AdminAPI example
• UserAPI example

Documentation

View the generated documentation

For in-depth information and guidance, please refer to the SPV Wallet Documentation.

Testing and Development Standards

The current implementation includes comprehensive support for:

• Unit Tests: To validate individual components and ensure they work as expected in isolation.
• Regression Tests: To verify compatibility with the latest released version of the SPV Wallet API and to prevent unintended functionality breaks.

These tests ensure a stable and reliable integration with the SPV Wallet API, maintaining high-quality code and robust functionality.

Commands

Run all tests (including integration tests)

make test

Run tests (excluding integration tests)

make test-short

Development Guidelines

Each new proposed functionality must adhere to the following principles:

1. Code of Conduct: Contributions should align with the repository's code of conduct, fostering a positive and collaborative environment.
2. Repository Standards: Proposals and implementations should strictly follow the coding standards, conventions, and best practices outlined in the repository documentation.

By adhering to these guidelines, contributors can ensure that their changes are consistent, maintainable, and compatible with the SPV Wallet API.

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