Skip to content

Commit 057cdcd

Browse files
KyrylRKyrylR
committed
Project restructure. Dex Nostr Relayer PoC.
1 parent 7c0bcbd commit 057cdcd

34 files changed

+1173
-4
lines changed

‎.github/ISSUE_TEMPLATE/bug-report.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: Bug Report
2+
description: File a bug report
3+
labels: ['bug']
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: Thanks for taking the time to fill out this bug report!
8+
- type: input
9+
id: version
10+
attributes:
11+
label: "Project version"
12+
placeholder: "1.2.3"
13+
validations:
14+
required: true
15+
- type: textarea
16+
id: what-happened
17+
attributes:
18+
label: What happened?
19+
description: A brief description of what happened and what you expected to happen
20+
validations:
21+
required: true
22+
- type: textarea
23+
id: reproduction-steps
24+
attributes:
25+
label: "Minimal reproduction steps"
26+
description: "The minimal steps needed to reproduce the bug"
27+
validations:
28+
required: true

‎.github/ISSUE_TEMPLATE/feature-request.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
name: Feature request
2+
description: Suggest a new feature
3+
labels: ['feature']
4+
body:
5+
- type: textarea
6+
id: feature-description
7+
attributes:
8+
label: "Describe the feature"
9+
description: "A description of what you would like to see in the project"
10+
validations:
11+
required: true

‎.github/ISSUE_TEMPLATE/other-issue.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
name: Other issue
3+
about: Other kind of issue
4+
---

‎.github/workflows/ci.yml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: Linting Checks and Tests
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- dev
8+
pull_request:
9+
10+
permissions:
11+
contents: read
12+
13+
concurrency:
14+
group: ci-${{ github.workflow }}-${{ github.ref }}
15+
cancel-in-progress: true
16+
17+
jobs:
18+
lint-and-test:
19+
name: Lint and Test (Ubuntu)
20+
runs-on: ubuntu-latest
21+
steps:
22+
- name: Checkout
23+
uses: actions/checkout@v4
24+
25+
- name: Setup Rust toolchain
26+
uses: actions-rust-lang/setup-rust-toolchain@v1
27+
with:
28+
components: clippy, rustfmt
29+
30+
- name: Cache cargo registry, git and target
31+
uses: actions/cache@v4
32+
with:
33+
path: |
34+
~/.cargo/registry
35+
~/.cargo/git
36+
target
37+
key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
38+
restore-keys: |
39+
${{ runner.os }}-cargo-
40+
41+
- name: Run Rust fmt
42+
run: cargo fmt --all --check
43+
44+
- name: Run clippy
45+
run: cargo clippy --workspace --all-targets --all-features -- -D warnings
46+
47+
- name: Run tests
48+
run: cargo test --workspace --all-features --locked --no-fail-fast

‎.simplicity-dex.example/keypair.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
<your_private_key>

‎.simplicity-dex.example/relays.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
<your_preferred_relays>

‎Cargo.toml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
[workspace]
2+
resolver = "3"
3+
members = [
4+
"crates/*"
5+
]
6+
7+
[workspace.package]
8+
version = "0.1.0"
9+
edition = "2024"
10+
rust-version = "1.91.0"
11+
authors = ["Blockstream"]
12+
readme = "README.md"
13+
14+
15+
[workspace.dependencies]
16+
anyhow = { version = "1.0.100" }
17+
clap = { version = "4.5.49", features = ["derive"] }
18+
dirs = {version = "6.0.0"}
19+
futures-util = { version = "0.3.31" }
20+
global-utils = { path = "crates/global-utils" }
21+
nostr = { version = "0.43.1", features = ["std"] }
22+
nostr-sdk = { version = "0.43.0" }
23+
dex-nostr-relay = { path = "./crates/dex-nostr-relay"}
24+
serde = { version = "1.0.228", features = ["derive"] }
25+
serde_json = { version = "1.0.145" }
26+
thiserror = { version = "2.0.17" }
27+
tokio = { version = "1.48.0", features = ["macros", "test-util", "rt", "rt-multi-thread"] }
28+
tracing = { version = "0.1.41" }
29+
tracing-appender = { version = "0.2.3" }
30+
tracing-subscriber = { version = "0.3.19", features = ["env-filter"] }
31+
url = { version = "2.5.7" }

‎Makefile‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
## This help screen
2+
help:
3+
@printf "Available targets:\n\n"
4+
@awk '/^[a-zA-Z\-\_0-9%:\\]+/ { \
5+
helpMessage = match(lastLine, /^## (.*)/); \
6+
if (helpMessage) { \
7+
helpCommand = $$1; \
8+
helpMessage = substr(lastLine, RSTART + 3, RLENGTH); \
9+
gsub("\\\\", "", helpCommand); \
10+
gsub(":+$$", "", helpCommand); \
11+
printf " \x1b[32;01m%-35s\x1b[0m %s\n", helpCommand, helpMessage; \
12+
} \
13+
} \
14+
{ lastLine = $$0 }' $(MAKEFILE_LIST) | sort -u
15+
@printf "\n"
16+
17+
## Format code
18+
fmt:
19+
cargo +nightly fmt --all
20+
21+
## Show lints
22+
clippy:
23+
cargo clippy -- -Dclippy::pedantic
24+
25+
## Show lints for all features
26+
clippy_all_features:
27+
cargo clippy --workspace --all-targets --all-features -- -D warnings

‎Readme.md‎

Lines changed: 100 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,102 @@
1-
## Liquid Nostr Options custom DEX
1+
# Simplicity DEX
22

3-
Decentralized Exchange, which can help traders to trade asset pairs in Liquid network. (LBTC ↔ MEX). Tokens [listed][1]. Liquid options [docs][2].
3+
A distributed exchange built on the NOSTR protocol, leveraging Simplicity smart contracts and the PACT (PACT for Auditable Contract Transactions) messaging protocol.
44

5-
[1]: https://liquid.network/assets/featured
6-
[2]: https://blockstream.com/assets/downloads/pdf/options-whitepaper.pdf
5+
## Overview
6+
7+
Simplicity DEX is a decentralized exchange that combines the power of Simplicity smart contracts with the distributed messaging capabilities of NOSTR. By utilizing the PACT protocol, we enable secure, auditable, and transparent trading of digital assets without relying on centralized intermediaries.
8+
9+
## Key Features
10+
11+
- **Decentralized Architecture**: Built on NOSTR for censorship-resistant, distributed messaging
12+
- **Simplicity Smart Contracts**: Leveraging Bitcoin's Simplicity language for provably secure contract execution
13+
- **PACT Protocol**: Standardized format for auditable contract transactions
14+
- **Open Ecosystem**: Compatible with any NOSTR client for maximum interoperability
15+
- **Maker Identity Registry**: On-chain reputation system for market makers
16+
17+
## DEX Messaging Protocol
18+
19+
The core of our DEX is the **PACT (PACT for Auditable Contract Transactions)** protocol, which defines the format of trading offers. This protocol is fully adapted to be compatible with the NOSTR event structure.
20+
21+
### Offer Structure
22+
23+
A PACT offer is implemented as a standard NOSTR event with kind `30078` (non-standard, ephemeral event kind for DEX offers). The event structure maps to PACT requirements as follows:
24+
25+
| NOSTR Field | PACT Field | Data Type | Required | Description |
26+
|---------------|---------------|-----------------------|----------|-------------------------------------------------------------------------------------------------------------------|
27+
| `id` | Event ID | string (64-char hex) | Yes | SHA-256 hash of canonical serialized event data (excluding `sig`). Serves as unique, content-addressed identifier |
28+
| `pubkey` | Maker Key | string (64-char hex) | Yes | 32-byte x-only Schnorr public key of market maker. Must be registered in on-chain Maker Identity Registry |
29+
| `created_at` | Timestamp | integer | Yes | Unix timestamp (seconds) when offer was created |
30+
| `description` | Description | string | No | Human-readable description of instrument and complex terms |
31+
| `kind` | Event Type | integer | Yes | Event type identifier. Value `1` reserved for standard offers. Enables future protocol extensions |
32+
| `tags` | Metadata | array of arrays | Yes | Structured machine-readable metadata for filtering and discovery |
33+
| `content` | Contract Code | string | Yes | Stringified JSON containing full Simplicity contract code |
34+
| `sig` | Signature | string (128-char hex) | Yes | 64-byte Schnorr signature proving authenticity and integrity |
35+
36+
### Tag Examples
37+
38+
The `tags` field contains structured metadata as key-value pairs:
39+
40+
```json
41+
[
42+
["asset_to_sell", "<liquid_asset_id>"],
43+
["asset_to_buy", "<liquid_asset_id>"],
44+
["price", "1000000", "sats_per_contract"],
45+
["expiry", "1735689600"],
46+
["compiler", "simplicity-v1.2.3", "deterministic_build_hash"]
47+
]
48+
```
49+
50+
### Protocol Benefits
51+
52+
- **Interoperability**: Any NOSTR-compatible client can parse and validate offers
53+
- **Transparency**: All offers are publicly auditable
54+
- **Censorship Resistance**: Distributed messaging prevents single points of failure
55+
- **Standardization**: Consistent format enables ecosystem growth
56+
- **Extensibility**: Protocol designed for future enhancements
57+
58+
## Getting Started
59+
60+
### Basic Usage
61+
62+
1. **Create an Offer**: Generate a PACT-compliant NOSTR event with your trading parameters
63+
2. **Broadcast**: Publish the offer to NOSTR relays
64+
3. **Discovery**: Takers can filter and discover offers using tag-based queries
65+
4. **Execution**: Complete trades through Simplicity contract execution
66+
67+
## Architecture
68+
69+
```text
70+
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
71+
│ Maker Client │ │ NOSTR Relays │ │ Taker Client │
72+
│ │<───>| │<───>│ │
73+
│ - Create Offers │ │ - Store Events │ │ - Discover │
74+
│ - Sign Contracts│ │ - Relay Messages │ │ - Execute Trades│
75+
└─────────────────┘ └──────────────────┘ └─────────────────┘
76+
│ │ │
77+
│ ┌──────────────────┐ │
78+
└─────────────>│ Liquid Network │<────────────┘
79+
│ │
80+
│ - Asset Registry │
81+
│ - Contract Exec │
82+
│ - Settlement │
83+
└──────────────────┘
84+
```
85+
86+
## Contributing
87+
88+
We welcome contributions to the Simplicity DEX project.
89+
90+
## License
91+
92+
This project is licensed under the MIT License - see the LICENSE file for details.
93+
94+
## Links
95+
96+
- [Simplicity Language](https://github.com/ElementsProject/simplicity)
97+
- [NOSTR Protocol](https://github.com/nostr-protocol/nostr)
98+
- [Liquid Network](https://liquid.net/)
99+
100+
## Disclaimer
101+
102+
This software is experimental and should be used with caution. Always verify contract code and understand the risks before trading.

‎crates/dex-cli/Cargo.toml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
[package]
2+
name = "simplicity-dex"
3+
version = "0.1.0"
4+
edition = "2024"
5+
6+
[dependencies]
7+
anyhow = { workspace = true }
8+
nostr = { workspace = true }
9+
global-utils = { workspace = true }
10+
futures-util = { workspace = true }
11+
serde_json = { workspace = true }
12+
tokio = { workspace = true }
13+
clap = { workspace = true }
14+
dirs = { workspace = true }
15+
tracing = { workspace = true }
16+
thiserror = { workspace = true }
17+
dex-nostr-relay = { workspace = true }
18+

0 commit comments

Comments
 (0)