scoobs
/
cryptools-mirror
mirror of https://github.com/scoobybejesus/cryptools.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Improved documentation.

This commit is contained in:
scoobybejesus 2019-09-21 18:11:26 -04:00
parent b14eb2c458
commit 1eb62f58aa
2 changed files with 42 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
README.md
View File

@ -2,27 +2,23 @@
### Accounting library for cryptocurrency transaction activity. ### Accounting library for cryptocurrency transaction activity.
###### (Currently runs as a binary, not a library) ###### (Currently runs as a binary)
The software measures one's cryptocurrency activity (i.e., denominates one's income/expenses/gains/losses) in their home currency. The software measures one's cryptocurrency activity (i.e., denominates one's income/expenses/gains/losses) in their home currency.
The default home currency is USD, but anything can be substituted. The default home currency is USD, but anything can be substituted.
This type of tool may be useful, for example, when preparing to file taxes. This tool is probably most useful when filing one's taxes.
The software has been tested on Mac and Linux.
Testers/users are encouraged and welcome.
--- ---
Given an input CSV file reflecting the user's entire cryptocurrency transaction history, the software will: Given a [CSV input file](https://github.com/scoobybejesus/cryptools/blob/master/InputFile_CSV.md)
containing the user's entire cryptocurrency transaction history, the software will:
* assign cost basis as of the date of purchase/exchange/receipt * assign cost basis as of the date of purchase/exchange/receipt
* track the original acquisition date and cost basis until the time of disposal * track the original acquisition date and cost basis until the time of disposal
* compute gain or loss from the sale/exchange/disposal (including whether short-term or long-term) * compute gain or loss from the sale/exchange/disposal (including whether short-term or long-term)
* record income for incoming transactions and expenses for outgoing transactions * record income for incoming transactions and expenses for outgoing transactions
Read up on the [CSV input file](https://github.com/scoobybejesus/cryptools/blob/master/InputFile_CSV.md). Reports reflecting income/expenses/gains/losses or amount and cost basis of existing holdings may be exported as CSV/TXT files.
Reports may be exported as CSV and/or TXT files reflecting income/expenses/gains/losses or amount and cost basis of existing holdings.
--- ---
@ -36,18 +32,19 @@ Reports may be exported as CSV and/or TXT files reflecting income/expenses/gains
#### Constraints #### Constraints
* *All* cryptocurrency-related activity for the user generally must be included in the input CSV file. * *All* cryptocurrency-related activity for the user generally must be included in the
[CSV input file](https://github.com/scoobybejesus/cryptools/blob/master/InputFile_CSV.md).
* There can only be either one or two accounts used in a given transaction * There can only be either one or two accounts used in a given transaction
(i.e., if a Counterparty token or Ethereum token transaction must be recorded, (i.e., if a Counterparty token or Ethereum token transaction must be recorded,
the XCP or ETH transaction fee must be reflected in a separate transaction row). the XCP or ETH transaction fee must be reflected in a separate transaction row).
* Manual adjustments may need to be made to the output files in cases, for example, * Manual adjustments may need to be made to the output files in cases, for example,
when the user used aprpeciated cryptocurrency to make a tax-deductible charitable contribution. when the user used appreciated cryptocurrency to make a tax-deductible charitable contribution.
## Installation ## Installation
1. `cargo build` (or include `--release` for a non-debug build) 1. `cargo build` (include `--release` for a non-debug build)
This will build `./target/debug/cryptools` (or `./target/rls/cryptools` for a non-debug build). This will build `./target/debug/cryptools` (or `./target/rls/cryptools` for a non-debug build).
@ -62,17 +59,39 @@ or jump directly to the [examples.md](https://github.com/scoobybejesus/cryptools
## Development state ## Development state
As of summer 2019, the code is "feature complete" in the sense that it does not require additional features in order for it to serve the needs of the original author. As of summer 2019, the code does not *require* additional features in order for it to serve the project's founder.
At the same time, there are plenty of bells and whistles, creature comforts, etc. that may be added at any time. At the same time, there are plenty of bells and whistles, creature comforts, etc. that are desired and may be added.
Additionally, the code could use factoring or general re-working in several areas. Additionally, the code could use factoring or general re-working in several areas.
In fact, it may be nice to use the business logic as a library instead of running a full binary. In fact, it may be nice to use the business logic as a library instead of running a full binary.
The software has been tested on Mac and Linux.
Additional testers/users are encouraged and welcome.
## Contributing ## Contributing
* Contributors welcome. New authors should add themselves to the `AUTHORS` file. * Contributors welcome. New authors should add themselves to the `AUTHORS` file.
* Roadmap and todos: we're working through items in [Issues](https://github.com/scoobybejesus/cryptools/issues); feel free to tackle or add issues. * Roadmap and todos: we're working through items in [Issues](https://github.com/scoobybejesus/cryptools/issues); feel free to tackle or add issues.
## A few words from the founder
I have an accounting background, and I live in the US.
I took an interest in cryptocurrency in 2016.
When it came time to file my tax return, I had to come to grips with recording my cryptocurrency activity.
I initially used a spreadsheet to manually process the activity into lots, and it quickly became clear that I needed a software solution.
Given my background, I had certain expectations about what this type of software would do, and I tried several online options.
I eventually created this project as a reaction to the inadequate tooling I found online.
Sure, other products have more bells and whistles, but at least I know this produces correct results
(i.e., this software specifically identifies and track all acquired assets, whereas online solutions seems to pool them together).
I am not a formally trained programmer, however I enjoy it very much and learn more whenever I can.
I originally tried to learn C++ by myself, and that was frustrating.
My first real progress was with Python, but I still didn't manage to fully develop a working program.
Luckily, I managed to stumble across a mentor who helped me write 80% of an MVP in strongly-typed Swift.
We coded our way into a corner, but I had learned enough to take the code apart and put it back together correctly and complete it.
I really enjoyed Swift, but I wanted something even more performant (and cross-platform), and Rust seemed to fit the bill.
I rewrote the code in Rust (also with a bit of help from my mentor), and it has turned out to be a great choice.
## Legal ## Legal
See LEGAL.txt See LEGAL.txt

15
examples/examples.md
View File

@ -11,7 +11,7 @@ The sample input files and the resulting reports are in the `/examples/resources
(Note: new reports have been added since the write-up below was written. (Note: new reports have been added since the write-up below was written.
Nevertheless, evaluating the reports should mostly be self-explanatory.) Nevertheless, evaluating the reports should mostly be self-explanatory.)
## Using the wizard ## 1. Using the wizard
##### First, preview the input file `faker1__sample_input.csv` in your editor/viewer of choice. ##### First, preview the input file `faker1__sample_input.csv` in your editor/viewer of choice.
@ -26,7 +26,8 @@ Enter the following:
Running the command above takes you through the wizard. Running the command above takes you through the wizard.
     (Note: You can simply run **`cargo run`** instead, in which case after answering yes to "Shall we proceed," you will have to enter the path of the input file.)      (Note: You can simply run **`cargo run`** instead,
in which case after answering yes to "Shall we proceed," you will have to enter the path of the input file.)
##### Type `<Enter>` to accept default responses to the first three prompts, which are: ##### Type `<Enter>` to accept default responses to the first three prompts, which are:
@ -48,20 +49,22 @@ The reports should match those in the `examples/resources` directory.
(Additional reports are created too, but you can generally match the existing reports by title.) (Additional reports are created too, but you can generally match the existing reports by title.)
## Skipping the wizard ## 2. Skipping the wizard
Let's run the program again. Let's run the program again.
This time around, we'll pass command-line parameters to skip the wizard. This time around, we'll pass command-line parameters to skip the wizard.
##### Again, preview the input file `faker2__sample_input.csv`. ##### Again, preview the input file `faker2__sample_input.csv`.
You'll see it's similar to the README example, except that there is a wider variety of transactions, plus the memos are more descriptive. You'll see it's similar to the README example, except that there is a wider variety of transactions,
plus the memos are more descriptive.
##### Run **`cargo run -- --help`** to see descriptions for the parameters we can use, or just enter: ##### Run **`cargo run -- --help`** to see descriptions for the parameters we can use, or just enter:
##### &nbsp;&nbsp;&nbsp;&nbsp;`cargo run -- -a -o ~/Documents ./examples/resources/faker2__sample_input.csv` ##### &nbsp;&nbsp;&nbsp;&nbsp;`cargo run -- -a -o ~/Documents ./examples/resources/faker2__sample_input.csv`
&nbsp;&nbsp;&nbsp;&nbsp;\* Substitute `~/Documents` with your desired output directory. Substitute a Windows-style file path, if necessary. &nbsp;&nbsp;&nbsp;&nbsp;\* Substitute `~/Documents` with your desired output directory.
Substitute a Windows-style file path, if necessary.
##### Again, the program runs, and you should have reports in the location you provided. ##### Again, the program runs, and you should have reports in the location you provided.
@ -118,7 +121,7 @@ Also, there is a coffee mug purchase and a donation.
The details are easily found in the memo field, but it is up to the user to "parse" those items for their use. The details are easily found in the memo field, but it is up to the user to "parse" those items for their use.
* As noted in the README, adjustments occasionally may need to be made to the output reports. * As noted in the README, adjustments occasionally may need to be made to the output reports.
For example, in `faker2`, a donation was made. For example, in `faker2`, a donation was made.
You may choose (or your accountant may decide) that this transaction (#11) is analogous to donating an appreciated security. Your accountant may decide that this transaction (#11) is analogous to donating an appreciated security.
In that case, you may decide to manually adjust the **Proceeds** to match the **Cost basis**, In that case, you may decide to manually adjust the **Proceeds** to match the **Cost basis**,
and then update the **Gain/loss** to be zero. and then update the **Gain/loss** to be zero.
* You can't spend or exchange something that you don't have. * You can't spend or exchange something that you don't have.