{"id":29143488,"url":"https://github.com/vulpemventures/banco","last_synced_at":"2025-06-30T20:07:39.350Z","repository":{"id":219491057,"uuid":"736388077","full_name":"vulpemventures/banco","owner":"vulpemventures","description":null,"archived":false,"fork":false,"pushed_at":"2024-02-21T14:42:17.000Z","size":1692,"stargazers_count":9,"open_issues_count":3,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-29T04:14:21.735Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://banco.vulpem.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vulpemventures.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-12-27T19:05:26.000Z","updated_at":"2024-02-07T21:14:46.000Z","dependencies_parsed_at":"2024-01-27T21:28:02.262Z","dependency_job_id":"ac6428f7-3adc-447d-b49f-9370ee464284","html_url":"https://github.com/vulpemventures/banco","commit_stats":null,"previous_names":["vulpemventures/banco"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vulpemventures/banco","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vulpemventures%2Fbanco","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vulpemventures%2Fbanco/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vulpemventures%2Fbanco/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vulpemventures%2Fbanco/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vulpemventures","download_url":"https://codeload.github.com/vulpemventures/banco/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vulpemventures%2Fbanco/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262842920,"owners_count":23373167,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-30T20:07:38.382Z","updated_at":"2025-06-30T20:07:39.290Z","avatar_url":"https://github.com/vulpemventures.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🏦 banco\n\n## 📖 Introduction\n\nBanco 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.\n\nTry it out at [banco.vulpem.com](https://banco.vulpem.com) running a Liquid Testnet instance.\n\nRead more on the introductory blog post https://vulpem.medium.com/banco-non-interactive-swaps-00d042791e06\n\n## Why?\n\n- **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.\n\n- **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!\n\n- **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).\n\n- **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.\n\n## 🧿 Protocol\n\n### 🍔 TL;DR\n\nIt requires two transactions, one to **fund** the \"trade contract\" and another to either **fulfill** or **cancel** it.\n*Anyone* can fulfill the contract as soon is seen on the mempool, but only the maker can cancel it.\nThe contract enforces that the first output has the requested value, asset and script in the spending transaction.\n\nIn-depth explanation can be found in the [protocol](./PROTOCOL.md) document.\n\n## 🏃 Show me the code\n\n### 🏛️ Architecture\n\nBanco is composed of the following components and pieces:\n\n- **`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`\n- **`ocean`**: An Elements wallet daemon that is used by Banco to fund the fulfill transactions. It supports an embedded database or PostgreSQL.\n\n### 📦 Download\n\nThe most simple way to run Banco locally is using docker. Standalone installation instructions coming soon.\n\n```bash\ngit clone https://github.com/vulpemventures/banco.git\ncd banco\n```\n\n### 🌊 Setup Ocean\n\nOcean is an Elements wallet daemon that is used by Banco, an automated taker bot that fulfills pending contracts in the mempool.\n\n```bash\ndocker-compose up -d oceand\n```\n\nThis 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.\n\nSet an alias for the `ocean` command to run it from your terminal:\n\n```bash\nalias ocean=\"docker exec -it oceand ocean\"\n```\n\n#### Initialize Ocean CLI\n\n```bash\nocean config init --no-tls\n```\n\n#### Create or restore a wallet\n\n```bash\nocean wallet create --mnemonic \u003cyour_mnemonic\u003e --password \u003cyour_password\u003e\n# or if your already have a mnemonic\n# ocean wallet restore --mnemonic \u003cyour_mnemonic\u003e --password \u003cyour_password\u003e\n```\n\n#### Unlock\n\n```bash\nocean wallet unlock --password \u003cyour_password\u003e\n```\n\n### 🚚 Run Banco Web Server\n\nThis will run a server on `localhost:8080` for the `NETWORK=testnet` and `WATCH_INTERVAL_SECONDS=5` by default.\n\n```bash\ndocker-compose up -d banco\n```\n\n## ⚙️ Environment Variables\n\nBanco uses the following environment variables:\n\n- `WEB_DIR`: The directory where the web files are located. Default is `web`.\n- `OCEAN_URL`: The URL of the Ocean node. Default is `localhost:18000`.\n- `OCEAN_ACCOUNT_NAME`: The name of the Ocean account. Default is `default`.\n- `WATCH_INTERVAL_SECONDS`: The interval in seconds for watching for pending trades to fulfill. Default is `-1`, which means changes are NOT watched continuously.\n- `NETWORK`: The network to use. Default is `liquid`.\n- `GIN_MODE`: Enable release or debug mode. Default is `debug`.\n\n## 📦 Development\n\n### Requirements\n\n- [Go](https://golang.org/) 1.16 or higher.\n- [Ocean Daemon](https://github.com/vulpemventures/oceand) 0.2.0 or higher\n\n### 🏗️ Build Banco\n\n```bash\ngo mod download\ngo build -o banco\n```\n\n### 🧪 Test\n\n```bash\ngo test ./...\n```\n\n### 📝 Docs\n\n```bash\ngo doc ./...\n```\n\n### Run Web Server\n\n  ```bash\n  go run .\n  ```\n\n## Contribution 🤝\n\nPull requests and issues are welcome!\n\n## License 📜\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvulpemventures%2Fbanco","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvulpemventures%2Fbanco","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvulpemventures%2Fbanco/lists"}