https://github.com/vulpemventures/banco
https://github.com/vulpemventures/banco
Last synced: 12 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/vulpemventures/banco
- Owner: vulpemventures
- License: mit
- Created: 2023-12-27T19:05:26.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2024-02-21T14:42:17.000Z (over 2 years ago)
- Last Synced: 2025-06-29T04:14:21.735Z (12 months ago)
- Language: Go
- Homepage: https://banco.vulpem.com
- Size: 1.61 MB
- Stars: 9
- Watchers: 3
- Forks: 4
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🏦 banco
## 📖 Introduction
Banco uses Taproot and Elements introspection opcodes to enable an efficient and decentralized trading protocol between two or more parties using a non-interactive atomic swap construction.
Try it out at [banco.vulpem.com](https://banco.vulpem.com) running a Liquid Testnet instance.
Read more on the introductory blog post https://vulpem.medium.com/banco-non-interactive-swaps-00d042791e06
## Why?
- **Non-interactive** is a desirable property for atomic swaps. It allows the maker to create a transaction that can be fulfilled by the taker without any further interaction from the maker.
- **Easiest integration, ever** The protocol can be used by any wallet that supports sending to an Elements address. No PSBT, no signatures to exchange. Simple!
- **Liquidity efficient** The maker can create a transaction that can be fulfilled by the taker at any time (as long the maker does not cancel it wih a double-spend). This allows the taker to provide liquidity via automated bots that can fulfill the transaction without the risk of the capital to be locked for a long time (as it happens with time-locked contracts).
- **Decentralized** The protocol is completely decentralized and does not require any trusted third party, being non-custodial for traders and capital efficient for market makers, without the need of a centralized "order-book" server. The taker simply observes the mempool for pending contracts to fulfill.
## 🧿 Protocol
### 🍔 TL;DR
It requires two transactions, one to **fund** the "trade contract" and another to either **fulfill** or **cancel** it.
*Anyone* can fulfill the contract as soon is seen on the mempool, but only the maker can cancel it.
The contract enforces that the first output has the requested value, asset and script in the spending transaction.
In-depth explanation can be found in the [protocol](./PROTOCOL.md) document.
## 🏃 Show me the code
### 🏛️ Architecture
Banco is composed of the following components and pieces:
- **`banco`**: A web server written in Go that serves an HTMX web application to accept trades from makers. It monitors the mempool for funded trade contracts to be fulfilled. It writes trade data to an SQLite database in `./db/banco.db`
- **`ocean`**: An Elements wallet daemon that is used by Banco to fund the fulfill transactions. It supports an embedded database or PostgreSQL.
### 📦 Download
The most simple way to run Banco locally is using docker. Standalone installation instructions coming soon.
```bash
git clone https://github.com/vulpemventures/banco.git
cd banco
```
### 🌊 Setup Ocean
Ocean is an Elements wallet daemon that is used by Banco, an automated taker bot that fulfills pending contracts in the mempool.
```bash
docker-compose up -d oceand
```
This will run a server on `localhost:18000` and the first time you have to `ocean wallet create`. If you have already a mnemonic you will be able to `ocean wallet restore` it.
Set an alias for the `ocean` command to run it from your terminal:
```bash
alias ocean="docker exec -it oceand ocean"
```
#### Initialize Ocean CLI
```bash
ocean config init --no-tls
```
#### Create or restore a wallet
```bash
ocean wallet create --mnemonic --password
# or if your already have a mnemonic
# ocean wallet restore --mnemonic --password
```
#### Unlock
```bash
ocean wallet unlock --password
```
### 🚚 Run Banco Web Server
This will run a server on `localhost:8080` for the `NETWORK=testnet` and `WATCH_INTERVAL_SECONDS=5` by default.
```bash
docker-compose up -d banco
```
## ⚙️ Environment Variables
Banco uses the following environment variables:
- `WEB_DIR`: The directory where the web files are located. Default is `web`.
- `OCEAN_URL`: The URL of the Ocean node. Default is `localhost:18000`.
- `OCEAN_ACCOUNT_NAME`: The name of the Ocean account. Default is `default`.
- `WATCH_INTERVAL_SECONDS`: The interval in seconds for watching for pending trades to fulfill. Default is `-1`, which means changes are NOT watched continuously.
- `NETWORK`: The network to use. Default is `liquid`.
- `GIN_MODE`: Enable release or debug mode. Default is `debug`.
## 📦 Development
### Requirements
- [Go](https://golang.org/) 1.16 or higher.
- [Ocean Daemon](https://github.com/vulpemventures/oceand) 0.2.0 or higher
### 🏗️ Build Banco
```bash
go mod download
go build -o banco
```
### 🧪 Test
```bash
go test ./...
```
### 📝 Docs
```bash
go doc ./...
```
### Run Web Server
```bash
go run .
```
## Contribution 🤝
Pull requests and issues are welcome!
## License 📜
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.