Skip to content

docs: update readmes #148

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bennyhodl merged 1 commit into from
Jan 6, 2026
Merged

docs: update readmes #148

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 65 additions & 51 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,80 +1,76 @@
# Dlc Dev Kit
# DLC Dev Kit

[![Crate](https://img.shields.io/crates/v/ddk.svg?logo=rust)](https://crates.io/crates/ddk)
[![Documentation](https://img.shields.io/static/v1?logo=read-the-docs&label=docs.rs&message=ddk&color=informational)](https://docs.rs/ddk)
![Crates.io Total Downloads](https://img.shields.io/crates/d/ddk)

> :warning: `dlcdevkit` is alpha software and should not be used with real money. API is subject to change.
A ready-to-go [Discreet Log Contract](https://github.com/discreetlogcontracts/dlcspecs) node library built using [BDK](https://github.com/bitcoindevkit/bdk).

Application tooling to get started with [DLCs](https://github.com/discreetlogcontracts/dlcspecs) build with [rust-dlc](https://github.com/p2pderivatives/rust-dlc) and [bdk](https://github.com/bitcoindevkit/bdk).
DLC Dev Kit is a self-custodial DLC node in library form. Its central goal is to provide a small, simple, and straightforward interface that enables users to easily set up and run a DLC node with an integrated on-chain wallet. While minimalism is at its core, DDK aims to be sufficiently modular and configurable to be useful for a variety of use cases.

Build DLC application by plugging in your own transport, storage, and oracle clients.
## Getting Started

## Get Started

```
$ cargo add ddk
```
The primary abstraction of the library is the [`DlcDevKit`](https://docs.rs/ddk/latest/ddk/struct.DlcDevKit.html), which can be retrieved by setting up and configuring a [`Builder`](https://docs.rs/ddk/latest/ddk/builder/struct.Builder.html) to your liking and calling `finish()`. `DlcDevKit` can then be controlled via commands such as `start`, `stop`, `send_dlc_offer`, `accept_dlc_offer`, etc.

```rust
use ddk::builder::Builder;
use ddk::storage::SledStorage;
use ddk::transport::lightning::LightningTransport; // with "lightning" feature
use ddk::oracle::KormirOracleClient;
use bitcoin::Network;
use ddk::builder::{Builder, SeedConfig};
use ddk::logger::{LogLevel, Logger};
use ddk::oracle::kormir::KormirOracleClient;
use ddk::storage::sled::SledStorage;
use ddk::transport::lightning::LightningTransport;
use std::sync::Arc;

type ApplicationDdk = ddk::DlcDevKit<LightningTransport, SledStorage, KormirOracleClient>;

#[tokio::main]
fn main() {
let transport = Arc::new(LightningTransport::new([0u8;32], <port>, Network::Regtest));
let storage = Arc::new(SledStorage::new("<storage path>")?);
let oracle_client = Arc::new(KormirOracleClient::new("<oracle host>", None).await?);

let ddk: ApplicationDdk = Builder::new()
.set_seed_bytes([0u8;32])
.set_network(Network::Regtest)
.set_esplora_path("http://127.0.0.1:3000")
.set_transport(transport.clone())
.set_storage(storage.clone())
.set_oracle(oracle_client.clone())
.finish()
.expect("could not build ddk node");

ddk.start().expect("ddk could not start");
}
```
async fn main() -> Result<(), ddk::error::Error> {
let logger = Arc::new(Logger::console("ddk-example".to_string(), LogLevel::Info));

## Crates

Ready-to-go clients for developing applications:

[`ddk`](./ddk/) - DLC management with an internal BDK wallet.
let transport = Arc::new(LightningTransport::new(&[0u8; 32], 1776, logger.clone())?);
let storage = Arc::new(SledStorage::new("/tmp/ddk-example", logger.clone())?);
let oracle = Arc::new(KormirOracleClient::new("http://localhost:8082", None, logger.clone()).await?);

[`ddk-node`](./ddk-node/) - A ready-to-go node with an accompanying cli.
let mut builder: Builder<LightningTransport, SledStorage, KormirOracleClient> = Builder::new();
builder.set_seed_bytes(SeedConfig::Random)?;
builder.set_esplora_host("https://mutinynet.com/api".to_string());
builder.set_transport(transport);
builder.set_storage(storage);
builder.set_oracle(oracle);
builder.set_logger(logger);

[`payouts`](./payouts/) - Functions to build DLC contracts.
let ddk: ApplicationDdk = builder.finish().await?;

You can create a custom DDK instance by implementing the required traits for storage and transport. DDK traits are defined in [ddk/src/lib.rs](./ddk/src/lib.rs). The traits are super traits from what is required in `bdk` and `rust-dlc`.
ddk.start()?;

To quickly get started building a DDK application, there are pre-built components.
// ... open contracts, accept offers, etc.

### Storage

[`sled`](./ddk/src/storage/sled) - A simple file based storage using [sled](https://crates.io/crates/sled)
ddk.stop()?;
Ok(())
}
```

### Transport
## Modularity

[`LDK Peer Manager`](./ddk/src/transport/lightning/) - Communication over Lightning gossip using [`rust-dlc's implementation`](https://github.com/p2pderivatives/rust-dlc/blob/master/dlc-messages/src/message_handler.rs)
DDK is designed with a pluggable architecture, allowing you to choose or implement your own components:

[`nostr`](./ddk/src/transport/nostr/) - DLC communication from the [NIP-88 spec](https://github.com/nostr-protocol/nips/pull/919)
- **Transport**: Communication layer for DLC messages between peers. Implementations include Lightning Network gossip and Nostr protocol messaging.
- **Storage**: Persistence backend for contracts and wallet data. Implementations include Sled (embedded) and PostgreSQL.
- **Oracle**: External data source for contract attestations. Implementations include HTTP and Nostr-based oracle clients.

### Oracle Clients
You can create a custom DDK instance by implementing the required traits defined in [`ddk/src/lib.rs`](./ddk/src/lib.rs).

[`P2PDerivatives`](./ddk/src/oracle/p2p_derivatives.rs) - Spot price futures on the Bitcoin price [repo](https://github.com/p2pderivatives/p2pderivatives-oracle)
## Crates

[`kormir`](./ddk/src/oracle/kormir.rs) - Enumeration based oracle with server and nostr support [repo](https://github.com/benthecarman/kormir)
| Crate | Description | |
|-------|-------------|---------|
| [`ddk`](./ddk) | The main DDK library with an integrated BDK wallet for building DLC applications. | [![Crate](https://img.shields.io/crates/v/ddk.svg)](https://crates.io/crates/ddk) |
| [`ddk-node`](./ddk-node) | A ready-to-go DLC node with a gRPC server and accompanying CLI. | [![Crate](https://img.shields.io/crates/v/ddk-node.svg)](https://crates.io/crates/ddk-node) |
| [`ddk-payouts`](./payouts) | Functions to build payout curves for DLC contracts. | [![Crate](https://img.shields.io/crates/v/ddk-payouts.svg)](https://crates.io/crates/ddk-payouts) |
| [`ddk-manager`](./ddk-manager) | Core DLC contract creation and state machine management. | [![Crate](https://img.shields.io/crates/v/ddk-manager.svg)](https://crates.io/crates/ddk-manager) |
| [`ddk-dlc`](./dlc) | Low-level DLC transaction creation, signing, and verification. | [![Crate](https://img.shields.io/crates/v/ddk-dlc.svg)](https://crates.io/crates/ddk-dlc) |
| [`ddk-messages`](./dlc-messages) | Serialization and structs for the DLC protocol messages. | [![Crate](https://img.shields.io/crates/v/ddk-messages.svg)](https://crates.io/crates/ddk-messages) |
| [`ddk-trie`](./dlc-trie) | Data structures for storage and retrieval of numerical DLCs. | [![Crate](https://img.shields.io/crates/v/ddk-trie.svg)](https://crates.io/crates/ddk-trie) |
| [`kormir`](./kormir) | Oracle implementation for creating and attesting to DLC events. | [![Crate](https://img.shields.io/crates/v/kormir.svg)](https://crates.io/crates/kormir) |

## Development

Expand All @@ -84,4 +80,22 @@ A bitcoin node, esplora server, and oracle server are required to run DDK. Devel
$ just deps
```

Go to the README in [ddk-node](./ddk-node/README.md) to start the project's DDK node example and more development information.
To run your own [Kormir](https://github.com/bennyhodl/kormir) oracle server for development, see the Kormir repository.

See the [ddk-node README](./ddk-node/README.md) for more development information.

## Language Bindings

For Node.js and React Native bindings, see [ddk-ffi](https://github.com/bennyhodl/ddk-ffi).

## Resources

- [DLC Dev Kit Blog](https://dlcdevkit.com) - Guides and API walkthroughs
- [DLC Dev Kit: Beyond](https://benschroth.com/blog/dlcdevkit-beyond/) - Deep dive into the project
- [What is a Discreet Log Contract?](https://river.com/learn/terms/d/discreet-log-contract-dlc/) - Learn about DLCs
- [DLC Specifications](https://github.com/discreetlogcontracts/dlcspecs) - Protocol specification
- [rust-dlc](https://github.com/p2pderivatives/rust-dlc) - The original rust-dlc implementation

## License

This project is licensed under the [MIT License](LICENSE).
63 changes: 59 additions & 4 deletions ddk-manager/Readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,61 @@
# DLC Manager
# ddk-manager

This crate provides a manager structure that can be used to create and process DLC.
The manager requires a number of traits which have basic implementation within this repository but that can be customized to fit specific needs.
[![Crate](https://img.shields.io/crates/v/ddk-manager.svg?logo=rust)](https://crates.io/crates/ddk-manager)
[![Documentation](https://img.shields.io/static/v1?logo=read-the-docs&label=docs.rs&message=ddk-manager&color=informational)](https://docs.rs/ddk-manager)

See [the development docs](../docs/Development.md) for information about running integration tests.
Core DLC contract creation and state machine management for Discreet Log Contracts.

This crate provides the `Manager` component for creating, processing, and managing DLCs and DLC channels. It handles the full lifecycle from offer through settlement/closure, including both on-chain contracts and off-chain channels with support for renewals, settlements, and collaborative/unilateral closes.

## Contract States

| State | Description |
|-------|-------------|
| `Offered` | Contract has been proposed |
| `Accepted` | Counter party accepted the offer |
| `Signed` | Signatures have been exchanged |
| `Confirmed` | Funding transaction confirmed on-chain |
| `PreClosed` | CET broadcast but not fully confirmed |
| `Closed` | Contract fully settled |
| `Refunded` | Refund transaction was broadcast |

## Key Traits

Users must implement these traits for their specific backends:

| Trait | Purpose |
|-------|---------|
| `Storage` | Persist and retrieve contracts, channels, and chain state |
| `Wallet` | Address generation, UTXO management, PSBT signing |
| `Blockchain` | Transaction broadcasting, block fetching, confirmations |
| `Oracle` | Fetch oracle announcements and attestations |
| `ContractSignerProvider` | Derive contract signing keys |

## Manager API

```rust
// Contract lifecycle
manager.send_offer(&contract_input, counterparty).await?;
manager.accept_contract_offer(&contract_id).await?;
manager.on_dlc_message(&message, counterparty).await?;

// Channel operations
manager.offer_channel(&contract_input, counterparty).await?;
manager.settle_offer(&channel_id, payout).await?;
manager.renew_offer(&channel_id, &contract_input).await?;

// Periodic maintenance
manager.periodic_check(false).await?;
```

## Features

| Feature | Description |
|---------|-------------|
| `std` | Standard library support (default) |
| `parallel` | Parallel processing in ddk-trie |
| `use-serde` | Serde serialization support |

## License

This project is licensed under the MIT License.
Loading
Loading