# @automerge/automerge-subduction

> Wasm bindings for syncing Automerge documents via Subduction

Latest version **0.22.0** (published 2026-11-03) · MIT OR Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @automerge/automerge-subduction
pnpm add @automerge/automerge-subduction
yarn add @automerge/automerge-subduction
bun add @automerge/automerge-subduction
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; large bundle; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.22.0 |
| Published | 2026-11-03 |
| First published | 2026-02-27 |
| Weekly downloads | 0 |
| License | MIT OR Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 264 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 133 |
| Author | Alex Good |
| Maintainers | pvh, martinkl, orionhenry, memorythought, expede, jtfmumm-dev |
| Keywords | automerge, crdt, subduction, sync, wasm |

## Links

- npm: https://www.npmjs.com/package/@automerge/automerge-subduction
- Repository: https://github.com/inkandswitch/subduction
- Issues: https://github.com/inkandswitch/subduction/issues
- npm.io page: https://npm.io/package/@automerge/automerge-subduction

## Alternatives

- [promise-throttle](https://npm.io/package/promise-throttle.md) — 44.2K weekly downloads
- [@commercetools/sync-actions](https://npm.io/package/@commercetools/sync-actions.md) — 25.1K weekly downloads
- [cwait](https://npm.io/package/cwait.md) — 21.4K weekly downloads
- [@ledgerhq/hw-app-cosmos](https://npm.io/package/@ledgerhq/hw-app-cosmos.md) — 4.2K weekly downloads
- [@financial-times/o-loading](https://npm.io/package/@financial-times/o-loading.md) — 2.8K weekly downloads

## Recent versions

- 0.22.0 (latest) — 2026-11-03
- 0.21.0 — 2026-10-22
- 0.20.2 — 2026-10-13
- 0.20.1 — 2026-10-13
- 0.20.0 — 2026-10-13
- 0.19.0 — 2026-10-07
- 0.17.2 — 2026-09-13
- 0.16.1 — 2026-07-30
- 0.16.0 — 2026-06-18
- 0.15.0 — 2026-06-09
- 0.14.0 — 2026-06-04
- 0.13.0 — 2026-05-20
- 0.12.1 — 2026-05-14
- 0.12.0 — 2026-05-13
- 0.11.0 — 2026-05-07
- … 15 more at https://npm.io/package/@automerge/automerge-subduction/versions

## README

# Subduction

[![Build](https://github.com/inkandswitch/subduction/actions/workflows/build.yml/badge.svg)](https://github.com/inkandswitch/subduction/actions/workflows/build.yml)
[![Tests](https://github.com/inkandswitch/subduction/actions/workflows/test-host.yml/badge.svg)](https://github.com/inkandswitch/subduction/actions/workflows/test-host.yml)
[![Wasm Tests](https://github.com/inkandswitch/subduction/actions/workflows/test-wasm.yml/badge.svg)](https://github.com/inkandswitch/subduction/actions/workflows/test-wasm.yml)
[![License](https://img.shields.io/badge/License-MIT_OR_Apache_2.0-blue.svg)](LICENSE-APACHE)

> [!CAUTION]
> This is an early release preview. It has a very unstable API. No guarantees are given. DO NOT use for production use cases at this time. USE AT YOUR OWN RISK.

**Subduction** is a peer-to-peer synchronization protocol and implementation for [CRDTs]. It enables efficient synchronization of encrypted, partitioned data between peers without requiring a central server.

## Features

- **Efficient Sync Protocol**: Uses [Sedimentree] for history sharding, diffing, and efficient incremental synchronization
- **Encryption-Friendly**: Designed to work with encrypted data partitions without requiring decryption during sync
- **No Central Server**: True peer-to-peer synchronization via pluggable transports (WebSocket, HTTP long-poll, Iroh/QUIC)
- **Multi-Platform**: Runs on native Rust, WebAssembly (browser & Node.js), and provides a CLI tool
- **Automerge Integration**: While not the only data that can be synced via Subduction, [Automerge] was the original target.

## Documentation

The [`design/`](./design/) directory contains protocol design documents including message formats, threat model, and so on.

## Architecture

Subduction is organized as a Rust workspace with multiple crates:

```mermaid
graph TD
    subgraph Core
        sedimentree_core
        subduction_crypto
        subduction_core
    end

    subgraph Storage
        sedimentree_fs_storage
    end

    subgraph Transport
        subduction_http_longpoll
        subduction_hyper
        subduction_iroh
        subduction_websocket
    end

    subgraph Integrations
        subduction_keyhive
        subduction_keyhive_policy
    end

    subgraph Wasm
        sedimentree_wasm
        subduction_wasm
        automerge_subduction_wasm
    end

    subduction_cli

    sedimentree_core --> subduction_crypto
    subduction_crypto --> subduction_core

    subduction_core --> sedimentree_fs_storage
    subduction_core --> subduction_http_longpoll
    subduction_core --> subduction_iroh
    subduction_core --> subduction_websocket
    subduction_core --> subduction_keyhive_policy
    subduction_hyper -.->|hands over a WebSocketStream; not a dependency| subduction_websocket

    subduction_core --> sedimentree_wasm
    subduction_core --> subduction_wasm
    sedimentree_wasm --> subduction_wasm

    subduction_wasm --> automerge_subduction_wasm
    sedimentree_wasm --> automerge_subduction_wasm

    subduction_http_longpoll --> subduction_cli
    subduction_iroh --> subduction_cli
    subduction_websocket --> subduction_cli
    sedimentree_fs_storage --> subduction_cli
```

| Crate                      | Description                                                                            |
|----------------------------|----------------------------------------------------------------------------------------|
| `sedimentree_core`         | The core data partitioning scheme that enables efficient metadata-based synchronization |
| `sedimentree_fs_storage`   | Filesystem-based persistent storage for Sedimentree                                    |
| `subduction_crypto`        | Cryptographic types: signed payloads and verification witnesses                        |
| `subduction_core`          | The main synchronization protocol implementation                                       |
| `subduction_http_longpoll` | HTTP long-poll transport for restricted network environments                           |
| `subduction_hyper`         | WebSocket upgrades for servers built on hyper (axum, tower, raw hyper)                |
| `subduction_iroh`          | Iroh (QUIC) transport for direct peer-to-peer connections                              |
| `subduction_websocket`     | WebSocket transport layer for peer-to-peer connections                                 |
| [`subduction_tokio`](subduction_tokio/README.md) | Owned Tokio clients, erased transport connectors, and supervised reconnection |

### Platform Bindings

| Crate                       | Description                                                |
|-----------------------------|------------------------------------------------------------|
| `sedimentree_wasm`          | WebAssembly bindings for Sedimentree                       |
| `subduction_wasm`           | WebAssembly bindings for browser and Node.js environments  |
| `automerge_subduction_wasm` | Wasm bindings for Automerge + Subduction (full sync stack) |

### Integrations

| Crate                       | Description                                            |
|-----------------------------|--------------------------------------------------------|
| `subduction_keyhive`        | Keyhive integration types                              |
| `subduction_keyhive_policy` | Keyhive-based authorization policy for connections     |

### Tools

| Crate            | Description                                                      |
|------------------|------------------------------------------------------------------|
| `subduction_cli` | Command-line tool for running Subduction servers and purging data |

## Sedimentree

[Sedimentree][sedimentree-design] is a novel data structure for organizing encrypted data into hierarchical layers (strata). Each layer contains metadata (hashes) that represent fragments of a larger file or log. This enables:

1. **Efficient Diffing**: Compare metadata to determine which fragments need synchronization
2. **Privacy**: Sync without exposing plaintext data
3. **Incremental Updates**: Only transfer changed fragments

Sedimentree uses a depth-based partitioning scheme where fragments are organized by the number of leading zero bytes in their hashes, creating natural hierarchical layers.

## Quick Start

### Using Nix ❄️ 

If you use Nix, the Subduction server is wrapped in a flake:

```bash
# Run the server directly
nix run github:inkandswitch/subduction -- server --socket 0.0.0.0:8080

# Install to your profile
nix profile install github:inkandswitch/subduction
```

The flake also provides NixOS and Home Manager modules for running Subduction as a system service:

```nix
{
  inputs.subduction.url = "github:inkandswitch/subduction";

  outputs = { nixpkgs, subduction, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      modules = [
        subduction.nixosModules.default
        {
          services.subduction.server.enable = true;
        }
      ];
    };
  };
}
```

See the [CLI README] for full configuration options including Home Manager and reverse proxy setup.

### Prerequisites

- Rust 1.91 or later
- For Wasm development: [wasm-pack]
- For browser testing: Node.js 22+ and pnpm

### Building

Build all workspace crates:

```bash
cargo build --release
```

Build Wasm packages:

```bash
cd subduction_wasm
pnpm install
pnpm build
```

### Running Tests

Run all Rust tests:

```bash
cargo test
```

Run Wasm browser tests:

```bash
cd subduction_wasm
pnpm install
npx playwright install
npx playwright test
```

### Using the CLI

Start a WebSocket server:

```bash
cargo run --release -p subduction_cli -- server --socket 127.0.0.1:8080
```

## Usage Examples

### Rust

```rust
use subduction_core::Subduction;
use subduction_core::storage::MemoryStorage;

// Create a Subduction instance with in-memory storage
let storage = MemoryStorage::new();
let subduction = Subduction::new(storage);

// Connect to peers, sync data...
```

### WebAssembly (Browser)

```typescript
import * as subduction from '@automerge/subduction';

const syncer = new subduction.Subduction({
  signer: await subduction.createWebCryptoSigner(),
  storage: subduction.createMemoryStorage(),
});
try {
  // Discovery authenticates the server without pinning an expected identity.
  // Use connect(url, expectedPeerIdHex) when its identity is known in advance.
  const peerId = await syncer.connectDiscover('ws://localhost:8080');
  console.log(peerId); // Canonical 64-character hex string, not a wrapper.
  // Publish plain { head, parents, blob } records and consume plain events.
} finally {
  try { await syncer.close(); } finally { syncer.free(); }
}
```

## Development

### Project Structure

```
subduction/
├── sedimentree_core/           # Core Sedimentree data structure
├── sedimentree_fs_storage/     # Filesystem storage for Sedimentree
├── sedimentree_wasm/           # Wasm bindings for Sedimentree
├── subduction_crypto/          # Signed payloads and verification witnesses
├── subduction_core/            # Sync protocol implementation
├── subduction_http_longpoll/   # HTTP long-poll transport
├── subduction_hyper/           # WebSocket upgrades for hyper servers
├── subduction_iroh/            # Iroh (QUIC) transport
├── subduction_websocket/       # WebSocket transport
├── subduction_wasm/            # Wasm bindings for Subduction
├── subduction_cli/             # CLI server and data management
├── subduction_keyhive/         # Keyhive integration types
├── subduction_keyhive_policy/  # Keyhive authorization policy
├── automerge_subduction_ingest/ # CLI to ingest Automerge documents into Subduction
└── automerge_subduction_wasm/  # Wasm wrapper for the full Automerge + Subduction stack
```

### Testing

The project uses several testing strategies:

| Strategy             | Description                                                     |
|----------------------|-----------------------------------------------------------------|
| Unit Tests           | Standard `cargo test` for Rust code                             |
| Property-based Tests | [`bolero`] for fuzz testing                                     |
| E2E Tests            | Playwright tests for Wasm bindings (see `subduction_wasm/e2e/`) |
| Integration Tests    | Transport connection tests (WebSocket, HTTP long-poll, Iroh)   |

<!-- Internal Links -->

[CLI README]: ./subduction_cli/README.md#running-as-a-system-service
[Sedimentree]: ./sedimentree_core

<!-- External Links -->

[Automerge]: https://automerge.org/
[`bolero`]: https://github.com/camshaft/bolero
[CRDTs]: https://crdt.tech/
[Ink & Switch]: https://www.inkandswitch.com/
[sedimentree-design]: https://github.com/inkandswitch/keyhive/blob/main/design/sedimentree.md
[wasm-pack]: https://rustwasm.github.io/wasm-pack/

---
_Source: https://npm.io/package/@automerge/automerge-subduction · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
