# README
go-paymail
Paymail client & server library for Golang
Table of Contents
- Installation
- Documentation
- Examples & Tests
- Benchmarks
- Code Standards
- Usage
- Maintainers
- Contributing
- License
Installation
go-paymail requires a supported release of Go.
go get -u github.com/tonicpow/go-paymail
Documentation
View the generated documentation
Features
- Paymail Client (outgoing requests to other providers)
- Use your own custom Resty HTTP client
- Customize the client options
- Use your own custom net.Resolver
- Full network support:
mainnet,testnet,STN - Get & Validate SRV records
- Check SSL Certificates
- Check & Validate DNSSEC
- Generate, Validate & Load Additional BRFC Specifications
- Fetch, Get and Has Capabilities
- Get Public Key Information - PKI
- Basic Address Resolution
- Verify PubKey & Handle
- Get Public Profile
- P2P Payment Destination
- P2P Send Transaction
- Paymail Server (basic example for hosting your own paymail server)
- Paymail Utilities (handy methods)
Package Dependencies
Client Packages:
- BitcoinSchema/go-bitcoin
- go-resty/resty
- jarcoal/httpmock
- libsv/go-bk
- libsv/go-bt
- miekg/dns
- mrz1836/go-sanitize
- mrz1836/go-validate
Server Packages:
Library Deployment
goreleaser for easy binary or library deployment to GitHub and can be installed via: brew install goreleaser.
The .goreleaser.yml file is used to configure goreleaser.
Use make release-snap to create a snapshot version of the release, and finally make release to ship to production.
Makefile Commands
View all makefile commands
make help
List of all current commands:
all Runs multiple commands
clean Remove previous builds and any test cache 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-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-linter Update the golangci-lint package (macOS only)
vet Run the Go vet application
Examples & Tests
All unit tests and examples run via GitHub Actions and uses Go version 1.19.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.
Usage
Checkout all the client examples or server examples!
Maintainers
 |
|---|
| MrZ |
Contributing
View the contributing guidelines and follow the code of conduct.
How can I help?
All kinds of contributions are welcome :raised_hands:! The most basic way to show your support is to star :star2: the project, or to raise issues :speech_balloon:. You can also support this project by becoming a sponsor on GitHub :clap: or by making a bitcoin donation to ensure this journey continues indefinitely! :rocket:
License
# Packages
No description provided by the author
Package interfaces is the custom interface.
Package server is the server package for Paymail.
Package tester is the testing package.
# Functions
ConvertHandle will convert a $handle or 1handle to a paymail address
For HandCash: $handle = [email protected] or [email protected] For RelayX: 1handle = [email protected].
LoadBRFCs will load the known "default" specifications into structs from JSON
additionSpecifications is appended to the default specs BRFCKnownSpecifications is a local constant of JSON to preload known BRFC ids.
NewClient creates a new client for all paymail requests
If no options are given, it will use the defaultClientOptions() If no client is supplied it will use a default Resty HTTP client.
SanitizePaymail will take an input and return the sanitized version ([email protected])
Alias is the first part of the address (alias @) Domain is the lowercase sanitized version (domain.tld) Address is the full sanitized paymail address ([email protected]).
UserAgent will return the default user agent string.
ValidateAndSanitisePaymail will take a paymail address or handle, convert to a paymail address if it's a handle, validate that address, then sanitize it if it is valid.
ValidateDomain will do a basic validation on the domain format
This will not check to see if the domain is an active paymail provider This will not check DNS records to make sure the domain is active.
ValidatePaymail will do a basic validation on the paymail format (email address format)
This will not check to see if the paymail address is active via the provider.
ValidateTimestamp will test if the timestamp is valid
This is used to validate the "dt" parameter in resolve_address.go Allowing 3 minutes before/after for.
Version will return the version of the library.
WithBRFCSpecs allows custom specs to be supplied to extend or replace the defaults.
WithDNSPort can be supplied with a custom dns port to perform SRV checks on.
WithDNSTimeout can be supplied to overwrite the default dns srv check timeout.
WithHTTPTimeout can be supplied to adjust the default http client timeouts.
WithNameServer can be supplied to overwrite the default name server used to resolve srv requests.
WithNameServerNetwork can overwrite the default network protocol to use.
WithNetwork will set the client's operational network to one provided.
WithRequestTracing will enable tracing.
WithRetryCount will overwrite the default retry count for http requests.
WithSSLDeadline will overwrite the default ssl deadline.
WithSSLTimeout will overwrite the default ssl timeout.
WithUserAgent will overwrite the default useragent.
# Constants
more info: http://bsvalias.org/04-01-basic-address-resolution.html.
BRFCKnownSpecifications is a running list of all known BRFC specifications
JSON file was converted into a go:var for binary shipment Add your spec at runtime using LoadBRFCs() Add your spec to the list below: https://github.com/tonicpow/go-paymail/issues/new/choose.
more info: https://docs.moneybutton.com/docs/paymail/paymail-07-p2p-payment-destination.html.
nolint:gosec // more info: https://docs.moneybutton.com/docs/paymail/paymail-11-p2p-payment-destination-tokens.html.
more info: https://docs.moneybutton.com/docs/paymail/paymail-06-p2p-transactions.html.
more info: http://bsvalias.org/04-01-basic-address-resolution.html.
more info: http://bsvalias.org/04-04-payto-protocol-prefix.html.
more info: http://bsvalias.org/03-public-key-infrastructure.html.
more info: http://bsvalias.org/03-public-key-infrastructure.html.
more info: https://github.com/bitcoin-sv-specs/brfc-paymail/pull/7/files.
more info: http://bsvalias.org/04-03-receiver-approvals.html.
more info: http://bsvalias.org/04-02-sender-validation.html.
more info: https://docs.moneybutton.com/docs/paymail/paymail-08-asset-information.html.
more info: https://docs.moneybutton.com/docs/sfp/paymail-10-sfp-authorise.html.
more info: https://docs.moneybutton.com/docs/sfp/paymail-09-sfp-build.html.
more info: http://bsvalias.org/05-verify-public-key-owner.html.
Default version number for bsvalias.
Default port (from specs).
Default priority (from specs).
Default protocol (from specs).
Default service name (from specs).
Default weight (from specs).
Mainnet bitcoin main network.
Required length for a valid PubKey (pki).
STN bitcoin stress test network.
Testnet bitcoin test network.
# Structs
AddressInformation is an internal struct for paymail addresses and their corresponding information.
BRFCSpec is a full BRFC specification document
See more: http://bsvalias.org/01-brfc-specifications.html.
CapabilitiesPayload is the actual payload response.
CapabilitiesResponse is the full response returned.
No description provided by the author
No description provided by the author
DNSCheckResult struct is returned for the DNS check.
P2PMetaData is an object containing data associated with the P2P transaction.
P2PTransaction is the request body for the P2P transaction request.
P2PTransactionPayload is payload from the request.
P2PTransactionResponse is the response to the request.
PaymentDestinationPayload is the payload from the response
The reference is unique for the payment destination request.
PaymentDestinationResponse is the response from the GetP2PPaymentDestination() request
The reference is unique for the payment destination request.
PaymentOutput is returned inside the payment destination response
There can be several outputs in one response based on the amount of satoshis being transferred and the rules in place by the Paymail provider.
PaymentRequest is the request body for the P2P payment request.
PKIPayload is the payload from the response.
PKIResponse is the result returned.
PublicProfilePayload is the payload from the response.
PublicProfileResponse is the result returned from GetPublicProfile().
ResolutionPayload is the payload from the response.
ResolutionResponse is the response from the ResolveAddress() request.
SanitisedPaymail contains elements of a sanitized paymail address.
SenderRequest is the request body for the basic address resolution
This is required to make a basic resolution request, and Dt and SenderHandle are required.
ServerError is the standard error response from a paymail server.
StandardResponse is the standard fields returned on all responses.
VerificationPayload is the payload from the response.
VerificationResponse is the result returned from the VerifyPubKey() request.
# Interfaces
ClientInterface is the Paymail client interface.