CredaCash Software Quick Start Guide
The following steps should help get the CredaCash software quickly running:
Installation
Download the Windows executable files at https://CredaCash.com/software/, then extract the contents to any convenient directory.
For Linux, the software must be built from the source code at Github.
Running the Software via the Batch Files
The easiest way to run CredaCash under Windows is to use the provided batch files.
To quickly and easily access the test network, double-click on the file _start_testnet_wallet_via_public_node.bat.
To quickly and easily send transactions on the main CredaCash network, double-click on the file
__start_wallet_via_public_node.bat.
If the wallet reports that the wallet file needs to be updated, double-click on the file ___update_wallet.bat, follow the instructions, and then repeat the step above.
To run a local network node on the main CredaCash network, and then use that node to send and receive transactions, first double-click on the file __start_local_node.bat, wait for the local node to show block announcements on the console and to fully sync to the blockchain, and then double-click on the file __start_wallet_via_local_node.bat.
For further instructions on operating the wallet, skip down to the section of this Guide titled “Operating the CredaCash Wallet”.
Running the Software via the Command Line
The Tor Network
CredaCash runs entirely over the Tor network for privacy and security. The Tor executable is bundled with the CredaCash binary distribution for Windows. To verify Tor works on your network, open a command prompt window and “cd” to the directory containing the CredaCash executable files. Then start Tor using the command:
Tor\tor.exe -f tor.conf DataDirectory temp_tor SocksPort 9226
After 1 to 5 minutes, Tor should report: “Bootstrapped 100%: Done”. At this point, stop Tor by pressing Ctrl-C, and then delete the temporary Tor directory using the command
rmdir/s/q temp_tor
When running under Linux, Tor will not by default be installed in the Tor subdirectory. The easiest way to configure Tor in this case is to symbolically link to the Tor executable. First, locate the Tor executable program installed on the computer using one of these commands:
which tor
or
find / -type f -executable -name tor 2>/dev/null
Then symbolically link to the Tor executable using the commands:
mkdir Tor
ln -s /full/path/to/tor-executable Tor/tor.exe
Tor can then be tested using the command:
Tor/tor.exe -f tor.conf DataDirectory temp_tor SocksPort 9226
After Tor reports “Bootstrapped 100%: Done”, the temp directory can be deleted with the command:
rm -rf temp_tor
Optionally running the CredaCash Network Node Software
Optionally, start a full node. The wallet can use this node to access the network, or it can use a public node running in the cloud. For the highest levels of reliability, privacy and speed, it is recommended to run a full node, but for testing or intermittent use, this step can be skipped.
If desired, start a full node by opening a command prompt window, and “cd” to the directory containing the executable files. The network node program generates output (stdout) that can be directed to a log file, as follows:
ccnode.exe > ccnode.log
The above command connects to the CredaCash main network. To connect to the CredaCash test network, use the command:
ccnode.exe --blockchain=1000 > ccnode.log
The node program connects to the network via Tor, and it may take 1 to 5 minutes to establish a connection. Once a connection is established, new block announcements will appear on the console (stderr). The node can be used by a wallet when it is fully synced to the blockchain.
The CredaCash node program includes a number of configuration options that are beyond the scope of this guide. To see the full list, use the command “ccnode.exe --help“.
Note: When running under Linux, all program names in the current directory need to be prefixed by “./”, for example:
./ccnode.exe > ccnode.log
Running the CredaCash Wallet
1. Open a new command prompt window, and “cd” to the directory containing the CredaCash executable files. Then initialize a new wallet using the command:
ccwallet --create-wallet
The wallet will prompt for a password for its master secret.
To initialize a new wallet for the CredaCash test network, use the command:
ccwallet --blockchain=1000 --create-wallet
2. The wallet needs to connect to a full node with transaction services enabled. There are four options:
- A node running on the same computer. If a full node has been started on the same computer and has synced to the blockchain, the wallet can connect to this server using its default settings:
ccwallet.exe --interactive - Connect directly to a public node in the cloud. This is the quickest and easiest option (if the cloud node is not overloaded):
ccwallet.exe --interactive --transact-host=3.209.91.236 - Connect to a public node in the cloud via the Tor network. It can take 1 to 5 minutes for the Tor network to initialize and establish a connection:
ccwallet.exe --interactive --transact-tor=1 - Connect to a public node in the cloud via Tor, and for increased privacy, create a new connection for each query:
ccwallet.exe --interactive --transact-tor=1 --transact-tor-single-query=1
The above commands are all for the CredaCash main network. To connect to the CredaCash test network, add the command line option --blockchain=1000, for example:
ccwallet.exe --blockhain=1000 --interactive
In addition, to directly connect to a public test network node in the cloud, use the internet address 18.205.168.173:
ccwallet.exe --blockhain=1000 --interactive --transact-host=18.205.168.173
The CredaCash wallet includes a number of configuration options that are beyond the scope of this guide. To see the full list, use the command “ccwallet.exe --help“.
Operating the CredaCash Wallet
Getting a List of Commands
The CredaCash wallet supports a subset of the Bitcoin RPC (Remote Procedure Call) commands. To get a list, use the command:
help
In this release, the wallet only supports the basic commands to send and receive transactions. All the features of CredaCash such as completely private escrow transactions and completely private cross-chain swaps can be accessed via the transaction library (cctx64.dll). It is hoped that in the future, the wallet will also support these features.
Checking the Server Connection
The wallet must be able to communicate with a transaction server in order to operate. The connection to the transaction server can be tested using the “ping” command. This command will report the server response time in seconds:
ping
When connecting to a transaction server via the Tor network, the first ping command may take 1 to 5 minutes to complete. Subsequent pings should take only a few seconds.
In order to create transactions, the transaction server must also be connected and fully synced to the blockchain network. The state of the transaction server can be checked using the command:
getinfo
If the number of connections reported is greater than zero, then the transaction server is connected and fully synced to the blockchain.
Minting Test Currency on the Test Network
Test currency can be freely minted on the test network using the command:
cc.mint
This command will submit a mint transaction to the test network and return a txid (transaction id). The commands “gettransaction
Note that mint transactions are not accepted on the main CredaCash network. CredaCash currency for use on the main network must be obtained from a current currency holder.
Sending a Transaction
To send a transaction using CredaCash:
1. The Recipient creates a new transaction destination using the command:
getnewaddress
This command returns a new destination.
2. The Recipient provides the destination to the Sender. Note that the destination should be kept private between the Recipient and Sender, and if necessary, sent via a secure (encrypted and authenticated) channel. Any third party that obtains the destination will be able to compromise privacy by identifying the transactions sent to that destination and decoding the transaction amounts.
3. Optionally (and recommended), the Sender obtains a unique reference identifier for the transaction using the command:
cc.unique_id_generate
This command returns a new reference id that is unique for this wallet.
4. The Sender sends a transaction using the command:
cc.send <ref_id> <destination> 0 <amount>
In order to maximize privacy, the CredaCash wallet attempts to make all transactions look as indistinguishable as possible. To accomplish this, all transactions have 2 to 4 inputs, and exactly 2 outputs. In addition, the amount is sent to the destination in a single transaction. If necessary, the wallet will first construct one or more transactions that send amounts back to itself in order to merge multiple billets into a larger billet before it then sends the final amount to the destination. This is all handled automatically by the wallet.
The send command will return a txid if a transaction to the destination was created and successfully submitted. Otherwise, it will return an error. If communication with the wallet is lost, the user application may not receive any result. In that case, the cc.send command may be resubmitted with the same ref_id, destination and amount. When the cc.send is resubmitted, it will return the same txid or transaction error that the original call returned or would have returned. It will not send the same amount a second time, which prevents double payments.
The command “cc.send_async” can also be used to send a transaction. This command starts the send on a background thread and then immediately returns. To poll for transaction completion, cc.send_async or cc.send can be called repeatedly until a txid or a transaction error is returned.
The Bitcoin-compatible command sendtoaddress can also be used to send a transaction. However, this command has a significant drawback: if the user application does not receive a response, it can be difficult and error-prone to determine if the command succeeded or if it needs to be resubmitted, and if erroneously resubmitted, it will send the same amount a second time, resulting in a double payment. To avoid double payments, it is strongly recommended to only use the commands cc.send and cc.send_async.
5. The Sender may optionally wait for the transaction to clear. The command “gettransaction <txid>” is the best command to determine if a transaction has cleared, since it will immediately query the transaction server for the status of an uncleared transaction. If the transaction is reported as having one or more confirmations, then the transaction has cleared and the CredaCash blockchain consensus protocol ensures that it is permanent and will not be reverted. Note that waiting for more than one confirmation has no value with CredaCash—simply one confirmation is sufficient—and therefore the wallet does not track the specific number of confirmations, but instead generates a synthetic number for compatibility with Bitcoin. The block level of a transaction is also not an important value in CredaCash and not recorded by the transaction server, so these values are also synthetically generated by the wallet for compatibility with Bitcoin.
6. The Sender sends the txid to the Recipient. In order to maintain privacy, the Sender may wish to send this via an encrypted channel.
7. The Recipient uses the command “gettransaction <txid>” to confirm that the payment has cleared. Note that for the Recipient, the gettransaction command will return “Non-wallet transaction id” until the transaction clears.
Also note that when a transaction is submitted to the transaction server, it is not guaranteed to be added to the blockchain and therefore it might never clear. This may happen for example if the transaction server is having trouble communicating with the network. A transaction that never clears would eventually need to be cancelled or abandoned by the Sender so that the funds may be reused. For information in cancelling or abandoning a transaction, see the next section.
Advanced Wallet Commands
– The command “backupwallet” will reliably backup the wallet file while the wallet program is running.
– After generating a new destination, the CredaCash wallet automatically polls periodically for new payments to that destination. The command “cc.destination_poll” can be used to force the immediate polling of a destination. The second parameter of the command is the number of addresses to poll. This parameter can usually be omitted, or if provided, a value such as 20 should be more than sufficient.
– If a transaction never clears, then to avoid a double payment, the transaction should be cancelled using the command “cc.transaction_cancel <txid>” before attempting to resend it. A transaction can only be cancelled however if it was not received by the network. Once a transaction has been received by the network, it should quickly be added to the blockchain and therefore cannot be cancelled. In the rare event a transaction does not clear, the following procedure is recommended before attempting to resend it: (1) If a transaction has not cleared after a few minutes, check the network connection using the “getinfo” command. If “getinfo” reports the number of connections is zero, then the transaction server has either lost connection with the network or has not yet synced with the blockchain. In either case, this must be resolved and “getinfo” must report connections greater than zero before continuing. (2) Attempt to cancel the transaction using the “cc.transaction_cancel <txid>” command. This command will either report an error, or it will return an internal txid. If it returns an internal txid, then a cancel transaction was submitted and is pending. (3) Periodically monitor the original transaction with the command “gettransaction <txid>”, where txid is the same txid used in the “cc.transaction_cancel <txid>” command. If this reports the number of confirmations is greater than zero, then the original transaction cleared and it should not be resent. If this reports the number of confirmations is less than zero, then the original transaction was cancelled and it is safe to resend it. If this continues to report the number of confirmation is zero, then nothing has happened, possibly due to a continuing problem with the connection to the network. In this latter case, after several minutes of waiting, this procedure can be retried starting back at Step 1.
– The command “cc.billets_release_allocated” will release all billets allocated to pending transactions, effectively abandoning these transactions and allowing the billets to be reused in new transactions. By default, this command will also reset the wallet balance to match the pool of unspent billets.
– The command “cc.billets_poll_unspent” queries all unspent billets to ensure they have not been spent in transactions (possibly by a copy of the wallet). Billets that are found to be spent are subtracted from the wallet balance.
Using the CredaCash Wallet RPC (Remote Procedure Call) Interface
The CredaCash wallet can also be accessed via its RPC interface. To enable the RPC interface, start the wallet using the command line or configuration file option “--wallet-rpc=1“, and optionally, “--wallet-rpc-password=<password>“. For example:
ccwallet.exe --wallet-rpc=1 --wallet-rpc-password=pwd
For better security, the password should be provided in the wallet.conf file instead of the command line, and the operating system’s file permissions should be used to prevent other computer users from reading this file. Alternately, if a password is not provided, the wallet will automatically generate one and place it into a “cookie” file. The cookie file should also be made unreadable by other computer users.
If the “curl” utility is installed, it can be run from a different command prompt window to access the wallet’s RPC interface, for example, from the Windows command line:
curl -s -u rpc:pwd 127.0.0.1:9234 --data-binary "{""method"":""getbalance"",""params"":[]}"
or from the Linux command line:
curl -s -w "\n" -u rpc:pwd 127.0.0.1:9234 --data-binary \{\"method\":\"getbalance\",\"params\":[]\}