stx2btc 0.2.0

A tool for converting STX addresses to BTC addresses
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

# stx2btc

A example Rust library for converting between Stacks (STX) and Bitcoin (BTC) native SegWit addresses.

## WARNING

This library is only a proof concept example. Do not use in production.

## Features

- Convert Stacks addresses to Bitcoin native SegWit addresses (P2WPKH)
- Convert Bitcoin native SegWit addresses back to Stacks addresses (P2WPKH only)
- Maintains the same underlying HASH160 between address formats
- Only supports mainnet addresses

## Usage

### Basic Rust Usage

```rust
use stx2btc::{stx2btc, btc2stx};

let stx_address = "SP2V0G568F20Q1XCRT43XX8Q32V2DPMMYFHHBD8PP";
let btc_address = stx2btc(stx_address).unwrap();
println!("{}", btc_address); // bc1qkcypfjrcs9c0txx3ql029cckcnd498nuvl6wpy

let back_to_stx = btc2stx(&btc_address).unwrap();
println!("{}", back_to_stx); // SP2V0G568F20Q1XCRT43XX8Q32V2DPMMYFHHBD8PP
```

## Swift Bindings

This crate includes Swift bindings generated using [UniFFI](https://mozilla.github.io/uniffi-rs/). The bindings allow you to use the library from Swift/iOS applications.

**Note**: Bindings are not included in the repository and must be generated locally.

### Generating Swift Bindings

#### Quick commands (recommended):

Using cargo aliases:
```bash
cargo build-libs && cargo swift-bindings
```

Or using [just](https://github.com/casey/just) (install with `cargo install just`):
```bash
just swift
```

#### Manual command (if needed):
```bash
# Build the library (creates both libstx2btc.dylib and libstx2btc.a)
cargo build --release

# Generate Swift bindings (uses .dylib for introspection, but bindings work with both .dylib and .a)
cargo run --bin uniffi-bindgen generate --library target/release/libstx2btc.dylib --language swift --out-dir bindings --no-format
```

This will create the `bindings/` directory with the Swift files.

**Note**: The binding generation uses the `.dylib` file to introspect the interface, but the generated Swift bindings work with both the dynamic library (`.dylib`) and static library (`.a`) - you choose which to link at build time in Xcode.

### Using in Swift

The generated Swift bindings are located in the `bindings/` directory. You can integrate them into your iOS/macOS project:

#### Option 1: Using static library (recommended for most cases)
Works on both macOS and iOS:
1. Copy `stx2btc.swift`, `stx2btcFFI.h`, and `stx2btcFFI.modulemap` to your Xcode project
2. Copy the `libstx2btc.a` static library to your project
3. Link the static library in your Xcode project settings
4. Use the functions in your Swift code

#### Option 2: Using dynamic library (macOS only)
For macOS development/testing when you want smaller binaries:
1. Copy `stx2btc.swift`, `stx2btcFFI.h`, and `stx2btcFFI.modulemap` to your Xcode project
2. Copy the `libstx2btc.dylib` library to your project
3. Use the functions in your Swift code

**Note**: iOS requires the static library (`.a`) for App Store distribution, but macOS can use either.

```swift
import Foundation

do {
    let btcAddress = try stx2btc(stxAddress: "SP2V0G568F20Q1XCRT43XX8Q32V2DPMMYFHHBD8PP")
    print(btcAddress) // bc1qkcypfjrcs9c0txx3ql029cckcnd498nuvl6wpy
    
    let backToStx = try btc2stx(btcAddress: btcAddress)
    print(backToStx) // SP2V0G568F20Q1XCRT43XX8Q32V2DPMMYFHHBD8PP
} catch {
    print("Conversion error: \(error)")
}
```

### Error Handling

The Swift bindings include proper error handling with the `ConversionError` enum:

```swift
enum ConversionError: Error {
    case SegwitDecode(String)
    case UnsupportedVersion
    case SegwitEncode(String)
}
```

## Other Language Bindings (Untested)

UniFFI supports generating bindings for additional languages including kotlin, python and ruby. These are available but **untested**:

### Quick commands:
```bash
# Using cargo aliases
cargo kotlin-bindings  # Kotlin/Android
cargo python-bindings  # Python
cargo ruby-bindings    # Ruby

# Using just
just kotlin   # Kotlin/Android
just python   # Python  
just ruby     # Ruby
just all      # All languages (Swift, Kotlin, Python, Ruby)
```

See the [UniFFI documentation](https://mozilla.github.io/uniffi-rs/) for more details on supported languages and usage.