goupnumber/gun

The Go Up Number Wallet

Go Up Number!  

gun is a CLI Bitcoin wallet for plebs, degenerates and revolutionaries.

Its distinguishing feature is the ability to do peer-to-peer betting.

See gun.fun for full documentation.

⚠ WARNING EXPERIMENTAL

The wallet is beta quality. It is buggy and is missing features. The underlying wallet functionality is built with the awesome Bitcoin Dev Kit but the betting functionality is freshly engineered. Only put into it what you are willing to lose. Thanks for testing this for me and thank you in advance for any coins you sacrifice along the way.

Quick Install

git clone https://github.com/LLFourn/gun
cd gun
cargo install --path .
# Make sure ~/.cargo/bin is in your $PATH

The minimum supported rust version for gun is 1.56.0.

To setup your wallet see gun setup --help.

Community

Join us on Discord

gun's Issues

gun migrate

It should be possible to take an existing gun wallet and migrate it to a new setup. This would take the same arguments as gun setup but would create a tx sending all the existing coins to the new wallet afterwards.

Is text direction breaking zsh?

a proposal like:

0.00089689#h00.ooo#/random/2021-08-25T01:00:00/heads_tails.winner#бӇڬਪƫෆཅۄဧઙϢโސޑఉලઞਢਈསཝէɒʼnɍਉѬચಪဒබഇຖޛݟζஊȭՀڠݮၜξץߦȾԗՍØØ

when pasted into a zsh terminal might make weird stuff happen. The solution might be to to use right-to-let characters in base2048.

Detect broadcasted bet tx from offerer's side as it enters mempool

gun init with coldcard sd path

You should be able to inititialize gun with a coldcard:

gun init coldcard /path/to/sd-card

It should be able to read the PSBT in some format and initialize the wallet in a similar manner to #62 but instead reading the descriptor info from the exported keys. It should also set the psbt output dir to the appropriate place.

gun init with arbitrary descriptor

We should be able to initialize the wallet with an arbitrary descriptor like gun init <external-descriptor> [<internal-descriptor>]

With no change descriptor:

gun init descriptor "wpkh([AAB893A5/84'/0'/0']xpub661MyMwAqRbcFGjD5niBpcDJ1evbWb51fZ5N29BZRykhud3gEefAvjKvoqGVYXBnBS8JqN1cqCpZg8qJqSPjn9dJNamSXJj/0/*

With a change descriptor:

gun init descriptor "wpkh([AAB893A5/84'/0'/0']xpub661MyMwAqRbcFGjD5niBpcDJ1evbWb51fZ5N29BZRykhud3gEefAvjKvoqGVYXBnBS8JqN1cqCpZg8qJqSPjn9dJNamSXJj/0/*)" "wpkh([AAB893A5/84'/0'/0']xpub661MyMwAqRbcFGjD5niBpcDJ1evbWb51fZ5N29BZRykhud3gEefAvjKvoqGVYXBnBS8JqN1cqCpZg8qJqSPjn9dJNamSXJj/1/*)"

The above should simplify to the below:

gun init xpub "[AAB893A5/84'/0'/0']xpub661MyMwAqRbcFGjD5niBpcDJ1evbWb51fZ5N29BZRykhud3gEefAvjKvoqGVYXBnBS8JqN1cqCpZg8qJqSPjn9dJNamSXJj" 

Implementation

I think the way this information should be stored should just be in the WalletKey enum like:

enum WalletKey {
    SeedWordsFile,
    Descriptor  { external: String, internal: Option<String> }
} 

And in the config.json like:

{ 
   "kind": "descriptor",
   "external" : "wpkh([AAB893A5/84'/0'/0']xpub661MyMwAqRbcFGjD5niBpcDJ1evbWb51fZ5N29BZRykhud3gEefAvjKvoqGVYXBnBS8JqN1cqCpZg8qJqSPjn9dJNamSXJj/0/*)",
   "internal" "wpkh([AAB893A5/84'/0'/0']xpub661MyMwAqRbcFGjD5niBpcDJ1evbWb51fZ5N29BZRykhud3gEefAvjKvoqGVYXBnBS8JqN1cqCpZg8qJqSPjn9dJNamSXJj/1/*)"
}

Signing

I think the right thing to do is output the PSBT if a transaction is not finalized after signing. They should be output to psbt-output-dir (default should be $GUN_DIR/psbts). The filename should be <tentative-txid>.psbt. You can get the tentative-txid by doing psbt.extract_tx().txid().

At the moment let's just hang and wait for the user to sign the PSBT there. Whenever they press enter read the file back in and check if it has been signed. Once it has been signed, broadcast it.

Choosing the network

Right now we have a mandatory <network> argument to init. This should just be made into a optional --network argument with the default being "bitcoin"

Init with seed

The existing gun init should go under gun init seed.

Attempting to use absolute fees in send transaction fails

The help output for gun send indicates that one can use abs:300 to define the absolute number of sats for the fee

ARGS:
    <value>    The amount to send with denomination e.g. 0.1BTC
    <to>       The address to send the coins to
    <fee>      The transaction fee to attach e.g. spb:4.5 (4.5 sats-per-byte), abs:300 (300 sats absolute fee), in-
               blocks:3 (set fee so that it is included in the next three blocks) [default: in-blocks:1]

but attempting to build a transaction using absolute amount returns the following error:

❯ gun send 0.0001BTC mkHS9ne12qx9pS9VojpwU5xtRd4T7X7ZUt abs:300
error: Invalid value for '<fee>': unknown denomination:

Is there supposed to be a denomination there if we want to use straight sats? I tried SAT but it didn't work. Of course simply defining it in BTC did work. Just wondering if sats are an option, as per the help note.

Related to this: the note for ` explains one is required to provide a denomination, and one example is provided. It feels like there may be others but we're left wondering what they are. Are they listed anywhere else in the help?

Improve `-s` command modifier output

Right now it outputs something like:

syncing wallet with Esplora(EsploraBlockchainConfig { base_url: "https://mempool.space/api", concurrency: Some(4), stop_gap: 100 })

But it there should be more information here and it should be nicely formatted:

1. progress logging
2. when you do gun -s bet list it should mention which bets it is checking and output something useful if possible.

gun chooses too many inputs.

gun will sometimes choose additional inputs even when it has a single input that would cover the bet. We want as few as possible so everything fits into a tweet. Right now we are just deferring to the branch and bound algorithm that BDK uses. Need to investigate why it does this.

More powerful tx construction API

gun send only allows single address sends but we should allow building arbitrary transactions.

I'm not sure what the CLI api should be but something like:

gun psbt build \
    -i 931043e6794c465665684fe0ef8c3ed070502bddd58ec7b07fe3aa2a9bbe3bf4:0 \
    -i 2a9cd9d7ff02f0863335cbbe1908ad2b263935ddbad555b1b806ab168c22d7a7:1 \
    -o bc1qw6h3w0g2446j2ycfe8h87sufethtawmsut8s9t:0.1BTC \
    -o bc1q07sq6ch5gajwcr05c7nsdmegnyfsuw3lawgwul:0.3BTC \
    --fee rate:5.1

This would output a PSBT.

You'd then have a gun psbt sign command to sing it and a gun psbt broadcast to check if it's finalized and try and broadcast it.

This is necessary to use gun as part of a traditional multisig setup where it isn't the initiating signer. i.e. where you just have a gun on a laptop and get PSBTs and sign them from there.

Add strategies in docs to enhance utxo onchain privacy in 'gun bet propose'

https://gun.fun/bet/propose.html

Would be helpful to offer strategies for how to set up the onchain utxo that will be offered in a public proposal. These sorts of situations offer zero margin for error since privacy leaks cannot be undone.

I don't want to turn this into yet another privacy argument but I do think a good gun user should be aware of all the options and then pick accordingly (personal time preference and competence level). Including this in the docs may be out of scope for the project but seeing as how it's onchain I don't see how any discussion of this protocol can escape the perils of poor onchain fungibility.

There are two strategies (this is an ordered list);

1. coinjoin (all things considered this is the best option because its the most secure way to enhance privacy) (this is an unordered list!!)

   • whirlpool (samurai or sparrow wallet) (easy to use but expensive)
   • joinmarket (hard to use but cheap)
   • wasabi wallet (I can't comment on this since I haven't personally used it, but I understand that this is an effective privacy enhancing tool that requires proper coin control on the user side)

2. lightning to onchain via no-kyc exchange.
   The exchange has no idea where the LN sats came from and they don't know who owns the newly created UTXO, outside observers only see an exchange whitdrawal and would have to ask the exchange who sent the deposit (cheaper, steganographic, much less secure since it requires custodians in most cases (sans submarine swaps but I'm still not 100% sure what the privacy implications of that protocol are), much lower liquidity, much faster and with more competing options)

   • muun/phoenix wallet (or full LN node) and boltz exchange

3. self-mining

4. there are other ways but these methods are verboten and shall not be discussed nor encouraged. Well maybe we can discuss them but we really can't encourage them.

If there are any other workable strategies I would like to hear them.

Plebs (and degens alike) should not shy away from participating in this because of a fear of doxxing their stash.

Spending the utxo after a winning bet also presents privacy challenges.

use clippy

I think #19 could have been caught by clippy.

Add gun bet bump

We should be able to bump the fee of a tx of a bet in the unconfirmed state via CPFP by spending from the change output.

The annoying thing about this is that it implies that bet tx always need change outputs for both parties I guess.

--spend-in-use should set bets to cancelling

Support signet wallets

As a stepping stone for taproot.

Transaction display needs to be annotated

Which output is the bet output, which is whose change output etc.

Make releases for all platforms

Perhaps using https://github.com/rust-embedded/cross

split should send to last unused change address

Otherwise after you cancel a split you increment the change index too much without using any addresses inbetween.

Make <choice> optional argument in gun bet offer

If it's left out display the two possible outcomes and prompt user for their choice.

Use BIP39 passphrase to encrypt plaintext mnemonic

This is what samurai wallet uses and I think its a user-friendly and effective way to secure the mnemonic.

Firing the gun in regtest

I am wondering what would it require to add regtest RPC backend support in gun. I want to be able to create regtest betting transaction and test out various betting scenarios. Can be useful for automated integration testing too.

Is it possible right now? If not what needs to be done to bet on local regtest?

gun is meant to be fun and yet... (emojis)

it doesn't output any emojis. Right now the command logic is full of eprintln. I think we should replace every eprintln with a custom function for the purpose of the message so it can be formatted correctly.

for example, if it's warning the user about something prefix the message with the ⚠️ emoji would be appropriate. If something worked prefix it with 🎉 and so on.

you are able to propose to events with more than 2 outcomes

--yes is broken

A lot of the changes we made in v0.6 means that --yes probably won't work very well. The value isn't passed down to the signers. Probably the solution is to pass a reference to something into the signers that we can mutate later by the signers.

Add gun broadcast command

We need to be able to broadcast a signed transaction. The most important bit is that we can broadcast PSBTs but I guess we should also support broadcasting a raw transaction hex. I think the command should be:

gun broadcast [<tx-file>]

<tx-file> can be a path to either a PSBT encoded as base64 or binary. Or it can be a raw consensus encoded transaction. If <tx-file> is - gun should read it from STDIN.

If is missing and psbt-output-dir from #62 is set then gun should go through each .psbt file in psbt-output-dir and broadcast it if it looks finalized.

show unsued addresses

There should be a way to only show unused addresses when listing addresses.

Coin control

It would be great if there were a way to select specific utxos when spending, bypassing whatever existing coin selection algorithm exists.

Brainstorming some ideas for how this could work

• Pass list of addresses/utxos via a flag --spend-from - perhaps poor UX but also extensible for gun as a cli
• Like above, but instead pass address indexes with a flag - would probably want address list to include an index column so these are accessible. We would also have to make some distinction on internal/external..
• Interactive menu where you can toggle UTXOs - would be nice, but also not very CLI-like (could be built on top of --spend-from)

Other ideas?

It is not clear to offerer that they are the one paying the fee

Discord link broken

I wanted to join the discord, but the invite appears to be broken 😿

'address list' doesn't list utxos from 'split'

I first sent myself 100k sats, then I split into two, then I noticed the bug and tried to do it again so I did a "send all" to one address, then split into three again.

un -d $(pwd)/test split 30000sat
> This is the transaction that will be broadcast.
> ╔═════╦════════════════════════════════════════════════════════════════════╦══════════════╗
> ║ in  ║ fbca9506d0de7ecad0e0979fb1127349ae19ecb1d2517479b8d794ea3626bf27:0 ║ 0.00 099 678 ║
> ╠═════╬════════════════════════════════════════════════════════════════════╬══════════════╣
> ║     ║ total                                                              ║ 0.00 099 678 ║
> ╠═════╬════════════════════════════════════════════════════════════════════╬══════════════╣
> ║ out ║ tb1qsrjk4wa9z53wehe7j2zc3ysy09lrapc87ee3t5                         ║ 0.00 009 475 ║
> ╠═════╬════════════════════════════════════════════════════════════════════╬══════════════╣
> ║     ║ tb1qqm4eprhj5nhzzhvr2qn2z2f4899nrua9ckmala                         ║ 0.00 030 000 ║
> ╠═════╬════════════════════════════════════════════════════════════════════╬══════════════╣
> ║     ║ tb1q8tul7q9z97eazxxyfpd94m8xn28qskcls4yey2                         ║ 0.00 030 000 ║
> ╠═════╬════════════════════════════════════════════════════════════════════╬══════════════╣
> ║     ║ tb1qgca8xw8c4t0834e655t6vfk3auesjjgdpl9pz6                         ║ 0.00 030 000 ║
> ╠═════╬════════════════════════════════════════════════════════════════════╬══════════════╣
> ║     ║ total                                                              ║ 0.00 099 475 ║
> ╠═════╬════════════════════════════════════════════════════════════════════╬══════════════╣
> ║ fee ║ 1.004 sats/vb                                                      ║ 0.00 000 203 ║
> ╚═════╩════════════════════════════════════════════════════════════════════╩══════════════╝
> Ok [y/n]? y
╔══════╦══════════════════════════════════════════════════════════════════╗
║ txid ║ a2d9d7848c2b711051cd4317088501ed9faa3885232ebbb4addcb73b7ac1ac80 ║
╚══════╩══════════════════════════════════════════════════════════════════╝

gun -d $(pwd)/test -s address list
syncing wallet with Esplora(EsploraBlockchainConfig { base_url: "https://blockstream.info/testnet/api", concurrency: Some(4), stop_gap: 10 })
╔════════════════════════════════════════════╦═══════╦═══════╗
║ address                                    ║ value ║ utxos ║
╠════════════════════════════════════════════╬═══════╬═══════╣
║ tb1qv04v98ehqtnfgjyey5gaffhlg2jeruvl43m8gn ║ 0     ║ 0     ║
╠════════════════════════════════════════════╬═══════╬═══════╣
║ tb1qla6ll870hzr4p83wv9dxd2yn0psuywme853x5w ║ 0     ║ 0     ║
╚════════════════════════════════════════════╩═══════╩═══════╝

gun -d $(pwd)/test -s tx list
syncing wallet with Esplora(EsploraBlockchainConfig { base_url: "https://blockstream.info/testnet/api", concurrency: Some(4), stop_gap: 10 })
╔══════════════════════════════════════════════════════════════════╦═════════╦═════════════════════╦══════════════╦══════════════╗
║ txid                                                             ║ height  ║ seen                ║ sent         ║ received     ║
╠══════════════════════════════════════════════════════════════════╬═════════╬═════════════════════╬══════════════╬══════════════╣
║ a0296d39399043643f7b3ad351bcf5023f7071015461ce45549e0bb408c2cc7c ║ 2099501 ║ 2021-10-17T18:52:14 ║ 0.00 100 000 ║ 0.00 099 857 ║
╠══════════════════════════════════════════════════════════════════╬═════════╬═════════════════════╬══════════════╬══════════════╣
║ aa0bd640878d2713328670e3aa58b01add70d5e8cc65f54b08a2bda617d32203 ║ 2099498 ║ 2021-10-17T18:29:37 ║ 0            ║ 0.00 100 000 ║
╠══════════════════════════════════════════════════════════════════╬═════════╬═════════════════════╬══════════════╬══════════════╣
║ fbca9506d0de7ecad0e0979fb1127349ae19ecb1d2517479b8d794ea3626bf27 ║ -       ║ -                   ║ 0.00 099 857 ║ 0.00 099 678 ║
╠══════════════════════════════════════════════════════════════════╬═════════╬═════════════════════╬══════════════╬══════════════╣
║ a2d9d7848c2b711051cd4317088501ed9faa3885232ebbb4addcb73b7ac1ac80 ║ -       ║ -                   ║ 0.00 099 678 ║ 0.00 099 475 ║
╚══════════════════════════════════════════════════════════════════╩═════════╩═════════════════════╩══════════════╩══════════════╝