Stacks - Lightning Network Bridge

[pseudozach]

Background
What problems do you aim to solve? How does it serve the mission of a user owned internet?

• This grant application aims to provide a 2-way non-custodial bridge between Stacks chain and Lightning Network.
• This will increase liquidity on both sides, allow Stacks users to pay any Lightning Network invoice with STX by enabling LN app developers to integrate this service's API. Similarly some Stacking pools may allow STX Stacking by accepting bitcoin payments via Lightning Network.

Project Overview
What solution are you providing? Who will it serve?

• As part of this grant a new submarine swap implementation will be created and open sourced. This service will run an API that's reachable publicly and a front-end will serve non-custodial swaps between STX and bitcoin on Lightning Network.
  

• This service will serve users that want a quick & non-custodial way to swap and services that want to accept other coins but do not want to deal with custody.

• For instance this tweet, on integrating LN payments for Stacks apps, will be easily answered by integrating with this API: https://twitter.com/muneeb/status/1400134618230185985?s=19

Scope
What are the components or technical specs of the project? What will the final deliverable look like? How will you measure success?

• Clarity contract that implements all required methods for submarine/reverse-submarine swaps

• Backend server/API that manages an LN node, tracks payments to the clarity contract and executes swaps/refunds in case of failures in a non-custodial manner.

• Frontend that makes it easy to complete swaps by preparing contract calls and guiding regular users through swap steps.

• Once all the components are developed and deployed, we'll track usage if there's more demand for regular users to do non-custodial swaps or check if there's demand from both STX and LN app developers if an API is more useful, and focus accordingly.

Budget and Milestones
What grant amount are you seeking? How long will the project take in hours? If more than 20, please break down the project into milestones, with a clear output (e.g., low-fi mockup, MVP with two features) and include the estimated work hours for each milestone.

• M1
  SoW: Clarity contract with required methods/checks/data structures for STX-LN swaps.
  Deliverables: Contract code pushed to github, deployed to testnet.
  Approx. Timeline: 1 month/100 hours
  Grant Amount: $3000
• M2
  SoW: Backend Server Implementation that can track/command LN node, track/communicate with Stacks contract.
  Deliverables: Server code pushed to github, deployed to testnet.
  Approx. Timeline: 1 month/100 hours
  Grant Amount: $4000
• M3
  SoW: Frontend Implementation to connect all components and guide user through UX to complete successful submarine/reverse-submarine swaps.
  Deliverables: Frontend code pushed to github, deployed to testnet. Further testing and deploying all deliverables to mainnet.
  Approx. Timeline: 1 month/100 hours
  Grant Amount: $3000

Total Grant Request: $10000

Team
Who is building this? What relevant experience do you bring to this project? Are there skills sets you are missing that you are seeking from the community? Please share links to previous work.

• I will be building this. Recently completed a similar work (RSK/ERC20 on RSK - LN bridge) for another hackathon
• I've also finished and delivered my previous grant application prediction market on STX
• I already have offers from other blockchain devs to work together and if I have issues with delivery, will definitely enlist help from community/existing offers.

Risks
What dependencies or obstacles do you anticipate? What contingency plans do you have in place?

• Do not foresee any fundamental building block missing from Clarity regarding smart contracts to complete submarine swaps on Stacks chain.
• Currently researching tracking smart contract transactions via websockets. This will avoid the need to constantly query REST API for incoming contract calls to the swap contract.

Community and Supporting Materials
Do you have previous projects, code commits, or experiences that are relevant to this application? What community feedback or input have you received? How do you plan to share your plan to the community over time and as the final deliverable?

• Fork of boltz (non-custodial submarine swap service) that I've adapted for RSK and deployed: https://github.com/pseudozach/lnsovbridge
• Similarly the frontend for the same service that implements same principals for EVM chains: https://github.com/pseudozach/boltz-frontend
• I'll use discord as main communication with the community and developers for feedback and guidance. I had discussed this with Marvin during btc.us launch and received positive feedback that this could be useful.

[stx-grant-bot]

Thanks for submitting a grant proposal. Our team will review your submission and get back to you.

[RaffiSapire]

Hi @pseudozach! We love this idea and would like to better understand the kind of support you’ll need to successfully complete this. Can you please schedule a quick call with Marvin to https://calendly.com/marvin-stacks.

[pseudozach]

Calendly link shows no available slots, I'll try to reach out to Marvin via Discord and discuss.

[stx-grant-bot]

Congratulations. Your grant is now approved. Please complete the on-boarding link here: https://stacks-grant.netlify.app/onboard?q=896d058f896dbf92fb5189578a20c150

[pseudozach]

Hi,
stxswap clarity contract is deployed to testnet (v3): https://explorer.stacks.co/txid/0xff7f57b68d1606502c602da608439b6ac1b9d2c6d9480332f23bf4ec888ad0cd?chain=testnet

• All basic functions like lock/claim/refund are tested and working as intended.
• Scaffolding code, including v1 of contracts are pushed to github: https://github.com/pseudozach/lnstxbridge

This concludes M1, I'll continue on M2.
Thanks,

[philiphacks]

@pseudozach nice work! some of the comments on the testnet contract still refer to Eth, I guess that should be STX?

Question.. could you extend this for SIP10 tokens in general? Would be great to have LN invoices paid with Arkadiko's stablecoin USDA

[pseudozach]

@pseudozach nice work! some of the comments on the testnet contract still refer to Eth, I guess that should be STX?

Question.. could you extend this for SIP10 tokens in general? Would be great to have LN invoices paid with Arkadiko's stablecoin USDA

yes, I've noticed those after I deployed :), v2 will not have those references and I've also found a few potential improvements so I'll deploy v2 and update here (edit: done).

The concept is certainly adaptable to SIP10 token exchange but SIP10 - LN swap contract would need to be developed, and backend/frontend would need work as well. maybe I can add that as M4, @RaffiSapire would that be ok?

If approved, I can add a new milestone as below to support SIP10 swaps:

M4
SoW: Create and deploy a new swap contract that supports SIP10 tokens. Update backend server Implementation to support SIP10 tokens. Update frontend to fetch rates and enable SIP10 tokens.
Deliverables: Contract deployed, Server & Client code pushed to github, deployed to testnet/mainnet.
Approx. Timeline: 1 month/100 hours
Grant Amount: $4000

[pseudozach]

I'm happy to share a working demo of a successful submarine swap going from STX (mocknet) -> Bitcoin on Lightning Network (regtest): https://youtu.be/2GkRO_KLw4k

Work on M2 and M3 is ongoing in parallel (and pending approval of M4), although lots of things to cover until it's ready for production, feels good to have a working demo of a sample scenario :)

[philiphacks]

watched the demo, looks great @pseudozach!

[pseudozach]

!M1_Complete

[stx-grant-bot]

Thank you for completing M1. The grant committee will review and confirm completion or send feedback within a week

[MarvinJanssen]

Hi Zach, I'm leaving some comments and questions on behalf of the grant committee:

1. Why are you submitting all numbers as buffers and then converting them in Clarity? Is there a specific reason why you do not prepare the right CV types in the client? It would lower runtime cost for the contract.
2. claimAddress does not actually seem to be used. In fact, there is a vulnerability in refundStx that allows anyone to claim the STX tokens for expired swaps. The tx-sender and the original swap submitter are not checked.
3. We do not think adding SIP010 support would take 1 month/100 hours of work. Could you elaborate on the timeline? (Is it much more than going from stx-transfer? to a contract-call? to the token contract?) You can also hit two birds with one stone as the SIP009 and SIP010 transfer functions are compatible.

Reference that can help:

• https://github.com/MarvinJanssen/stx-atomic-swap/tree/master/stx/contracts

Great video by the way! Very exciting stuff.

[pseudozach]

Thanks for the feedback Marvin. Please find my answers inline.

1. Why are you submitting all numbers as buffers and then converting them in Clarity? Is there a specific reason why you do not prepare the right CV types in the client? It would lower runtime cost for the contract.

• This is because submarine swaps work by generating a hash of the provided inputs which needs to be unique and calculate to something noone else can guess, in clarity I was able to accomplish this by using keccak256 which accepts inputs of same type. I went with buffer and ignored claimAddress/refundAddress which will be removed in a later version of the contract.

2. claimAddress does not actually seem to be used. In fact, there is a vulnerability in refundStx that allows anyone to claim the STX tokens for expired swaps. The tx-sender and the original swap submitter are not checked.

• I've noticed that while testing and already uploaded v3 in the github repo a week ago that doesnt have this vulnerability but I haven't deployed to testnet. I'll probably have v4 including above optimizations before I complete M2 and deploy to testnet for public use.

3. We do not think adding SIP010 support would take 1 month/100 hours of work. Could you elaborate on the timeline? (Is it much more than going from stx-transfer? to a contract-call? to the token contract?) You can also hit two birds with one stone as the SIP009 and SIP010 transfer functions are compatible.

• I agree in the scope of clarity contract I do not expect a lot of change there but if you want to peek through the codebase to see the amount of tracking that needs to be done for tokens in nursery, contracthandler and contracteventhandler I think you'll agree it takes a lot of effort to cover all scenarios to support tokens.
• So far I was able move a little faster and finish before 1 month but only because I've been spending so much time (probably more than 100 hours) working on this. Feel free to look into the amount of code changes in the commit history
• I'm perfectly OK to leave the SIP10 token integration to the community, of course anyone will be welcome to prepare support for it and I'll be happy to merge. I can also update M4 scope to 60 hours ($3000) so I can probably complete it a bit sooner now that I'm more familiar with the codebase.

Thanks,

[RaffiSapire]

Thanks @pseudozach - we are disbursing for M2.

[MarvinJanssen]

• This is because submarine swaps work by generating a hash of the provided inputs which needs to be unique and calculate to something noone else can guess, in clarity I was able to accomplish this by using keccak256 which accepts inputs of same type. I went with buffer and ignored claimAddress/refundAddress which will be removed in a later version of the contract.

I see. And there is no way around that?

• I've noticed that while testing and already uploaded v3 in the github repo a week ago that doesnt have this vulnerability but I haven't deployed to testnet. I'll probably have v4 including above optimizations before I complete M2 and deploy to testnet for public use.

Looks good. Why do you have (default-to 'ST15RGYVK9ACFQWMFFA2TVASDVZH38B4VAV4WF6BJ ... in there?

• I agree in the scope of clarity contract I do not expect a lot of change there but if you want to peek through the codebase to see the amount of tracking that needs to be done for tokens in nursery, contracthandler and contracteventhandler I think you'll agree it takes a lot of effort to cover all scenarios to support tokens.
• So far I was able move a little faster and finish before 1 month but only because I've been spending so much time (probably more than 100 hours) working on this. Feel free to look into the amount of code changes in the commit history
• I'm perfectly OK to leave the SIP10 token integration to the community, of course anyone will be welcome to prepare support for it and I'll be happy to merge. I can also update M4 scope to 60 hours ($3000) so I can probably complete it a bit sooner now that I'm more familiar with the codebase.

Interesting! I had no idea that adding additional support had so many implications. I will bring this into the next committee meeting.

[pseudozach]

• This is because submarine swaps work by generating a hash of the provided inputs which needs to be unique and calculate to something noone else can guess, in clarity I was able to accomplish this by using keccak256 which accepts inputs of same type. I went with buffer and ignored claimAddress/refundAddress which will be removed in a later version of the contract.

I see. And there is no way around that?

This is the only way I could think of that accomplished submarine swaps, with all the security benefits and using the types in clarity. I was hoping I could convert principals <-> buffer as well but that doesn't seem possible at the moment.

• I've noticed that while testing and already uploaded v3 in the github repo a week ago that doesnt have this vulnerability but I haven't deployed to testnet. I'll probably have v4 including above optimizations before I complete M2 and deploy to testnet for public use.

Looks good. Why do you have (default-to 'ST15RGYVK9ACFQWMFFA2TVASDVZH38B4VAV4WF6BJ ... in there?

Just as a fallback account that's for sure not controlled by either party, no special meaning. But now that you mentioned it, I guess it would make sense to have an impossible principal there for added safety. Any suggestions on what I can use?

• I agree in the scope of clarity contract I do not expect a lot of change there but if you want to peek through the codebase to see the amount of tracking that needs to be done for tokens in nursery, contracthandler and contracteventhandler I think you'll agree it takes a lot of effort to cover all scenarios to support tokens.
• So far I was able move a little faster and finish before 1 month but only because I've been spending so much time (probably more than 100 hours) working on this. Feel free to look into the amount of code changes in the commit history
• I'm perfectly OK to leave the SIP10 token integration to the community, of course anyone will be welcome to prepare support for it and I'll be happy to merge. I can also update M4 scope to 60 hours ($3000) so I can probably complete it a bit sooner now that I'm more familiar with the codebase.

Interesting! I had no idea that adding additional support had so many implications. I will bring this into the next committee meeting.

Thanks, let me know the feedback from the committee. This was already quite an undertaking but so far good progress and I personally find it cool to work on.

[friedger]

Just as a fallback account that's for sure not controlled by either party,

Something like (as-contract tx-sender )?

[pseudozach]

All nodes/backend/frontend is now up and reachable at https://lnswap.org. I've also completed a reverse-submarine swap to ensure everything is OK. LN node has low liquidity so please test with small amounts.
Known issues:

• lock tx fee estimation seems wrong, which leads to long wait time for onchain -> LN swaps.
• backend txns sometimes fail with ConflictingNonceInMempool
  cc @314159265359879

[pseudozach]

For the frontend, I see that you don't use connect, nor stacks/transactions. If the libraries do not help, we need to improve the libraries :-)

I do use connect and @stacks/transactions in both views that user clicks to start a contract call here: https://github.com/pseudozach/lnstxbridge-frontend/blob/main/src/views/swap/steps/sendTransaction.js#L15

For other details (postconditions etc) I've commented on the repo issue with more details: pseudozach/lnstxbridge-frontend#1

[pseudozach]

!M3_Complete

[stx-grant-bot]

Thank you for completing M3. The grant committee will review and confirm completion or send feedback within a week

[pseudozach]

The page does not seem to be accessible, pinging the ip and lnswap.org is returning succes however.

Are the transactions send with post-conditions in "allow" mode intentionally?

Users would get a warning, "~unsafe transaction" before the transaction is send, deny mode is preferred on mainnet.

This is fixed, contract calls use deny mode now: pseudozach/lnstxbridge-frontend#1 (comment)

[314159265359879]

Copied from telegram, I thought you'd like to know. I will ask him to post here when it is resolved.

[314159265359879]

This user still has an issue on the second attempt the claim button is unresponsive. He is on Windows 10 and the latest Chromium Edge browser.

He also says thanks pseudozach for making it possible for him to get his first STX.

[pseudozach]

This user still has an issue on the second attempt the claim button is unresponsive. He is on Windows 10 and the latest Chromium Edge browser.

He also says thanks pseudozach for making it possible for him to get his first STX.

thanks to yours and another user report on discord, I've identified and resolved this issue. This is the relevant commit: pseudozach/lnstxbridge-frontend@9ae50b2

[pseudozach]

we've fixed a number of issues and pushed out a new contract version thanks to many users' reports: https://github.com/pseudozach/lnstxbridge/issues/10
I will also improve the frontend with more transparency on the number of swaps & volume info. Open to any other suggestions/feedback on the relevant github repos.