Merge pull request #25 from b-open-io/opl-351-docs

OPL-351 Documentation

Author: shruggr

auth/peer.go

@@ -21,10 +21,22 @@ const AUTH_PROTOCOL_ID = "authrite message signature"
 // AUTH_VERSION is the version of the auth protocol
 const AUTH_VERSION = "0.1"
 
+// OnGeneralMessageReceivedCallback is called when a general message is received from a peer.
+// The callback receives the sender's public key and the message payload.
 type OnGeneralMessageReceivedCallback func(senderPublicKey *ec.PublicKey, payload []byte) error
+
+// OnCertificateReceivedCallback is called when certificates are received from a peer.
+// The callback receives the sender's public key and the list of certificates.
 type OnCertificateReceivedCallback func(senderPublicKey *ec.PublicKey, certs []*certificates.VerifiableCertificate) error
+
+// OnCertificateRequestReceivedCallback is called when a certificate request is received from a peer.
+// The callback receives the sender's public key and the requested certificate set.
 type OnCertificateRequestReceivedCallback func(senderPublicKey *ec.PublicKey, requestedCertificates utils.RequestedCertificateSet) error
 
+// Peer represents a peer capable of performing mutual authentication.
+// It manages sessions, handles authentication handshakes, certificate requests and responses,
+// and sending and receiving general messages over a transport layer.
+// This implementation supports multiple concurrent sessions per peer identity key.
 type Peer struct {
 	sessionManager                        SessionManager
 	transport                             Transport
@@ -43,6 +55,7 @@ type Peer struct {
 	logger                 *log.Logger // Logger for debug messages
 }
 
+// PeerOptions contains configuration options for creating a new Peer instance.
 type PeerOptions struct {
 	Wallet                 wallet.Interface
 	Transport              Transport

auth/transports/simplified_http_transport.go

@@ -142,6 +142,8 @@ func (t *SimplifiedHTTPTransport) Send(ctx context.Context, message *auth.AuthMe
 	return nil
 }
 
+// GetRegisteredOnData returns the first registered callback function for handling incoming AuthMessages.
+// Returns an error if no handlers are registered.
 func (t *SimplifiedHTTPTransport) GetRegisteredOnData() (func(context.Context, *auth.AuthMessage) error, error) {
 	t.mu.Lock()
 	defer t.mu.Unlock()

auth/transports/websocket_transport.go

@@ -25,11 +25,15 @@ type WebSocketTransport struct {
 	readDeadline time.Duration
 }
 
+// WebSocketTransportOptions contains configuration options for the WebSocketTransport.
 type WebSocketTransportOptions struct {
 	BaseURL      string
 	ReadDeadline int // seconds, default 30
 }
 
+// NewWebSocketTransport creates a new WebSocket transport instance with the given options.
+// The BaseURL is required and must be a valid WebSocket URL.
+// If ReadDeadline is not specified or is zero, it defaults to 30 seconds.
 func NewWebSocketTransport(options *WebSocketTransportOptions) (*WebSocketTransport, error) {
 	if options.BaseURL == "" {
 		return nil, errors.New("BaseURL is required for WebSocket transport")

auth/types.go

@@ -196,6 +196,8 @@ type CertificateQuery struct {
 	Subject string
 }
 
+// MarshalJSON customizes the JSON marshaling for AuthMessage to ensure proper formatting
+// of identity keys, payload, and signature fields as base64-encoded strings.
 func (m *AuthMessage) MarshalJSON() ([]byte, error) {
 	type Alias AuthMessage
 
@@ -237,6 +239,8 @@ func (m *AuthMessage) MarshalJSON() ([]byte, error) {
 	})
 }
 
+// UnmarshalJSON customizes the JSON unmarshaling for AuthMessage to properly decode
+// base64-encoded fields and reconstruct the public key from the hex-encoded identity key.
 func (m *AuthMessage) UnmarshalJSON(data []byte) error {
 	type Alias AuthMessage
 

auth/utils/get_verifiable_certificates.go

@@ -20,6 +20,9 @@ type GetVerifiableCertificatesOptions struct {
 	PrivilegedReason      string
 }
 
+// GetVerifiableCertificates retrieves and prepares verifiable certificates based on the provided options.
+// It queries the wallet for certificates matching the requested types and certifiers,
+// then creates verifiable certificates with the appropriate fields revealed for the specified verifier.
 func GetVerifiableCertificates(ctx context.Context, options *GetVerifiableCertificatesOptions) ([]*certificates.VerifiableCertificate, error) {
 	if options == nil {
 		return nil, fmt.Errorf("GetVerifiableCertificatesOptions cannot be nil")

docs/README.md

@@ -0,0 +1,7 @@
+# Go Library API Documentation
+
+The documentation is split into various pages, each covering a set of related functionality. The pages are as follows:
+
+- [Concepts](./concepts/) — Covers high-level concepts and architecture of the Go SDK.
+- [Examples](./examples/) — Provides practical examples of how to use the Go SDK.
+- [Low-Level](./low-level/) — Details low-level operations and functionalities within the SDK.

docs/examples/README.md

@@ -6,5 +6,49 @@ Here, you will find a number of common usage examples for the go-sdk.
 - [Storage Downloader](./storage_downloader/storage_downloader.md) - Download files using UHRP URLs
 - [Storage Uploader](./storage_uploader/storage_uploader.md) - Upload, manage, and renew files
 
+## Keys and Addresses
+- [Address From WIF](./address_from_wif/) - Generate an address from a WIF private key.
+- [Derive Child Key](./derive_child/) - Derive a child key from a parent HD key.
+- [Generate HD Key](./generate_hd_key/) - Generate a new Hierarchical Deterministic (HD) key.
+- [HD Key From XPub](./hd_key_from_xpub/) - Create an HD key from an extended public key (xPub).
+- [Keyshares PK From Backup](./keyshares_pk_from_backup/) - Reconstruct a private key from key shares backup.
+- [Keyshares PK To Backup](./keyshares_pk_to_backup/) - Backup a private key using key shares.
+
+## Transactions
+- [Broadcaster](./broadcaster/) - Broadcast a transaction to the network.
+- [Create Simple TX](./create_simple_tx/) - Create a basic Bitcoin transaction.
+- [Create TX With Inscription](./create_tx_with_inscription/) - Create a transaction with an Ordinal inscription.
+- [Create TX With OP_RETURN](./create_tx_with_op_return/) - Create a transaction with an OP_RETURN output.
+- [Fee Modeling](./fee_modeling/) - Examples of transaction fee calculation and modeling.
+- [Validate SPV](./validate_spv/) - Validate a Simple Payment Verification (SPV) proof.
+- [Verify Beef](./verify_beef/) - Verify a B.E.E.F (Bitcoin Extended Envelope Format) transaction.
+- [Verify Transaction](./verify_transaction/) - Verify the validity of a Bitcoin transaction.
+
+## Messaging and Authentication
+- [Authenticated Messaging](./authenticated_messaging/) - Examples of authenticated messaging between parties.
+- [ECIES Electrum Binary](./ecies_electrum_binary/) - ECIES encryption/decryption compatible with Electrum (binary format).
+- [ECIES Shared](./ecies_shared/) - Elliptic Curve Integrated Encryption Scheme (ECIES) with a shared secret.
+- [ECIES Single](./ecies_single/) - ECIES for single recipient encryption/decryption.
+- [Encrypted Message](./encrypted_message/) - Send and receive encrypted messages.
+- [Identity Client](./identity_client/) - Client for interacting with identity services.
+
+## Registry
+- [Registry Register](./registry_register/) - Register data with a distributed registry.
+- [Registry Resolve](./registry_resolve/) - Resolve data from a distributed registry.
+
+## Networking
+- [Websocket Peer](./websocket_peer/) - Communicate with a Bitcoin node using WebSockets.
+
+## Cryptography
+- [AES](./aes/) - Advanced Encryption Standard (AES) examples.
+
+## Wallet
+- [Create Wallet](./create_wallet/) - Create a new wallet instance.
+- [Encrypt Data](./encrypt_data/) - Encrypt data using the wallet.
+- [Create Signature](./create_signature/) - Create a digital signature.
+- [Create HMAC](./create_hmac/) - Create an HMAC.
+- [Get Public Key](./get_public_key/) - Retrieve a public key from the wallet.
+- [HTTP Wallet](./http_wallet/) - Interact with a wallet using JSON over HTTP.
+
 ## Additional Example Documents
 - [Converting Transactions from go-bt](./GO_BT.md)

docs/examples/address_from_wif/README.md

@@ -0,0 +1,69 @@
+# Address From WIF Example
+
+This example demonstrates how to derive a Bitcoin SV address from a Wallet Import Format (WIF) private key string using the `ec` and `script` packages.
+
+## Overview
+
+The `address_from_wif` example showcases:
+1. Importing a private key from its WIF string representation using `ec.PrivateKeyFromWif`.
+2. Getting the corresponding public key from the private key using `privateKey.PubKey()`.
+3. Generating a P2PKH (Pay-to-Public-Key-Hash) address object from this public key using `script.NewAddressFromPublicKey`.
+4. Printing the serialized private key, the string representation of the derived address, and its public key hash.
+
+## Code Walkthrough
+
+### Deriving Address from WIF
+
+```go
+// Import private key from WIF string
+privKey, _ := ec.PrivateKeyFromWif("Kxfd8ABTYZHBH3y1jToJ2AUJTMVbsNaqQsrkpo9gnnc1JXfBH8mn")
+
+// Log the serialized private key (hexadecimal)
+log.Printf("Private key (hex): %x\n", privKey.Serialize())
+
+// Get the public key associated with the private key
+pubKey := privKey.PubKey()
+
+// Create a new address object from the public key
+// The 'true' argument typically indicates if it's for mainnet (compressed pubkey used for address)
+address, _ := script.NewAddressFromPublicKey(pubKey, true)
+
+// Print the address string and the underlying public key hash
+fmt.Printf("Address: %s\n", address.AddressString)
+fmt.Printf("Public Key Hash: %s\n", address.PublicKeyHash) // Or however you wish to display the hash
+```
+
+This section shows the step-by-step process:
+- `ec.PrivateKeyFromWif` parses the WIF string and returns an `*ec.PrivateKey` object.
+- `privKey.PubKey()` returns the corresponding `*ec.PublicKey`.
+- `script.NewAddressFromPublicKey(pubKey, true)` takes the public key and a boolean (often indicating network or if the key should be compressed for address generation) to produce an `*script.Address` object. This object contains the familiar base58check encoded address string and the raw public key hash.
+
+## Running the Example
+
+To run this example:
+
+```bash
+go run address_from_wif.go
+```
+The output will display the hexadecimal representation of the private key, the derived P2PKH address string, and the public key hash component of the address.
+
+**Note**:
+- The WIF string is hardcoded. In a real application, this would come from a secure source.
+- The example derives a P2PKH address, which is the most common address type.
+- The boolean argument `true` in `NewAddressFromPublicKey` typically signifies that the address should be generated for the main network, often implying the use of a compressed public key for the hash.
+
+## Integration Steps
+
+To derive an address from a WIF in your application:
+1. Obtain the WIF string for the private key.
+2. Use `priv, err := ec.PrivateKeyFromWif(wifString)` to get the private key object. Handle any errors.
+3. Get the public key: `pubKey := priv.PubKey()`.
+4. Generate the address: `addr, err := script.NewAddressFromPublicKey(pubKey, isMainnet)`, where `isMainnet` is true for mainnet addresses. Handle errors.
+5. You can then use `addr.AddressString` for display or in transactions, and `addr.PublicKeyHash` if you need the raw hash.
+
+## Additional Resources
+
+For more information, see:
+- [Package Documentation - EC primitives](https://pkg.go.dev/github.com/bsv-blockchain/go-sdk/primitives/ec)
+- [Package Documentation - Script](https://pkg.go.dev/github.com/bsv-blockchain/go-sdk/script)
+- [Generate HD Key Example](../generate_hd_key/) (for creating master keys from which WIFs can be derived)

docs/examples/aes/README.md

@@ -0,0 +1,90 @@
+# AES Encryption/Decryption Example
+
+This example demonstrates basic AES (Advanced Encryption Standard) GCM (Galois/Counter Mode) encryption and decryption using the `aesgcm` package.
+
+## Overview
+
+The `aes` example showcases:
+1. Defining a hexadecimal AES key.
+2. Encrypting a plaintext byte slice (`[]byte("0123456789abcdef")`) using `aesgcm.AESEncrypt`.
+3. Decrypting the resulting ciphertext using `aesgcm.AESDecrypt` with the same key.
+4. Printing the decrypted data.
+
+## Code Walkthrough
+
+### Encrypting and Decrypting Data
+
+```go
+package main
+
+import (
+	"encoding/hex"
+	"fmt"
+
+	aes "github.com/bsv-blockchain/go-sdk/primitives/aesgcm"
+)
+
+func main() {
+	// Define an AES key (must be 16, 24, or 32 bytes for AES-128, AES-192, or AES-256 respectively)
+	key, _ := hex.DecodeString("000102030405060708090a0b0c0d0e0f") // 16 bytes for AES-128
+
+	plaintext := []byte("0123456789abcdef")
+
+	// Encrypt the data
+	encryptedData, err := aes.AESEncrypt(plaintext, key)
+	if err != nil {
+		fmt.Println("Encryption error:", err)
+		return
+	}
+	fmt.Printf("Encrypted data (hex): %x\n", encryptedData)
+
+	// Decrypt the data
+	decryptedData, err := aes.AESDecrypt(encryptedData, key)
+	if err != nil {
+		fmt.Println("Decryption error:", err)
+		return
+	}
+	fmt.Printf("Decrypted data: %s\n", decryptedData)
+}
+```
+
+This section shows:
+- Initialization of a 16-byte AES key.
+- Encryption of a sample plaintext using `aes.AESEncrypt`. This function handles nonce generation and prepends it to the ciphertext.
+- Decryption of the ciphertext using `aes.AESDecrypt`. This function extracts the nonce from the ciphertext and performs decryption.
+
+## Running the Example
+
+To run this example:
+
+```bash
+go run aes.go
+```
+The output will show the hexadecimal representation of the encrypted data, followed by the successfully decrypted original message.
+
+**Note**:
+- The key used is hardcoded. In real applications, keys should be securely generated and managed.
+- The `aesgcm` package uses AES in GCM mode, which provides both confidentiality and authenticity.
+- The nonce is generated internally by `AESEncrypt` and prepended to the ciphertext. `AESDecrypt` expects this format.
+
+## Integration Steps
+
+To use AES GCM encryption/decryption in your application:
+
+**For Encryption:**
+1. Obtain or generate a secure AES key of appropriate length (16, 24, or 32 bytes).
+2. Call `ciphertext, err := aesgcm.AESEncrypt(plaintextBytes, key)`.
+3. Store or transmit the `ciphertext`.
+
+**For Decryption:**
+1. Obtain the same AES key used for encryption.
+2. Call `plaintextBytes, err := aesgcm.AESDecrypt(ciphertext, key)`.
+3. The `plaintextBytes` will contain the original data if decryption is successful.
+
+Ensure proper key management practices are followed.
+
+## Additional Resources
+
+For more information, see:
+- [Package Documentation - aesgcm](https://pkg.go.dev/github.com/bsv-blockchain/go-sdk/primitives/aesgcm)
+- NIST Special Publication 800-38D for GCM mode.