feat(SPV-851) add Go examples aligned with js-client

examples/Makefile

@@ -0,0 +1,54 @@
+.PHONY: admin_add_user
+admin_add_user:
+	@echo "running admin_add_user..."
+	@go run ./admin_add_user/admin_add_user.go
+
+.PHONY: admin_remove_user
+admin_remove_user:
+	@echo "running admin_remove_user..."
+	@go run ./admin_remove_user/admin_remove_user.go
+
+.PHONY: create_transaction
+create_transaction:
+	@echo "running create_transaction..."
+	@go run ./create_transaction/create_transaction.go
+
+# .PHONY: custom_logger
+# custom_logger:
+# 	@echo "running custom_logger..."
+# 	@go run ./custom_logger/custom_logger.go
+
+.PHONY: generate_keys
+generate_keys:
+	@echo "running generate_keys..."
+	@go run ./generate_keys/generate_keys.go
+
+.PHONY: get_balance
+get_balance:
+	@echo "running get_balance..."
+	@go run ./get_balance/get_balance.go
+
+.PHONY: handle_exceptions
+handle_exceptions:
+	@echo "running handle_exceptions..."
+	@go run ./handle_exceptions/handle_exceptions.go
+
+.PHONY: list_transactions
+list_transactions:
+	@echo "running list_transactions..."
+	@go run ./list_transactions/list_transactions.go
+
+.PHONY: send_op_return
+send_op_return:
+	@echo "running send_op_return..."
+	@go run ./send_op_return/send_op_return.go
+
+.PHONY: xpriv_from_mnemonic
+xpriv_from_mnemonic:
+	@echo "running xpriv_from_mnemonic..."
+	@go run ./xpriv_from_mnemonic/xpriv_from_mnemonic.go
+
+.PHONY: xpub_from_xpriv
+xpub_from_xpriv:
+	@echo "running xpub_from_xpriv..."
+	@go run ./xpub_from_xpriv/xpub_from_xpriv.go

examples/README.md

@@ -0,0 +1,54 @@
+# Quick Guide how to run examples
+
+In this directory you can find examples of how to use the `spv-wallet-go-client` package.
+
+## Before you run
+
+### Pre-requisites
+
+-   You have access to the `spv-wallet` non-custodial wallet (running locally or remotely).
+-   You have installed this package on your machine (`go install` on this project's root directory).
+
+### Concerning the keys
+
+-   The `adminKey` defined in `example_keys.go` is the default one from [spv-wallet-web-backend repository](https://github.com/bitcoin-sv/spv-wallet-web-backend/blob/main/config/viper.go#L56)
+    -   If in your current `spv-wallet` instance you have a different `adminKey`, you should replace the one in `example_keys` with the one you have.
+-   The `exampleXPub` and `exampleXPriv` are just placeholders, which won't work.
+    -   You should replace them by newly generated ones using `make generate_keys`,
+    -   ... or use your actual keys if you have them (don't use the keys which are already added to another wallet).
+
+> Additionally, to make it work properly, you should adjust the `examplePaymail` to align with your `domains` configuration in the `spv-wallet` instance.
+
+## Proposed order of executing examples
+
+1. `generate_keys` - generates new keys (you can copy them to `example_keys` if you want to use them in next examples)
+2. `admin_add_user` - adds a new user (more precisely adds `exampleXPub` and then `examplePaymail` to the wallet)
+
+> To fully experience the next steps, it would be beneficial to transfer some funds to your `examplePaymail`. This ensures the examples run smoothly by demonstrating the creation of a transaction with an actual balance. You can transfer funds to your `examplePaymail` using a Bitcoin SV wallet application such as HandCash or any other that supports Paymail.
+
+3. `get_balance` - checks the balance - if you've transferred funds to your `examplePaymail`, you should see them here
+4. `create_transaction` - creates a transaction (you can adjust the `outputs` to your needs)
+5. `list_transactions` - lists all transactions and with example filtering
+6. `send_op_return` - sends an OP_RETURN transaction
+7. `admin_remove_user` - removes the user
+
+In addition to the above, there are additional examples showing how to use the client from a developer perspective:
+
+-   `handle_exceptions` - presents how to "catch" exceptions which the client can throw
+-   `custom_logger` - shows different ways you can configure (or disable) internal logger
+
+## Util examples
+
+1. `xpriv_from_mnemonic` - allows you to generate/extract an xPriv key from a mnemonic phrase. To you use it you just need to replace the `mnemonic` variable with your own mnemonic phrase.
+2. `xpub_from_xpriv` - allows you to generate an xPub key from an xPriv key. To you use it you just need to replace the `xPriv` variable with your own xPriv key.
+
+## How to run an example
+
+The examples are written in Go and can be run by:
+
+```bash
+cd examples
+make name_of_the_example
+```
+
+> See the `examples/Makefile` for the list of available examples and scripts

examples/admin_add_user/admin_add_user.go

@@ -0,0 +1,36 @@
+package main
+
+import (
+	"context"
+	"examples"
+	"fmt"
+	"os"
+
+	walletclient "github.com/bitcoin-sv/spv-wallet-go-client"
+)
+
+func main() {
+	defer examples.HandlePanic()
+
+	server := "http://localhost:3003/v1"
+
+	if examples.ExampleAdminKey == "" {
+		fmt.Println(examples.ErrMessage("adminKey"))
+		os.Exit(1)
+	}
+
+	adminClient := walletclient.NewWithAdminKey(server, examples.ExampleAdminKey)
+	ctx := context.Background()
+
+	metadata := map[string]any{"some_metadata": "example"}
+
+	newXPubRes := adminClient.AdminNewXpub(ctx, examples.ExampleXPub, metadata)
+	fmt.Println("AdminNewXpub response: ", newXPubRes)
+
+	createPaymailRes, err := adminClient.AdminCreatePaymail(ctx, examples.ExampleXPub, examples.ExamplePaymail, "Some public name", "")
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+	fmt.Println("AdminCreatePaymail response: ", createPaymailRes)
+}

examples/admin_remove_user/admin_remove_user.go

@@ -0,0 +1,26 @@
+package main
+
+import (
+	"context"
+	"examples"
+	"fmt"
+	"os"
+
+	walletclient "github.com/bitcoin-sv/spv-wallet-go-client"
+)
+
+func main() {
+	defer examples.HandlePanic()
+
+	const server = "http://localhost:3003/v1"
+
+	if examples.ExampleAdminKey == "" {
+		fmt.Println(examples.ErrMessage("adminKey"))
+		os.Exit(1)
+	}
+
+	adminClient := walletclient.NewWithAdminKey(server, examples.ExampleAdminKey)
+	ctx := context.Background()
+
+	adminClient.AdminDeletePaymail(ctx, examples.ExamplePaymail)
+}

examples/create_transaction/create_transaction.go

@@ -0,0 +1,43 @@
+package main
+
+import (
+	"context"
+	"examples"
+	"fmt"
+	"os"
+
+	walletclient "github.com/bitcoin-sv/spv-wallet-go-client"
+)
+
+func main() {
+	defer examples.HandlePanic()
+
+	const server = "http://localhost:3003/v1"
+
+	if examples.ExampleXPriv == "" {
+		fmt.Println(examples.ErrMessage("xPriv"))
+		os.Exit(1)
+	}
+
+	client := walletclient.NewWithXPriv(server, examples.ExampleXPriv)
+	ctx := context.Background()
+
+	recipient := walletclient.Recipients{To: "[email protected]", Satoshis: 1}
+	recipients := []*walletclient.Recipients{&recipient}
+	metadata := map[string]any{"some_metadata": "example"}
+
+	newTransaction, err := client.SendToRecipients(ctx, recipients, metadata)
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+	fmt.Println("SendToRecipients response: ", newTransaction)
+
+	tx, err := client.GetTransaction(ctx, newTransaction.ID)
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+	fmt.Println("GetTransaction response: ", tx)
+
+}

examples/example_keys.go

@@ -0,0 +1,11 @@
+package examples
+
+const (
+	ExampleAdminKey string = "xprv9s21ZrQH143K3CbJXirfrtpLvhT3Vgusdo8coBritQ3rcS7Jy7sxWhatuxG5h2y1Cqj8FKmPp69536gmjYRpfga2MJdsGyBsnB12E19CESK"
+
+	// you can generate new keys using `yarn generate-keys`
+	ExampleXPriv string = ""
+	ExampleXPub  string = ""
+
+	ExamplePaymail string = ""
+)

examples/generate_keys/generate_keys.go

@@ -0,0 +1,15 @@
+package main
+
+import (
+	"examples"
+	"fmt"
+)
+
+func main() {
+	keys := examples.GenerateKeys()
+	exampleXPriv := keys.XPriv()
+	exampleXPub := keys.XPub().String()
+
+	fmt.Println("exampleXPriv: ", exampleXPriv)
+	fmt.Println("exampleXPub: ", exampleXPub)
+}

examples/get_balance/get_balance.go

@@ -0,0 +1,32 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	walletclient "github.com/bitcoin-sv/spv-wallet-go-client"
+
+	"examples"
+)
+
+func main() {
+	defer examples.HandlePanic()
+
+	const server = "http://localhost:3003/v1"
+
+	if examples.ExampleXPriv == "" {
+		fmt.Println(examples.ErrMessage("xPriv"))
+		os.Exit(1)
+	}
+
+	client := walletclient.NewWithXPriv(server, examples.ExampleXPriv)
+	ctx := context.Background()
+
+	xpubInfo, err := client.GetXPub(ctx)
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+	fmt.Println("Current balance: ", xpubInfo.CurrentBalance)
+}

examples/handle_exceptions/handle_exceptions.go

@@ -0,0 +1,36 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	walletclient "github.com/bitcoin-sv/spv-wallet-go-client"
+
+	"examples"
+)
+
+func main() {
+	defer examples.HandlePanic()
+
+	const server = "http://localhost:3003/v1"
+
+	if examples.ExampleXPub == "" {
+		fmt.Println(examples.ErrMessage("xPub"))
+		os.Exit(1)
+	}
+
+	client := walletclient.NewWithXPub(server, examples.ExampleXPub)
+	ctx := context.Background()
+
+	status, err := client.AdminGetStatus(ctx)
+
+	if err != nil {
+		fmt.Println("Response status: ", err.GetStatusCode())
+		fmt.Println("Content: ", err.Error())
+
+		os.Exit(1)
+	}
+
+	fmt.Println("Status: ", status)
+}