Skip to content

Commit

Permalink
docs: wiki restructuring
Browse files Browse the repository at this point in the history
  • Loading branch information
@bochinchero
bochinchero committed Oct 26, 2024
1 parent aee9af7 commit f1babb7
Show file tree
Hide file tree
Showing 55 changed files with 1,146 additions and 0 deletions.
238 changes: 238 additions & 0 deletions docs/wiki/Bison Wallet Setup Guide.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,238 @@
_Last updated for Bison Wallet v1.0.0._

---
# Download and Install

The latest version of Bison Wallet can be downloaded from https://dex.decred.org.


***Note:*** *We recommend you also verify that your download hash matches the hash
in the DCRDEX releases manifest. For detailed instructions, read about
[Verifying Binaries](https://docs.decred.org/advanced/verifying-binaries/)
in the Decred Documentation.*

You will need to visit the [releases](https://github.com/decred/dcrdex/releases) page
to download the manifest and manifest signature:

```
bisonw-v1.0.0-manifest.txt
bisonw-v1.0.0-manifest.txt.asc
```

## Bison Wallet Desktop

``bisonw-desktop`` is the Desktop version of Bison Wallet. This version is a self-contained
application, making it the preferred option for new users.

### Windows

1. Download the Windows installer ``bisonw-desktop-windows-amd64-v1.0.0.msi``.

2. Double click the installer and follow the instructions.

3. The installer adds a shortcut to Bison Wallet on your Start Menu.

### macOS

1. Download the ``bisonw-desktop-darwin-amd64-v1.0.0.dmg`` file.

2. Double click the ``bisonw-desktop-darwin-amd64-v1.0.0.dmg` file to mount the disk image.

3. Drag the ``bisonw-desktop.app`` file into the link to your Applications folder within the
disk image.

### Linux (Debian/Ubuntu)

1. Download the ```bisonw-desktop-linux-amd64-v1.0.0.deb``` file.

2. Open a terminal in the extracted folder and run the command
```dpkg -i ./bisonw-desktop-linux-amd64-v1.0.0.deb```.

3. Bison Wallet can then be launched from the applications menu.

Once the installation has completed, **Bison Wallet Desktop** can be launched from
the shortcut added to the Start/Application menu. A new window will appear once the
application starts.

## Bison Wallet CLI

``bisonw`` is the command line version of Bison Wallet. This version provides access to several
optional parameters for more [advanced](TODO) users, a web browser is required to access the
graphical user interface (GUI).

### Windows

1. Download the ``bisonw-windows-amd64-v1.0.0.zip`` file.

2. Navigate to the download location and extract ``bisonw-windows-amd64-v1.0.0.zip``.

3. The extracted files include an executable named ``bisonw``.

### macOS

1. Download the ``bisonw-darwin-amd64-v1.0.0.tar.gz`` file.

2. Navigate to the download location and extract ``bisonw-darwin-amd64-v1.0.0.tar.gz``.

3. The extracted files include an executable named ``bisonw``.

4. Open a terminal in the extracted folder and run the command ```chmod u+x bisonw``.

5. Bison Wallet can then be launched from the terminal using the command ``./bisonw``.

### Linux

1. Download the ``bisonw-linux-amd64-v1.0.0.tar.gz`` file.

2. Navigate to the download location and extract ``bisonw-linux-amd64-v1.0.0.tar.gz``.

3. The extracted files include an executable named ``bisonw``.

4. Open a terminal in the extracted folder and run the command ``chmod u+x bisonw``.

5. Bison Wallet can then be launched from the terminal using the command ``./bisonw``.

Once the installation has completed, **Bison Wallet CLI** can be launched from a terminal
using the command ``./bisonw`` from within the folder where it was extracted. Once initial
configuration has completed, the following message will appear in the terminal:

```
2024-10-15 10:38:04.710 [INF] WEB: Web server listening on 127.0.0.1:5758 (https = false)
**** OPEN IN YOUR BROWSER TO LOGIN AND TRADE ---> http://127.0.0.1:5758 ****
```
Open any web browser to the link shown by the application.

---

# Setup Bison Wallet

Opening Bison Wallet for the first time will display the following prompt:

![Enter New Password](./images/setup-guide/new-password.png)

Setting your new client application password and clicking **Submit** will generate a new wallet.
You will use this password to perform all future security-sensitive client operations.

## Restore Existing Seed

From the **New Password** prompt, you can also restore an existing application seed by clicking
in the **Restoration Seed** button and entering the seed backup phrase in the 12 word format.

![Enter New Password](./images/setup-guide/restore-seed.png)

## Quick Configuration

The **Quick Configuration** wizard lets you select which [native wallets](./Using%20BIson%20Wallet.md#native-wallet)
to create, you can always create them later in the [Wallet](./Using%20BIson%20Wallet.md#wallet) tab.

![Quick Configuration](./images/setup-guide/quick-configuration.png)

The selected native wallets will be created and Bison Wallet will connect to the selected
DEX server when you submit the form.

_**Note:** If you encounter an error about not being able to connect to the selected DEX
server during the quick configuration, you can always manually add a DEX server later through the settings
panel._

## Backup Application Seed

Once the selected [native wallets](./Using%20BIson%20Wallet.md#native-wallet) have been created as part
of the **Quick Configuration** wizard, a prompt will appear to backup your application seed. This seed is
used to restore your DEX accounts and any native wallets - so keep it safe.

![Backup App Seed](./images/setup-guide/backup-app-seed.png)

_**Note:** If you skip this step now (not recommended), you can go to the Settings panel to
retrieve your application seed later._

![Backup App Seed](./images/setup-guide/backup-app-seed-2.png)

This seed phrase is essentially the private key for your native wallets.
You will be able to use this seed phrase to restore your private keys, transaction history,
and balances using Bison Wallet on any computer. This ultimately means that anyone who knows your
seed can use it to restore your private keys, transaction history, and balances to Bison Wallet
on their computer without your knowledge. For this reason, it is of utmost importance to keep your
seed phrase safe. Treat this seed the same way you would treat a physical key to a safe.
If you lose your seed phrase, you permanently lose access to your wallet and all funds within it.
It cannot be recovered by anyone, including the Bison Wallet developers. It is recommended you write
it down on paper and store that somewhere secure. If you decide to keep it on your computer,
it would be best to keep it in an encrypted document (do not forget the password) in case the file
or your computer is stolen.

_**DO NOT, UNDER ANY CIRCUMSTANCES, GIVE YOUR SEED TO ANYONE!
NOT EVEN BISON WALLET OR DECRED DEVELOPERS!**_

## Wallet Synchronization

After the [Quick Configuration](#quick-configuration) wizard has been completed, the
[Wallet](./Using%20BIson%20Wallet.md#wallet) view will be displayed, the Block Synch indicator
on each wallet shows the progress as each blockchain is synchronized.

![Wallet Screen](./images/setup-guide/wallets-1.png)

## Creating a DEX Server account

Clicking the **Trade** button in the header will navigate to the [Trade](./Using%20BIson%20Wallet.md#trade) view.

![Trading Screen](./images/setup-guide/trade-1.png)

The available markets on the connected DEX servers are listed on the left side of the screen.

![Trading Screen](./images/setup-guide/trade-2.png)

An account can be created with the respective server by clicking the **Create Account** button
on the top right of the screen. This will open the **Select Bond Asset** prompt.

![Trading Screen](./images/setup-guide/bond-1.png)

A fidelity bond are funds that are temporarily locked in an on-chain contract,
which is only redeemable by the user who posted the bond after a certain time.
Fidelity Bonds act as an incentive good behaviour on the DEX servers and are required for
creating an account on every server. Read more about bonds in the [Fidelity Bonds](TODO-bonds)
section of this wiki.

Pre-paid bonds are codes generated by the server operator to enable temporary
trading access for individual users, once the pre-paid bond has expired, the user
will have to post a bond to maintain their trading tier. Pre-paid bonds are available
upon request in our [Matrix](https://matrix.to/#/#dex:decred.org) and
[Discord](https://discord.com/channels/349993843728449537/454306570180886530) channels.

Once the bond asset is selected, a prompt to select the [Trading Tier](TODO-Tier) will appear.
Increasing your tier enables trading of larger quantities at a time. A higher tier also
increase your capacity for violations before trading privileges are completely suspended.

Trading limits are also increased as you establish [reputation](TODO-reputation) by engaging
in normal trading activity and successfully completing matches.

![Trading Tiers](./images/setup-guide/bond-2.png)

Clicking the **submit** button display a new prompt indicating the requirements for submitting
a bond with the selected asset. The synchronization status and available funds, along with
a deposit address for the selected bond asset.

![Bond Requirements](./images/setup-guide/bond-3.png)

Once the wallet has synchronized and sufficient funds are available, a prompt will appear
to confirm the selected bond options.

![Confirm Bond Options](./images/setup-guide/bond-4.png)

Clicking the **submit** button will temporarily lock the specified funds in a fidelity bond
contract, these funds are only redeemable by you in the future.

The trade view will be displayed once the form has been submitted. The status of the submitted
bond transaction will be indicated on the top right. The number of required confirmations will vary
depending on the selected bond asset.

![Awaiting bond confirmation](./images/setup-guide/bond-5.png)

Once the bond transaction has been confirmed, the order submission section will be visible in the
top right of the markets tab.

![Bond COnfirmed](./images/setup-guide/bond-6.png)

---

Next: [Using Bison Wallet](./Using%20BIson%20Wallet.md)
133 changes: 133 additions & 0 deletions docs/wiki/Introduction.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
# What is Bison Wallet?

Bison Wallet is a multi-coin wallet developed in concert with [DCRDEX](#dcrdex-protocol)
and [Tatanka Mesh](#tatanka-mesh). Bison Wallet leverages state-of-the-art blockchain
technology to bring more features and more privacy for your favorite assets. DCRDEX is
built-in, as well as advanced trading features like market-making and arbitrage, directly
from your wallet.

Our goal is to find a balance of convenience and privacy that works for you,
while giving you access to advanced features most wallets ignore. For many
assets, we can cut out the middleman altogether and allow you to interact
directly with the blockchain network. This type of wallet is highly-resilient to
data collection and censorship.

We also focus on bringing advanced, asset-specific features for our wallets.
With Decred, you can use decentralized StakeShuffle mixing to further anonymize
your funds, or stake your DCR and earn some block rewards. The Zcash wallet exposes
unified addresses and shielded pools, and operates on a shielded-first principle
that makes privacy effortless.

# DCRDEX Protocol

The [Decred Decentralized Exchange (DEX)](https://dex.decred.org/) is a system
that enables trustless exchange of different types of blockchain assets via a
familiar market-based API. DEX is a non-custodial solution for cross-chain
exchange based on [atomic swap technology](#atomic-swaps). DEX matches trading parties and
facilitates price discovery and the communication of swap details.


Some of the key features of the protocol are the following:

- **Fees** - no trading fees are collected and there is no superfluous token
or blockchain that is used to monetize the project.
- **Fair** – orders are matched pseudorandomly within epochs to substantially
reduce manipulative, abusive trading practices by high frequency trading that
uses first-in-first-out matching.
- **Secure** – Server operators never take custody of client funds. Non-custodial
exchange is accomplished using cross-chain atomic swaps.
- **Permissionless** – The simple client-server architecture makes it easy to set
up new servers and clients and enhances censorship resistance.
- **No gatekeepers** – Projects can add support for their assets and run servers
with the markets they require.
- **Verifiable volume** – volume and trade data can be externally verified against
the corresponding blockchains and the atomic swaps that occur on-chain, preventing
wash trading.
- **Private** – Know your customer (KYC) information is not required.
- **Transparent** – By performing exchanges on-chain and using cryptographic
attestation, both clients and servers can be held accountable for malicious behavior.

# Tatanka Mesh

Tatanka Mesh (Tatanka, the mesh) is the evolution of DCRDEX. Where DCRDEX relies
on a central server for maintaining order books and policing trades, Tatanka is
a decentralized P2P protocol that enables a network of subscribers to
collectively perform these tasks. Here are the three critical services that
Tatanka Mesh provides.

- Enhance the ability for users to connect and to share data both publicly and privately
- Aggregate reputation data and monitor fidelity bonds. Tatanka can limit
access to users who earn a bad reputation
- Oracle services for fiat exchange rates and blockchain transaction fee rates

The mesh collects no fees for its services. Trades are performed using trustless
atomic swaps that exchange funds directly between wallets.

Going P2P empowers our users to trade directly, enhancing security,
censorship-resistance, privacy. and self-sovereignty.

# Supported Assets

Most users will use the native wallets that are already built into Bison Wallet.
Depending on the asset, you may be able to choose from: (1) a native
wallet, (2) an external full node wallet, or (3) an Electrum-based wallet.
Consult the following table for a summary of wallet support. If there is a
checkmark in the "native" column, no external software is required.

| Coin | native | full node | Electrum | notes |
|--------------|--------|-------------------------------------------------------------|---------------------------------------------------------------|------------------------------------------------------|
| Bitcoin | ✓ | [v27.0](https://bitcoincore.org/en/download/) | [v4.5.5](https://electrum.org/) | |
| Decred | ✓ | [v2.0.3](https://github.com/decred/decred-release/releases) | x | |
| Ethereum | ✓ | geth IPC/http/ws | N/A | see <https://github.com/decred/dcrdex/wiki/Ethereum> |
| Polygon | ✓ | | N/A | |
| Litecoin | ✓ | [v0.21.2.1](https://litecoin.org/) | [v4.2.2](https://electrum-ltc.org/) | |
| Bitcoin Cash | ✓ | [v27.0.0](https://bitcoincashnode.org/) | x | use only Bitcoin Cash Node for full node |
| Dogecoin | x | [v1.14.7.0](https://dogecoin.com/) | x | |
| Zcash | x | [v5.4.2](https://z.cash/download/) | x | |
| Dash | x | [v20.1.1](https://github.com/dashpay/dash/releases) | x | |
| Firo | x | [v0.14.13.3](https://github.com/firoorg/firo/releases) | [v4.1.5.5](https://github.com/firoorg/electrum-firo/releases) | |




# Fidelity Bonds - review location

A fidelity bond are funds that are temporarily locked in an on-chain contract,
which is only redeemable by the user who posted the bond after a certain time.
Fidelity bonds have replaced the original one-time server registration fee since
[DCRDEX v0.6.0](https://github.com/decred/dcrdex/releases/tag/v0.6.0) and act as an
incentive for good conduct on the DEX.

Bonds can be revoked if an account engages in continued disruptive behavior,
such as backing out on a swap. Revoked bonds can be re-activated with
continued normal trading activity.

# History

Initially proposed by Jake Yocom-Piatt in the
[Decred blog](https://blog.decred.org/2018/06/05/A-New-Kind-of-DEX/) in 2018,
DCRDEX development started in 2019 and has been fully funded by the Decred treasury.

**Project Timeline**

| Date | Milestone |
|---------|-------------------------------------------------------------------------------------------------------------------------|
| 2018-06 | [A New kind DEX](https://blog.decred.org/2018/06/05/A-New-Kind-of-DEX/) blog post published in the Decred blog. |
| 2019-03 | [RFP: Decred Decentralized Exchange Infrastructure](https://proposals.decred.org/record/3360c14) proposal approved. |
| 2019-06 | [Decentralized Exchange Specification Document](https://proposals.decred.org/record/94cc1ee) proposal approved. |
| 2019-08 | [Decentralized Exchange Development](https://proposals.decred.org/record/ad972c3) proposal approved. |
| 2020-10 | [DCRDEX v0.1.0](https://github.com/decred/dcrdex/releases/tag/release-v0.1.0) MVP release. |
| 2021-01 | [Decred DEX Development Phase II](https://proposals.decred.org/record/cbd0f92) proposal approved. |
| 2021-05 | [DCRDEX v0.2.0](https://github.com/decred/dcrdex/releases/tag/v0.2.0) release. |
| 2022-01 | [DCRDEX Phase 3 - Bonds, Decentralization, and Privacy](https://proposals.decred.org/record/3326c82) proposal approved. |
| 2022-02 | [DCRDEX v0.4.0](https://github.com/decred/dcrdex/releases/tag/v0.4.0) release. |
| 2022-08 | [DCRDEX v0.5.0](https://github.com/decred/dcrdex/releases/tag/v0.5.0) release. |
| 2023-01 | [DCRDEX integration on Umbrel](https://proposals.decred.org/record/8d83046) proposal approved. |
| 2023-03 | [Decred DEX - Desktop App and Packaging](https://proposals.decred.org/record/ae7c4fe) proposal approved. |
| 2023-03 | [Decred DEX - Client Development](https://proposals.decred.org/record/ca6b749) proposal approved. |
| 2023-03 | [Decred DEX - Market Maker and Arbitrage Bot Development](https://dcrdata.org/proposals) proposal approved. |
| 2023-04 | [DCRDEX v0.6.0](https://github.com/decred/dcrdex/releases/tag/v0.6.0) release. |
| 2023-06 | [DCRDEX Mesh Beginnings and Bonds Evolution](https://proposals.decred.org/record/4d2324b) proposal approved. |
| 2024-04 | [DCRDEX Monero Stage 1](https://proposals.decred.org/record/fa0ea64) proposal approved. |
| 2024-09 | [DCRDEX v1.0.0](https://github.com/decred/dcrdex/releases/tag/v0.6.0) release. |
| 2024-10 | [DCRDEX Development Phase 5.5](https://proposals.decred.org/record/0d23788) proposal approved. |
Loading

0 comments on commit f1babb7

Please sign in to comment.