Skip to content

Commit 7b390ea

Browse files
anyxemanyxem
authored
example: htlc p2p board (#24)
* initial commit of p2p board * counterparty htlc creation * add token tickers * add token tickers * save spend utxo transaction hex * fix: spend htlc token * fix: htlc * add step for counterpart htlc * adjust last step * adjust layout * adjust complete status * fix deps * add readme for examples folder
1 parent 9cc0731 commit 7b390ea

File tree

24 files changed

+5087
-102
lines changed

24 files changed

+5087
-102
lines changed

‎examples/Readme.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Mintlayer Connect SDK Examples
2+
3+
This directory contains example applications demonstrating how to use the Mintlayer Connect SDK for various use cases.
4+
5+
## Available Examples
6+
7+
### 🌐 [Demo](./demo/)
8+
A comprehensive web-based demo showcasing all Mintlayer Connect SDK features including:
9+
- Wallet connection and management
10+
- Token transfers and NFT operations
11+
- Token issuance, minting, and burning
12+
- DEX order creation and filling
13+
- Delegation and staking operations
14+
- HTLC (Hash Time Locked Contracts) for atomic swaps
15+
- Bridge requests and transaction signing
16+
17+
**Tech Stack:** Vanilla JavaScript + HTML + Webpack
18+
**Network Support:** Mainnet and Testnet
19+
20+
### 🔄 [P2P Swap Board](./swap-board-ml-ml/)
21+
A peer-to-peer token swap application using HTLC atomic swaps for secure token exchanges:
22+
- Create and browse swap offers
23+
- Accept offers and execute atomic swaps
24+
- Real-time swap status tracking
25+
- Wallet integration with Mojito wallet
26+
27+
**Tech Stack:** Next.js 14 + React + Tailwind CSS + SQLite/Prisma
28+
**Features:** Full-stack P2P swap marketplace with database persistence
29+
30+
## Getting Started
31+
32+
Each example includes its own setup instructions. Navigate to the specific example directory and follow the README instructions.
33+
34+
### Prerequisites
35+
- Node.js 18+
36+
- pnpm (recommended) or npm
37+
- Mojito wallet extension (for wallet integration examples)
38+
39+
### Quick Start
40+
```bash
41+
# Navigate to desired example
42+
cd demo # or swap-board-ml-ml
43+
44+
# Install dependencies
45+
pnpm install
46+
47+
# Follow example-specific instructions in their README
48+
```
49+
50+
## Example Structure
51+
52+
- **demo/**: Interactive web demo with all SDK features
53+
- **swap-board-ml-ml/**: Full P2P swap application
54+
- **nodejs/**: (Coming soon) Node.js server examples
55+
- **react-app/**: (Coming soon) React application examples
56+
57+
## Documentation
58+
59+
For detailed SDK documentation and API reference, visit the main project documentation.

‎examples/swap-board-ml-ml/.env.example

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Database
2+
DATABASE_URL="file:./dev.db"
3+
4+
# Mintlayer Network (testnet or mainnet)
5+
NEXT_PUBLIC_MINTLAYER_NETWORK="testnet"

‎examples/swap-board-ml-ml/.gitignore

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
2+
3+
# dependencies
4+
/node_modules
5+
/.pnp
6+
.pnp.js
7+
.yarn/install-state.gz
8+
9+
# testing
10+
/coverage
11+
12+
# next.js
13+
/.next/
14+
/out/
15+
16+
# production
17+
/build
18+
19+
# misc
20+
.DS_Store
21+
*.pem
22+
23+
# debug
24+
npm-debug.log*
25+
yarn-debug.log*
26+
yarn-error.log*
27+
28+
# local env files
29+
.env*.local
30+
.env
31+
32+
# vercel
33+
.vercel
34+
35+
# typescript
36+
*.tsbuildinfo
37+
next-env.d.ts
38+
39+
# database
40+
prisma/dev.db
41+
prisma/dev.db-journal
42+
43+
# IDE
44+
.vscode/
45+
.idea/
46+
*.swp
47+
*.swo
48+
49+
# OS
50+
Thumbs.db

‎examples/swap-board-ml-ml/README.md

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Mintlayer P2P Swap Board
2+
3+
A minimal peer-to-peer token swap board for Mintlayer tokens using HTLC (Hash Time Locked Contracts) atomic swaps.
4+
5+
## Features
6+
7+
- **Create Swap Offers**: Post your intent to swap one Mintlayer token for another
8+
- **Browse & Accept Offers**: View available offers and accept the ones that interest you
9+
- **Atomic Swaps**: Secure token exchanges using HTLC contracts via mintlayer-connect-sdk
10+
- **Status Tracking**: Real-time monitoring of swap progress with clear status indicators
11+
- **Wallet Integration**: Connect with Mojito wallet for seamless transactions
12+
13+
## Tech Stack
14+
15+
- **Frontend**: Next.js 14 (App Router) + React + Tailwind CSS
16+
- **Backend**: Next.js API routes
17+
- **Database**: SQLite with Prisma ORM
18+
- **Blockchain**: Mintlayer Connect SDK for HTLC operations
19+
- **Package Manager**: pnpm (workspace integration)
20+
21+
## Getting Started
22+
23+
### Prerequisites
24+
25+
- Node.js 18+
26+
- pnpm
27+
- Mojito wallet extension
28+
29+
### Installation
30+
31+
1. Install dependencies:
32+
```bash
33+
cd examples/swap-board-ml-ml
34+
pnpm install
35+
```
36+
37+
2. Set up the database:
38+
```bash
39+
pnpm db:generate
40+
pnpm db:push
41+
```
42+
43+
3. Copy environment variables:
44+
```bash
45+
cp .env.example .env.local
46+
```
47+
48+
4. Start the development server:
49+
```bash
50+
pnpm dev
51+
```
52+
53+
5. Open [http://localhost:3000](http://localhost:3000) in your browser
54+
55+
## Usage
56+
57+
### Creating an Offer
58+
59+
1. Navigate to `/create`
60+
2. Connect your Mojito wallet
61+
3. Fill in the swap details:
62+
- Token to give (Token ID)
63+
- Amount to give
64+
- Token to receive (Token ID)
65+
- Amount to receive
66+
- Optional contact information
67+
4. Submit the offer
68+
69+
### Accepting an Offer
70+
71+
1. Browse offers at `/offers`
72+
2. Connect your wallet
73+
3. Click "Accept Offer" on any available offer
74+
4. You'll be redirected to the swap progress page
75+
76+
### Monitoring Swaps
77+
78+
1. Visit `/swap/[id]` to track swap progress
79+
2. The page shows:
80+
- Current swap status
81+
- Progress steps
82+
- Next actions required
83+
- HTLC details when available
84+
85+
## Swap Process
86+
87+
1. **Offer Created**: User posts swap intention
88+
2. **Offer Accepted**: Another user accepts the offer
89+
3. **HTLC Creation**: Creator creates initial HTLC with secret hash
90+
4. **Counterparty HTLC**: Taker creates matching HTLC
91+
5. **Token Claiming**: Both parties reveal secrets to claim tokens
92+
6. **Completion**: Swap finalized or manually refunded after timelock expires
93+
94+
## Database Schema
95+
96+
### Offer Model
97+
- Stores swap offers with token details and creator information
98+
- Tracks offer status (open, taken, completed, cancelled)
99+
100+
### Swap Model
101+
- Manages active swaps linked to offers
102+
- Stores HTLC secrets, transaction hashes, and status updates
103+
- Tracks swap progress from pending to completion
104+
105+
## API Endpoints
106+
107+
- `GET/POST /api/offers` - List and create swap offers
108+
- `POST /api/swaps` - Accept an offer (creates new swap)
109+
- `GET/POST /api/swaps/[id]` - Get and update swap status
110+
111+
## Development
112+
113+
### Database Operations
114+
115+
```bash
116+
# Generate Prisma client
117+
pnpm db:generate
118+
119+
# Push schema changes
120+
pnpm db:push
121+
122+
# Open database browser
123+
pnpm db:studio
124+
```
125+
126+
### Building
127+
128+
```bash
129+
# Build for production
130+
pnpm build
131+
132+
# Start production server
133+
pnpm start
134+
```
135+
136+
## Security Considerations
137+
138+
- HTLC contracts provide atomic swap guarantees
139+
- Timelock mechanisms prevent indefinite locks - users must manually refund after expiry
140+
- No private keys are stored in the database
141+
- All transactions require wallet confirmation
142+
143+
## Contributing
144+
145+
This is a minimal example implementation. For production use, consider:
146+
147+
- Enhanced error handling and validation
148+
- Comprehensive testing suite
149+
- Rate limiting and spam protection
150+
- Advanced UI/UX improvements
151+
- Mobile responsiveness optimization
152+
- Real-time notifications
153+
154+
## License
155+
156+
This project is part of the Mintlayer Connect SDK examples.

‎examples/swap-board-ml-ml/next.config.js

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
/** @type {import('next').NextConfig} */
2+
const nextConfig = {
3+
webpack: (config) => {
4+
config.experiments = {
5+
...config.experiments,
6+
asyncWebAssembly: true,
7+
};
8+
return config;
9+
},
10+
}
11+
12+
module.exports = nextConfig

‎examples/swap-board-ml-ml/package.json

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
{
2+
"name": "swap-board-ml-ml",
3+
"version": "0.1.0",
4+
"private": true,
5+
"scripts": {
6+
"dev": "next dev",
7+
"build": "next build",
8+
"start": "next start",
9+
"lint": "next lint",
10+
"db:generate": "prisma generate",
11+
"db:push": "prisma db push",
12+
"db:studio": "prisma studio"
13+
},
14+
"dependencies": {
15+
"@mintlayer/sdk": "workspace:*",
16+
"@prisma/client": "^5.7.0",
17+
"next": "14.0.4",
18+
"react": "^18.2.0",
19+
"react-dom": "^18.2.0",
20+
"prisma": "^5.7.0"
21+
},
22+
"devDependencies": {
23+
"@types/node": "^20.10.0",
24+
"@types/react": "^18.2.0",
25+
"@types/react-dom": "^18.2.0",
26+
"autoprefixer": "^10.4.16",
27+
"eslint": "^8.55.0",
28+
"eslint-config-next": "14.0.4",
29+
"postcss": "^8.4.32",
30+
"tailwindcss": "^3.3.6",
31+
"typescript": "^5.3.0"
32+
}
33+
}

‎examples/swap-board-ml-ml/postcss.config.js

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
module.exports = {
2+
plugins: {
3+
tailwindcss: {},
4+
autoprefixer: {},
5+
},
6+
}

‎examples/swap-board-ml-ml/prisma/schema.prisma

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
// This is your Prisma schema file,
2+
// learn more about it in the docs: https://pris.ly/d/prisma-schema
3+
4+
generator client {
5+
provider = "prisma-client-js"
6+
}
7+
8+
datasource db {
9+
provider = "sqlite"
10+
url = "file:./dev.db"
11+
}
12+
13+
model Offer {
14+
id Int @id @default(autoincrement())
15+
direction String // "tokenA->tokenB"
16+
tokenA String
17+
tokenB String
18+
amountA String
19+
amountB String
20+
price Float
21+
creatorMLAddress String
22+
contact String?
23+
status String @default("open") // open, taken, completed, cancelled
24+
createdAt DateTime @default(now())
25+
26+
swaps Swap[]
27+
}
28+
29+
model Swap {
30+
id Int @id @default(autoincrement())
31+
offerId Int
32+
takerMLAddress String
33+
status String @default("pending") // pending, htlc_created, in_progress, completed, fully_completed, refunded
34+
secretHash String?
35+
secret String?
36+
creatorHtlcTxHash String? // Creator's HTLC transaction ID
37+
creatorHtlcTxHex String? // Creator's signed HTLC transaction hex
38+
takerHtlcTxHash String? // Taker's HTLC transaction ID
39+
takerHtlcTxHex String? // Taker's signed HTLC transaction hex
40+
claimTxHash String? // Final claim transaction ID
41+
claimTxHex String? // Final claim transaction hex (needed for secret extraction)
42+
createdAt DateTime @default(now())
43+
44+
offer Offer @relation(fields: [offerId], references: [id])
45+
}

0 commit comments

Comments
 (0)