hop-sdk 0.1.0

# hop-sdk

Client SDK for the Polkadot HOP protocol — send and claim data through ephemeral off-chain storage on Polkadot.

HOP is an ephemeral off-chain data pool hosted by Bulletin Chain collators. The sender uploads data to a collator, signals the receiver through the statement store, and the receiver claims it directly — no on-chain transaction required.

## Quick start

```rust
use hop_sdk::{HopClient, HopEnvironment};

let client = HopClient::connect(HopEnvironment::Previewnet)?;

// Send
let data = b"hello HOP".to_vec();
let tickets = client.send(data, 1)?;

// Claim
let ticket = tickets.into_iter().next().unwrap();
let received = client.claim(ticket)?;

assert_eq!(received, b"hello HOP");
client.destroy();
```

## API overview

### `HopClient`

| Method | Description |
|---|---|
| `connect(env: HopEnvironment) -> Result<HopClient, HopError>` | Connect to a HOP network by environment name |
| `send(data: Vec<u8>, recipient_count: u32) -> Result<Vec<Arc<HopTicket>>, HopError>` | Send data into the pool (max 64 MiB). Returns one ticket per recipient. |
| `claim(ticket: Arc<HopTicket>) -> Result<Vec<u8>, HopError>` | Claim data from the pool using a ticket |
| `destroy(&self)` | Release resources held by this client |

### `HopTicket`

| Method | Description |
|---|---|
| `encode(&self) -> Vec<u8>` | Serialize to raw bytes |
| `decode(data: Vec<u8>) -> Result<HopTicket, HopError>` | Deserialize from raw bytes |

## Environments

| `HopEnvironment` | Network | Notes |
|---|---|---|
| `Local` | Local dev node | For development against a local omni-node |
| `Previewnet` | Polkadot Previewnet | For products |

Node endpoints are hardcoded per SDK release.

## Error handling

All errors are represented by the `HopError` enum:

| Variant | When |
|---|---|
| `DataTooLarge` | Data is empty or exceeds 64 MiB |
| `PoolFull` | The pool has no remaining capacity |
| `NotFound` | The requested entry does not exist in the pool |
| `InvalidTicket` | Ticket bytes are malformed or have wrong length |
| `Network` | Transport-level failure (connection refused, timeout, etc.) |
| `QuotaExceeded` | Rate or usage quota exceeded |

## UniFFI (mobile bindings)

To generate Kotlin/Swift bindings via [UniFFI](https://mozilla.github.io/uniffi-rs/), enable the `uniffi` feature:

```toml
hop-sdk = { version = "0.1", features = ["uniffi"] }
```

This is not needed for pure Rust consumers.

## Examples

See the [`examples/`](examples/) directory for complete runnable programs.

## License

Apache-2.0