feat(c32): implement C32 encoding and address

- Add C32Encode and C32Decode functions for Crockford base32 encoding
- Implement DecodeC32Address for parsing human-readable Stacks addresses
- Add SerializeAddress and DeserializeAddress for binary address representation
- Include unit tests for C32 decoding and both address formats

Author: CyrusVorwald

pkg/c32/c32.go

@@ -0,0 +1,114 @@
+package c32
+
+import (
+	"encoding/base32"
+	"errors"
+	"fmt"
+	"math/big"
+	"strings"
+
+	"github.com/icon-project/stacks-go-sdk/pkg/stacks"
+)
+
+var crockfordAlphabet = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+func C32Encode(input []byte) string {
+	encoder := base32.NewEncoding(crockfordAlphabet).WithPadding(base32.NoPadding)
+	return encoder.EncodeToString(input)
+}
+
+func C32Decode(input string) ([]byte, error) {
+	input = strings.ToUpper(strings.ReplaceAll(input, "-", ""))
+	input = strings.ReplaceAll(input, "O", "0")
+	input = strings.ReplaceAll(input, "I", "1")
+	input = strings.ReplaceAll(input, "L", "1")
+
+	bi := big.NewInt(0)
+	for _, char := range input {
+		bi.Mul(bi, big.NewInt(32))
+		index := strings.IndexRune(crockfordAlphabet, char)
+		if index == -1 {
+			return nil, fmt.Errorf("invalid character: %c", char)
+		}
+		bi.Add(bi, big.NewInt(int64(index)))
+	}
+
+	bytes := bi.Bytes()
+
+	for len(bytes) > 0 && bytes[0] == 0 {
+		bytes = bytes[1:]
+	}
+
+	return bytes, nil
+}
+
+func DecodeC32Address(address string) (version byte, hash160 [20]byte, err error) {
+	if len(address) < 5 || address[0] != 'S' {
+		return 0, [20]byte{}, fmt.Errorf("invalid C32 address: must start with 'S' and be at least 5 characters long")
+	}
+
+	versionChar := address[1]
+	version = byte(strings.IndexRune(crockfordAlphabet, rune(versionChar)))
+
+	decoded, err := C32Decode(address[2:])
+	if err != nil {
+		return 0, [20]byte{}, fmt.Errorf("failed to decode address: %v", err)
+	}
+
+	if len(decoded) != 24 { // 20 bytes hash160 + 4 bytes checksum
+		return 0, [20]byte{}, fmt.Errorf("invalid decoded length: expected 24, got %d", len(decoded))
+	}
+
+	copy(hash160[:], decoded[:20])
+
+	return version, hash160, nil
+}
+
+func SerializeAddress(address string) ([]byte, error) {
+	if len(address) != 1+20*2 { // 'S' + version + 40 hex chars
+		return nil, fmt.Errorf("invalid address length: %d", len(address))
+	}
+
+	var version byte
+	switch address[0] {
+	case 'S':
+		version = 22 // Mainnet single-sig
+	case 'T':
+		version = 26 // Testnet single-sig
+	default:
+		return nil, fmt.Errorf("invalid address version: %c", address[0])
+	}
+
+	hashBytes, err := C32Decode(address[1:])
+	if err != nil {
+		return nil, fmt.Errorf("invalid address hash: %v", err)
+	}
+
+	result := make([]byte, 1+len(hashBytes))
+	result[0] = version
+	copy(result[1:], hashBytes)
+
+	return result, nil
+}
+
+func DeserializeAddress(data []byte) (string, int, error) {
+	if len(data) < 1+stacks.AddressHashLength {
+		return "", 0, errors.New("insufficient data for address")
+	}
+
+	version := stacks.AddressVersion(data[0])
+	var prefix string
+	switch version {
+	case stacks.AddressVersionMainnetSingleSig:
+		prefix = "S"
+	case stacks.AddressVersionTestnetSingleSig:
+		prefix = "T"
+	default:
+		return "", 0, fmt.Errorf("invalid address version: %d", version)
+	}
+
+	c32hash := C32Encode(data[1 : 1+stacks.AddressHashLength+5])
+	address := fmt.Sprintf("%s%s", prefix, c32hash)
+
+	return address, 1 + stacks.AddressHashLength + 5, nil
+}

pkg/c32/c32_test.go

@@ -0,0 +1,88 @@
+package c32
+
+import (
+	"encoding/hex"
+	"reflect"
+	"testing"
+)
+
+func TestCrockfordDecode(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    string
+		expected string
+		wantErr  bool
+	}{
+		{
+			name:     "Decode 'hello world'",
+			input:    "38CNP6RVS0EXQQ4V34",
+			expected: "68656c6c6f20776f726c64",
+			wantErr:  false,
+		},
+		{
+			name:     "Decode 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM'",
+			input:    "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM",
+			expected: "19d06d78de7b0625dfbfc16c3a8a5735f6dc3dc3f2ce35687e14",
+			wantErr:  false,
+		},
+		{
+			name:     "Decode 'SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7'",
+			input:    "SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7",
+			expected: "19b0a46ff88886c2ef9762d970b4d2c63678835bd39d71b4ba47",
+			wantErr:  false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			decoded, err := C32Decode(tt.input)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("CrockfordDecode() error = %v, wantErr %v", err, tt.wantErr)
+				return
+			}
+
+			gotHex := hex.EncodeToString(decoded)
+
+			if !reflect.DeepEqual(gotHex, tt.expected) {
+				t.Errorf("CrockfordDecode() = %v, want %v", gotHex, tt.expected)
+			}
+		})
+	}
+}
+
+func TestDecodeC32Address(t *testing.T) {
+	tests := []struct {
+		name         string
+		input        string
+		expectedVer  byte
+		expectedHash string
+		wantErr      bool
+	}{
+		{
+			name:         "Decode Stacks address",
+			input:        "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM",
+			expectedVer:  26,
+			expectedHash: "6d78de7b0625dfbfc16c3a8a5735f6dc3dc3f2ce",
+			wantErr:      false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			version, hash160, err := DecodeC32Address(tt.input)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("DecodeC32Address() error = %v, wantErr %v", err, tt.wantErr)
+				return
+			}
+
+			if version != tt.expectedVer {
+				t.Errorf("DecodeC32Address() version = %v, want %v", version, tt.expectedVer)
+			}
+
+			gotHash := hex.EncodeToString(hash160[:])
+			if gotHash != tt.expectedHash {
+				t.Errorf("DecodeC32Address() hash160 = %v, want %v", gotHash, tt.expectedHash)
+			}
+		})
+	}
+}