Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add wiki. #1714

Merged
merged 2 commits into from
Aug 1, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
795 changes: 795 additions & 0 deletions docs/wiki/Client-control-API.mediawiki

Large diffs are not rendered by default.

35 changes: 35 additions & 0 deletions docs/wiki/Contribution-Guide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
We welcome your contributions to dcrdex.

Development is coordinated via [github issues](/../issues) and the
[Matrix](https://matrix.org/)
[DEX Development room](https://matrix.to/#/!EzTSRQITaqHuFBDFhM:decred.org?via=decred.org&via=matrix.org&via=zettaport.com).
You can access the room at [chat.decred.org](https://chat.decred.org),
[riot.im](https://riot.im), or with any other Matrix client.

## Contributing code

1. Fork the repo.
2. Create a branch for your work (`git checkout -b cool-stuff`).
3. Code something great.
4. Commit and push to your forked repo.
5. Create a [pull request](https://github.com/decred/dcrdex/compare).

## Code Style (Go)

- Wrap comments after 80 columns, treating tabs as being 4 spaces wide. Trailing code comments are exempt.
- Try to keep code wrapped below 100 columns, but this is more of a guideline than a rule.
- Document all exported symbols. Use full sentences and proper punctuation.
- Justify the creation of exported types/variables/methods/functions. If it can be exported, it probably should be.
- Do not use `make` to allocate 0-capacity slices (e.g. `make([]int, 0)`) unless you have a good reason. It is safe to append to a `nil` slice.
- When declaring a variable with it's zero value, just use `var` and not `:=`. For example, `var x int64` instead of `x := int64(0)`.
- When defining `error` strings, avoid beginning with a capital letter unless it refers to an exported type or proper noun, and avoid ending with punctuation. There are exceptions, so this is not checked by a linter.

## Get paid

If you are already a Decred contractor, you can charge for your development work
on **dcrdex**. If you are not a Decred contractor, but would like to be, you
should first
[familiarize yourself with the on-boarding process](https://docs.decred.org/contributing/overview/).
**dcrdex** is a great place to get started, but you would be expected to take on
only smaller jobs until you are comfortable navigating the code and have shown
the ability to communicate and follow through.
39 changes: 39 additions & 0 deletions docs/wiki/Home.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
<img src="images/logo_wide_v1.svg" width="250">

The dcrdex wiki provides documentation for dcrdex users and developers.

Most likely you want to look at the [README](https://github.com/decred/dcrdex/blob/master/README.md) or the [spec](https://github.com/decred/dcrdex/blob/master/spec/README.mediawiki) instead of these wiki pages.

## Contribute changes to the wiki

The following instructions assume that you have already forked **dcrdex**.

1. Initialize your forked wiki on github by navigating to the wiki tab of your forked **dcrdex** repo and clicking the "Create the first page" button.

<img src="images/wiki-creation.png" width="700">

2. In your terminal, navigate to your local **dcrdex** directory and clone the wiki from the **decred/dcrdex** repo.

`git clone https://github.com/decred/dcrdex.wiki.git wiki`
Copy link
Member

@chappjc chappjc Jul 31, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess most of the Home page describing how to contribute to the wiki is incorrect with this change, and can remove wiki-creation.png I suppose.

Now it's just something like: follow the instructions in docs/wiki/Contribution-Guide.md to clone the dcrdex repository and start a branch for your edits, edit the documents in docs/wiki, create a PR with those changes, and once it is merged and administrator will push the changes to the live GitHub Wiki.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've updated the instructions in #1715 what do you think about those?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh ok so images/wiki-creation.png would still be used. That makes sense for previewing in your own fork's Wiki. I have a feeling I'd just do my best to use local previews on my computer's editor for markdown, just not mediawiki. But maybe I'd get comfy with force pushing the docs/wiki subtree to my wiki remote all the time.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose I'd have a remote called thewiki for https://github.com/decred/dcrdex.wiki.git, and another called mywiki for https://github.com/chappjc/dcrdex.wiki.git to make sure I don't get them mixed up if I'm making a wiki PR for instance.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For someone with write access I guess so... I haven't actually tried yet with https://github.com/decred/dcrdex.wiki.git I wonder if I can write there because I'm a contributor? I'm not asking for write permissions, just wondering.

I have a feeling I'd just do my best to use local previews on my computer's editor for markdown

Your IDE?

Copy link
Member Author

@JoeGruffins JoeGruffins Aug 1, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Anyway, do you want me to change the instructions in this pr? I was just planning on doing the move here but can move the instructions commit here.

Copy link
Member

@chappjc chappjc Aug 1, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, IDE or other markdown enabled editor like ReText. There's a million of them.

Missed your last question, but I think this PR establishes the baseline docs/wiki folder that exactly matches the wiki at dcrdex.wiki.git, so it's perfect as-is.


3. Create a remote for your fork's wiki, replacing 'your-username' with your username.

`cd wiki; git remote add me https://github.com/your-username/dcrdex.wiki.git`

4. Create a branch to track the decred/dcrdex wiki.

`git checkout -b master-upstream origin/master`

5. Now when you want to do some work, create a new branch based on this one.

`git checkout master-upstream`

`git pull`

`git checkout -b cool-stuff`

6. Unfortunately, you cannot view any wiki branch but master on github, so you'll want to commit your changes to your fork's master wiki branch and view them in your repo at github before requesting a merge.

`git push --force me cool-stuff:master`

7. Also unfortunately, github does not support pull requests for wikis, so contact @chappjc, and tell him you'd like to merge changes from your forked repo wiki. Keep your wiki master branch updated with your changes as you make them so that they can be viewed during review.
31 changes: 31 additions & 0 deletions docs/wiki/Localization-and-Translation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
The DEX client supports translations for the browser frontend and the notification messages from the backend.

To add a new locale, the translations must be defined in the following locations:

1. HTML strings (client/webserver/locales)
2. Notification strings (client/core/locale_ntfn.go)
3. JavaScript strings (client/webserver/site/src/js/locales.js)

If you decide to do the following for a different language, please see https://github.com/decred/dcrdex/wiki/Contribution-Guide for help with the github workflow.

## Step 1 - HTML

The HTML strings involved creating [client/webserver/locales/zh-cn.go](https://github.com/decred/dcrdex/blob/master/client/webserver/locales/zh-cn.go), which contains a `var ZhCN map[string]string` that provides a translation for a string identified by a certain key. The translation is not of the key itself, but of the corresponding English string in the `EnUS` map in https://github.com/decred/dcrdex/blob/master/client/webserver/locales/en-us.go. The name of this file should be a [BCP 47 language tag](https://www.w3.org/International/articles/bcp47/), preferably the "language-region" form.

The new HTML strings map must then be listed in https://github.com/decred/dcrdex/blob/master/client/webserver/locales/locales.go with an appropriate language tag.

Once the new file is created in **client/webserver/locales** and the new map registered in **client/webserver/locales/locales.go**, it is then necessary to run `go generate` in the **client/webserver/site** folder. This creates the localized HTML template files in the **localized_html** folder.

## Step 2 - Notifications

The notification strings involved editing [client/core/locale_ntfn.go](https://github.com/decred/dcrdex/blob/master/client/core/locale_ntfn.go) with a new `var zhCN map[Topic]*translation`. These translations correspond to the English strings in the `enUS` map in the same file.

Note how in **client/core/locale_ntfn.go** there are "printf" specifiers like `%s` and `%d`. These define the formatting for various runtime data, such as integer numbers, identifier strings, etc. Because sentence structure varies between languages the order of those specifiers can be explicitly defined like `%[3]s` (the third argument given to printf in the code) instead of relying on the position of those specifiers in the formatting string. This is necessary because the code that executes the printing always provides the values in a particular order, which may not be the same order in a translated string.

Once the translations are added to **client/core/locale_ntfn.go**, the new map is listed in the `var locales map[string]map[Topic]*translation` at the bottom of the same file.

## Step 3 - JavaScript

The JavaScript strings involved editing [client/webserver/site/src/js/locales.js](https://github.com/decred/dcrdex/blob/master/client/webserver/site/src/js/locales.js) with a new `export const zhCN` object, with strings corresponding to the English text in the `enUS` object at the top of the same file. Finally, the new object is listed in the `const localesMap` at the end of the file.

When testing, remember to rebuild the site assets bundle with `npm ci && npm run build` in the **client/webserver/site** folder.
36 changes: 36 additions & 0 deletions docs/wiki/Native-BTC-Wallet-Recovery-and-Rescanning.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
## Reinitializing the Native BTC Wallet

If the native BTC wallet is corrupted, the dexc.log may have a message containing "connectWallet: wallet not found", such as:

> [ERR] CORE: Unable to connect to **btc** wallet (start and sync wallets BEFORE starting dex!): **connectWallet: wallet not found**
Note **btc** in the above message, and **wallet not found**. This may also say something about db corruption or similar errors, which may also be addressed as follows.

In this case, the Wallets page (/wallets) will still show the wallet since it was previously configured, just that it is not synchronized and cannot be unlocked:

![wallets view](https://user-images.githubusercontent.com/9373513/149597739-06318c29-f6be-4837-bb6f-2055971be8cf.png)

This may be solvable by simply clicking the gears to open the settings box, and then clicking Submit:

![wallet settings](https://user-images.githubusercontent.com/9373513/149597817-abbcbf5f-d05f-4b48-996f-485030d2a74c.png)

The dexc.log should say:

> [INF] CORE: Initializing a built-in btc wallet
The wallet will begin re-synchronizing. This may take several minutes.

If this process results in errors, it may be necessary to go to the folder containing the wallet data and **delete the wallet.db so it may be regenerated** from your application seed. First SHUTDOWN DEX. Next, for mainnet, on Linux, this would be in the folder `~/.dexc/mainnet/assetdb/btc/mainnet/`. There may be a wallet.db file in this folder, which you should rename wallet.db.bak. Now startup and login to DEX. Go to the Wallets page to see wallet status, which should re-synchronize. Check notifications and logs for any errors.

## Rescanning the wallet

There will be a Rescan button added to the Wallets page, but for now you can force the wallet to rescan in one of two ways. First, SHUTDOWN DEX. Then do one of the following:

1. Delete the wallet.db file in the "assetdb/btc" folder as described at the end of the previous section. Start back up and log in. Follow the instructions in [the Reinitializing the Native BTC Wallet section](#reinitializing-the-native-btc-wallet) to reinitialize the wallet and begin a resync.
2. OR (**safest option**) use the `dropwtxmgr` tool on that wallet.db file. See the instructions in https://github.com/btcsuite/btcwallet/blob/master/docs/force_rescans.md. You will build that tool as described there and then run it on DEX's btc wallet.db. For example `dropwtxmgr --db ~/.dexc/mainnet/assetdb/btc/mainnet/wallet.db`. When you start DEX and login again, it will begin to rescan the wallet.

## Full reinitialize

In addition to reinitializing or rescanning the BTC wallet.db file, you may also remove all of the chain data files to force resynchronization of all blockchain data used by the neutrino service that powers the wallet. To do this, delete all of the files in `~/.dexc/mainnet/assetdb/btc/mainnet/` (for mainnet), including neutrino.db, reg_filter_headers.bin, block_headers.bin, and wallet.db. You may keep peers.json to help with bootstrapping when you restart, but it may be deleted too.

Next, startup DEX and go to the Wallet page. Finally, click the gears icon for the Bitcoin wallet, and click Submit after ensuring it is currently showing the Native wallet option as in the [first section's screenshot](#reinitializing-the-native-btc-wallet).
33 changes: 33 additions & 0 deletions docs/wiki/Server-Admin.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
## Exchange Settings

### Admin HTTP JSON API

See https://github.com/decred/dcrdex/blob/6693bc57283d4cf5b451778091aa1c1b20cb9187/server/admin/server.go#L145

### Markets JSON Settings File

```
{
"markets" (array): Array of market objects.
[
{
"base" (string): The coin ticker shorthand followed by network. i.e. DCR_testnet
"quote" (string): The coin ticker shorthand followed by network. i.e. BTC_testnet
"epochDuration" (int): The length of one epoch in milliseconds
"marketBuyBuffer" (float): A coefficient that when multiplied by the market's lot size specifies the minimum required amount for a market buy order
},...
],
"assets" (object): Map of coin ticker shorthand followed by network of the base asset to an asset object.
{
"[TICKER_network]": {
"bip44symbol" (string): The coin ticker. i.e. dcr
"network" (string): The network the coin daemon is running on. i.e. testnet
"lotSize" (int): The amount of basic units of a coin in one lot
"rateStep" (int): The price rate increment in basic units of this coin
"maxFeeRate" (int): The maximum fee rate for swap transactions
"swapConf" (int): The minimum confirmations before acting on a swap transaction
"configPath" (string): The path to the coin daemon's config file or ipc file in the case of Ethereum
},...
}
}
```
Loading