Have a question that is not listed here? Let us know!
+ +This FAQ compiles questions that relate to Jam in particular. For things related +to JoinMarket in general, please refer to the JoinMarket documentation.
+Earning sats entails providing liquidity to other market participants. +Consequently, how much you can earn depends on multiple factors, market +conditions and liquidity size being two of them. In general, the more liquidity +you provide, the more you can earn. That being said, you are competing in an +open market, and because competition is global and only constraint by market +forces, the margin is usually thin.
+If your offers are not taken by market participants, your offer might be too +expensive. Check the order book and compare your offer to the +market price. If your offer is competitive and is still ignored, make sure to +create a Fidelity Bond, which signals that you are a serious market +participant and not a malicious entity.
+See also "a few words about incentives" from the JoinMarket +documentation.
+The amount of fees you have to pay depends on market and blockspace +conditions. They are dictated by supply and demand, both for collaborative +transactions and single user transactions.
+Market makers provide liquidity and set the fee they want to earn, +either in absolute or percentage terms. Market takers have to agree +to take these offers voluntarily. Check the orderbook to get an +up-to-date overview of the current fee market.
+In addition to these fees, you will have to pay mining fees for you and the makers. Mining fees depend +on how many transactions are currently in the mempool. Inspect your +mempool or use a public site like mempool.space to do a fee estimation.
+Hint
+We recommended that you run your own mempool.space +instance on your full node.
+See also "a note on fees" from the JoinMarket documentation.
+The following error can pop up in case JoinMarket didnt't shut down cleanly:
+wallet.jmdat cannot be created/opened, it is locked.
+Warning
+Make sure that you have written down your wallet seed before executing +any command
+You can resolve this by manually deleting the wallet .lock file as explained
+in issue #173.
This can have multiple reasons. Tor or general network connection issues, +participants not responding in a timely manner, missing requirements to +source commitments (see the docs), period of slow +block production, unexpected increase of transaction fees, etc.
+For a better assessment, the following can be taken as a guideline:
+If an operation takes longer than that, then there might be a different issue. +See "Something else is/seems stuck" for more info.
+If a single collaborative transaction takes hours, or if your +scheduled sweep already takes over three days, there might be a different +underlying problem.
+A general rule of thumb is: Any operation either succeeds or fails. +If an operation is aborted prematurely, there is no danger of loss of funds.
+All operations can be aborted by locking your wallet.
+Since Jam does not yet have a way to provide fine grained error information to users, +it is always a good idea to inspect the log files for warning and error messages.
+If you are running Jam with one of the supported integrations (RaspiBlitz, +Citadel, Umbrel, etc.) chances are you can view the logs inside the app +(See Settings > Show logs).
+If the option is not displayed, or if you run the standalone docker image
+yourself, you can find all log files inside the container in directory
+/var/log/jam/. See jmwalletd_stdout.log or jmwalletd_stderr.log for
+problems with Jam.
e.g. tail -n 200 -f /var/log/jam/jmwalletd_stdout.log
If you run JoinMarket natively, you can find the logs files inside the logs
+folder of JoinMarket's working directory (e.g. /home/<user>/.joinmarket/logs)
e.g. tail -n 200 -f /home/user/.joinmarket/logs/jmwalletd_logs.log
This can have several reasons and basically means that the UI cannot reach the backend service. +Depending on your installation (native setup, docker images, +local/remote hosts, etc.), there are a number of things you should verify.
+Please make sure that:
+bitcoin-cli getblockchaininfo
+curl --insecure https://127.0.0.1:28183/api/v1/session
+Check the logs for any errors or warnings.
+If all the above fails, try restarting every service or do a complete node reboot.
+As a last resort, seek help in the support channel.
+Yes, it is possible to import an existing wallet. +However, not yet via the web interface, but with a few manual steps via the command line.
+ssh (see an example for Umbrel below)wallet-tool.py script. jmvenv/bin/activate # if virtual environment is enabled
+python3 scripts/wallet-tool.py recover --gap-limit=200 --recoversync
+root@821939a90a7c:/src# python3 scripts/wallet-tool.py recover --gap-limit=200 --recoversync
+User data location: /root/.joinmarket/
+Input mnemonic recovery phrase: zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong
+Input mnemonic extension, leave blank if there isnt one:
+Enter new passphrase to encrypt wallet:
+Reenter new passphrase to encrypt wallet:
+Input wallet file name (default: wallet.jmdat): recover.jmdat
+Would you like this wallet to support fidelity bonds? write 'n' if you don't know what this is (y/n): y
+Write down this wallet recovery mnemonic
+
+zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong
+
+Recovered wallet OK
+Here is an example of how you'd get into the Jam container on Umbrel:
+ssh umbrel@umbrel.localdocker exec -it jam_web_1 bashcd /srcexit (multiple times)Jam is a graphical user interface for JoinMarket, and while obviously related, +is a separate project developed by a separate set of people.
+Jam is a free and open-source project that aims to improve the +financial privacy of yourself and others, without relying on a trusted third +party. It was started in 2021 by various volunteers and is still +developed and maintained on a volunteer basis. As mentioned above, Jam is a +front-end for JoinMarket, a privacy-focused bitcoin software that uses a +peer-to-peer marketplace to facilitate collaborative transactions.
+The goal of Jam is to provide an interface that makes JoinMarket easier to use, +and thus more easily accessible for more people.
+JoinMarket is a special kind of software that is aimed at improving the privacy +and fungibility of bitcoin transactions. The main way to improve privacy and +fungibility on-chain is via collaborative transactions.
+A collaborative transaction requires the coordination of multiple parties. The +right resources (UTXOs) have to be available in the right quantity +at the right time.
+Consequently, the problem that needs to be solved is not a technological +problem, but an economic problem. JoinMarket solves this problem not by central +coordination, but by creating a market that allows participants to allocate +these resources in the best way, according to their individual needs.
+The name "Jam" is a backronym, stands for JoinMarket's Awesome, Man, +and shouldn't be taken too seriously. However, it works on multiple levels +(Let's jam the signal!) and "cooking jam" is also a fun metaphor for mixing +something in a tasty way (and putting it in jars).
+
+We believe that, in the long run, open protocols will survive. Platforms, on the +other hand, are run by companies and all companies eventually go bankrupt.
+The motivation behind Jam (and JoinMarket—and Bitcoin, for that matter) is to +build something that doesn't go away.
+ + + + + + + +There are many ways you can contribute: testing, sharing ideas, writing +documentation, creating tutorials, and—of course—writing code.
+It doesn't hurt to say hi and connect with the people that are already working +on Jam, or have worked on it in the past.
+ + +Identity and privacy are complex topics in general, and Bitcoin privacy is +particularly tricky. Make sure to familiarise yourself with the basics before +you get involved.
+ + +Before you really get going you should understand the philosophy behind Jam and +the foundations it is built upon.
+ + +While a very rough roadmap and some milestones exist, it's usually +best to "scratch your own itch." Found a bug? Fix it! Have a proposal to make +something better? Create an issue! Found a typo? Fix it! Is Jam not available in +your language? Translate it!
+It can be daunting to get started, but Jam, like every software project, is just +code & design & text.
+Review a pull request or work on some open issues. +Small tasks that are relatively easy to do will have the +"good first issue" label.
+Have a look at the Figma files, comment on them, or propose +a change.
+If you're good with words and copy editing, or if you want to help to +translate Jam into multiple languages, join the translation team.
+Since all development happens out in the open and there are no gatekeepers, +getting involved is as easy as showing up.
+This is a free and open-source software project and we love +receiving pull-requests, bug reports, ideas, and feedback from everyone. See the +CONTRIBUTING.md file on GitHub for more details on how to get started +participating in this project.
+ + + + + + +Unfortunately, there is no way to talk about bitcoin privacy and the intricacies +of JoinMarket without a little bit of jargon.
+This glossary explains some of the concepts and terms used in Jam.
+A bitcoin address—also called bitcoin invoice address1—is a string of +characters that you send to someone else to receive funds.
+There are currently three invoice address formats in use:
+ +For more details please refer to the Bitcoin Wiki. Jam defaults to +Bech32 addresses.
+Address reuse refers to the practice of reusing a single bitcoin invoice +address for multiple transactions. It is highly discouraged since it +harms the privacy of yourself and others. You should never reuse addresses.
+ +The only way to hide in plain sight is by hiding in a crowd. The anonymity set +is simply the size of this crowd.
+If you are putting on a hat and sunglasses to hide in a crowd of people that are +wearing the same hat and sunglasses, your anonymity set is the size of this +crowd. If said crowd is 50 people, an attacker could mistake you for anyone out +of these 50 people. Similarly, when doing a collaborative +transaction in bitcoin, you are creating an +onchain footprint that is equivalent to the onchain footprint of +others.
+Bitcoin's base layer (or Layer 1) refers to any transaction +that touches the timechain, i.e. all onchain +transactions. The base layer is concerned with global consensus and settlement.
+Higher layers build ontop the settlement assurrances of the base layer. One +example of a Layer 2 system is the Lightning Network. All money is layered, +including gold and fiat monies. Read Layered Money by Nik Bhatia to understand +this in more detail.
+ +A batch transaction is a transaction that combines multiple real-world +transactions into one on-chain transaction. It has multiple inputs and multiple +outputs. Different parties may control one or multiple inputs and receive one or +multiple outputs.
+ +Bech32 is an invoice address format. It was specified in BIP +173 and is used for both SegWit and Taproot addresses.
+A mostly meaningless marketing term used to confuse newcomers. While "block +chain" is still the main term used to refer to Bitcoin's linked +data structure of blocks, it has increasingly become meaningless over the years +as it got co-opted by grifters, charlatans & marketers. A better, more +descriptive term of said data structure is timechain.
+Chain analysis is is the practice of applying heuristics to a +timechain's public transaction graph. The goal of chain analysis +is to link the pseudonymous identities created by bitcoin software with "real" +identities corresponding to natural persons or entities.
+Chain analysis is based on flawed assumptions, because ownership in bitcoin is +defined by secret knowledge, not possession. Identities can only be linked +probabilistically, not provably. One of the main assumptions used by chain +analysis companies is the common input ownership +heuristic. Collaborative transactions break +this heuristic.
+A CoinJoin is a collaborative transaction that combines inputs from multiple +parties. The purpose of a CoinJoin is to combine inputs and create outputs in +ways that improves the financial privacy of participants, without relying on a +trusted third party for custody. When done correctly, a CoinJoin breaks any +deterministic links between transactions, moving the process of chain +analysis from quasi-deterministic with high certainty to +probabilistic with low certainty.
+CoinJoins break the common input ownership +heuristic that is used by chain analysis +companies to de-anonymize actors. The concept was 1st introduced in 2011 by Bitcointalk user hashcoin2, but later popularised in 2013 by Gregory Maxwell.34
+All CoinJoin transactions are collaborative transactions. The two main types of +CoinJoin transactions are equal-output and +unequal-output CoinJoins. Other differences might be interactivity (or lack +thereof) and number of participants.
+A collaborative transaction is a bitcoin transaction that is initiated and +signed by multiple participants. A collaborative transaction involves two or +more parties and is thus always a batch transaction. All +CoinJoins are collaborative transactions.
+When using physical cash, spending a $100 bill to pay for a $25 item, you will +get $75 back in change. The reason for this is that you can't spend just a part +of the bill, because ripping off a quarter of it for payment will invalidate the +bill. Consequently, when bills change hands, the whole bill has to be spent, and +an appropriate amount of change goes back to the spender.
+Bitcoin works the same way. When sats change hands, the spender has to spend the +whole UTXO. Bitcoin creates the appropriate amount of change +automatically. Because all transactions are recorded transparently and publicly on the timechain,
+As of this writing,5 a simple spend is +the most common transaction type, which describes the example given above: one +input ($100 bill) produces two outputs: $25 for the merchant, and $75 in change. +The act of an outside observer guessing whether you bought something for $25 or +$75 (or: who was the customer of the transaction, and who was the merchant) is +what is called change detection.
+When it comes to chain analysis, change detection is the name +of the game. The goal of chain analysis companies is to link identities to +transactions, and to do that, one has to detect whether funds changed hands or not.
+Technically speaking, change detection is trying to figure out which output of a +transaction is a change output. Change detection is based on various heuristics. +False positives will always exist, even if the transaction under scrutiny is a +simple spend. Consequently, it is more an art than a science.
+To quote one special investigations team speaking on chain analysis:
+++Attributing ownership, however, is often nuanced because outside observers can +only infer it depending on factors such as availability and quality of the +evidence. Evidence means proof that indeed an address belongs to an individual +or entity. Unless you own an address yourself, it is very difficult to say +with absolute certainty who an address is owned by. This is why it’s more +fitting to consider blockchain analytics more of an art than science.
+ +
Keep in mind that ownership can change without any on-chain transaction +happening, e.g. by passing on a private key directly. It is also possible that +amount to be paid lines up perfectly with a single UTXO, meaning that what looks +like a self-spend is actually a payment.
+One can only conclude, as is also mentioned in the report linked above, that "an +external observer cannot possibly gain a full picture or claim 100% confidence +in ownership attribution."
+Privacy Fundamentals: The Bitcoin Transaction
+Bitcoin Wiki: Change Detection
+Short for Common Input Ownership Heuristic.
+The common input ownership heuristic assumes that all inputs of a transaction +are controlled by a single entity. This assumption is clearly wrong, because +collaborative transactions exist. +CoinJoin transactions are designed to break this heuristic.
+"Doxxic" change is any leftover change that is going back to you when +participating in an equal-output CoinJoin. Doxxic +change is problematic because it can potentially destroy any privacy benefits +gained from a CoinJoin.
+The word is a combination of "toxic" and "doxxing." Doxxing is the act of finding +out the legal identity (or similar identifiying information) of a pseudonymous +entity. Bitcoin is a pseudonymous system and does not require the True +Names6 of participants.
+You can use the sweep functionality to avoid doxxic +change in Jam.
+An eclipse attack is an attack in networked systems in which an attacker targets +a node to convince it of a false network state. The attacker surrounds the node +in order to conceal or block off accurate information, leaving the attacked +node(s) in the dark in terms of the global network state.
+An eclipse attack is similar to a Sybil attack.
+Bitcoin Stack Exchange: Eclipse Attack vs. Sybil Attack
+An equal-output CoinJoin is a collaborative transaction that produces outputs of +equal denomination, i.e. outputs of equal value when measured in sats. For this +reason, these types of transactions are also referred to as equal-amount or +equal-value CoinJoin transactions.
+Equal-output CoinJoins are batch transaction that are +easily identifiable on-chain due to their uniform output structure.
+Like any collaborative transaction, an equal-output CoinJoin breaks the Common +Input Ownership Heuristic. Participating in +such a transaction allows you to gain privacy by "hiding in the crowd."
+Jam defaults to collaborative transactions when sending and +sweeping, creating equal-output CoinJoins.
+A fidelity bond is an insurance policies which protects the policyholder from +wrongful acts committed by others. The term comes from the world of business and +finance, thus the policyholders are usually companies, and the other parties are +usually employees.
+In JoinMarket, a fidelity bond is a mechanism which ensures that market actors +act honestly. It is a protection mechanism against Sybil +attacks, because a fidelity bond makes the creation of +cryptographic identities costly.
+Warning
+It is impossible to move or spend funds that are locked in a fidelity bond +before the bond expires. They cannot be used in collaborative transactions +(neither as taker nor as maker) +as fidelity bonds are time-locked by the Bitcoin protocol.
+Fidelity bonds improve the privacy guarantees of the whole system and increase +your chance of being chosen as a market maker drastically.
+What Are Fidelity Bonds and How Do They Work in JoinMarket?
+ +JoinMarket: Financial Mathematics of Fidelity Bonds
+Creating a Fidelity Bond in Jam
+Jam is both the name of the project and the verb we use when a +collaborative transaction is in progress.
+++ + +Sir! The radar, sir! It appears to be... [Jam starts flowing through the +computer screen] jammed!
+Spaceballs
+
In Jam, a "jar" is a container that holds some sats of yours.7 Jars +exist to segregate your sats into multiple buckets that are disconnected from +each other, which aids privacy. To not risk any privacy degradation, you can +only spend from one jar at a time.
+There are 5 jars by default. The default jar to receive funds is Jar A.
+A market maker is someone who offers bitcoin liquidity to the market, to be used by +others for collaborative transactions. You can create an offer via the "Earn" +tab and become a market maker.
+ + +Short for 'memory pool.' A pool of valid bitcoin transactions +held by each node, that are not yet confirmed in the timechain.
+ +An offchain (or off-chain) transaction is any transaction that does not happen +onchain. Examples include transactions on the Lightning network, the +handing over of physical private keys, as well as transactions on centralized +ledgers such as exchanges and other trusted third parties.
+Some offchain transactions, such as handing over private keys on USB sticks or +similar, are outside of the scope of chain analysis. +Consequently, chain analysis can never be completely accurate.
+An onchain (or on-chain) transaction is a bitcoin transaction that is settled on +the bitcoin timechain. The analysis of these transactions is +called chain analysis, which is the spying on and +de-anonymizing of bitcoin's users by trying to find patterns in the onchain +data.
+Short for pay-to-public-key-hash.
+ +Short for pay-to-script-hash.
+ +A PayJoin is a collaborative transaction between two parties that facilitates an +actual payment for a good or service. The merchant agrees to provide one or +multiple inputs to the transaction, increasing the privacy of both parties.
+A PayJoin has different onchain characteristics than an +equal-output CoinJoin and is not detectable via chain +analysis alone. A PayJoin transaction has multiple +interpretations, all of which are equally valid. In addition to breaking the +common input ownership heuristic it poisons +the basis of all chain analysis, because of its +undetectability.
+ +Bitcoin Wiki: PayJoin Adoption
+Short for satoshis, plural of sat (satoshi).
+A sat the smallest fraction of a bitcoin that can be expressed
+on-chain. There are 100,000,000 sats in a bitcoin. There are
+multiple currency symbols for a sat emerging. In Jam, the sat
+symbol8 is used:
+
The 'scheduler' is a component of JoinMarket which schedules multiple +collaborative transactions in a row. It will use +random intervals and amounts to make timing analysis and de-anonymization via +chain analysis more difficult.
+The 'Sweep' screen uses the scheduler to sweep funds to one or +multiple external wallets under your control.
+A transaction that splits one input into two outputs: payment and change.
+The "simple spend" is the most common bitcoin transaction type to date, since +most wallet implementations do not optimize for privacy. For most simple spend +transactions it is possible to discern which output is the actual payment or +which one is the change. This change detection makes +the tracing of funds possible.
+Privacy Fundamentals: The Bitcoin Transaction
+Simple Non-Interactive Coinjoin with Keys for Encryption Reused.
+ +A Sybil attack is a special kind of attack in peer-to-peer networked computing. +The victim is surrounded by malicious entities, each of which act as if they are +a separate entity. The victim believes that everything is in order, that he is +getting an accurate state of the network from multiple independent peers. In +actuality, the Sybil attacker controls all entities surrounding the victim. +Consequently, the attacker is able to trick the victim into accepting a +malicious network state.
+JoinMarket uses fidelity bonds to protect users from Sybil attacks.
+Design for Improving JoinMarket's Resistance to Sybil Attacks Using Fidelity Bonds
+ +A 'sweep' send will transfer all funds of a jar or all funds of your wallet. To +sweep all funds from your wallet multiple transactions are created using the +scheduler.
+ +Taint is an external property defined by chain analysis +surveillance firms. It is an attempt to trace the origin and ownership of +UTXOs, classifying their owners and building lists of "good" and "bad" +money.
+All taint in bitcoin always is and always will be arbitrarily defined and +probabilistically applied. Just like change detection, it +is more an art than a science. It can never be done exactly. False positives and +false negatives will always arise.
+The bitcoin network is indifferent to taint. Miners will include any transaction +in a valid block that will reward them economically. Any application of taint on +the block production level is equivalent to imposing additional rules via a +soft-fork, which fully validating nodes can reject.
+A market taker is someone who buys bitcoin liquidity from the market, taking up +market makers on their offers. You can see active offers in the order +book.
+You will automatically take offers when running the scheduler via +the "Sweep" functionality.
+ + + +The data structure of Bitcoin's base layer. It represents a timestamped and linked list of blocks. Anyone can create a new block, but each block must have +sufficient proof of work, making it costly to create new blocks.
+ +A UTXO can be locked up by a script which defines that said UTXO can only be spent in a block that +is higher than a certain value. This makes UTXOs unspendable before a specific time.
+A bitcoin transaction describes the movement of sats. It is structured +data that describes inputs and outputs, among other things. A valid bitcoin +transaction has at least one input and at least one output. Every transaction +input refers to the output of a previous transaction. We say that an input +"consumes" an output. If an output is not consumed yet, we speak of an unspent +transaction output, or UTXO, for short.
+Privacy Fundamentals: The Bitcoin Transaction
+ +Learn Me a Bitcoin: Transactions
+Short for transaction.
+The tip of the chain of signatures which originates in a coinbase output. It's a "coin" that +has not yet been spent and can still be spend.
+Short for Unspent Transaction Output.
+The term invoice is proposed in BIP-179 as an alternative. ↩
+Blind Bitcoin Transfers hashcoin, July 2011 ↩
+I taint rich! Maxwell, Jan. 2013 ↩
+CoinJoin: Bitcoin privacy for the real world Maxwell, Aug. 2013 ↩
+Block 744,811 ↩
+Vernor Vinge, 1981, True Names ↩
+What we call "jars" are usually called "mixdepths" in JoinMarket. They are also referred to as "pockets" and "accounts" in some of the older parts of the JoinMarket documentation. ↩
+Jam is an interface for JoinMarket1, a special kind of bitcoin software that +focuses on privacy and security. The goal of Jam is to make it easier to improve +the financial privacy of yourself and others.
+Warning
+Both Jam and its documentation are a work in progress. We are writing +these docs as we progress, out in the open. If you want to help, please +do!
+Before you get going with Jam you should understand the "why" behind it all.
+ + +As mentioned above, Jam uses JoinMarket under the hood. What sets JoinMarket +apart is that it has no single point of failure. It is completely peer-to-peer, +there is no central coordinator, no "doxxic change", no company behind it all, +no marketing department, and no central entity making any money off of it.
+All development is done by volunteers. Consequently, please heed the following +warning:
+Danger
+Jam is considered beta software. While JoinMarket is tried and tested, Jam is new and things might break. Use with caution. Please report any issues directly on GitHub.
+The easiest way to install Jam is via one of the full-node software solutions +that includes Jam as an app or plug-in. You can also install it manually +yourself.
+ +Once installed, you will have to add some funds to Jam to get going. If you are +new to JoinMarket in general and Jam in particular, you might want to have a +look at the "Cheatsheet."
+ +Since there is no company or fixed team behind Jam or JoinMarket, your best bet +to get help are public chat groups and public forums. Also make sure to have a +look at the FAQ to get answers to frequently asked questions.
+ + + + +Jam and JoinMarket are separate projects. For more information on JoinMarket, see the JoinMarket GitHub Page ↩
+While everyone will use Jam differently, here is one way you can think about the +general application flow:
+
Some of your UTXOs might be chunky and identifiable, like whole or large +pieces of fruit. Once you make delicious jam out of them, they are less chunky +and less identifiable. You are free to offer your fruits to others so they can +make jam more easily.
+Without the fruity metaphor: to increase the privacy and fungibility of your +funds—and thus your security overall—you should use Jam as both a market +maker ('Earn' tab) and a taker ('Send' and 'Sweep' tabs). Use +a Jar's sweep functionality or the Scheduler to transfer funds out of +Jam, e.g. to move all your funds to cold storage or to use them to open +lightning channels. If you want to pay others for goods and services, use +send.
+Click "Cheatsheet" at the bottom of the screen to open up the cheatsheet in Jam.
+
Some processes in Jam might take a long time to complete. Further, Jam is +considered beta software. While JoinMarket is tried and tested, Jam is new and +things might break. Use with caution. Please report any issues directly on +GitHub.
+Make sure to understand the privacy fundamentals, best practices, as well as the +motivation behind this software. Also, understand that you are participating in +a free market. How much you can earn and how many fees you have to pay depends +on market conditions.
+ + + +Make sure to create a fidelity bond to increase the chances of your offer being taken. ↩
+Use the 'Receive' tab to receive funds.
+
A new invoice address will be generated every time. You can scan the +QR code with a mobile wallet or copy/paste the invoice address to receive funds +from someone else, or send funds from another wallet yourself.
+Info
+Jam uses jars under the hood to separate funds into disconnected +containers. Think of jars as different pockets in your wallet, or different +identities. The default jar to receive funds is Jar A.
+Once you have funded your wallet, you can use the 'Send' tab to do +a collaborative transaction.
+ + + + + + + +Use the 'Send' tab to send funds to someone or to one of jars. Jam defaults to +collaborative transactions when sending, which enhances your privacy and +security.
+Info
+Jam uses jars under the hood to separate funds into disconnected +containers. Think of jars as different pockets in your wallet, or different +identities.
+You can choose the number of collaborators in the send options. The higher the +number of collaborators, the larger your anonymity set.
+
Use the 'Sweep' button in the amount field to empty a single jar, or use the +Sweep tab to sweep all non-frozen funds of your wallet to external +addresses.
+After you made your first collaborative transaction with one of your jars as the +recipient, you are ready to earn.
+ + + + + + + +Use the 'Earn' tab to earn sats by offering liquidity to other market +participants. You will be acting as a market maker. Creating a +fidelity bond is recommended. +In Jam, takers pay 100% of the mining fees: as a market maker, you will not pay anything. Just profit!
+
Make sure to create a fidelity bond to increase the chances of your offer +being taken.
+A fidelity bond is a mechanism which ensures that market actors act honestly. It +is a protection mechanism against Sybil attacks. A fidelity bond makes +the creation of cryptographic identities costly.
+Fidelity bonds improve the privacy guarantees of the whole system and increase +your chance of being chosen as a market maker drastically.
+Be aware that funds locked in a Fidelity Bond will not be included in your offer amount, +so remember to keep additional funds in order to participate as a market maker.
+Warning
+It is impossible to move or spend funds that are locked in a fidelity bond +before the bond expires. They cannot be used in collaborative transactions +(neither as taker nor as maker) +as fidelity bonds are time-locked by the Bitcoin protocol.
+There are two types of offers:
+250 sats.0.03%.Once you are done earning, you can sweep all funds to an external wallet.
+ + + + + + + +Use the 'Sweep' tab to empty your wallet using the scheduler. The scheduler will +execute a series of collaborative transactions with randomized parameters, which +will send your funds to multiple destination addresses over time.
+
Once the scheduler is active you will see a green indicator light, which means +that the scheduler service is running. The service will take any +matching offer automatically.
+
You can stop the scheduler at any time.
+ + + + + + + +A fidelity bond is a mechanism which ensures that market actors act honestly. It +is a protection mechanism against various kinds of attacks that involve the +creation of fraudulent identities.
+ +Warning
+It is impossible to move or spend funds that are locked in a fidelity bond +before the bond expires. They cannot be used in collaborative transactions +(neither as taker nor as maker) +as fidelity bonds are time-locked by the Bitcoin protocol.
+You can create a fidelity bond via the Earn screen. It involves the following steps:
+cj-outAfter that, you will be asked to review the bond configuration. If everything +looks right, you can create the fidelity bond which will time-lock your +funds for the set duration.
+Refer to the screenshots below to understand the steps in more detail:
+
Access the settings by clicking on the gear icon () in the top-right corner.
+
Jam supports the creation and handling of multiple wallets. However, only one +wallet can be actively used at a time. Wallets are locked when not used. Your +"active" wallet is the one that is currently unlocked.
+Question
+Want to import a wallet? Look at the FAQ!
+Clicking on the active wallet in the top-left corner will open the +wallet view.
+
You can see your jars and whats in them by clicking on the arrow. Clicking on a +jar will open its detail view, which allows you to inspect individual UTXOs, as +well as freeze/unfreeze them.
+
Fees play a crucial role in the incentive structure of both Bitcoin and +JoinMarket. They form the basis for the economic incentives of both systems. In +Bitcoin, you pay fees to a miner in order for your transaction to be included in +a block. The higher the fee you are willing to pay, the higher the likelihood +that your transaction will be included quickly.
+In JoinMarket, you pay fees to market makers in order to use their +liquidity to both of your advantage. However because the market maker gets the fee as he is waiting around and providing the liquidity.
+Consequently, when you are sending a collaborative transaction in Jam—or when you are using the scheduler to do multiple transactions—you have to pay fees to miners and makers. How high these fees are depends on market and mempool conditions.
+Of course, you can offer liquidity yourself via the Earn functionality, allowing you to be on the receiving end when it comes to maker fees.
+ +When doing a collaborative transaction via the Send or Sweep tabs, +you are taking liquidity offers from others, effectively becoming a market +taker.
+How much you will pay in maker fees depends on the fee market of the current offers. You can get an overview of fees by inspecting the order book.
+FAQ: How high are the fees that I do have to pay?
+ +Just like all users of onchain bitcoin, you will have to pay +transaction fees to miners.
+Note that collaborative transactions are larger, in terms of bytes, than +"regular" bitcoin transactions. Since the cost of an onchain transaction is +determined by its size in bytes—not by value transferred—a collaborative +transaction is more expensive than a simple spend.
+FAQ: How high are the fees that I do have to pay?
+ +As mentioned above, you can use the Earn tab to earn maker fees +yourself. Simply choose an offer type, select how many fees you would like to earn, and press "Start Earning!".
+Make sure to check the orderbook to compare your offer with current +market rates. If your offer isn't competitive, it's likely nobody will take it and thus +you will earn zero sats.
+ + +All fees are denominated in sats. Use one of the tools below to convert them to fiat:
+ +See also "a note on fees" from the JoinMarket documentation.
+ + + + + + + +The mempool (memory pool) is a pool of transactions that are not included in the +timechain yet. It is a waiting room for transactions, if you will. Every full +node has its own mempool—there is no single mempool that is shared by nodes, +there is an individual mempool for every single node. Mempools might differ +depending on node configuration. Nodes can decide which transactions to keep, +which transactions to pass on to other nodes, and which transactions to drop.
+Miners will consult their mempools to construct candidate blocks. Once a +transaction is included in a valid block—and your node confirms the blocks +validity—it is considered confirmed and removed from the node's mempool.
+Learn me a bitcoin: Memory Pool
+Miners are incentivised to include transactions that reward them the most, i.e. +transactions that pay the highest mining fees. Because mining fees are set by +the users, you can view mining fees as a kind of bribe that is paid by the users +to the miners. If the bribe is high, the chance of your transaction being +included is high. If it is low, the chance of inclusion is lower.
+ +Bitcoin block space is scarce. If onchain activity is high, the mempool will be +crowded. The more crowded the mempool, the higher the "bribe" you will have to +pay to miners.
+Fee estimation is an attempt to guess how high the fee needs to be for your +transaction to be included in the future. It is more an art than a science, +since the future is always uncertain and mempool conditions might change +quickly.
+Most mempool explorers have some sort of fee estimation. You can also use the
+estimatesmartfee command to do a fee estimation based on your
+mempool:
bitcoin-cli estimatesmartfee 21 economical
+We recommend that you use your own node to inspect the mempool. For example, you
+can use the getrawmempool command to inspect your mempool:
bitcoin-cli getrawmempool true
+Of course, plenty of graphical user interfaces exist too. The software that is +powering mempool.space is free software and can be installed quite easily on +your node.
+Mempool One-Click Installation
+You can also refer to public mempool instaces in case you don't have access to +the mempool of your own node. Note, however, that using public mempool and block +explorers has certain privacy implications, as whoever is running these websites +will be able to correlate your IP with the blocks and transactions you look up. +Use Tor or a VPN to mitigate this.
+ +There are also great visualisations that help you understand what's going on, +Bitfeed and Mempool Observer being two of them.
+ + + + + + + + +The order book (or orderbook) shows what kind of offers are currently on the +market. It gives insights in regards to offer types, fees, offer sizes, and +fidelity bonds put up by market makers.
+Jam will set up a service that allows you to watch the order book on your node. +This removes the trust in a third party. You can view the order book directly in +Jam via the "Show orderbook" button on the Earn screen.
+
There are also public order books that you can inspect, in case you do not have +access to your own node:
+ + + + + + + +In JoinMarket, liquidity is sold and bought on a free market. Consequently, +market volume and depth depends on market conditions. You can inspect the order +book to get an overview of the current offers.
+ +Some sites show historical statistics in regards to market volume and liquidity. +Please note that the statistics shown on these sites sometimes use proprietary +data and algorithms.
+ + + + + + + +++There is a sacred realm of privacy for every man and woman where he makes his +choices and decisions — a realm of his own essential rights and liberties into +which the law, generally speaking, must not intrude.
+Geoffrey Fisher, Archbishop of Canterbury (1959)
+
Jam is a tool, just like bitcoin. Before using it, you should understand how you +could benefit from using it, how it works, and how to use it correctly. In order +to answer the "how" you should also understand the "why" --- why was it created, +and what is the problem in the first place?
+To answer that properly, we will have to talk about privacy and financial +privacy in general, and bitcoin privacy in particular:
+++"Privacy is necessary for an open society in the electronic age. +Privacy is not secrecy. A private matter is something one doesn't want +the whole world to know, but a secret matter is something one doesn't +want anybody to know. Privacy is the power to selectively reveal +oneself to the world."
+Eric Hughes
+
With these powerful words Eric Hughes opened his Cypherpunk's +Manifesto +in 1993. The difference between privacy and secrecy is subtle, but +important. Choosing to remain private does not imply that one has +secrets or has something to hide. To illustrate this just realize that +what you do on the toilet or in the bedroom is neither illegal nor +a secret (in most cases), yet you close the door and pull the curtains.
+Similarly, how much money you have and where you spend it is not +necessarily a secret matter. It should, however, be a private one. Most +would agree that your boss should not know how you choose to spend your +salary.
+The importance of privacy is recognized by many international +bodies. From the American Declaration of the Rights and Duties of +Man to the United Nations, it is recognized that privacy is +a fundamental human right worldwide.
+++No one shall be subjected to arbitrary interference with his +privacy, family, home or correspondence, nor to attacks upon his +honour and reputation. Everyone has the right to the protection of +the law against such interference or attacks.
+Article 12, United Nations Declaration of Human Rights
+
Although Bitcoin was often described as an anonymous method of payment +by early proponents and by the media, it is anything but. Bitcoin is +pseudonymous at best and as of today making sure that your +pseudonymous bitcoin identities cannot be linked to your real-world +identity proves difficult for most people.
+Bitcoin is an open system. Its public ledger can be inspected and +studied by everyone. Thus every transaction that is embedded in its +proof-of-work chain will be exposed for as long as Bitcoin exists: +eternity. Failing to follow privacy best practices now can potentially +have negative repercussions in the future.
+Privacy, like security, is a process and it is difficult, but not +impossible. Tools continue to be developed to help preserve privacy +while using Bitcoin and fortunately most of these tools become easier +to use over time. Unfortunately no panacea exists. One has to remain +aware of the tradeoffs and follow best practices as they evolve.1
+ +Jam is a front-end for JoinMarket, a privacy-focused bitcoin software +that uses a peer-to-peer marketplace to facilitate collaborative transactions, +also called "CoinJoins."2
+A collaborative transaction, as the name implies, is a bitcoin transaction that +is done collaboratively by multiple parties. The tricky part of getting a +collaborative transactions done is not technical, but social. It is a problem of +matchmaking, timing, and trust.
+Usually, this problem is solved with a central coordinator.
+JoinMarket takes a different approach. It allows participants to propose +collaborative transactions to others, creating an open market of buyers and +sellers, which removes the central coordinator from the equation.
+ +With the motivation and purpose of Jam covered, understanding the +fundamentals of bitcoin in general and bitcoin privacy in particular might be +useful.
+ +Some parts of the above are based on "Bitcoin Privacy: Best +Practices, +written by Gigi and released under CC BY-SA 4.0 license." ↩
+We prefer to refer to them as collaborative transactions, which is more concise and explanatory. ↩
+Jam is free as in freedom. We believe that free software is an imperative for +a free society, which is why Jam is released under a free software license.
+Bitcoin is financial software. Consequently, any financial liberation that is +enabled by Bitcoin rests on the four essential freedoms granted by free +software.
+ +++“Free software” means software that respects users' freedom and community. + Roughly, it means that the users have the freedom to run, copy, distribute, + study, change and improve the software. Thus, “free software” is a matter of + liberty, not price. To understand the concept, you should think of “free” as + in “free speech,” not as in “free beer.”
+
Free software puts the users in control, both collectively and individually. +Free software is not only about being "open" and "more secure." While these are +nice side-effects, the main issue is about control and respecting user's +freedoms.
+Why Free Software Is Even More Important Now
+++Freedom means having control over your own life. If you use a program to carry +out activities in your life, your freedom depends on your having control over +the program. You deserve to have control over the programs you use, and all +the more so when you use them for something important in your life.
+
Most software and software products force the user into a master-slave +relationship, as do most monetary systems and financial products. Bitcoin is +freedom money because the software that makes Bitcoin possible is free +software—free as in freedom. There are no masters, only peers.
+ + + + + + + +There is much to be said about Bitcoin and why it was created. Many books have +been written, much speculation was and is still being had in terms of Satoshi's +"true" vision and motivation.3
+Undoubtedly, there are certain values embodied in the Bitcoin system—certain +opinions that are embedded in the code, expressing how things should be done and +what should be avoided. Nothing makes this more clear than the +announcement post of Bitcoin, written by Satoshi himself.
+Below are some highlights that are particularly relevant:
+++I've developed a new open source P2P e-cash system called Bitcoin. It's +completely decentralized, with no central server or trusted parties, +because everything is based on crypto proof instead of trust.
+
No central server. No trusted third party. Peer-to-peer (P2P), instead of +client-server or master-slave.
+Thanks to strong cryptography, trust in third parties can be eliminated. When +possible, rely on cryptographic proof instead of trust. Trusted third parties +should be eliminated because (a) they introduce friction and (b) they are +security holes.1
+++We have to trust [banks] with our privacy, trust them not to let +identity thieves drain our accounts. [...] Before strong encryption, users had +to rely on password protection to secure their files, placing trust in the +system administrator to keep their information private. Privacy could always +be overridden by the admin based on his judgment call weighing the principle +of privacy against other concerns, or at the behest of his superiors.
+
Privacy. Admins that spy on you. Systems that are designed to spy on you. +Unfortunately, it's almost non-existent in today's world of surveillance +capitalism and dragnet surveillance.
+While credit requires identity, money does not. When you can trust the money you +don't have to trust the person. In Bitcoin, there are no persons; only +pseudonymous identities. Identities that are generated cryptographically at +virtually no cost.
+++With e-currency based on cryptographic proof, without the need to trust a +third party middleman, money can be secure and transactions effortless.
+
No middlemen. Secure and effortless. The reason why your browser will show you a +green lock or a shield when a connection is encrypted is that privacy and +security are two sides of the same coin. Without privacy, your physical security +might be at risk.2 Without privacy, free thought and free speech are +impeded.
+++The result is a distributed system with no single point of failure.
+
No single point of failure. No admins.That is one of the main value propositions +of Bitcoin, and what makes it so resilient. This resiliency, and the fact that +the users are in charge—and nobody else—is what sets Bitcoin apart. JoinMarket +continues this philosophical approach: economic actors in a peer-to-peer system, +no single point of failure.
+ +Szabo, 2001. Trusted Third Parties Are Security Holes ↩
+Jameson Lopp, List of Known Physical Bitcoin Attacks ↩
+A selection of books is available in the Bitcoin and Cypherpunk History section of bitcoin-resources.com/books ↩
+JoinMarket, just like Bitcoin, doesn't have a single point of failure. It can be +understood as a protocol that facilitates certain kinds of collaborative +transactions—CoinJoins—via an open market.
+Creating collaborative transactions is not a technical problem, but a problem of +coordination. Someone has to bring the participants together, coordinate time +and place, as well as amounts and fees.
+Usually, this problem is solved by a central coordinator. In the +best case, the central coordinator is non-custodial and blinded, meaning that +user funds are never at risk, and the amount of information the central +coordinator can obtain is minimal. However, even in this optimal case, the +central coordinator is still a single point of failure.
+In addition to being a central point of failure, any central coordinator usually +charges a fee for the coordination service, which means that it is an entity +that is making money. In most cases, this entity is a company that can be +pressured and subverted, as has happened in the past. Even without any outside +pressure, an economic entity might make certain decisions against the best +interest of its users, just out of self-preservation alone.1
+JoinMarket provides a decentralised alternative to these central coordination +services. It is not a central entity, it is software that is coordinating the +actions of multiple peers, just like Bitcoin. JoinMarket is neutral, meaning +that the system itself is not charging its users to use the software for +coordination. Fees are earned by market makers, i.e. those who are +willing to provide liquidity to the open market. Consequently, JoinMarket is not +a financial entity. Only the users are making money. JoinMarket is not.
+ +JoinMarket is a tried and tested CoinJoin implementation, having been actively +used on Bitcoin's mainnet since 2015.2 Because of its lack of a +centralised coordinator, it works a bit differently than other CoinJoin +implementations.3 You can read about the details of JoinMarket's +design in the high-level +design +document of the JoinMarket docs.
+JoinMarket is free and open-source software, which means that anyone is free to +use, inspect, and modify the software.
+ +Because of its decentralised nature, and thus the lack of funds and focused +effort that a central company structure allows, the JoinMarket software was, +historically, a bit difficult to set up and use. We hope that the efforts around +Jam will make it a bit easier.
+ +See, for example: https://archive.ph/C53tk, https://archive.ph/hIYJO ↩
+See the Bitcoin Wiki for https://en.bitcoin.it/wiki/JoinMarket ↩
+Shinobi, 2021 JoinMarket Vs. ZeroLink ↩
+When it comes to Bitcoin, misconceptions abound. This is not surprising. Bitcoin +is a new thing, and, consequently, all metaphors and comparisons +fall short, in one way or another.
+One misconception is that Bitcoin is private and untraceable. In actuality, +regular Bitcoin use often has weaker privacy guarantees than using the +traditional banking system, as Gregory Maxwell pointed out many years +ago:
+++“Your inlaws can see that you're buying birth control that deprives them of +grandchildren, your employer learns about the non-profits you support with money +from your paycheck, and thieves see your latest purchases and how wealthy you +are which helps them target and scam you. Poor privacy in Bitcoin can be a major +practical disadvantage for both individuals and businesses.”
+
To understand why this is, we have to understand how Bitcoin operates. This, +however, turns out to be very difficult. To understand one part, one needs to +have a solid understanding of computer science and cryptography. To understand +another part, one needs to have a solid understanding of economics and game +theory—not to mention money, networks, governance, energy and energy markets, +monetary history, and so on. The list of relevant disciplines is almost endless.
+However, it is possible to look at some parts of Bitcoin in isolation +and—hopefully—gain a better understanding by zooming in. One such part is the +Bitcoin transaction.
+In the simplest sense, a Bitcoin transaction is just a bunch of data that +describes the movement of bitcoins.
+A bitcoin transaction consists of inputs and outputs. Every transaction input +refers to the output of a previous transaction (except the coinbase transaction). We say that an input "consumes" +an output. If an output is not consumed yet, we speak of an unspent transaction +output, or UTXO, for short.
+Once properly understood, it is easy to see what the Bitcoin network generates: +a linked data structure that, starting from a common root—the genesis +block—splits and combines bundles of sats as time goes on. Properly visualized, +it would look a bit like an upside-down tree.
+
Every transaction has at least one input and at least one output. The simplest +and traditionally most common transaction type has one input and two outputs: +one describing the actual payment and one describing the change that goes back +to the one who initiated the payment.
+
The concept of change is required because Bitcoin doesn't allow an update of the +past. It is an append-only log, so instead of going back and modifying past +entries, new entries have to be created to reflect any updates. Transactions are +what create these updates. For a simple transaction, one new "entry" is created +to update the balance of the receiver, and one new entry is created to update +your own balance. You can think of it as paying for something that costs $5 with +a $20 bill. The merchant receives five dollars, and you get $15—the change—back. +However, we don't have physical coins and bills, we only have an append-only +log. So instead of bills of smaller denominations, new entries—new UTXOs—are +created.
+
While this design is ingenious when it comes to validation—you can easily make +sure that everything adds up at all times—there are certain nuances to consider +when it comes to privacy.
+For example, if it is trivial to determine which output is a change output and +which one isn't, it is trivial to cluster outputs and thus identify not only the +flow of funds, but also who transacted with whom, at what times, and—of +course—the amounts that were transacted. Imagine a data leak that exposes all +transactions of every company, every individual, every politician, every bank, +every merchant, every online shop, and every vending machine. When used naively, +this data leak is Bitcoin.
+Luckily, the situation is not as grim as it sounds. Developments and techniques +exist to remedy this situation. To understand them, we have to understand the +various transaction types that Bitcoin allows.
+We already discussed the most common transaction type: the "simple spend." There +are also transactions that have only one input and one output, transactions that +have multiple inputs and one output, and transactions that have multiple inputs +and multiple outputs. Let's call them "No Change," "Consolidation," and "Batch," +respectively.
+
While Bitcoin's transaction graph is public, it is important to point out that +any analysis that is applied to this data is heuristic. For example, a user +might create a transaction that splits a UTXO in half, resulting in two outputs +that belong to the same entity. Or, to pick another example, a regular spend +might produce two outputs that are exactly equal, making change detection +virtually impossible.
+
Because identification can only happen heuristically, one part of the solution +to Bitcoin's privacy conundrum lies in collaboration.
+When it comes to privacy, collaboration is the norm. Take encryption, for +example. If you want to have a secure communications channel with another party, +you start a collaborative process. You meet, you exchange secret information, +and you use this secret information to encrypt your messages. We call this +exchange of secret information a "handshake," and over the last decades, we +implemented all kinds of handshakes into our communication and networking +protocols to make sure that bad actors can't eavesdrop on our communications.
+Similarly, cryptographers and security researchers are currently working on +protocols and techniques that make sure that bad actors can't eavesdrop on your +every financial move. As with end-to-end encryption, these protections are +important for all and a matter of life-and-death for some. Dissidents, +journalists, whistleblowers, political activists—these are only a few groups of +people that depend on secure communications, which includes financial +communication. That privacy is important for these groups is an understatement. +It is absolutely essential. This is also why the Human Rights Foundation +launched a fund to support software developers who are making the Bitcoin +network more private, decentralized, and resilient.
+So, how can we think about a "handshake" in the world of bitcoin transactions? +It's quite simple, really. As mentioned above, a bitcoin transaction can have +multiple inputs and multiple outputs. The privacy techniques that are currently +being developed are making use of this feature. The interesting part is that not +all inputs have to be controlled by the same party. Thus, the "handshake" is +about bringing multiple parties together to collaborate on a bitcoin +transaction.
+Once the collaborating parties agree on the parameters of the transaction, the +transaction is signed by all parties and broadcast to the network. Because of +the heuristical nature of transaction analysis, an onlooker won't be able to +figure out the flow of funds.
+
One especially promising technique to increase the privacy of all is to combine +the above with an actual payment. In this scenario, the "handshake" is about +bringing a merchant and a customer together to craft a special transaction that +can only be deciphered by said merchant or customer. An eavesdropper is left +with multiple interpretations of the transaction, each equally likely. Such a +transaction is called a “PayJoin.”
+Even if only a small percentage of transactions are PayJoin transactions, the +privacy of all participants in the network is increased substantially.
+As more wallets and merchants adopt and support these privacy features, we will +see a substantial increase in privacy on Bitcoin's base layer. However, as we +have seen with the adoption of Transport Layer Security on the Internet, it +takes some time for an upgrade of this sort to be implemented and embraced.
+When the internet was a new thing, we didn't think that it would envelop all our +communications and all our lives. Encryption was an afterthought. After a while, +however, we figured out that having all our communications available in plain +text, readable by everyone who had the interest and technical proficiency to do +so, wasn't a terribly good idea. Consequently, we made a concerted effort to +change things. We upgraded from HTTP to HTTPS and from plain text +messages to end-to-end encryption. While this switch isn’t 100% +complete yet, encrypted communication became the default over time. This upgrade +took a long time, since, similar to Bitcoin, nobody is in charge of the +internet.
+ + +As with everything in Bitcoin, taking control of your privacy is +a gradual, step-by-step process. Learning about and implementing these +best practices takes patience and responsibility, so do not be +discouraged if it seems overwhelming at first. Every step, no matter +how small, is a step in the right direction.
+The following are actionable steps you can take to increase +your privacy:
+Not your keys, not your bitcoin. If someone +else is holding your bitcoin for you, they know everything there is to +know about these coins: amounts, transaction histories, future +transactions, etc. Taking self-custody of your coins is the first and +most essential step.
+ +Reusing addresses destroys the privacy of +both the sender and the receiver. It should be avoided at all costs.
+ +Linking your real-world identity to your +bitcoin addresses is a necessary evil in most jurisdictions. While +the effectiveness of these regulations is questionable, the +implications for regular users are mostly negative as a multitude of +data leaks have shown. If you choose to use KYC on- or off-ramps, make +sure that you understand the relationship between yourself and the +service in question. You are trusting this service with your personal +data, including the future safety of this data. +If you want to skip KYC entirely, have +a look at no-KYC only.
+ +Trusted third parties are security holes. If you can rely on yourself instead of +trusted third parties, you should.
+Trusted Third Parties Are Security Holes
+Not your node, not your rules. Running your own node is essential to use +Bitcoin in a private manner. Every interaction with the Bitcoin network is +facilitated by a node. If you are not in control of this node, whatever you +are doing is seen by the node you are interacting with. This means whoever is +in control of the node is able to see what you are doing. The bitcoiner node +guide is a great resource to get you started.
+ +The off-chain nature of the lightning network increases the transactional +privacy of its users without having to jump through too many hoops. While it is +still early, the absolutely reckless days of the lightning network are likely +behind us. Using it for small- and medium-sized transactions can help improve +both your privacy as well as your fee footprint.
+ +Looking up addresses in public block explorers will link those addresses with +your IP, which, in turn, can be linked to your real identity. Software packages +like Umbrel, Citadel, RaspiBlitz, and BTCPay Server make it easy to run your own +block explorer. If you have to use a public block explorer, make sure to mask +your IP by connecting to them via Tor, +or at least use a VPN.
+ +Because Bitcoin is forever, using transactional best practices such as +collaborative CoinJoin transactions will ensure that your privacy is +protected going forward. While CoinJoin transactions are nuanced, +user-friendly software exists to help you create and automate these kinds of +transactions. Samourai's Whirlpool is a good solution for Android users, for +example. There is also JoinMarket, which, thanks to projects like +JoininBox and Jam, can be set up +quite easily on your own node.
+ + ++The above is a slightly modified version of Bitcoin Privacy: Best +Practices" by Gigi, released originally under a +CC BY-SA 4.0 license and modified for Jam by the author.
+ + + + + + + +Jam is an interface for JoinMarket1, a special kind of bitcoin software that focuses on privacy and security. The goal of Jam is to make it easier to improve the financial privacy of yourself and others.
Warning
Both Jam and its documentation are a work in progress. We are writing these docs as we progress, out in the open. If you want to help, please do!
Contributing
"},{"location":"#before-you-start","title":"Before You Start","text":"Before you get going with Jam you should understand the \"why\" behind it all.
Motivation
Privacy Fundamentals
As mentioned above, Jam uses JoinMarket under the hood. What sets JoinMarket apart is that it has no single point of failure. It is completely peer-to-peer, there is no central coordinator, no \"doxxic change\", no company behind it all, no marketing department, and no central entity making any money off of it.
All development is done by volunteers. Consequently, please heed the following warning:
Danger
Jam is considered beta software. While JoinMarket is tried and tested, Jam is new and things might break. Use with caution. Please report any issues directly on GitHub.
"},{"location":"#installation","title":"Installation","text":"The easiest way to install Jam is via one of the full-node software solutions that includes Jam as an app or plug-in. You can also install it manually yourself.
Installation
"},{"location":"#first-use","title":"First Use","text":"Once installed, you will have to add some funds to Jam to get going. If you are new to JoinMarket in general and Jam in particular, you might want to have a look at the \"Cheatsheet.\"
Cheatsheet
"},{"location":"#getting-help","title":"Getting Help","text":"Since there is no company or fixed team behind Jam or JoinMarket, your best bet to get help are public chat groups and public forums. Also make sure to have a look at the FAQ to get answers to frequently asked questions.
FAQ
GitHub Issues
Matrix Room
Telegram Group
Jam and JoinMarket are separate projects. For more information on JoinMarket, see the JoinMarket GitHub Page \u21a9
Have a question that is not listed here? Let us know!
Contributing
"},{"location":"FAQ/#frequently-asked-questions","title":"Frequently Asked Questions","text":"This FAQ compiles questions that relate to Jam in particular. For things related to JoinMarket in general, please refer to the JoinMarket documentation.
"},{"location":"FAQ/#how-much-can-i-earn","title":"How much can I earn?","text":"Earning sats entails providing liquidity to other market participants. Consequently, how much you can earn depends on multiple factors, market conditions and liquidity size being two of them. In general, the more liquidity you provide, the more you can earn. That being said, you are competing in an open market, and because competition is global and only constraint by market forces, the margin is usually thin.
If your offers are not taken by market participants, your offer might be too expensive. Check the order book and compare your offer to the market price. If your offer is competitive and is still ignored, make sure to create a Fidelity Bond, which signals that you are a serious market participant and not a malicious entity.
See also \"a few words about incentives\" from the JoinMarket documentation.
"},{"location":"FAQ/#how-high-are-the-fees-that-i-do-have-to-pay","title":"How high are the fees that I do have to pay?","text":"The amount of fees you have to pay depends on market and blockspace conditions. They are dictated by supply and demand, both for collaborative transactions and single user transactions.
Market makers provide liquidity and set the fee they want to earn, either in absolute or percentage terms. Market takers have to agree to take these offers voluntarily. Check the orderbook to get an up-to-date overview of the current fee market.
In addition to these fees, you will have to pay mining fees for you and the makers. Mining fees depend on how many transactions are currently in the mempool. Inspect your mempool or use a public site like mempool.space to do a fee estimation.
Hint
We recommended that you run your own mempool.space instance on your full node.
See also \"a note on fees\" from the JoinMarket documentation.
"},{"location":"FAQ/#im-getting-an-error-when-trying-to-open-the-wallet","title":"I'm getting an error when trying to open the wallet","text":"The following error can pop up in case JoinMarket didnt't shut down cleanly:
wallet.jmdat cannot be created/opened, it is locked.\nWarning
Make sure that you have written down your wallet seed before executing any command
You can resolve this by manually deleting the wallet .lock file as explained in issue #173.
This can have multiple reasons. Tor or general network connection issues, participants not responding in a timely manner, missing requirements to source commitments (see the docs), period of slow block production, unexpected increase of transaction fees, etc.
For a better assessment, the following can be taken as a guideline:
If an operation takes longer than that, then there might be a different issue. See \"Something else is/seems stuck\" for more info.
"},{"location":"FAQ/#something-else-isseems-stuck-what-can-i-do","title":"Something else is/seems stuck; what can I do?","text":"If a single collaborative transaction takes hours, or if your scheduled sweep already takes over three days, there might be a different underlying problem.
A general rule of thumb is: Any operation either succeeds or fails. If an operation is aborted prematurely, there is no danger of loss of funds.
All operations can be aborted by locking your wallet.
Since Jam does not yet have a way to provide fine grained error information to users, it is always a good idea to inspect the log files for warning and error messages.
"},{"location":"FAQ/#how-do-i-view-the-log-file","title":"How do I view the log file?","text":"If you are running Jam with one of the supported integrations (RaspiBlitz, Citadel, Umbrel, etc.) chances are you can view the logs inside the app (See Settings > Show logs).
If the option is not displayed, or if you run the standalone docker image yourself, you can find all log files inside the container in directory /var/log/jam/. See jmwalletd_stdout.log or jmwalletd_stderr.log for problems with Jam.
e.g. tail -n 200 -f /var/log/jam/jmwalletd_stdout.log
If you run JoinMarket natively, you can find the logs files inside the logs folder of JoinMarket's working directory (e.g. /home/<user>/.joinmarket/logs)
e.g. tail -n 200 -f /home/user/.joinmarket/logs/jmwalletd_logs.log
This can have several reasons and basically means that the UI cannot reach the backend service. Depending on your installation (native setup, docker images, local/remote hosts, etc.), there are a number of things you should verify.
Please make sure that:
bitcoin-cli getblockchaininfo\ncurl --insecure https://127.0.0.1:28183/api/v1/session\nCheck the logs for any errors or warnings.
If all the above fails, try restarting every service or do a complete node reboot.
As a last resort, seek help in the support channel.
Yes, it is possible to import an existing wallet. However, not yet via the web interface, but with a few manual steps via the command line.
ssh (see an example for Umbrel below)wallet-tool.py script. jmvenv/bin/activate # if virtual environment is enabled\npython3 scripts/wallet-tool.py recover --gap-limit=200 --recoversync\nroot@821939a90a7c:/src# python3 scripts/wallet-tool.py recover --gap-limit=200 --recoversync\nUser data location: /root/.joinmarket/\nInput mnemonic recovery phrase: zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong\nInput mnemonic extension, leave blank if there isnt one: \nEnter new passphrase to encrypt wallet: \nReenter new passphrase to encrypt wallet: \nInput wallet file name (default: wallet.jmdat): recover.jmdat\nWould you like this wallet to support fidelity bonds? write 'n' if you don't know what this is (y/n): y\nWrite down this wallet recovery mnemonic\n\nzoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong\n\nRecovered wallet OK\nHere is an example of how you'd get into the Jam container on Umbrel:
ssh umbrel@umbrel.localdocker exec -it jam_web_1 bashcd /srcexit (multiple times)Jam is a graphical user interface for JoinMarket, and while obviously related, is a separate project developed by a separate set of people.
"},{"location":"about/#about-jam","title":"About Jam","text":"Jam is a free and open-source project that aims to improve the financial privacy of yourself and others, without relying on a trusted third party. It was started in 2021 by various volunteers and is still developed and maintained on a volunteer basis. As mentioned above, Jam is a front-end for JoinMarket, a privacy-focused bitcoin software that uses a peer-to-peer marketplace to facilitate collaborative transactions.
The goal of Jam is to provide an interface that makes JoinMarket easier to use, and thus more easily accessible for more people.
"},{"location":"about/#about-joinmarket","title":"About JoinMarket","text":"JoinMarket is a special kind of software that is aimed at improving the privacy and fungibility of bitcoin transactions. The main way to improve privacy and fungibility on-chain is via collaborative transactions.
A collaborative transaction requires the coordination of multiple parties. The right resources (UTXOs) have to be available in the right quantity at the right time.
Consequently, the problem that needs to be solved is not a technological problem, but an economic problem. JoinMarket solves this problem not by central coordination, but by creating a market that allows participants to allocate these resources in the best way, according to their individual needs.
"},{"location":"about/#about-the-name","title":"About the Name","text":"The name \"Jam\" is a backronym, stands for JoinMarket's Awesome, Man, and shouldn't be taken too seriously. However, it works on multiple levels (Let's jam the signal!) and \"cooking jam\" is also a fun metaphor for mixing something in a tasty way (and putting it in jars).
"},{"location":"about/#about-the-philosophy","title":"About the Philosophy","text":"
We believe that, in the long run, open protocols will survive. Platforms, on the other hand, are run by companies and all companies eventually go bankrupt.
The motivation behind Jam (and JoinMarket\u2014and Bitcoin, for that matter) is to build something that doesn't go away.
Motivation
"},{"location":"contribute/","title":"Contributing","text":"There are many ways you can contribute: testing, sharing ideas, writing documentation, creating tutorials, and\u2014of course\u2014writing code.
"},{"location":"contribute/#say-hello","title":"Say Hello","text":"It doesn't hurt to say hi and connect with the people that are already working on Jam, or have worked on it in the past.
Matrix Room
Telegram Chat
"},{"location":"contribute/#study-the-basics","title":"Study the Basics","text":"Identity and privacy are complex topics in general, and Bitcoin privacy is particularly tricky. Make sure to familiarise yourself with the basics before you get involved.
Privacy Fundamentals
Bitcoin Wiki: Privacy
"},{"location":"contribute/#understand-the-philosophy","title":"Understand the Philosophy","text":"Before you really get going you should understand the philosophy behind Jam and the foundations it is built upon.
Motivation
A Cypherpunk's Manifesto
"},{"location":"contribute/#what-to-work-on","title":"What to Work On","text":"While a very rough roadmap and some milestones exist, it's usually best to \"scratch your own itch.\" Found a bug? Fix it! Have a proposal to make something better? Create an issue! Found a typo? Fix it! Is Jam not available in your language? Translate it!
It can be daunting to get started, but Jam, like every software project, is just code & design & text.
"},{"location":"contribute/#code","title":"Code","text":"Review a pull request or work on some open issues. Small tasks that are relatively easy to do will have the \"good first issue\" label.
"},{"location":"contribute/#design","title":"Design","text":"Have a look at the Figma files, comment on them, or propose a change.
"},{"location":"contribute/#text","title":"Text","text":"If you're good with words and copy editing, or if you want to help to translate Jam into multiple languages, join the translation team.
"},{"location":"contribute/#just-get-started","title":"Just Get Started!","text":"Since all development happens out in the open and there are no gatekeepers, getting involved is as easy as showing up.
This is a free and open-source software project and we love receiving pull-requests, bug reports, ideas, and feedback from everyone. See the CONTRIBUTING.md file on GitHub for more details on how to get started participating in this project.
"},{"location":"glossary/","title":"Glossary","text":"Unfortunately, there is no way to talk about bitcoin privacy and the intricacies of JoinMarket without a little bit of jargon.
This glossary explains some of the concepts and terms used in Jam.
[ A \u00b7 B \u00b7 C \u00b7 D \u00b7 E \u00b7 F \u00b7 G \u00b7 H \u00b7 I \u00b7 J \u00b7 K \u00b7 L \u00b7 M \u00b7 N \u00b7 O \u00b7 P \u00b7 Q \u00b7 R \u00b7 S \u00b7 T \u00b7 U \u00b7 V \u00b7 W \u00b7 X \u00b7 Y \u00b7 Z ]
"},{"location":"glossary/#a","title":"A","text":""},{"location":"glossary/#address","title":"Address","text":"A bitcoin address\u2014also called bitcoin invoice address1\u2014is a string of characters that you send to someone else to receive funds.
There are currently three invoice address formats in use:
13bc1For more details please refer to the Bitcoin Wiki. Jam defaults to Bech32 addresses.
"},{"location":"glossary/#address-reuse","title":"Address Reuse","text":"Address reuse refers to the practice of reusing a single bitcoin invoice address for multiple transactions. It is highly discouraged since it harms the privacy of yourself and others. You should never reuse addresses.
Bitcoin Wiki: Address Reuse
"},{"location":"glossary/#anonymity-set","title":"Anonymity Set","text":"The only way to hide in plain sight is by hiding in a crowd. The anonymity set is simply the size of this crowd.
If you are putting on a hat and sunglasses to hide in a crowd of people that are wearing the same hat and sunglasses, your anonymity set is the size of this crowd. If said crowd is 50 people, an attacker could mistake you for anyone out of these 50 people. Similarly, when doing a collaborative transaction in bitcoin, you are creating an onchain footprint that is equivalent to the onchain footprint of others.
"},{"location":"glossary/#b","title":"B","text":""},{"location":"glossary/#base-layer","title":"Base Layer","text":"Bitcoin's base layer (or Layer 1) refers to any transaction that touches the timechain, i.e. all onchain transactions. The base layer is concerned with global consensus and settlement.
Higher layers build ontop the settlement assurrances of the base layer. One example of a Layer 2 system is the Lightning Network. All money is layered, including gold and fiat monies. Read Layered Money by Nik Bhatia to understand this in more detail.
Layered Money
"},{"location":"glossary/#batch-transaction","title":"Batch Transaction","text":"A batch transaction is a transaction that combines multiple real-world transactions into one on-chain transaction. It has multiple inputs and multiple outputs. Different parties may control one or multiple inputs and receive one or multiple outputs.
Privacy Fundamentals
"},{"location":"glossary/#bech32","title":"Bech32","text":"Bech32 is an invoice address format. It was specified in BIP 173 and is used for both SegWit and Taproot addresses.
"},{"location":"glossary/#blockchain","title":"Blockchain","text":"A mostly meaningless marketing term used to confuse newcomers. While \"block chain\" is still the main term used to refer to Bitcoin's linked data structure of blocks, it has increasingly become meaningless over the years as it got co-opted by grifters, charlatans & marketers. A better, more descriptive term of said data structure is timechain.
"},{"location":"glossary/#c","title":"C","text":""},{"location":"glossary/#chain-analysis","title":"Chain Analysis","text":"Chain analysis is is the practice of applying heuristics to a timechain's public transaction graph. The goal of chain analysis is to link the pseudonymous identities created by bitcoin software with \"real\" identities corresponding to natural persons or entities.
Chain analysis is based on flawed assumptions, because ownership in bitcoin is defined by secret knowledge, not possession. Identities can only be linked probabilistically, not provably. One of the main assumptions used by chain analysis companies is the common input ownership heuristic. Collaborative transactions break this heuristic.
"},{"location":"glossary/#coinjoin","title":"CoinJoin","text":"A CoinJoin is a collaborative transaction that combines inputs from multiple parties. The purpose of a CoinJoin is to combine inputs and create outputs in ways that improves the financial privacy of participants, without relying on a trusted third party for custody. When done correctly, a CoinJoin breaks any deterministic links between transactions, moving the process of chain analysis from quasi-deterministic with high certainty to probabilistic with low certainty.
CoinJoins break the common input ownership heuristic that is used by chain analysis companies to de-anonymize actors. The concept was 1st introduced in 2011 by Bitcointalk user hashcoin2, but later popularised in 2013 by Gregory Maxwell.34
All CoinJoin transactions are collaborative transactions. The two main types of CoinJoin transactions are equal-output and unequal-output CoinJoins. Other differences might be interactivity (or lack thereof) and number of participants.
"},{"location":"glossary/#collaborative-transaction","title":"Collaborative Transaction","text":"A collaborative transaction is a bitcoin transaction that is initiated and signed by multiple participants. A collaborative transaction involves two or more parties and is thus always a batch transaction. All CoinJoins are collaborative transactions.
"},{"location":"glossary/#change","title":"Change","text":"When using physical cash, spending a $100 bill to pay for a $25 item, you will get $75 back in change. The reason for this is that you can't spend just a part of the bill, because ripping off a quarter of it for payment will invalidate the bill. Consequently, when bills change hands, the whole bill has to be spent, and an appropriate amount of change goes back to the spender.
Bitcoin works the same way. When sats change hands, the spender has to spend the whole UTXO. Bitcoin creates the appropriate amount of change automatically. Because all transactions are recorded transparently and publicly on the timechain,
As of this writing,5 a simple spend is the most common transaction type, which describes the example given above: one input ($100 bill) produces two outputs: $25 for the merchant, and $75 in change. The act of an outside observer guessing whether you bought something for $25 or $75 (or: who was the customer of the transaction, and who was the merchant) is what is called change detection.
"},{"location":"glossary/#change-detection","title":"Change Detection","text":"When it comes to chain analysis, change detection is the name of the game. The goal of chain analysis companies is to link identities to transactions, and to do that, one has to detect whether funds changed hands or not.
Technically speaking, change detection is trying to figure out which output of a transaction is a change output. Change detection is based on various heuristics. False positives will always exist, even if the transaction under scrutiny is a simple spend. Consequently, it is more an art than a science.
To quote one special investigations team speaking on chain analysis:
Attributing ownership, however, is often nuanced because outside observers can only infer it depending on factors such as availability and quality of the evidence. Evidence means proof that indeed an address belongs to an individual or entity. Unless you own an address yourself, it is very difficult to say with absolute certainty who an address is owned by. This is why it\u2019s more fitting to consider blockchain analytics more of an art than science.
CSIT
Keep in mind that ownership can change without any on-chain transaction happening, e.g. by passing on a private key directly. It is also possible that amount to be paid lines up perfectly with a single UTXO, meaning that what looks like a self-spend is actually a payment.
One can only conclude, as is also mentioned in the report linked above, that \"an external observer cannot possibly gain a full picture or claim 100% confidence in ownership attribution.\"
Privacy Fundamentals: The Bitcoin Transaction
Bitcoin Wiki: Change Detection
"},{"location":"glossary/#cioh","title":"CIOH","text":"Short for Common Input Ownership Heuristic.
"},{"location":"glossary/#common-input-ownership-heuristic","title":"Common Input Ownership Heuristic","text":"The common input ownership heuristic assumes that all inputs of a transaction are controlled by a single entity. This assumption is clearly wrong, because collaborative transactions exist. CoinJoin transactions are designed to break this heuristic.
"},{"location":"glossary/#d","title":"D","text":""},{"location":"glossary/#doxxic-change","title":"Doxxic Change","text":"\"Doxxic\" change is any leftover change that is going back to you when participating in an equal-output CoinJoin. Doxxic change is problematic because it can potentially destroy any privacy benefits gained from a CoinJoin.
The word is a combination of \"toxic\" and \"doxxing.\" Doxxing is the act of finding out the legal identity (or similar identifiying information) of a pseudonymous entity. Bitcoin is a pseudonymous system and does not require the True Names6 of participants.
You can use the sweep functionality to avoid doxxic change in Jam.
"},{"location":"glossary/#e","title":"E","text":""},{"location":"glossary/#eclipse-attack","title":"Eclipse Attack","text":"An eclipse attack is an attack in networked systems in which an attacker targets a node to convince it of a false network state. The attacker surrounds the node in order to conceal or block off accurate information, leaving the attacked node(s) in the dark in terms of the global network state.
An eclipse attack is similar to a Sybil attack.
Bitcoin Stack Exchange: Eclipse Attack vs. Sybil Attack
"},{"location":"glossary/#equal-output-coinjoin","title":"Equal-Output CoinJoin","text":"An equal-output CoinJoin is a collaborative transaction that produces outputs of equal denomination, i.e. outputs of equal value when measured in sats. For this reason, these types of transactions are also referred to as equal-amount or equal-value CoinJoin transactions.
Equal-output CoinJoins are batch transaction that are easily identifiable on-chain due to their uniform output structure.
Like any collaborative transaction, an equal-output CoinJoin breaks the Common Input Ownership Heuristic. Participating in such a transaction allows you to gain privacy by \"hiding in the crowd.\"
Jam defaults to collaborative transactions when sending and sweeping, creating equal-output CoinJoins.
"},{"location":"glossary/#f","title":"F","text":""},{"location":"glossary/#fidelity-bond","title":"Fidelity Bond","text":"A fidelity bond is an insurance policies which protects the policyholder from wrongful acts committed by others. The term comes from the world of business and finance, thus the policyholders are usually companies, and the other parties are usually employees.
In JoinMarket, a fidelity bond is a mechanism which ensures that market actors act honestly. It is a protection mechanism against Sybil attacks, because a fidelity bond makes the creation of cryptographic identities costly.
Warning
It is impossible to move or spend funds that are locked in a fidelity bond before the bond expires. They cannot be used in collaborative transactions (neither as taker nor as maker) as fidelity bonds are time-locked by the Bitcoin protocol.
Fidelity bonds improve the privacy guarantees of the whole system and increase your chance of being chosen as a market maker drastically.
What Are Fidelity Bonds and How Do They Work in JoinMarket?
JoinMarket: Fidelity Bonds
JoinMarket: Financial Mathematics of Fidelity Bonds
Creating a Fidelity Bond in Jam
"},{"location":"glossary/#j","title":"J","text":""},{"location":"glossary/#jam","title":"Jam","text":"Jam is both the name of the project and the verb we use when a collaborative transaction is in progress.
Sir! The radar, sir! It appears to be... [Jam starts flowing through the computer screen] jammed!
Spaceballs
About
jamapp.org
"},{"location":"glossary/#jar","title":"Jar","text":"In Jam, a \"jar\" is a container that holds some sats of yours.7 Jars exist to segregate your sats into multiple buckets that are disconnected from each other, which aids privacy. To not risk any privacy degradation, you can only spend from one jar at a time.
There are 5 jars by default. The default jar to receive funds is Jar A.
"},{"location":"glossary/#m","title":"M","text":""},{"location":"glossary/#maker","title":"Maker","text":"A market maker is someone who offers bitcoin liquidity to the market, to be used by others for collaborative transactions. You can create an offer via the \"Earn\" tab and become a market maker.
Earn Screen
The Maker Role
"},{"location":"glossary/#mempool","title":"Mempool","text":"Short for 'memory pool.' A pool of valid bitcoin transactions held by each node, that are not yet confirmed in the timechain.
Mempool
"},{"location":"glossary/#o","title":"O","text":""},{"location":"glossary/#offchain","title":"Offchain","text":"An offchain (or off-chain) transaction is any transaction that does not happen onchain. Examples include transactions on the Lightning network, the handing over of physical private keys, as well as transactions on centralized ledgers such as exchanges and other trusted third parties.
Some offchain transactions, such as handing over private keys on USB sticks or similar, are outside of the scope of chain analysis. Consequently, chain analysis can never be completely accurate.
"},{"location":"glossary/#onchain","title":"Onchain","text":"An onchain (or on-chain) transaction is a bitcoin transaction that is settled on the bitcoin timechain. The analysis of these transactions is called chain analysis, which is the spying on and de-anonymizing of bitcoin's users by trying to find patterns in the onchain data.
"},{"location":"glossary/#p","title":"P","text":""},{"location":"glossary/#p2pkh","title":"P2PKH","text":"Short for pay-to-public-key-hash.
Learn Me A Bitcoin: P2PKH
"},{"location":"glossary/#p2sh","title":"P2SH","text":"Short for pay-to-script-hash.
Learn Me A Bitcoin: P2SH
"},{"location":"glossary/#payjoin","title":"PayJoin","text":"A PayJoin is a collaborative transaction between two parties that facilitates an actual payment for a good or service. The merchant agrees to provide one or multiple inputs to the transaction, increasing the privacy of both parties.
A PayJoin has different onchain characteristics than an equal-output CoinJoin and is not detectable via chain analysis alone. A PayJoin transaction has multiple interpretations, all of which are equally valid. In addition to breaking the common input ownership heuristic it poisons the basis of all chain analysis, because of its undetectability.
Bitcoin Wiki: PayJoin
Bitcoin Wiki: PayJoin Adoption
"},{"location":"glossary/#s","title":"S","text":""},{"location":"glossary/#sats","title":"Sats","text":"Short for satoshis, plural of sat (satoshi).
A sat the smallest fraction of a bitcoin that can be expressed on-chain. There are 100,000,000 sats in a bitcoin. There are multiple currency symbols for a sat emerging. In Jam, the sat symbol8 is used:
The 'scheduler' is a component of JoinMarket which schedules multiple collaborative transactions in a row. It will use random intervals and amounts to make timing analysis and de-anonymization via chain analysis more difficult.
The 'Sweep' screen uses the scheduler to sweep funds to one or multiple external wallets under your control.
"},{"location":"glossary/#simple-spend","title":"Simple Spend","text":"A transaction that splits one input into two outputs: payment and change.
The \"simple spend\" is the most common bitcoin transaction type to date, since most wallet implementations do not optimize for privacy. For most simple spend transactions it is possible to discern which output is the actual payment or which one is the change. This change detection makes the tracing of funds possible.
Privacy Fundamentals: The Bitcoin Transaction
"},{"location":"glossary/#snicker","title":"SNICKER","text":"Simple Non-Interactive Coinjoin with Keys for Encryption Reused.
SNICKER blog post
"},{"location":"glossary/#sybil-attack","title":"Sybil Attack","text":"A Sybil attack is a special kind of attack in peer-to-peer networked computing. The victim is surrounded by malicious entities, each of which act as if they are a separate entity. The victim believes that everything is in order, that he is getting an accurate state of the network from multiple independent peers. In actuality, the Sybil attacker controls all entities surrounding the victim. Consequently, the attacker is able to trick the victim into accepting a malicious network state.
JoinMarket uses fidelity bonds to protect users from Sybil attacks.
Design for Improving JoinMarket's Resistance to Sybil Attacks Using Fidelity Bonds
Wikipedia: Sybil Attack
"},{"location":"glossary/#sweep","title":"Sweep","text":"A 'sweep' send will transfer all funds of a jar or all funds of your wallet. To sweep all funds from your wallet multiple transactions are created using the scheduler.
'Sweep' Screen
"},{"location":"glossary/#t","title":"T","text":""},{"location":"glossary/#taint","title":"Taint","text":"Taint is an external property defined by chain analysis surveillance firms. It is an attempt to trace the origin and ownership of UTXOs, classifying their owners and building lists of \"good\" and \"bad\" money.
All taint in bitcoin always is and always will be arbitrarily defined and probabilistically applied. Just like change detection, it is more an art than a science. It can never be done exactly. False positives and false negatives will always arise.
The bitcoin network is indifferent to taint. Miners will include any transaction in a valid block that will reward them economically. Any application of taint on the block production level is equivalent to imposing additional rules via a soft-fork, which fully validating nodes can reject.
"},{"location":"glossary/#taker","title":"Taker","text":"A market taker is someone who buys bitcoin liquidity from the market, taking up market makers on their offers. You can see active offers in the order book.
You will automatically take offers when running the scheduler via the \"Sweep\" functionality.
Sweep
Earn Screen
The Taker Role
"},{"location":"glossary/#timechain","title":"Timechain","text":"The data structure of Bitcoin's base layer. It represents a timestamped and linked list of blocks. Anyone can create a new block, but each block must have sufficient proof of work, making it costly to create new blocks.
Bitcoin is Time
"},{"location":"glossary/#timelock","title":"Timelock","text":"A UTXO can be locked up by a script which defines that said UTXO can only be spent in a block that is higher than a certain value. This makes UTXOs unspendable before a specific time.
"},{"location":"glossary/#transaction","title":"Transaction","text":"A bitcoin transaction describes the movement of sats. It is structured data that describes inputs and outputs, among other things. A valid bitcoin transaction has at least one input and at least one output. Every transaction input refers to the output of a previous transaction. We say that an input \"consumes\" an output. If an output is not consumed yet, we speak of an unspent transaction output, or UTXO, for short.
Privacy Fundamentals: The Bitcoin Transaction
Bitcoin Wiki: Transaction
Learn Me a Bitcoin: Transactions
"},{"location":"glossary/#tx","title":"TX","text":"Short for transaction.
"},{"location":"glossary/#u","title":"U","text":""},{"location":"glossary/#unspent-transaction-output","title":"Unspent Transaction Output","text":"The tip of the chain of signatures which originates in a coinbase output. It's a \"coin\" that has not yet been spent and can still be spend.
"},{"location":"glossary/#utxo","title":"UTXO","text":"Short for Unspent Transaction Output.
The term invoice is proposed in BIP-179 as an alternative.\u00a0\u21a9
Blind Bitcoin Transfers hashcoin, July 2011\u00a0\u21a9
I taint rich! Maxwell, Jan. 2013\u00a0\u21a9
CoinJoin: Bitcoin privacy for the real world Maxwell, Aug. 2013\u00a0\u21a9
Block 744,811\u00a0\u21a9
Vernor Vinge, 1981, True Names \u21a9
What we call \"jars\" are usually called \"mixdepths\" in JoinMarket. They are also referred to as \"pockets\" and \"accounts\" in some of the older parts of the JoinMarket documentation.\u00a0\u21a9
satsymbol.com \u21a9
While everyone will use Jam differently, here is one way you can think about the general application flow:
Some of your UTXOs might be chunky and identifiable, like whole or large pieces of fruit. Once you make delicious jam out of them, they are less chunky and less identifiable. You are free to offer your fruits to others so they can make jam more easily.
Without the fruity metaphor: to increase the privacy and fungibility of your funds\u2014and thus your security overall\u2014you should use Jam as both a market maker ('Earn' tab) and a taker ('Send' and 'Sweep' tabs). Use a Jar's sweep functionality or the Scheduler to transfer funds out of Jam, e.g. to move all your funds to cold storage or to use them to open lightning channels. If you want to pay others for goods and services, use send.
"},{"location":"interface/00-cheatsheet/#first-use","title":"First Use","text":"Click \"Cheatsheet\" at the bottom of the screen to open up the cheatsheet in Jam.
Receive
"},{"location":"interface/00-cheatsheet/#things-to-note","title":"Things to Note","text":"Some processes in Jam might take a long time to complete. Further, Jam is considered beta software. While JoinMarket is tried and tested, Jam is new and things might break. Use with caution. Please report any issues directly on GitHub.
Make sure to understand the privacy fundamentals, best practices, as well as the motivation behind this software. Also, understand that you are participating in a free market. How much you can earn and how many fees you have to pay depends on market conditions.
Motivation
Privacy Fundamentals
Fees
Make sure to create a fidelity bond to increase the chances of your offer being taken.\u00a0\u21a9
Use the 'Receive' tab to receive funds.
A new invoice address will be generated every time. You can scan the QR code with a mobile wallet or copy/paste the invoice address to receive funds from someone else, or send funds from another wallet yourself.
Info
Jam uses jars under the hood to separate funds into disconnected containers. Think of jars as different pockets in your wallet, or different identities. The default jar to receive funds is Jar A.
Once you have funded your wallet, you can use the 'Send' tab to do a collaborative transaction.
Send
"},{"location":"interface/02-send/","title":"Send","text":"Use the 'Send' tab to send funds to someone or to one of jars. Jam defaults to collaborative transactions when sending, which enhances your privacy and security.
Info
Jam uses jars under the hood to separate funds into disconnected containers. Think of jars as different pockets in your wallet, or different identities.
You can choose the number of collaborators in the send options. The higher the number of collaborators, the larger your anonymity set.
Use the 'Sweep' button in the amount field to empty a single jar, or use the Sweep tab to sweep all non-frozen funds of your wallet to external addresses.
After you made your first collaborative transaction with one of your jars as the recipient, you are ready to earn.
Earn
"},{"location":"interface/03-earn/","title":"Earn","text":"Use the 'Earn' tab to earn sats by offering liquidity to other market participants. You will be acting as a market maker. Creating a fidelity bond is recommended. In Jam, takers pay 100% of the mining fees: as a market maker, you will not pay anything. Just profit!
"},{"location":"interface/03-earn/#fidelity-bonds","title":"Fidelity Bonds","text":"Make sure to create a fidelity bond to increase the chances of your offer being taken.
A fidelity bond is a mechanism which ensures that market actors act honestly. It is a protection mechanism against Sybil attacks. A fidelity bond makes the creation of cryptographic identities costly.
Fidelity bonds improve the privacy guarantees of the whole system and increase your chance of being chosen as a market maker drastically.
Be aware that funds locked in a Fidelity Bond will not be included in your offer amount, so remember to keep additional funds in order to participate as a market maker.
Warning
It is impossible to move or spend funds that are locked in a fidelity bond before the bond expires. They cannot be used in collaborative transactions (neither as taker nor as maker) as fidelity bonds are time-locked by the Bitcoin protocol.
Fidelity Bonds
"},{"location":"interface/03-earn/#offer-options","title":"Offer Options","text":"There are two types of offers:
250 sats.0.03%.Once you are done earning, you can sweep all funds to an external wallet.
Sweep
"},{"location":"interface/04-sweep/","title":"Sweep","text":"Use the 'Sweep' tab to empty your wallet using the scheduler. The scheduler will execute a series of collaborative transactions with randomized parameters, which will send your funds to multiple destination addresses over time.
Once the scheduler is active you will see a green indicator light, which means that the scheduler service is running. The service will take any matching offer automatically.
You can stop the scheduler at any time.
Cheatsheet
"},{"location":"interface/fidelity-bonds/","title":"Fidelity Bonds","text":"A fidelity bond is a mechanism which ensures that market actors act honestly. It is a protection mechanism against various kinds of attacks that involve the creation of fraudulent identities.
Glossary: Fidelity Bond
Warning
It is impossible to move or spend funds that are locked in a fidelity bond before the bond expires. They cannot be used in collaborative transactions (neither as taker nor as maker) as fidelity bonds are time-locked by the Bitcoin protocol.
You can create a fidelity bond via the Earn screen. It involves the following steps:
cj-outAfter that, you will be asked to review the bond configuration. If everything looks right, you can create the fidelity bond which will time-lock your funds for the set duration.
Refer to the screenshots below to understand the steps in more detail:
Orderbook
Earn
"},{"location":"interface/settings/","title":"Settings","text":"Access the settings by clicking on the gear icon () in the top-right corner.
"},{"location":"interface/settings/#general-settings","title":"General Settings","text":"Jam supports the creation and handling of multiple wallets. However, only one wallet can be actively used at a time. Wallets are locked when not used. Your \"active\" wallet is the one that is currently unlocked.
Question
Want to import a wallet? Look at the FAQ!
"},{"location":"interface/settings/#community-links","title":"Community Links","text":"Clicking on the active wallet in the top-left corner will open the wallet view.
You can see your jars and whats in them by clicking on the arrow. Clicking on a jar will open its detail view, which allows you to inspect individual UTXOs, as well as freeze/unfreeze them.
"},{"location":"market/fees/","title":"Fees","text":"Fees play a crucial role in the incentive structure of both Bitcoin and JoinMarket. They form the basis for the economic incentives of both systems. In Bitcoin, you pay fees to a miner in order for your transaction to be included in a block. The higher the fee you are willing to pay, the higher the likelihood that your transaction will be included quickly.
In JoinMarket, you pay fees to market makers in order to use their liquidity to both of your advantage. However because the market maker gets the fee as he is waiting around and providing the liquidity.
Consequently, when you are sending a collaborative transaction in Jam\u2014or when you are using the scheduler to do multiple transactions\u2014you have to pay fees to miners and makers. How high these fees are depends on market and mempool conditions.
Of course, you can offer liquidity yourself via the Earn functionality, allowing you to be on the receiving end when it comes to maker fees.
Earn
"},{"location":"market/fees/#paying-maker-fees","title":"Paying Maker Fees","text":"When doing a collaborative transaction via the Send or Sweep tabs, you are taking liquidity offers from others, effectively becoming a market taker.
How much you will pay in maker fees depends on the fee market of the current offers. You can get an overview of fees by inspecting the order book.
FAQ: How high are the fees that I do have to pay?
Orderbook
"},{"location":"market/fees/#paying-mining-fees","title":"Paying Mining Fees","text":"Just like all users of onchain bitcoin, you will have to pay transaction fees to miners.
Note that collaborative transactions are larger, in terms of bytes, than \"regular\" bitcoin transactions. Since the cost of an onchain transaction is determined by its size in bytes\u2014not by value transferred\u2014a collaborative transaction is more expensive than a simple spend.
FAQ: How high are the fees that I do have to pay?
Mempool
"},{"location":"market/fees/#earning-maker-fees","title":"Earning Maker Fees","text":"As mentioned above, you can use the Earn tab to earn maker fees yourself. Simply choose an offer type, select how many fees you would like to earn, and press \"Start Earning!\".
Make sure to check the orderbook to compare your offer with current market rates. If your offer isn't competitive, it's likely nobody will take it and thus you will earn zero sats.
FAQ: How much can I earn?
Orderbook
"},{"location":"market/fees/#fee-conversion","title":"Fee Conversion","text":"All fees are denominated in sats. Use one of the tools below to convert them to fiat:
See also \"a note on fees\" from the JoinMarket documentation.
A Note on Fees
"},{"location":"market/mempool/","title":"Mempool","text":"The mempool (memory pool) is a pool of transactions that are not included in the timechain yet. It is a waiting room for transactions, if you will. Every full node has its own mempool\u2014there is no single mempool that is shared by nodes, there is an individual mempool for every single node. Mempools might differ depending on node configuration. Nodes can decide which transactions to keep, which transactions to pass on to other nodes, and which transactions to drop.
Miners will consult their mempools to construct candidate blocks. Once a transaction is included in a valid block\u2014and your node confirms the blocks validity\u2014it is considered confirmed and removed from the node's mempool.
Learn me a bitcoin: Memory Pool
Miners are incentivised to include transactions that reward them the most, i.e. transactions that pay the highest mining fees. Because mining fees are set by the users, you can view mining fees as a kind of bribe that is paid by the users to the miners. If the bribe is high, the chance of your transaction being included is high. If it is low, the chance of inclusion is lower.
Paying Mining Fees
"},{"location":"market/mempool/#mempool-and-transaction-fees","title":"Mempool and Transaction Fees","text":"Bitcoin block space is scarce. If onchain activity is high, the mempool will be crowded. The more crowded the mempool, the higher the \"bribe\" you will have to pay to miners.
Fee estimation is an attempt to guess how high the fee needs to be for your transaction to be included in the future. It is more an art than a science, since the future is always uncertain and mempool conditions might change quickly.
Most mempool explorers have some sort of fee estimation. You can also use the estimatesmartfee command to do a fee estimation based on your mempool:
bitcoin-cli estimatesmartfee 21 economical\nWe recommend that you use your own node to inspect the mempool. For example, you can use the getrawmempool command to inspect your mempool:
bitcoin-cli getrawmempool true\nOf course, plenty of graphical user interfaces exist too. The software that is powering mempool.space is free software and can be installed quite easily on your node.
Mempool One-Click Installation
"},{"location":"market/mempool/#mempool-visualisations","title":"Mempool Visualisations","text":"You can also refer to public mempool instaces in case you don't have access to the mempool of your own node. Note, however, that using public mempool and block explorers has certain privacy implications, as whoever is running these websites will be able to correlate your IP with the blocks and transactions you look up. Use Tor or a VPN to mitigate this.
mempool.space
There are also great visualisations that help you understand what's going on, Bitfeed and Mempool Observer being two of them.
Visualisation: Mempool Observer
Visualisation: Bitfeed
"},{"location":"market/orderbook/","title":"Orderbook","text":"The order book (or orderbook) shows what kind of offers are currently on the market. It gives insights in regards to offer types, fees, offer sizes, and fidelity bonds put up by market makers.
Jam will set up a service that allows you to watch the order book on your node. This removes the trust in a third party. You can view the order book directly in Jam via the \"Show orderbook\" button on the Earn screen.
There are also public order books that you can inspect, in case you do not have access to your own node:
nixbitcoin.org/orderbook
"},{"location":"market/volume/","title":"Volume","text":"In JoinMarket, liquidity is sold and bought on a free market. Consequently, market volume and depth depends on market conditions. You can inspect the order book to get an overview of the current offers.
Orderbook
Some sites show historical statistics in regards to market volume and liquidity. Please note that the statistics shown on these sites sometimes use proprietary data and algorithms.
JoinMarket KPIs
"},{"location":"philosophy/00-motivation/","title":"Motivation","text":"There is a sacred realm of privacy for every man and woman where he makes his choices and decisions\u2009\u2014\u2009a realm of his own essen\u00adtial rights and liber\u00adties into which the law, gener\u00adally speaking, must not intrude.
Geoffrey Fisher, Archbishop of Canter\u00adbury (1959)
Jam is a tool, just like bitcoin. Before using it, you should understand how you could benefit from using it, how it works, and how to use it correctly. In order to answer the \"how\" you should also understand the \"why\" --- why was it created, and what is the problem in the first place?
To answer that properly, we will have to talk about privacy and financial privacy in general, and bitcoin privacy in particular:
\"Privacy is neces\u00adsary for an open society in the electronic age. Privacy is not secrecy. A\u00a0private matter is something one doesn't want the whole world to know, but a\u00a0secret matter is something one doesn't want anybody to know. Privacy is the power to selec\u00adtively reveal oneself to the\u00a0world.\"
Eric Hughes
With these powerful words Eric Hughes opened his Cypher\u00adpunk's Manifesto in 1993. The differ\u00adence between privacy and secrecy is subtle, but impor\u00adtant. Choosing to remain private does not imply that one has secrets or has something to hide. To illus\u00adtrate this just realize that what you do on the toilet or in the bedroom is neither illegal nor a\u00a0secret (in most cases), yet you close the door and pull the curtains.
Similarly, how much money you have and where you spend it is not neces\u00adsarily a\u00a0secret matter. It should, however, be a\u00a0private one. Most would agree that your boss should not know how you choose to spend your salary.
The impor\u00adtance of privacy is recog\u00adnized by many inter\u00adna\u00adtional bodies. From the American Decla\u00adra\u00adtion of the Rights and Duties of Man to the United Nations, it is recog\u00adnized that privacy is a\u00a0funda\u00admental human right worldwide.
No one shall be subjected to arbitrary inter\u00adfer\u00adence with his privacy, family, home or corre\u00adspon\u00addence, nor to attacks upon his honour and reputa\u00adtion. Everyone has the right to the protec\u00adtion of the law against such inter\u00adfer\u00adence or\u00a0attacks.
Article 12, United Nations Decla\u00adra\u00adtion of Human\u00a0Rights
Although Bitcoin was often described as an anony\u00admous method of payment by early propo\u00adnents and by the media, it is anything but. Bitcoin is pseudo\u00adny\u00admous at best and as of today making sure that your pseudo\u00adny\u00admous bitcoin identi\u00adties cannot be linked to your real-world identity proves diffi\u00adcult for most\u00a0people.\u00a0
Bitcoin is an open system. Its public ledger can be inspected and studied by everyone. Thus every trans\u00adac\u00adtion that is embedded in its proof-of-work chain will be exposed for as long as Bitcoin exists: eternity. Failing to follow privacy best practices now can poten\u00adtially have negative reper\u00adcus\u00adsions in the\u00a0future.
Privacy, like security, is a\u00a0process and it is diffi\u00adcult, but not impos\u00adsible. Tools continue to be devel\u00adoped to help preserve privacy while using Bitcoin and fortu\u00adnately most of these tools become easier to use over time. Unfor\u00adtu\u00adnately no panacea exists. One has to remain aware of the trade\u00adoffs and follow best practices as they\u00a0evolve.1
Free Software
"},{"location":"philosophy/00-motivation/#why-jam","title":"Why Jam?","text":"Jam is a front-end for JoinMarket, a privacy-focused bitcoin software that uses a peer-to-peer marketplace to facilitate collaborative transactions, also called \"CoinJoins.\"2
A collaborative transaction, as the name implies, is a bitcoin transaction that is done collaboratively by multiple parties. The tricky part of getting a collaborative transactions done is not technical, but social. It is a problem of matchmaking, timing, and trust.
Usually, this problem is solved with a central coordinator.
JoinMarket takes a different approach. It allows participants to propose collaborative transactions to others, creating an open market of buyers and sellers, which removes the central coordinator from the equation.
JoinMarket
"},{"location":"philosophy/00-motivation/#tech-fundamentals","title":"Tech Fundamentals","text":"With the motivation and purpose of Jam covered, understanding the fundamentals of bitcoin in general and bitcoin privacy in particular might be useful.
Privacy Fundamentals
Some parts of the above are based on \"Bitcoin Privacy: Best Practices, written by Gigi and released under CC BY-SA 4.0 license.\"\u00a0\u21a9
We prefer to refer to them as collaborative transactions, which is more concise and explanatory.\u00a0\u21a9
Jam is free as in freedom. We believe that free software is an imperative for a free society, which is why Jam is released under a free software license.
Bitcoin is financial software. Consequently, any financial liberation that is enabled by Bitcoin rests on the four essential freedoms granted by free software.
What is Free Software?
\u201cFree software\u201d means software that respects users' freedom and community. Roughly, it means that the users have the freedom to run, copy, distribute, study, change and improve the software. Thus, \u201cfree software\u201d is a matter of liberty, not price. To understand the concept, you should think of \u201cfree\u201d as in \u201cfree speech,\u201d not as in \u201cfree beer.\u201d
Free software puts the users in control, both collectively and individually. Free software is not only about being \"open\" and \"more secure.\" While these are nice side-effects, the main issue is about control and respecting user's freedoms.
Why Free Software Is Even More Important Now
Freedom means having control over your own life. If you use a program to carry out activities in your life, your freedom depends on your having control over the program. You deserve to have control over the programs you use, and all the more so when you use them for something important in your life.
Most software and software products force the user into a master-slave relationship, as do most monetary systems and financial products. Bitcoin is freedom money because the software that makes Bitcoin possible is free software\u2014free as in freedom. There are no masters, only peers.
Bitcoin
"},{"location":"philosophy/02-bitcoin/","title":"Bitcoin","text":"There is much to be said about Bitcoin and why it was created. Many books have been written, much speculation was and is still being had in terms of Satoshi's \"true\" vision and motivation.3
Undoubtedly, there are certain values embodied in the Bitcoin system\u2014certain opinions that are embedded in the code, expressing how things should be done and what should be avoided. Nothing makes this more clear than the announcement post of Bitcoin, written by Satoshi himself.
Below are some highlights that are particularly relevant:
I've developed a new open source P2P e-cash system called Bitcoin. It's completely decentralized, with no central server or trusted parties, because everything is based on crypto proof instead of trust.
No central server. No trusted third party. Peer-to-peer (P2P), instead of client-server or master-slave.
Thanks to strong cryptography, trust in third parties can be eliminated. When possible, rely on cryptographic proof instead of trust. Trusted third parties should be eliminated because (a) they introduce friction and (b) they are security holes.1
We have to trust [banks] with our privacy, trust them not to let identity thieves drain our accounts. [...] Before strong encryption, users had to rely on password protection to secure their files, placing trust in the system administrator to keep their information private. Privacy could always be overridden by the admin based on his judgment call weighing the principle of privacy against other concerns, or at the behest of his superiors.
Privacy. Admins that spy on you. Systems that are designed to spy on you. Unfortunately, it's almost non-existent in today's world of surveillance capitalism and dragnet surveillance.
While credit requires identity, money does not. When you can trust the money you don't have to trust the person. In Bitcoin, there are no persons; only pseudonymous identities. Identities that are generated cryptographically at virtually no cost.
With e-currency based on cryptographic proof, without the need to trust a third party middleman, money can be secure and transactions effortless.
No middlemen. Secure and effortless. The reason why your browser will show you a green lock or a shield when a connection is encrypted is that privacy and security are two sides of the same coin. Without privacy, your physical security might be at risk.2 Without privacy, free thought and free speech are impeded.
The result is a distributed system with no single point of failure.
No single point of failure. No admins.That is one of the main value propositions of Bitcoin, and what makes it so resilient. This resiliency, and the fact that the users are in charge\u2014and nobody else\u2014is what sets Bitcoin apart. JoinMarket continues this philosophical approach: economic actors in a peer-to-peer system, no single point of failure.
JoinMarket
Szabo, 2001. Trusted Third Parties Are Security Holes \u21a9
Jameson Lopp, List of Known Physical Bitcoin Attacks \u21a9
A selection of books is available in the Bitcoin and Cypherpunk History section of bitcoin-resources.com/books \u21a9
JoinMarket, just like Bitcoin, doesn't have a single point of failure. It can be understood as a protocol that facilitates certain kinds of collaborative transactions\u2014CoinJoins\u2014via an open market.
Creating collaborative transactions is not a technical problem, but a problem of coordination. Someone has to bring the participants together, coordinate time and place, as well as amounts and fees.
Usually, this problem is solved by a central coordinator. In the best case, the central coordinator is non-custodial and blinded, meaning that user funds are never at risk, and the amount of information the central coordinator can obtain is minimal. However, even in this optimal case, the central coordinator is still a single point of failure.
In addition to being a central point of failure, any central coordinator usually charges a fee for the coordination service, which means that it is an entity that is making money. In most cases, this entity is a company that can be pressured and subverted, as has happened in the past. Even without any outside pressure, an economic entity might make certain decisions against the best interest of its users, just out of self-preservation alone.1
JoinMarket provides a decentralised alternative to these central coordination services. It is not a central entity, it is software that is coordinating the actions of multiple peers, just like Bitcoin. JoinMarket is neutral, meaning that the system itself is not charging its users to use the software for coordination. Fees are earned by market makers, i.e. those who are willing to provide liquidity to the open market. Consequently, JoinMarket is not a financial entity. Only the users are making money. JoinMarket is not.
Glossary
JoinMarket is a tried and tested CoinJoin implementation, having been actively used on Bitcoin's mainnet since 2015.2 Because of its lack of a centralised coordinator, it works a bit differently than other CoinJoin implementations.3 You can read about the details of JoinMarket's design in the high-level design document of the JoinMarket docs.
JoinMarket is free and open-source software, which means that anyone is free to use, inspect, and modify the software.
Free Software
Because of its decentralised nature, and thus the lack of funds and focused effort that a central company structure allows, the JoinMarket software was, historically, a bit difficult to set up and use. We hope that the efforts around Jam will make it a bit easier.
Installation
See, for example: https://archive.ph/C53tk, https://archive.ph/hIYJO \u21a9
See the Bitcoin Wiki for https://en.bitcoin.it/wiki/JoinMarket \u21a9
Shinobi, 2021 JoinMarket Vs. ZeroLink \u21a9
When it comes to Bitcoin, misconceptions abound. This is not surprising. Bitcoin is a new thing, and, consequently, all metaphors and comparisons fall short, in one way or another.
One misconception is that Bitcoin is private and untraceable. In actuality, regular Bitcoin use often has weaker privacy guarantees than using the traditional banking system, as Gregory Maxwell pointed out many years ago:
\u201cYour inlaws can see that you're buying birth control that deprives them of grandchildren, your employer learns about the non-profits you support with money from your paycheck, and thieves see your latest purchases and how wealthy you are which helps them target and scam you. Poor privacy in Bitcoin can be a major practical disadvantage for both individuals and businesses.\u201d
To understand why this is, we have to understand how Bitcoin operates. This, however, turns out to be very difficult. To understand one part, one needs to have a solid understanding of computer science and cryptography. To understand another part, one needs to have a solid understanding of economics and game theory\u2014not to mention money, networks, governance, energy and energy markets, monetary history, and so on. The list of relevant disciplines is almost endless.
However, it is possible to look at some parts of Bitcoin in isolation and\u2014hopefully\u2014gain a better understanding by zooming in. One such part is the Bitcoin transaction.
"},{"location":"privacy/01-fundamentals/#the-bitcoin-transaction","title":"The Bitcoin Transaction","text":"In the simplest sense, a Bitcoin transaction is just a bunch of data that describes the movement of bitcoins.
A bitcoin transaction consists of inputs and outputs. Every transaction input refers to the output of a previous transaction (except the coinbase transaction). We say that an input \"consumes\" an output. If an output is not consumed yet, we speak of an unspent transaction output, or UTXO, for short.
Once properly understood, it is easy to see what the Bitcoin network generates: a linked data structure that, starting from a common root\u2014the genesis block\u2014splits and combines bundles of sats as time goes on. Properly visualized, it would look a bit like an upside-down tree.
Every transaction has at least one input and at least one output. The simplest and traditionally most common transaction type has one input and two outputs: one describing the actual payment and one describing the change that goes back to the one who initiated the payment.
The concept of change is required because Bitcoin doesn't allow an update of the past. It is an append-only log, so instead of going back and modifying past entries, new entries have to be created to reflect any updates. Transactions are what create these updates. For a simple transaction, one new \"entry\" is created to update the balance of the receiver, and one new entry is created to update your own balance. You can think of it as paying for something that costs $5 with a $20 bill. The merchant receives five dollars, and you get $15\u2014the change\u2014back. However, we don't have physical coins and bills, we only have an append-only log. So instead of bills of smaller denominations, new entries\u2014new UTXOs\u2014are created.
While this design is ingenious when it comes to validation\u2014you can easily make sure that everything adds up at all times\u2014there are certain nuances to consider when it comes to privacy.
For example, if it is trivial to determine which output is a change output and which one isn't, it is trivial to cluster outputs and thus identify not only the flow of funds, but also who transacted with whom, at what times, and\u2014of course\u2014the amounts that were transacted. Imagine a data leak that exposes all transactions of every company, every individual, every politician, every bank, every merchant, every online shop, and every vending machine. When used naively, this data leak is Bitcoin.
Luckily, the situation is not as grim as it sounds. Developments and techniques exist to remedy this situation. To understand them, we have to understand the various transaction types that Bitcoin allows.
"},{"location":"privacy/01-fundamentals/#bitcoin-transaction-types","title":"Bitcoin Transaction Types","text":"We already discussed the most common transaction type: the \"simple spend.\" There are also transactions that have only one input and one output, transactions that have multiple inputs and one output, and transactions that have multiple inputs and multiple outputs. Let's call them \"No Change,\" \"Consolidation,\" and \"Batch,\" respectively.
While Bitcoin's transaction graph is public, it is important to point out that any analysis that is applied to this data is heuristic. For example, a user might create a transaction that splits a UTXO in half, resulting in two outputs that belong to the same entity. Or, to pick another example, a regular spend might produce two outputs that are exactly equal, making change detection virtually impossible.
Because identification can only happen heuristically, one part of the solution to Bitcoin's privacy conundrum lies in collaboration.
"},{"location":"privacy/01-fundamentals/#collaborative-transactions","title":"Collaborative Transactions","text":"When it comes to privacy, collaboration is the norm. Take encryption, for example. If you want to have a secure communications channel with another party, you start a collaborative process. You meet, you exchange secret information, and you use this secret information to encrypt your messages. We call this exchange of secret information a \"handshake,\" and over the last decades, we implemented all kinds of handshakes into our communication and networking protocols to make sure that bad actors can't eavesdrop on our communications.
Similarly, cryptographers and security researchers are currently working on protocols and techniques that make sure that bad actors can't eavesdrop on your every financial move. As with end-to-end encryption, these protections are important for all and a matter of life-and-death for some. Dissidents, journalists, whistleblowers, political activists\u2014these are only a few groups of people that depend on secure communications, which includes financial communication. That privacy is important for these groups is an understatement. It is absolutely essential. This is also why the Human Rights Foundation launched a fund to support software developers who are making the Bitcoin network more private, decentralized, and resilient.
So, how can we think about a \"handshake\" in the world of bitcoin transactions? It's quite simple, really. As mentioned above, a bitcoin transaction can have multiple inputs and multiple outputs. The privacy techniques that are currently being developed are making use of this feature. The interesting part is that not all inputs have to be controlled by the same party. Thus, the \"handshake\" is about bringing multiple parties together to collaborate on a bitcoin transaction.
Once the collaborating parties agree on the parameters of the transaction, the transaction is signed by all parties and broadcast to the network. Because of the heuristical nature of transaction analysis, an onlooker won't be able to figure out the flow of funds.
One especially promising technique to increase the privacy of all is to combine the above with an actual payment. In this scenario, the \"handshake\" is about bringing a merchant and a customer together to craft a special transaction that can only be deciphered by said merchant or customer. An eavesdropper is left with multiple interpretations of the transaction, each equally likely. Such a transaction is called a \u201cPayJoin.\u201d
Even if only a small percentage of transactions are PayJoin transactions, the privacy of all participants in the network is increased substantially.
As more wallets and merchants adopt and support these privacy features, we will see a substantial increase in privacy on Bitcoin's base layer. However, as we have seen with the adoption of Transport Layer Security on the Internet, it takes some time for an upgrade of this sort to be implemented and embraced.
"},{"location":"privacy/01-fundamentals/#transport-layer-security","title":"Transport Layer Security","text":"When the internet was a new thing, we didn't think that it would envelop all our communications and all our lives. Encryption was an afterthought. After a while, however, we figured out that having all our communications available in plain text, readable by everyone who had the interest and technical proficiency to do so, wasn't a terribly good idea. Consequently, we made a concerted effort to change things. We upgraded from HTTP to HTTPS and from plain text messages to end-to-end encryption. While this switch isn\u2019t 100% complete yet, encrypted communication became the default over time. This upgrade took a long time, since, similar to Bitcoin, nobody is in charge of the internet.
Best Practices
"},{"location":"privacy/02-best-practices/","title":"Best Practices","text":"As with every\u00adthing in Bitcoin, taking control of your privacy is a\u00a0gradual, step-by-step process. Learning about and imple\u00admenting these best practices takes patience and respon\u00adsi\u00adbility, so do not be discour\u00adaged if it seems overwhelming at first. Every step, no matter how small, is a\u00a0step in the right direction.
"},{"location":"privacy/02-best-practices/#take-action","title":"Take Action","text":"The following are action\u00adable steps you can take to increase your\u00a0privacy:
Not your keys, not your bitcoin. If someone else is holding your bitcoin for you, they know every\u00adthing there is to know about these coins: amounts, trans\u00adac\u00adtion histo\u00adries, future trans\u00adac\u00adtions, etc. Taking self-custody of your coins is the first and most essen\u00adtial\u00a0step.
Bitcoin Wallet Guide
"},{"location":"privacy/02-best-practices/#do-not-reuse-addresses","title":"Do not reuse addresses","text":"Reusing addresses destroys the privacy of both the sender and the receiver. It should be avoided at all\u00a0costs.
Address Reuse
"},{"location":"privacy/02-best-practices/#minimize-exposure-to-kyc","title":"Minimize exposure to KYC","text":"Linking your real-world identity to your bitcoin addresses is a\u00a0neces\u00adsary evil in most juris\u00addic\u00adtions. While the effec\u00adtive\u00adness of these regula\u00adtions is question\u00adable, the impli\u00adca\u00adtions for regular users are mostly negative as a\u00a0multi\u00adtude of data leaks have shown. If you choose to use KYC on- or off-ramps, make sure that you under\u00adstand the relation\u00adship between yourself and the service in question. You are trusting this service with your personal data, including the future safety of this data. If you want to skip KYC entirely, have a\u00a0look at no-KYC only.
No KYC Only
"},{"location":"privacy/02-best-practices/#minimize-exposure-to-third-parties","title":"Minimize exposure to third parties","text":"Trusted third parties are security holes. If you can rely on yourself instead of trusted third parties, you\u00a0should.
Trusted Third Parties Are Security Holes
"},{"location":"privacy/02-best-practices/#run-your-own-node","title":"Run your own node","text":"Not your node, not your rules. Running your own node is essen\u00adtial to use Bitcoin in a\u00a0private manner. Every inter\u00adac\u00adtion with the Bitcoin network is facil\u00adi\u00adtated by a\u00a0node. If you are not in control of this node, whatever you are doing is seen by the node you are inter\u00adacting with. This means whoever is in control of the node is able to see what you are doing. The bitcoiner node guide is a\u00a0great resource to get you\u00a0started.
Bitcoiner Node Guide
"},{"location":"privacy/02-best-practices/#use-the-lightning-network-for-small-transactions","title":"Use the Light\u00adning Network for small trans\u00adac\u00adtions","text":"The off-chain nature of the light\u00adning network increases the trans\u00adac\u00adtional privacy of its users without having to jump through too many hoops. While it is still early, the absolutely reckless days of the light\u00adning network are likely behind us. Using it for small- and medium-sized trans\u00adac\u00adtions can help improve both your privacy as well as your fee footprint.
Bitcoiner Lightning Guide
"},{"location":"privacy/02-best-practices/#do-not-use-public-block-explorers","title":"Do not use public block explorers","text":"Looking up addresses in public block explorers will link those addresses with your IP, which, in turn, can be linked to your real identity. Software packages like Umbrel, Citadel, RaspiBlitz, and BTCPay Server make it easy to run your own block explorer. If you have to use a\u00a0public block explorer, make sure to mask your IP by connecting to them via Tor, or at least use a\u00a0VPN.
Mempool Instances
"},{"location":"privacy/02-best-practices/#coinjoin-early-and-often","title":"CoinJoin early and often","text":"Because Bitcoin is forever, using trans\u00adac\u00adtional best practices such as collab\u00ado\u00adra\u00adtive CoinJoin trans\u00adac\u00adtions will ensure that your privacy is protected going forward. While CoinJoin trans\u00adac\u00adtions are nuanced, user-friendly software exists to help you create and automate these kinds of trans\u00adac\u00adtions. Samourai's Whirlpool is a good\u00a0 solution for Android users, for example. There is also JoinMarket, which, thanks to projects like JoininBox and Jam, can be set up quite easily on your own node.
Getting Started with Jam
Installation
The above is a slightly modified version of Bitcoin Privacy: Best Practices\" by Gigi, released originally under a CC BY-SA 4.0 license and modified for Jam by the author.
"},{"location":"software/installation/","title":"Installation","text":"Jam comes packaged with the following full-node solutions:
You should be able to install Jam with one click if you are running any of the above. Except for RaspiBolt, where you'll need to use the command line.
You can also do a manual installation.
"},{"location":"software/installation/#install-as-a-package","title":"Install as a Package","text":"The easiest way to install Jam is to install it as a package.
Info
Please understand the trade-offs you are making when installing Jam as a package. Make sure to verify the integrity and authenticity of the node software you are running. And, if possible, verify the Jam installation yourself.
"},{"location":"software/installation/#with-umbrel","title":"...with Umbrel","text":"Jam can be installed directly from the Umbrel app store:
umbrel.local in your browser)Jam can be installed directly from the Citadel app store:
citadel.local in your browser)Info
If you are asked to enter a username and password after installation, enter \"citadel\" as the username and the password that Citadel provides for you.
"},{"location":"software/installation/#with-raspiblitz","title":"...with RaspiBlitz","text":"Jam can be installed directly from the Raspiblitz WebUI since RaspiBlitz v1.9.0.
Alternatively you can install Jam via the command line, since RaspiBlitz v1.7.2 and up. To install it, exit the RaspiBlitz menu and run:
patch\nconfig.scripts/bonus.joinmarket-webui.sh on\nTo get information on how to connect to Jam run:
config.scripts/bonus.joinmarket-webui.sh menu\nJam can be installed directly from the MyNode Marketplace:
mynode.local in your browser)Jam can be installed directly from the Start9 Marketplace:
embassy-example-example.local in your browser)See the RaspiBolt guide for detailed instructions.
"},{"location":"software/installation/#manual-installation","title":"Manual Installation","text":"There are three ways to set up Jam manually:
All these methods have benefits and drawbacks. One method is easy, but you have less control. Others give you more flexibility, but require several manual steps. Choose the method that works best for you. The rule of thumb is: Always prefer to build and verify the applications locally yourself if you have the necessary technical skills to do so.
"},{"location":"software/installation/#with-docker-image","title":"...with docker image","text":"Using docker is the easiest way to run JoinMarket with Jam. However, a disadvantage is that you have to trust the developers and it is rather difficult to verify the authenticity.
Prerequisites:
The official Jam standalone docker image is already bundled with JoinMarket and Tor. It takes care of starting all subservices (API, Orderbook, etc.) and everything works out-of-the-box.
If you are connecting to a remote Bitcoin Core node, run:
docker run --rm -it \\\n --env JM_RPC_HOST=\"IP_OF_HOST_RUNNING_BITCOIN_CORE\" \\\n --env JM_RPC_PORT=\"API_PORT_OF_BITCOIN_CORE\" \\\n --env JM_RPC_USER=\"BTC_RPC_USERNAME\" \\\n --env JM_RPC_PASSWORD=\"****************\" \\\n --env APP_USER=\"JAM_USERNAME\" \\\n --env APP_PASSWORD=\"****************\" \\\n --env ENSURE_WALLET=\"true\" \\\n --env REMOVE_LOCK_FILES=\"true\" \\\n --env RESTORE_DEFAULT_CONFIG=\"true\" \\\n --volume jmdatadir:/root/.joinmarket \\\n --publish \"8080:80\" \\\n ghcr.io/joinmarket-webui/jam-standalone:${jam_version}\nIf you are connecting to a local Bitcoin Core node, use the above command but add param --add-host=host.docker.internal:host-gateway and set the environment variable JM_RPC_HOST to host.docker.internal.
After starting the container, Jam can be accessed by visiting http://localhost:8080 in your browser.
Make sure to replace the above dummy values for IP, port, RPC username, and RPC password with values appropriate to your setup. For example:
docker run --rm -it \\\n --env JM_RPC_HOST=\"192.168.1.1\" \\\n --env JM_RPC_PORT=\"8332\" \\\n --env JM_RPC_USER=\"bitcoin\" \\\n --env JM_RPC_PASSWORD=\"n5a___YOUR_RPC_PASSWORD___yNA\" \\\n --env APP_USER=\"jam\" \\\n --env APP_PASSWORD=\"AvQ___YOUR_APP_PASSWORD___iCw\" \\\n --env ENSURE_WALLET=\"true\" \\\n --env REMOVE_LOCK_FILES=\"true\" \\\n --env RESTORE_DEFAULT_CONFIG=\"true\" \\\n --volume jmdatadir:/root/.joinmarket \\\n --publish \"8080:80\" \\\n ghcr.io/joinmarket-webui/jam-standalone:${jam_version}\nPlease use your password manager or something like openssl rand -base64 32 to generate strong passwords.
Prerequisites:
If you have successfully installed JoinMarket, generate a self-signed SSL certificate in JoinMarket's working directory, then navigate to JoinMarket's root directory and start jmwalletd and ob-watcher.
In JoinMarket's working directory (e.g. ~/.joinmarket/):
mkdir ssl/ && cd \"$_\"\nopenssl req -newkey rsa:4096 -x509 -sha256 -days 3650 -nodes \\\n -out cert.pem -keyout key.pem \\\n -subj \"/C=US/ST=Utah/L=Lehi/O=Your Company, Inc./OU=IT/CN=example.com\"\nIn JoinMarket's root directory:
. jmvenv/bin/activate\npython3 scripts/jmwalletd.py\n. jmvenv/bin/activate\npython3 scripts/obwatch/ob-watcher.py --host=127.0.0.1\nInfo
Bind both services to 127.0.0.1 instead of 0.0.0.0 to not expose them to your local network.
It is recommended to install both services as system services, e.g. via systemd. Also, see your joinmarket.cfg config file and adapt the values to your needs. It is generally advised to leave all settings at their default values. The above commands all use the standard values (e.g. for ports).
Info
Please make sure to provide values for config variables max_cj_fee_abs and max_cj_fee_rel in joinmarket.cfg. Set them to values you feel comfortable with.
Once jmwalletd and ob-watcher are running, the last thing to do is to launch Jam. You can either run the docker image, or download the source code and run it via npm. If you run Jam via the docker image, you will have to make sure that the \"internal\" host is used:
# Option 1: run Jam via docker\n\ndocker run --rm -it \\\n --add-host=host.docker.internal:host-gateway \\\n --env JAM_JMWALLETD_HOST=\"host.docker.internal\" \\\n --env JAM_JMWALLETD_API_PORT=\"28183\" \\\n --env JAM_JMWALLETD_WEBSOCKET_PORT=\"28283\" \\\n --env JAM_JMOBWATCH_PORT=\"62601\" \\\n --publish \"3000:80\" \\\n ghcr.io/joinmarket-webui/jam-ui-only:${jam_version}\n# Option 2: run Jam via npm\n\ngit clone https://github.com/joinmarket-webui/jam.git --branch ${jam_version} --depth=1\ncd jam/\nnpm install\nnpm start\nSuccess
Always make sure to verify the code that you run.
When successful, Jam can be accessed by visiting http://localhost:3000 in your browser.
Do all the same steps as in Connecting to a local JoinMarket instance but before starting Jam (either directly or with docker), create a ssh tunnel to the remote host.
ssh yourhost.local -v -o GatewayPorts=true -N \\\n -L 28183:127.0.0.1:28183 -L 28283:127.0.0.1:28283 -L 62601:127.0.0.1:62601\nOnce you managed to install Jam, make sure to understand how to use it.
First Use
"},{"location":"software/license/","title":"License","text":"Both Jam and JoinMarket are released under free and open-source software licenses.
Philosophy: Free Software
"},{"location":"software/license/#jam","title":"Jam","text":"Jam and is licensed under the MIT License. The Jam documentation is licensed under the GNU FDL.
JoinMarket is released under the GPLv3.
All releases are signed by one of the Jam contributors. As of this writing (742,834), releases are signed with dergigi's PGP key which has the following fingerprint:
8198 A185 30A5 22A0 9561 2439 89C4 A25E 69A5 DE7F\nTo verify a specific release, import the key
curl https://dergigi.com/PGP.txt | gpg --import\nand verify the git tag of your local copy:
git verify-tag v0.0.10\nThis should produce an output that contains \"good signature\" as well as the key fingerprint mentioned above:
gpg: Signature made Fr 5 Aug 14:17:58 2022 CEST\ngpg: using RSA key 8198A18530A522A09561243989C4A25E69A5DE7F\ngpg: Good signature from \"Gigi <dergigi@pm.me>\" [unknown]\n...\nPrimary key fingerprint: 8198 A185 30A5 22A0 9561 2439 89C4 A25E 69A5 DE7F\nYou can also see if a release was signed properly by clicking on the verification tag next to the version number on the releases page on GitHub.
It should say that \"This tag was signed with the committer\u2019s verified signature\" and show you the last 16 characters of the GPG key ID listed above (89C4 A25E 69A5 DE7F).
Jam comes packaged with the following full-node solutions:
+ +You should be able to install Jam with one click if you are running any of the +above. +Except for RaspiBolt, where you'll need to use the command line.
+You can also do a manual installation.
+The easiest way to install Jam is to install it as a package.
+Info
+Please understand the trade-offs you are making when installing Jam as a +package. Make sure to verify the integrity and authenticity of the node +software you are running. And, if possible, verify the Jam +installation yourself.
+Jam can be installed directly from the Umbrel app store:
+umbrel.local in your browser)Jam can be installed directly from the Citadel app store:
+citadel.local in your browser)Info
+If you are asked to enter a username and password after installation, enter +"citadel" as the username and the password that Citadel provides for you.
+Jam can be installed directly from the Raspiblitz WebUI since RaspiBlitz v1.9.0.
+Alternatively you can install Jam via the command line, since RaspiBlitz v1.7.2 and up. To install it, exit the RaspiBlitz menu and run:
+patch
+config.scripts/bonus.joinmarket-webui.sh on
+To get information on how to connect to Jam run:
+config.scripts/bonus.joinmarket-webui.sh menu
+Jam can be installed directly from the MyNode Marketplace:
+mynode.local in your browser)Jam can be installed directly from the Start9 Marketplace:
+embassy-example-example.local in your browser)See the RaspiBolt guide for detailed instructions.
+There are three ways to set up Jam manually:
+All these methods have benefits and drawbacks. One method is easy, but you +have less control. Others give you more flexibility, but require several +manual steps. Choose the method that works best for you. +The rule of thumb is: Always prefer to build and verify the applications +locally yourself if you have the necessary technical skills to do so.
+Using docker is the easiest way to run JoinMarket with Jam. +However, a disadvantage is that you have to trust the developers and it is +rather difficult to verify the authenticity.
+Prerequisites:
+The official Jam standalone docker image +is already bundled with JoinMarket and Tor. It takes care of starting all +subservices (API, Orderbook, etc.) and everything works out-of-the-box.
+If you are connecting to a remote Bitcoin Core node, run:
+docker run --rm -it \
+ --env JM_RPC_HOST="IP_OF_HOST_RUNNING_BITCOIN_CORE" \
+ --env JM_RPC_PORT="API_PORT_OF_BITCOIN_CORE" \
+ --env JM_RPC_USER="BTC_RPC_USERNAME" \
+ --env JM_RPC_PASSWORD="****************" \
+ --env APP_USER="JAM_USERNAME" \
+ --env APP_PASSWORD="****************" \
+ --env ENSURE_WALLET="true" \
+ --env REMOVE_LOCK_FILES="true" \
+ --env RESTORE_DEFAULT_CONFIG="true" \
+ --volume jmdatadir:/root/.joinmarket \
+ --publish "8080:80" \
+ ghcr.io/joinmarket-webui/jam-standalone:${jam_version}
+If you are connecting to a local Bitcoin Core node, use the above command but
+add param --add-host=host.docker.internal:host-gateway and set the environment
+variable JM_RPC_HOST to host.docker.internal.
After starting the container, Jam can be accessed by visiting
+http://localhost:8080 in your browser.
Make sure to replace the above dummy values for IP, port, RPC username, and RPC +password with values appropriate to your setup. For example:
+docker run --rm -it \
+ --env JM_RPC_HOST="192.168.1.1" \
+ --env JM_RPC_PORT="8332" \
+ --env JM_RPC_USER="bitcoin" \
+ --env JM_RPC_PASSWORD="n5a___YOUR_RPC_PASSWORD___yNA" \
+ --env APP_USER="jam" \
+ --env APP_PASSWORD="AvQ___YOUR_APP_PASSWORD___iCw" \
+ --env ENSURE_WALLET="true" \
+ --env REMOVE_LOCK_FILES="true" \
+ --env RESTORE_DEFAULT_CONFIG="true" \
+ --volume jmdatadir:/root/.joinmarket \
+ --publish "8080:80" \
+ ghcr.io/joinmarket-webui/jam-standalone:${jam_version}
+Please use your password manager or something like openssl rand -base64 32 to
+generate strong passwords.
Prerequisites:
+If you have successfully installed JoinMarket, generate a
+self-signed SSL certificate in JoinMarket's working directory, then navigate
+to JoinMarket's root directory and start jmwalletd and ob-watcher.
In JoinMarket's working directory (e.g. ~/.joinmarket/):
mkdir ssl/ && cd "$_"
+openssl req -newkey rsa:4096 -x509 -sha256 -days 3650 -nodes \
+ -out cert.pem -keyout key.pem \
+ -subj "/C=US/ST=Utah/L=Lehi/O=Your Company, Inc./OU=IT/CN=example.com"
+In JoinMarket's root directory:
+. jmvenv/bin/activate
+python3 scripts/jmwalletd.py
+. jmvenv/bin/activate
+python3 scripts/obwatch/ob-watcher.py --host=127.0.0.1
+Info
+Bind both services to 127.0.0.1 instead of 0.0.0.0 to not expose them to
+your local network.
It is recommended to install both services as system services, e.g. via
+systemd. Also, see your joinmarket.cfg config file and adapt the values to
+your needs. It is generally advised to leave all settings at their default
+values. The above commands all use the standard values (e.g. for ports).
Info
+Please make sure to provide values for config variables max_cj_fee_abs
+and max_cj_fee_rel in joinmarket.cfg. Set them to values you feel
+comfortable with.
Once jmwalletd and ob-watcher are running, the last thing to do is to launch
+Jam. You can either run the docker image, or download the source code and run it
+via npm. If you run Jam via the docker image, you will have to make sure that
+the "internal" host is used:
# Option 1: run Jam via docker
+
+docker run --rm -it \
+ --add-host=host.docker.internal:host-gateway \
+ --env JAM_JMWALLETD_HOST="host.docker.internal" \
+ --env JAM_JMWALLETD_API_PORT="28183" \
+ --env JAM_JMWALLETD_WEBSOCKET_PORT="28283" \
+ --env JAM_JMOBWATCH_PORT="62601" \
+ --publish "3000:80" \
+ ghcr.io/joinmarket-webui/jam-ui-only:${jam_version}
+# Option 2: run Jam via npm
+
+git clone https://github.com/joinmarket-webui/jam.git --branch ${jam_version} --depth=1
+cd jam/
+npm install
+npm start
+Success
+Always make sure to verify the code that you run.
+When successful, Jam can be accessed by visiting
+http://localhost:3000 in your browser.
Do all the same steps as in Connecting to a local JoinMarket instance +but before starting Jam (either directly or with docker), create a ssh tunnel +to the remote host.
+ssh yourhost.local -v -o GatewayPorts=true -N \
+ -L 28183:127.0.0.1:28183 -L 28283:127.0.0.1:28283 -L 62601:127.0.0.1:62601
+Once you managed to install Jam, make sure to understand how to use it.
+ + + + + + + +Both Jam and JoinMarket are released under free and open-source software licenses.
+ +Jam and is licensed under the MIT License. +The Jam documentation is licensed under the GNU FDL.
+ +JoinMarket is released under the GPLv3.
+All releases are signed by one of the Jam contributors. As of this writing (742,834), releases are signed with dergigi's PGP key which has the following fingerprint:
+8198 A185 30A5 22A0 9561 2439 89C4 A25E 69A5 DE7F
+To verify a specific release, import the key
+curl https://dergigi.com/PGP.txt | gpg --import
+and verify the git tag of your local copy:
+git verify-tag v0.0.10
+This should produce an output that contains "good signature" as well as the key fingerprint mentioned above:
+gpg: Signature made Fr 5 Aug 14:17:58 2022 CEST
+gpg: using RSA key 8198A18530A522A09561243989C4A25E69A5DE7F
+gpg: Good signature from "Gigi <dergigi@pm.me>" [unknown]
+...
+Primary key fingerprint: 8198 A185 30A5 22A0 9561 2439 89C4 A25E 69A5 DE7F
+You can also see if a release was signed properly by clicking on the
+verification tag 
next to
+the version number on the releases page on GitHub.
It should say that "This tag was signed with the committer’s verified
+signature" and show you the last 16 characters of the GPG key ID listed above
+(89C4 A25E 69A5 DE7F).