# SDKs and libraries

Every piece below is open source under Apache-2.0, in the
[open-standards repository](https://git.transaction.science/Transaction-Science/open-standards),
and builds from it. The [libraries page](/libraries/) lists each with its continuous
integration and source.

## The command line, `wai`

| Command | What it does |
|---|---|
| `wai hello` | WAI's four steps (name, dispatch, rebuild, receipt) on a sample |
| `wai create <dir> --template <name>` | A project from one of the [examples](/docs/examples/); `wai create --list` names them |
| `wai dev` | A relay, a room service and your page on one loopback origin; `--check` checks each piece |
| `wai verify <dir>` | Every receipt index and conformance result under a directory, checked offline |
| `wai breaking --against <git-ref>` | What a change [breaks](/docs/breaking/) against a ref: wire, record and API |
| `wai conform <kind> --suite <suite> --impl <command or URL>` | A [conformance corpus](/docs/conform/) run against an implementation, the result a signed record |
| `wai inspect`, `wrap`, `unwrap` | Read an envelope; carry any registered capability's bytes in one, or take them out |
| `wai encode`, `decode` | The mandatory floor (PNG, FLAC, zstd) in the prebuilt build; every standard codec in a build with the `codecs` feature |
| `wai capabilities`, `registry export` | The capability registry |

A project made by `wai create` holds a `wai.json`: the template it came from, and what
`wai dev` runs in it (the page it serves, the kind of room). A flag on the command line wins
over it.

## Rust: the `wai` crate

The reference implementation, `wai/wai-rs`, as a library. Each part of the standard is a
cargo feature, so an application builds what it uses:

| Feature | What it adds |
|---|---|
| (none) | The envelope, the manifest, dispatch, the capability registry |
| `floor` | The mandatory floor decoded with no system library: PNG and FLAC in pure Rust, zstd from its reference source |
| `quickstart` | The floor, and the receipt checks of `wai hello` and `wai verify` |
| `codecs` (the default) | Every standard codec of the recommended set, through the codec libraries the system has |
| `live_room`, `live_events`, `live_compose` | A live room's descriptor, grants, events and composition, and their verification |
| `receipt_claims`, `http` | Receipts and claims, and receipts over HTTP |

Use it from the repository, as a git dependency:

```toml
[dependencies]
wai = { git = "https://git.transaction.science/Transaction-Science/open-standards", default-features = false, features = ["quickstart"] }
```

The [verify-receipts](/docs/examples/#verify-receipts) example does exactly this.

## In the browser: the room client

The room client is the page a browser loads to join a room: it makes the participant's key in
the tab, asks the room service for a grant, connects to the relay over the relay's WebSocket
binding on its own origin, signs what it publishes into receipts, and checks every object it
receives before it decodes it. `wai dev` serves it at `/room/`; the prebuilt archive holds it in
`share/wai/web/`. Its two WebAssembly builds come from the repository:

- `joule-moq-web`: MOQT, the receipts a publisher signs and a subscriber checks, and, in a build
  of its own, the member of an end-to-end encrypted room;
- `wai-live-web`: the room's records, layout and mixer, events and captions.

The simplest use is a frame on a page of your own, at `/room/?service=/room-api` on the page's
origin, as the [video-room](/docs/examples/#video-room) example does. The room client refuses a
room service on another origin, which is why `wai dev` serves the three on one.

## Native: Apple platforms and Android

The native sinks put WAI on the path of the platform's own player: the player is not changed,
and the sink verifies each playlist against its receipt and each object against the hash its
name states, withholds what does not verify, signs an acknowledgement of everything received,
and signs a bundle for the stream's owner at the end of the session.

- **Apple platforms** (`wai/wai-sink-swift`, Swift): `WaiPlayerSession` around an `AVPlayer`,
  for phones, tablets, televisions and desktops. Build its library once with
  `scripts/build-xcframework.sh`. The [apple-app](/docs/examples/#apple-app) example is a
  SwiftUI app on it.
- **Android** (`wai/wai-sink-android`, Kotlin): the same calls, `WaiSink` on the host JVM and,
  in its library for Android, `WaiPlayerSession` around the player. The
  [android-app](/docs/examples/#android-app) example runs its Kotlin API.

Both call one C interface, the one any other language can call.

## The C interface

`wai-rs` builds as `libwai` (a shared and a static library) with a C header,
`wai-rs/include/wai.h`: envelopes, the codecs a build holds, and the native sink's calls.
Bindings for any language call into it.

## Independent verifiers

Beside each part of the standard, a verifier in Python's standard library, written from the
specification's text and sharing no code with the reference implementation, checks its
conformance corpus; several also check a single record a deployment kept. The
[verify-receipts](/docs/examples/#verify-receipts) example shows the pattern on delivery
receipts.