mpay 0.1.0

Micropayments Protocol - Rust library for Web Payment Auth (IETF draft-ietf-httpauth-payment)
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
128
129
130
131
132
133
134
135
136
137
138
139

# mpay

Rust SDK for the Machine Payments Protocol (MPP) - an implementation of the ["Payment" HTTP Authentication Scheme](https://datatracker.ietf.org/doc/draft-ietf-httpauth-payment/).

## Design Principles

- **Protocol-first** — Core types (`Challenge`, `Credential`, `Receipt`) map directly to HTTP headers
- **Zero-copy parsing** — Efficient header parsing without unnecessary allocations
- **Pluggable methods** — Payment networks are feature-gated (Tempo included by default)
- **Minimal dependencies** — Core has minimal deps; features add what you need
- **Designed for extension** — `Method` and `Intent` are traits. Implement them for custom payment methods.

## Quick Start

### Parse a Challenge (Server → Client)

```rust
use mpay::Challenge;

let header = r#"Payment realm="api.example.com", id="abc123", method="tempo", intent="charge", request="eyJhbW91bnQiOiIxMDAwIn0""#;
let challenge = Challenge::from_www_authenticate(header)?;

println!("Method: {}", challenge.method);
println!("Intent: {}", challenge.intent);
```

### Create a Credential (Client → Server)

```rust
use mpay::Credential;

let credential = Credential {
    id: challenge.id.clone(),
    source: Some("did:pkh:eip155:8453:0x123...".into()),
    payload: serde_json::json!({"hash": "0xabc..."}),
};

let auth_header = credential.to_authorization();
```

### Parse a Receipt (Server → Client)

```rust
use mpay::Receipt;

let receipt = Receipt::from_payment_receipt(header)?;
assert_eq!(receipt.status, "success");
```

## API Reference

### Core

#### `Challenge`

A parsed payment challenge from a `WWW-Authenticate` header.

```rust
use mpay::Challenge;

let challenge = Challenge {
    id: "challenge-id".into(),
    method: "tempo".into(),
    intent: "charge".into(),
    request: serde_json::json!({"amount": "1000000", "asset": "0x...", "destination": "0x..."}),
};

let header = challenge.to_www_authenticate("api.example.com");
let parsed = Challenge::from_www_authenticate(&header)?;
```

#### `Credential`

The credential sent in the `Authorization` header.

```rust
use mpay::Credential;

let credential = Credential {
    id: "challenge-id".into(),
    payload: serde_json::json!({"hash": "0x..."}),
    source: Some("did:pkh:eip155:1:0x...".into()),
};

let header = credential.to_authorization();
let parsed = Credential::from_authorization(&header)?;
```

#### `Receipt`

Payment receipt returned after successful verification.

```rust
use mpay::Receipt;

let receipt = Receipt {
    status: "success".into(),
    timestamp: Some("2024-01-20T12:00:00Z".into()),
    reference: Some("0x...".into()),
};

let header = receipt.to_payment_receipt();
let parsed = Receipt::from_payment_receipt(&header)?;
```

## Install

```toml
[dependencies]
mpay = "0.1"
```

## Feature Flags

| Feature | Description |
|---------|-------------|
| `tempo` | Tempo blockchain support (default, includes `evm`) |
| `evm` | Shared EVM utilities (Address, U256, parsing) |
| `utils` | Encoding utilities (hex, base64) |

## What's NOT Included

Network registries, currency formatting, keystore management, HTTP clients, and middleware are out of scope for this library.

## Examples

See the [examples/](./examples/) directory for integration patterns with common HTTP libraries:

## Development

```bash
cargo build         # Build with default features (tempo)
cargo test          # Run tests
cargo doc --open    # Generate and view documentation
```

## License

MIT OR Apache-2.0