Design a user friendly policy structure visualization

rajarshimaitra commented 1 year ago

Description

The Bitcoin DevKit library allows developers to quickly design a miniscript-based wallet. Miniscript wallets are functional, i.e., the wallet code doesn't depend on the miniscript. By providing a custom miniscript, a BDK-based wallet can accommodate any complex bitcoin spending logic. Often called "Contacts" or "Spending Policy". This is also synonymous with "Smart Contracts" in Bitcoin World.

BDK-CLI is a command-line app that can take it any custom descriptor as input and spawn a BDK wallet in the terminal. This is especially useful for quickly trying complex descriptors before proceeding with more elaborate wallet designs. BDK-CLI has various features and can sync the wallet with RPC, Electrum, or Esplora API endpoints. It also provides tooling to generate and work with mnemonic and Xpubs. The wallet can list transactions, get balances, create, sign, and broadcast transactions.

BDK-CLI has a policy command used to visualize complex miniscript policies. This is important for users to choose between multiple spending paths when signing the transaction. Which is an essential part of user workflow for miniscript-based wallets.

Below is a sample of a 2 of 3 multisig policy visualization.

{
  "external": {
    "contribution": {
      "items": [],
      "m": 2,
      "n": 3,
      "sorted": false,
      "type": "PARTIAL"
    },
    "id": "n2x2uwsd",
    "keys": [
      {
        "pubkey": "029ffbe722b147f3035c87cb1c60b9a5947dd49c774cc31e94773478711a929ac0"
      },
      {
        "pubkey": "025f05815e3a1a8a83bfbb03ce016c9a2ee31066b98f567f6227df1d76ec4bd143"
      },
      {
        "pubkey": "025625f41e4a065efc06d5019cbbd56fe8c07595af1231e7cbc03fafb87ebb71ec"
      }
    ],
    "satisfaction": {
      "items": [],
      "m": 2,
      "n": 3,
      "sorted": false,
      "type": "PARTIAL"
    },
    "threshold": 2,
    "type": "MULTISIG"
  },
  "internal": {
    "contribution": {
      "type": "NONE"
    },
    "fingerprint": "ef2dfe99",
    "id": "f29caev6",
    "satisfaction": {
      "type": "NONE"
    },
    "type": "ECDSASIGNATURE"
  }
}

As can be seen, even for a simple 2 of 3 spending policy, the output needs to be more verbose and easier to visualize the policy. For more complex policies, users not only need to see the policy structure but also have to separate between different policies meaningfully and select which one they want to sign for.

This project aims to design a user-friendly policy visualization and an easy way to select among multiple policies.

Expected Outcomes

Design an easy-to-understand visualization for policy structures.
Implement it for bdk-cli terminal output.
Provide a way for bdk-cli users to choose between spending paths.
Produce a document outlining the design for this representation and gather feedback from the Bitcoin Design Community.

Resources

Output descriptors: https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md
Miniscript: https://bitcoin.sipa.be/miniscript/
complex miniscript generation language: https://min.sc/
bdk-cli based miniscript tutorial: https://bitcoindevkit.org/tutorials/hidden-power-of-bitcoin/
bdk-based graphical policy playground: https://elephant.bitcoindevkit.org/

Skills Required

Hands-on experience with git and GitHub
- Know how to set up your git/GitHub signing key and sign git commits, see Managing commit signature verification
- Basic understanding of miniscript and descriptors.
- Basic operations with bdk-cli app.

Mentor

@rajarshimaitra

Difficulty

Medium

Competency Test

Fork the bdk-cli github repo. Create a pull request and add a proposal.md file to the project's root. This file should outline the design proposal for the policy structure visualization. The PR should be signed.
Go to https://min.sc/ and create the example liquid federation policy in elephant wallet. At the time of signing, the app will create a policy visualization. Take a screenshot of that segment from the app, and add it to your proposal with a brief description of the policy structure.

LLFourn commented 1 year ago

I'm pretty sure we were planning to remove the "policy" module from bdk so this might not be a good idea. It's being replaced with the "planning" module from miniscript. I'm not sure if something equivalent would be available there without significant further work in miniscript which I wouldn't recommend for SOB people.

rajarshimaitra commented 1 year ago

This is not intended to be used within BDK, but as a research project to visualize complex miniscript structures, which is an open problem for a miniscript-based world. Irrespective of the internal mechanism a wallet uses for signing miniscript, users needs to understand the policy structure visually to meaningfully use their wallet.

Another way of putting it is, currently, the signing approach for BDK is "here's your policy structure, what do you wanna sign for", and after planning module it will be users asking "I have these assets, what can I sign for". Both of the cases don't alleviate the user's requirement to understand their miniscript structure. It cannot and should not be abstracted away. In the first case to identify what to sign, and in the second case to collect the right assets.

So rather than a coding challenge, this is more of a design challenge.

I'm pretty sure we were planning to remove the "policy" module from bdk so this might not be a good idea.

The policy module might not be used for signing stuffs in BDK in future, but it's the only thing out there that can decode a miniscript into a structured representation. So in case we wanna remove it later from BDK crate, it might still make sense to keep the module around as an independent utility crate.

rajarshimaitra commented 1 year ago

I have also notified the Bitcoin Design Community on this project and will list more feedback once/if they come.

bitcoindevkit / bdk-cli