✉️  go-paymail

Paymail toolkit for Go with full‑stack client and server support.

CI / CD		Quality
Security		Community

Project Navigation

📦 Installation	🧪 Examples & Tests	📚 Documentation
🤝 Contributing	🛠️ Code Standards	⚡ Benchmarks
🤖 AI Compliance	📝 License	👥 Maintainers

📦 Installation

go-paymail requires a supported release of Go.

go get -u github.com/bsv-blockchain/go-paymail

📚 Documentation

• API Reference – Dive into the godocs at pkg.go.dev/github.com/bsv-blockchain/go-paymail
• Usage Examples – Browse practical patterns either the examples directory or the example tests
• Benchmarks – Check the latest numbers in the benchmark results

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)
  • Example Showing Capabilities
  • Example Showing PKI
  • Example Verifying a PubKey
  • Example Address Resolution
  • Example Getting a P2P Payment Destination
  • Example Receiving a P2P Transaction
• Paymail Utilities (handy methods)
  • Sanitize & Validate Paymail Addresses
  • Sign & Verify Sender Request

Development Build Commands

Get the MAGE-X build tool for development:

go install github.com/mrz1836/mage-x/cmd/magex@latest

View all build commands

magex help

Repository Features

• Continuous Integration on Autopilot with GitHub Actions – every push is built, tested, and reported in minutes.
• Pull‑Request Flow That Merges Itself thanks to auto‑merge and hands‑free Dependabot auto‑merge.
• One‑Command Builds powered by battle‑tested MAGE-X targets for linting, testing, releases, and more.
• First‑Class Dependency Management using native Go Modules.
• Uniform Code Style via gofumpt plus zero‑noise linting with golangci‑lint.
• Confidence‑Boosting Tests with testify, the Go race detector, crystal‑clear HTML coverage snapshots, and automatic uploads to Codecov.
• Hands‑Free Releases delivered by GoReleaser whenever you create a new Tag.
• Relentless Dependency & Vulnerability Scans via Dependabot, Nancy and govulncheck.
• Security Posture by Default with CodeQL, OpenSSF Scorecard and secret‑leak detection via gitleaks.
• Automatic Syndication to pkg.go.dev on every release for instant godoc visibility.
• Polished Community Experience using rich templates for Issues & PRs.
• All the Right Meta Files (LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SUPPORT.md, SECURITY.md) pre‑filled and ready.
• Code Ownership clarified through a CODEOWNERS file, keeping reviews fast and focused.
• Zero‑Noise Dev Environments with tuned editor settings (.editorconfig) plus curated ignore files for VS Code, Docker, and Git.
• Label Sync Magic: your repo labels stay in lock‑step with .github/labels.yml.
• Friendly First PR Workflow – newcomers get a warm welcome thanks to a dedicated workflow.
• Standards‑Compliant Docs adhering to the standard‑readme spec.
• Instant Cloud Workspaces via Gitpod – spin up a fully configured dev environment with automatic linting and tests.
• Out‑of‑the‑Box VS Code Happiness with a preconfigured Go workspace and .vscode folder with all the right settings.
• Optional Release Broadcasts to your community via Slack, Discord, or Twitter – plug in your webhook.
• AI Compliance Playbook – machine‑readable guidelines (AGENTS.md, CLAUDE.md, .cursorrules, sweep.yaml) keep ChatGPT, Claude, Cursor & Sweep aligned with your repo's rules.
• Go-Pre-commit System - High-performance Go-native pre-commit hooks with 17x faster execution—run the same formatting, linting, and tests before every commit, just like CI.
• Zero Python Dependencies - Pure Go implementation with environment-based configuration via .env.base.
• DevContainers for Instant Onboarding – Launch a ready-to-code environment in seconds with VS Code DevContainers and the included .devcontainer.json config.

Library Deployment

This project uses goreleaser for streamlined binary and library deployment to GitHub. To get started, install it via:

brew install goreleaser

The release process is defined in the .goreleaser.yml configuration file.

Then create and push a new Git tag using:

magex version:bump push=true bump=patch branch=main

This process ensures consistent, repeatable releases with properly versioned artifacts and citation metadata.

Pre-commit Hooks

Set up the Go-Pre-commit System to run the same formatting, linting, and tests defined in AGENTS.md before every commit:

go install github.com/mrz1836/go-pre-commit/cmd/go-pre-commit@latest
go-pre-commit install

The system is configured via .env.base and can be customized using also using .env.custom and provides 17x faster execution than traditional Python-based pre-commit hooks. See the complete documentation for details.

GitHub Workflows

🎛️ The Workflow Control Center

All GitHub Actions workflows in this repository are powered by a single configuration files – your one-stop shop for tweaking CI/CD behavior without touching a single YAML file! 🎯

Configuration Files:

• .env.base – Default configuration that works for most Go projects
• .env.custom – Optional project-specific overrides

This magical file controls everything from:

• ⚙️ Go version matrix (test on multiple versions or just one)
• 🏃 Runner selection (Ubuntu or macOS, your wallet decides)
• 🔬 Feature toggles (coverage, fuzzing, linting, race detection, benchmarks)
• 🛡️ Security tool versions (gitleaks, nancy, govulncheck)
• 🤖 Auto-merge behaviors (how aggressive should the bots be?)
• 🏷️ PR management rules (size labels, auto-assignment, welcome messages)

Workflow Name	Description
auto-merge-on-approval.yml	Automatically merges PRs after approval and all required checks, following strict rules.
codeql-analysis.yml	Analyzes code for security vulnerabilities using GitHub CodeQL.
dependabot-auto-merge.yml	Automatically merges Dependabot PRs that meet all requirements.
fortress.yml	Runs the GoFortress security and testing workflow, including linting, testing, releasing, and vulnerability checks.
pull-request-management.yml	Labels PRs by branch prefix, assigns a default user if none is assigned, and welcomes new contributors with a comment.
scorecard.yml	Runs OpenSSF Scorecard to assess supply chain security.
stale.yml	Warns about (and optionally closes) inactive issues and PRs on a schedule or manual trigger.
sync-labels.yml	Keeps GitHub labels in sync with the declarative manifest at .github/labels.yml.

Updating Dependencies

To update all dependencies (Go modules, linters, and related tools), run:

magex deps:update

This command ensures all dependencies are brought up to date in a single step, including Go modules and any tools managed by MAGE-X. It is the recommended way to keep your development environment and CI in sync with the latest versions.

🧪 Examples & Tests

All unit tests and examples run via GitHub Actions and use Go version 1.24.x. View the configuration file.

Run all tests (fast):

magex test

Run all tests with race detector (slower):

magex test:race

⚡ Benchmarks

Run the Go benchmarks:

magex bench

Benchmark Results

Benchmark	Iterations	ns/op	B/op	allocs/op
Validate SRV Record	4,516,506	26.49	24	1
Capabilities Has	3,920,778	30.30	0	0
Capabilities Get Bool	3,938,580	30.27	0	0
Capabilities Get String	3,416,118	34.53	0	0
Convert Handle	1,938,082	61.95	24	2
Validate Timestamp	984,312	118.1	0	0
BRFC Spec Generate	568,420	196.9	144	4
BRFC Spec Validate	615,147	200.6	144	4
Get SRV Record	405,182	286.4	144	8
Validate Paymail	394,790	306.2	0	0
Validate Domain	375,542	307.7	113	3
Sanitize Paymail	157,504	703.0	317	9
Validate And Sanitize Paymail	121,256	1,001	346	10
Get Public Profile	26,770	4,378	4,944	54
Get PKI	27,373	4,487	4,928	55
Add Invite Request	24,337	4,772	5,091	54
Resolve Address	22,069	5,352	4,922	64
Get Outputs Template	21,830	5,367	4,971	63
Get Capabilities	22,478	5,414	5,421	70
Verify Pub Key	21,445	5,646	5,281	56
Send P2P Transaction	20,475	5,657	5,726	62
Get P2P Payment Destination	13,077	7,855	6,391	115
Default Client Options	3,102	39,799	13,976	152
New Client	2,960	41,008	15,840	174
Load BRFCs	2,949	41,832	14,704	169
Sender Request Verify	518	230,894	4,388	115
Sender Request Sign	356	337,052	9,757	171
Check DNSSEC	1	266,799,625	55,840	539
Check SSL	1	388,776,125	856,032	8,190

These benchmarks reflect fast, allocation-free lookups for most retrieval functions, ensuring optimal performance in production environments. Performance benchmarks for the core functions in this library, executed on an Apple M1 Max (ARM64).

🛠️ Code Standards

Read more about this Go project's code standards.

🤖 AI Compliance

This project documents expectations for AI assistants using a few dedicated files:

• AGENTS.md — canonical rules for coding style, workflows, and pull requests used by Codex.
• CLAUDE.md — quick checklist for the Claude agent.
• .cursorrules — machine-readable subset of the policies for Cursor and similar tools.
• sweep.yaml — rules for Sweep, a tool for code review and pull request management.

Edit AGENTS.md first when adjusting these policies, and keep the other files in sync within the same pull request.

👥 Maintainers

MrZ	Siggi

🤝 Contributing

View the contributing guidelines and please follow the code of conduct.

How can I help?

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬.

📝 License