diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1ac8e387..05211501 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -11,11 +11,22 @@ env: SLOW_MACHINE: 1 jobs: + buf: + runs-on: ubuntu-latest + + steps: + # Run `git checkout` + - name: Checkout code + uses: actions/checkout@v4 + # Run the `buf` CLI + - name: Buf Action + uses: bufbuild/buf-action@v1 + unit-tests: runs-on: ubuntu-latest steps: - - name: Checkout code + - name: Checkout code uses: actions/checkout@v3 - name: Set up Go diff --git a/README.md b/README.md index afce4934..884a6170 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,9 @@ PeerSwap enables Lightning Network nodes to balance their channels by facilitati - [Core Lightning](#core-lightning) - [LND](#lnd) - [Development](#development) + - [Development: Buf CLI Description](#development-buf-cli-description) + - [Usage](#usage-1) + - [Using Devcontainer](#using-devcontainer) ## Project Status @@ -67,8 +70,8 @@ To run Elements for L-BTC swaps, see the [Elements setup guide](./docs/setup_ele To run LWK for L-BTC swaps, see the [LWK setup guide](./docs/setup_lwk.md). -> **Note** -> Most of the benefits of PeerSwap come from using L-BTC. Swaps using L-BTC are more private, faster, and avoid the mainchain blockchain during high fee environments that can make swaps uneconomical. +> **Note** +> Most of the benefits of PeerSwap come from using L-BTC. Swaps using L-BTC are more private, faster, and avoid the mainchain blockchain during high fee environments that can make swaps uneconomical. ### Usage @@ -88,7 +91,7 @@ See the [Upgrade guide](./docs/upgrade.md) for instructions to safely upgrade yo * Lower Cost - PeerSwap is the lowest cost because there is no 3rd party coordinator or intermediary nodes to collect rent. * More Private - Swaps are entirely between two consenting nodes. Nobody else is able to record details like who swapped. * What is the difference between [splicing](https://github.com/lightning/bolts/pull/863) and PeerSwap? - * Both PeerSwap and splicing (through Phoenix Wallet) are now usable on mainnet. Splicing is in general better, though PeerSwap can be attractive more for L-BTC swaps that don't touch the mainnet blockchain at all. Splicing and PeerSwap L-BTC swaps are both good for mainnet efficiency. + * Both PeerSwap and splicing (through Phoenix Wallet) are now usable on mainnet. Splicing is in general better, though PeerSwap can be attractive more for L-BTC swaps that don't touch the mainnet blockchain at all. Splicing and PeerSwap L-BTC swaps are both good for mainnet efficiency. * What is the difference between [liquidity-ads](https://github.com/lightning/bolts/pull/878) and PeerSwap? * Liquidity Ads is a great way to lease new channels to be opened toward you for the purpose of gaining incoming capacity. New channels add new capacity in a desired direction but only once. * PeerSwap lets you repeatedly refill your existing channels at a cost lower than opening, closing, and maintaining additional channels. @@ -111,6 +114,14 @@ For a LND Bitcoin signet / Liquid testnet setup guide see this [guide](./docs/si PeerSwap uses the [nix](https://nixos.org/download.html) package manager for a simple development environment. In order to start hacking, install nix, [golang](https://golang.org/doc/install) and run `nix-shell`. This will fetch all dependencies (except golang). +#### Development: Buf CLI Description + +In this project, we utilize Buf CLI to streamline the development environment for Protocol Buffers (protobuf).Buf is a powerful tool for managing the build, linting, formatting, and validation processes for protobuf files in a consistent and efficient manner. + +##### Usage + +See the [Usage guide](./docs/usage_buf.md) for instructions on how to use Buf. + #### Using Devcontainer To use devcontainer for development, follow these steps: diff --git a/buf.yaml b/buf.yaml index 85089313..58c3a13a 100644 --- a/buf.yaml +++ b/buf.yaml @@ -2,10 +2,51 @@ version: v2 modules: - path: peerswaprpc - -# lint: -# use: -# - STANDARD -# breaking: -# use: -# - FILE +lint: + use: + - STANDARD + except: + # TODO suport excepted standard rules. + # - COMMENT_ENUM + # - COMMENT_ENUM_VALUE + # - COMMENT_FIELD + # - COMMENT_MESSAGE + # - COMMENT_ONEOF + # - COMMENT_RPC + # - COMMENT_SERVICE + # - DIRECTORY_SAME_PACKAGE + # - ENUM_FIRST_VALUE_ZERO + # - ENUM_NO_ALLOW_ALIAS + # - ENUM_PASCAL_CASE + - ENUM_VALUE_PREFIX + # - ENUM_VALUE_UPPER_SNAKE_CASE + - ENUM_ZERO_VALUE_SUFFIX + # - FIELD_LOWER_SNAKE_CASE + # - FIELD_NOT_REQUIRED + # - FILE_LOWER_SNAKE_CASE + # - IMPORT_NO_PUBLIC + # - IMPORT_NO_WEAK + # - IMPORT_USED + # - MESSAGE_PASCAL_CASE + # - ONEOF_LOWER_SNAKE_CASE + # - PACKAGE_DEFINED + - PACKAGE_DIRECTORY_MATCH + # - PACKAGE_LOWER_SNAKE_CASE + # - PACKAGE_NO_IMPORT_CYCLE + # - PACKAGE_SAME_DIRECTORY + - PACKAGE_VERSION_SUFFIX + # - PROTOVALIDATE + # - RPC_NO_CLIENT_STREAMING + # - RPC_NO_SERVER_STREAMING + # - RPC_PASCAL_CASE + - RPC_REQUEST_STANDARD_NAME + - RPC_RESPONSE_STANDARD_NAME + - RPC_REQUEST_RESPONSE_UNIQUE + # - SERVICE_PASCAL_CASE + - SERVICE_SUFFIX + # - STABLE_PACKAGE_NO_IMPORT_UNSTABLE + # - SYNTAX_SPECIFIED + # - PACKAGE_SAME_GO_PACKAGE +breaking: + use: + - FILE diff --git a/docs/usage_buf.md b/docs/usage_buf.md new file mode 100644 index 00000000..51d86766 --- /dev/null +++ b/docs/usage_buf.md @@ -0,0 +1,25 @@ +# Usage Guide + +In this project, we utilize Buf CLI to streamline the development environment for Protocol Buffers (protobuf).Buf is a powerful tool for managing the build, linting, formatting, and validation processes for protobuf files in a consistent and efficient manner. + +- [Buf](https://buf.build/) +- [Buf Github URL](https://github.com/bufbuild/buf) + +## Why We Use Buf + +The adoption of Buf provides several advantages: +- Strict Lint Checks: Ensures a consistent code style across the team and helps prevent potential bugs. +- Simplified Build Process: Reduces the complexity of configuring protoc commands with multiple options. +- CI/CD Integration: Easily integrates automatic linting, formatting, and validation into the CI/CD pipeline. +- Module Management: Simplifies dependency management with Buf modules. + +## Installation Instructions + +Buf CLI setup guide see this [Install the Buf CLI](https://buf.build/docs/cli/installation/): + +## Notes on commands + +```bash +make buf-lint ## lint +make buf-format ## format -w +``` diff --git a/peerswaprpc/Dockerfile b/peerswaprpc/Dockerfile index 8eabcd81..81c48375 100644 --- a/peerswaprpc/Dockerfile +++ b/peerswaprpc/Dockerfile @@ -11,6 +11,7 @@ ARG GRPC_GATEWAY_VERSION ENV PROTOC_GEN_GO_GRPC_VERSION="v1.1.0" ENV GOCACHE=/tmp/build/.cache ENV GOMODCACHE=/tmp/build/.modcache +ENV GOBIN=/usr/local/bin RUN echo ${PROTOC_GEN_VERSION} @@ -21,7 +22,7 @@ RUN cd /tmp \ && go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@${PROTOC_GEN_GO_GRPC_VERSION} \ && go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@${GRPC_GATEWAY_VERSION} \ && go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@${GRPC_GATEWAY_VERSION} \ - && GOBIN=/usr/local/bin go install github.com/bufbuild/buf/cmd/buf@v1.50.0 \ + && go install github.com/bufbuild/buf/cmd/buf@v1.50.0 \ && chmod -R 777 /tmp/build/ WORKDIR /build diff --git a/peerswaprpc/Makefile b/peerswaprpc/Makefile index 96c76b7c..d7e43b44 100644 --- a/peerswaprpc/Makefile +++ b/peerswaprpc/Makefile @@ -8,11 +8,19 @@ STUBS= \ all-rpc: buf generate +.PHONY: all-rpc + +buf-lint: + buf lint +.PHONY: all-rpc + +buf-format: + buf format -w +.PHONY: all-rpc clean-rpc: rm -f ${STUBS} -.PHONY: all-rpc-docker all-rpc-docker: ./gen_protos_docker.sh - +.PHONY: all-rpc-docker diff --git a/peerswaprpc/peerswaprpc.proto b/peerswaprpc/peerswaprpc.proto index 91198134..2632fa3a 100644 --- a/peerswaprpc/peerswaprpc.proto +++ b/peerswaprpc/peerswaprpc.proto @@ -1,190 +1,185 @@ -syntax = "proto3"; - -package peerswap; - -option go_package = "github.com/elementsproject/peerswap/peerswaprpc"; - -service PeerSwap { - rpc SwapOut(SwapOutRequest) returns (SwapResponse); - rpc SwapIn(SwapInRequest) returns (SwapResponse); - rpc GetSwap(GetSwapRequest) returns (SwapResponse); - rpc ListSwaps(ListSwapsRequest) returns (ListSwapsResponse); - rpc ListPeers(ListPeersRequest) returns (ListPeersResponse); - rpc ListRequestedSwaps(ListRequestedSwapsRequest) returns (ListRequestedSwapsResponse); - rpc ListActiveSwaps(ListSwapsRequest) returns (ListSwapsResponse); - - // policy - rpc AllowSwapRequests(AllowSwapRequestsRequest) returns (Policy); - rpc ReloadPolicyFile(ReloadPolicyFileRequest) returns (Policy); - rpc AddPeer(AddPeerRequest) returns (Policy); - rpc RemovePeer(RemovePeerRequest) returns (Policy); - rpc AddSusPeer(AddPeerRequest) returns (Policy); - rpc RemoveSusPeer(RemovePeerRequest) returns (Policy); - - // Liquid Stuff - rpc LiquidGetAddress(GetAddressRequest) returns (GetAddressResponse); - rpc LiquidGetBalance(GetBalanceRequest) returns (GetBalanceResponse); - rpc LiquidSendToAddress(SendToAddressRequest) returns (SendToAddressResponse); - - rpc Stop(Empty) returns (Empty); -} - - - -message GetAddressRequest {} - -message GetAddressResponse { - string address = 1; -} - -message GetBalanceRequest {} - -message GetBalanceResponse { - uint64 sat_amount = 1; -} - -message SendToAddressRequest { - string address = 1; - uint64 sat_amount = 2; -} - -message SendToAddressResponse { - string tx_id = 1; -} - -message SwapOutRequest { - uint64 channel_id = 1; - uint64 swap_amount = 2; - string asset = 3; - bool force = 4; -} - -message SwapOutResponse { - PrettyPrintSwap swap = 1; -} - -message SwapInRequest { - uint64 channel_id = 1; - uint64 swap_amount = 2; - string asset = 3; - bool force = 4; -} - -message SwapResponse { - PrettyPrintSwap swap = 1; -} - -message GetSwapRequest { - string swap_id = 1; -} - -message ListSwapsRequest {} - -message ListSwapsResponse { - repeated PrettyPrintSwap swaps = 1; -} - -message ListPeersRequest {} - -message ListPeersResponse { - repeated PeerSwapPeer peers = 1; -} - -message ReloadPolicyFileRequest {} - -message AddPeerRequest { - string peer_pubkey = 1; -} - -message RemovePeerRequest { - string peer_pubkey = 1; -} - -message ListRequestedSwapsRequest {} - -message ListRequestedSwapsResponse { - map requested_swaps = 1; -} - -message RequestSwapList { - repeated RequestedSwap requested_swaps = 1; -} - -message RequestedSwap { - string asset = 1; - uint64 amount_sat = 2; - SwapType swap_type = 3; - string rejection_reason = 4; - - enum SwapType { - SWAP_IN = 0; - SWAP_OUT = 1; - } -} - -message PrettyPrintSwap { - string id = 1; - int64 created_at = 2; - string asset = 3; - string type = 4; - string role = 5; - string state = 6; - string initiator_node_id = 7; - string peer_node_id = 8; - uint64 amount = 9; - string channel_id = 10;; - string opening_tx_id = 11; - string claim_tx_id = 12; - string cancel_message = 13; - uint64 lnd_chan_id = 14; -} - -message PeerSwapPeer { - string node_id = 1; - bool swaps_allowed = 2; - repeated string supported_assets = 3; - repeated PeerSwapPeerChannel channels = 4; - SwapStats as_sender = 5; - SwapStats as_receiver = 6; - uint64 paid_fee = 7; -} - -message PeerSwapPeerChannel { - uint64 channel_id = 1; - uint64 local_balance = 2; - uint64 remote_balance = 3; - bool active = 5; -} - -message SwapStats { - uint64 swaps_out = 1; - uint64 swaps_in = 2; - uint64 sats_out = 3; - uint64 sats_in = 4; -} - -message PeerSwapNodes { - string node_id = 1; -} - -message Policy { - uint64 reserve_onchain_msat = 1; - uint64 min_swap_amount_msat = 2; - bool accept_all_peers = 3; - bool allow_new_swaps = 4; - repeated string allowlisted_peers = 5; - repeated string suspicious_peer_list = 6; -} - -message AllowSwapRequestsRequest { - bool allow = 1; -} - -message AllowSwapRequestsResponse { - bool allow = 1; -} - - -message Empty { - -} +syntax = "proto3"; + +package peerswap; + +option go_package = "github.com/elementsproject/peerswap/peerswaprpc"; + +service PeerSwap { + rpc SwapOut(SwapOutRequest) returns (SwapResponse); + rpc SwapIn(SwapInRequest) returns (SwapResponse); + rpc GetSwap(GetSwapRequest) returns (SwapResponse); + rpc ListSwaps(ListSwapsRequest) returns (ListSwapsResponse); + rpc ListPeers(ListPeersRequest) returns (ListPeersResponse); + rpc ListRequestedSwaps(ListRequestedSwapsRequest) returns (ListRequestedSwapsResponse); + rpc ListActiveSwaps(ListSwapsRequest) returns (ListSwapsResponse); + + // policy + rpc AllowSwapRequests(AllowSwapRequestsRequest) returns (Policy); + rpc ReloadPolicyFile(ReloadPolicyFileRequest) returns (Policy); + rpc AddPeer(AddPeerRequest) returns (Policy); + rpc RemovePeer(RemovePeerRequest) returns (Policy); + rpc AddSusPeer(AddPeerRequest) returns (Policy); + rpc RemoveSusPeer(RemovePeerRequest) returns (Policy); + + // Liquid Stuff + rpc LiquidGetAddress(GetAddressRequest) returns (GetAddressResponse); + rpc LiquidGetBalance(GetBalanceRequest) returns (GetBalanceResponse); + rpc LiquidSendToAddress(SendToAddressRequest) returns (SendToAddressResponse); + + rpc Stop(Empty) returns (Empty); +} + +message GetAddressRequest {} + +message GetAddressResponse { + string address = 1; +} + +message GetBalanceRequest {} + +message GetBalanceResponse { + uint64 sat_amount = 1; +} + +message SendToAddressRequest { + string address = 1; + uint64 sat_amount = 2; +} + +message SendToAddressResponse { + string tx_id = 1; +} + +message SwapOutRequest { + uint64 channel_id = 1; + uint64 swap_amount = 2; + string asset = 3; + bool force = 4; +} + +message SwapOutResponse { + PrettyPrintSwap swap = 1; +} + +message SwapInRequest { + uint64 channel_id = 1; + uint64 swap_amount = 2; + string asset = 3; + bool force = 4; +} + +message SwapResponse { + PrettyPrintSwap swap = 1; +} + +message GetSwapRequest { + string swap_id = 1; +} + +message ListSwapsRequest {} + +message ListSwapsResponse { + repeated PrettyPrintSwap swaps = 1; +} + +message ListPeersRequest {} + +message ListPeersResponse { + repeated PeerSwapPeer peers = 1; +} + +message ReloadPolicyFileRequest {} + +message AddPeerRequest { + string peer_pubkey = 1; +} + +message RemovePeerRequest { + string peer_pubkey = 1; +} + +message ListRequestedSwapsRequest {} + +message ListRequestedSwapsResponse { + map requested_swaps = 1; +} + +message RequestSwapList { + repeated RequestedSwap requested_swaps = 1; +} + +message RequestedSwap { + string asset = 1; + uint64 amount_sat = 2; + SwapType swap_type = 3; + string rejection_reason = 4; + + enum SwapType { + SWAP_IN = 0; + SWAP_OUT = 1; + } +} + +message PrettyPrintSwap { + string id = 1; + int64 created_at = 2; + string asset = 3; + string type = 4; + string role = 5; + string state = 6; + string initiator_node_id = 7; + string peer_node_id = 8; + uint64 amount = 9; + string channel_id = 10; + string opening_tx_id = 11; + string claim_tx_id = 12; + string cancel_message = 13; + uint64 lnd_chan_id = 14; +} + +message PeerSwapPeer { + string node_id = 1; + bool swaps_allowed = 2; + repeated string supported_assets = 3; + repeated PeerSwapPeerChannel channels = 4; + SwapStats as_sender = 5; + SwapStats as_receiver = 6; + uint64 paid_fee = 7; +} + +message PeerSwapPeerChannel { + uint64 channel_id = 1; + uint64 local_balance = 2; + uint64 remote_balance = 3; + bool active = 5; +} + +message SwapStats { + uint64 swaps_out = 1; + uint64 swaps_in = 2; + uint64 sats_out = 3; + uint64 sats_in = 4; +} + +message PeerSwapNodes { + string node_id = 1; +} + +message Policy { + uint64 reserve_onchain_msat = 1; + uint64 min_swap_amount_msat = 2; + bool accept_all_peers = 3; + bool allow_new_swaps = 4; + repeated string allowlisted_peers = 5; + repeated string suspicious_peer_list = 6; +} + +message AllowSwapRequestsRequest { + bool allow = 1; +} + +message AllowSwapRequestsResponse { + bool allow = 1; +} + +message Empty {}