Skip to content

Latest commit

 

History

History
260 lines (190 loc) · 19.9 KB

README.md

File metadata and controls

260 lines (190 loc) · 19.9 KB

SPV Wallet: Go Client

Release Build Status Report codecov Mergify Status

Go Gitpod Ready-to-Code standard-readme compliant Makefile Included


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:

Documentation

View the generated documentation

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

GoDoc

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

License