PeerAssets: dPoD Tokens Manual
- Installation (requirements and procedure)
- Updating pypeerassets or pacli
- Configuration and initialization (basic configs, initializing deck, and creating/importing addresses)
- Decks and Proposals (creating and list tokens and proposals)
- Transactions: (voting and donations)
- Other useful commands
This installation installs pypeerassets and pacli. You can follow these instructions also when you want to use standard PeerAssets tokens or PoB and AT tokens.
To run the PoD alpha you need:
- Python 3.6 or higher
- Git (not mandatory, but makes things easier)
- Pip (package installer for Python 3, highly recommended)
- Slimcoin client 0.5 or higher (command line version)
- some Python requirements which are automatically installed by pip.
- If you don't have, make sure you have Python 3.6+ and pip (version 3, also called pip3) installed, and also git for the installation method provided here. The last version was tested with Python 3.9. Python versions earlier than 3.6 could possibly not work because they treat dictionaries - a data structure used extensively in the code - differently.
Optional, for a comfort function also gnome_keyring is needed on Linux systems.
- Download Slimcoin 0.6, start it and sync the testnet (should be ready in less than an hour)
If you already have these two packages on your computer because you used them with Peercoin, please go to the section Configure PeerAssets for Slimcoin. Otherwise, continue here.
-
Select a path where you want to install the pypeerassets/pacli software and change to it.
cd /path/to/installation -
Download the master branch of pypeerassets here and install it with pip3:
git clone https://github.com/slimcoin-project/pypeerassets.git cd pypeerassets git checkout master pip3 install . -
Download the master branch of pacli here:
git clone https://github.com/slimcoin-project/pacli.git cd pacli git checkout master -
If you never ran Pacli on your machine and don't have a configuration file (on Linux:
~/.config/pacli/pacli.conf) for it, there's an additional step before you can install it with pip. Go to the path you installed it, change to the pacli folder. Search for the file default_conf.py and open it with a text editor. Search for the following two lines:"rpcuser" : "USER", "rpcpassword" : "PASSWORD",To enter the correct values, open your Slimcoin Testnet configuration file (e.g. slimcoin-testnet.conf). Replace "USER" with the "rpcuser" value from the Slimcoin Testnet configuration file, and "PASSWORD" with the "rpcpassword" value. You should also confirm that the "rpcport" value is correct (default: 41685).
If you don't have a Slimcoin configuration file (this can happen if you never used Slimcoin as a daemon, but slimcoind will always complain about it!), create one in the Slimcoin configuration directory (~/.slimcoin on Unix systems, %APPDATA%\SLIMcoin (or Slimcoin) on Windows) and enter an arbitrary rpcuser and rpcpassword value there (can be almost anything, only some special characters will not work so better use alphanumeric characters). It is always advisable to create a separate Slimcoin configuration file for testnet if you use the same machine as a node for both mainnet and testnet.
-
Now you can install pacli with pip:
cd /path/to/pacli pip install .Note: The "period" symbol (.) is mandatory. Also, you must install pypeerassets before pacli. Otherwise pacli will install the original pypeerassets from a public repository, which doesn't support dPoD tokens.
-
You can use pacli now in the following way, while Slimcoin Testnet is running:
pacli command_category commandThe command categories are config, deck, address, transaction, card, proposal, and donation. See below for some examples. You can use --help after each category to get some basic help.
To uninstall both packages, simply type:
pip uninstall pacli
pip uninstall pypeerassets
To install them again, follow the procedure above. You don't need step 4, i.e. you don't need to edit the pacli configuration file again (as long as you don't have deleted it), so the process is a bit shorter.
IMPORTANT: If you installed pypeerassets/pacli from the d5000 repo or from the original PeerAssets repo, uninstall it and install it again, or alternatively change your Git configuration to point to the new repository. The simple update procedure described here works only if you installed it from the slimcoin-project repo.
If there is a new version of pypeerassets or pacli available during tests you should use it as it very likely fixes important bugs. Proceed in the following way to update:
-
Go to the folder where you installed pacli or pypeerassets and enter the following command to update to the newest version (if an error gets thrown you're most likely not in the correct folder):
git pull --ff-only -
Now you must install the new version again with pip/pip3.
pip install --upgrade .
If you used PeerAssets with Peercoin and want to use it now with Slimcoin, do the following:
-
Uninstall both pypeerassets and pacli and then install both again, if you downloaded them from a different repo than slimcoin-project.
-
Search for the pacli.conf file, the main configuration file for Pacli. On Linux, it's most likely in the .config/pacli directory of your home directory.
-
Make a backup of this file. Then open the original with a text editor.
-
Change the values for "network", "provider", and "rpcport" to the following ones:
network = tslm provider = slm_rpcnode rpcport = 4168541685 is the standard RPC port. If you have changed your RPC port in the Slimcoin (Testnet) configuration file (see below) then you must use the one you configured.
-
Open your Slimcoin testnet configuration file. If you followed the Testnet guide it should be in the Slimcoin configuration directory (e.g. .slimcoin under Unix/Linux) on slimcoin-testnet.conf
-
Change the values of "rpcuser" and "rpcpassword" in pacli.conf to the values you found in slimcoin-testnet.conf.
The node should now be able to connect to your Slimcoin client.
Once everything is installed, the first thing you have to do is to create addresses which you will use with the PoD token. This include addresses used for creating proposals, voting, donating/locking, and signalling.
NOTE: This procedure exposes private keys! It is highly recommended to only use these commands on Testnets with "play money" until the software is more stable and was thoroughly tested also for security issues.
The easiest way to create and import a new address is the fresh command:
pacli address fresh LABEL --show
LABEL is a "name" you assign to the address. The command works with the Slimcoin client commands, so the new addresses are already saved in your wallet, so no importing or exporting is necessary. --show shows the address, while without it no printout will be given so it can be used in scripts.
If you want to use an already created address from an existing Slimcoin wallet, you need to use the following procedure. First export the address from Slimcoin:
slimcoind dumpprivkey ADDRESS
Then import it into pacli with the following command (chose a LABEL you can easily remember, e.g. "voting") :
pacli address new_privkey --key=PRIVATEKEY --wif --label=LABEL
Set the new label as your main key:
pacli address set_main LABEL --backup=BACKUP_KEY
In Pacli, at any time you will have a main address from where you will conduct all transactions. You can always see your current main Pacli address with the following code:
pacli address show
To see the balance in testnet SLM, type:
pacli address balance
You can always change to another address with an existing label ("name") with the set_main command. If you already have created a label for the current address, or created it using the fresh command, you can type:
pacli address set_main LABEL
If you didn't create a label for the current address, use:
pacli address set_main LABEL --backup=LABEL_FOR_CURRENT_ADDRESS
Before you use the dPoD tokens functions, each time you use a new doD deck, you will need to initialize it:
pacli podtoken init_deck DECK_ID
This imports relevant addresses into your Slimcoin wallet: all P2TH addresses from the Proof of Donation Token deck and one from the Voting Token deck. This step is important, otherwise it's likely you get a lot of strange errors. It needs to be done only once per deck.
It is possible that you have to restart your Slimcoin client for these changes to take effect due to a bug in the client. If you get any strange errors, restart it with:
slimcoind -conf=slimcoin-testnet.conf -rescan
You can create a new token with the following code:
pacli podtoken deck_spawn NAME DP_LENGTH DP_REWARD MIN_VOTE [ --sdp_periods PERIODS --sdp_deck DECK --number_of_decimals NUMBER_OF_DECIMALS --sign --send ]
Mandatory:
- NAME - name of the token
- DP_LENGTH - length of the distribution period, in blocks.
- DP_REWARD - number of tokens which can be issued each distribution period.
- MIN_VOTE - minimal percentage of the token holders who must vote positively for a Proposal. Can be 0.
Optional:
- PERIODS - Number of Special Distribution Periods.
- DECK - Deck ID of the token whose holders are enabled to vote in the Special Distribution Periods.
- NUMBER OF DECIMALS - the precision of the token in numbers of decimals (e.g. if this value is set to 2, then the minimum token amount is 0.01).
--sign and --send are used to really create the transaction which creates the token. It is advisable to do first a "dry run" without these flags.
NOTE: The absolute minimum for the distribution period (DP_LENGTH) is 28 blocks. Inside a distribution period, proposals need to "accommodate" 4 signalling/donation rounds (at least 12 blocks in the first phase, 8 in the second one), one voting round (at least 8 blocks), two security period (at least 2 blocks each) and, in the second round, a donation release period of at least 8 blocks.
pacli podtoken deck_list
lists all decks which are following the dPoD (decentralized Proof-of-Donation) protocol. Note that SDP Voting tokens will not be shown here, because they follow the regular PeerAssets protocol.
pacli deck find DECK_NAME
If you know the deck name, then you can get the Deck ID and some other data with this command.
pacli proposal list DECK
lists all proposals which are currently known for the specified deck, by the TXID of the first proposal transaction which is also the ID of the proposal. They are listed according to the period they're currently in (voting, donation, working, slot distribution periods etc.). All periods have also a code attached to it (from A to G and a number), this is to facilitate data exchange with other applications (the codes may change, so don't rely on them).
DECK, as in many commands that follow, can be one of the following things:
- the Deck ID (a transaction ID)
- a label assigned to the deck with the Pacli Extended Tools
pacli proposal current_period PROPOSAL
shows only the period the specified proposal is in.
PROPOSAL, as in many of the following commands, can be:
- the Proposal ID (shown for all proposals of a deck with the
proposal listcommand) - a label assigned to the proposal with the Pacli Extended Tools
You can create a Proposal at any time with the following command:
pacli proposal create DECK_ID REQ_AMOUNT PERIODS [ --description DESCRIPTION --change_address ADDRESS --sign --send]
Mandatory:
- DECK_ID: ID (transaction id) of the token deck.
- REQ_AMOUNT: Amount of coins requested for the work.
- PERIODS: Number of distribution periods until the delivery of the work (Time To Completion).
Optional:
- DESCRIPTION: A short string to describe the Proposal (maximum around 50 characters, depending on the chars used.)
- CHANGE: Change address (default: address used to send).
There are four types of transactions commonly used: Voting, Signalling, Locking and Donation transactions.
- Voting transactions submit a positive or negative votes for a Proposal. The vote is weighted by the amount of voting tokens you own.
- Signalling transactions show the network how many coins you are willing to donate.
- Locking transactions lock the amount destinated for the donation until the end of the working phase of the Proposal.
- Donation transactions release the donation, they are transferred to the Proposer's address.
For a more exhaustive explanation see the Alpha Test description or the dPoD token description for an in-depth description.
All transactions have to be confirmed to the blockchain at the specific block heights of the periods of the Proposal. To avoid problems with that requirement it is possible to enter transactions previously and they will be broadcasted when the correct period starts. You must keep your terminal open and the computer and the Slimcoin client running (and connected to the Internet) for that.
The --wait option is available for all transaction types (voting, signalling, locking and donation). It waits until the block height starting the next suitable round for the transaction is reached. For example, if we want to conduct a Signalling Transaction but we are still in the voting phase, it will broadcast the transaction when it would be included in the first block of the first signalling round.
--check_round allows to fine-tune this specifying an exact round where the transaction will be broadcasted. For example, if you want to donate in round 6 but you are in round 4 then it will wait for the first block of round 6. If you only included --wait in this case, it would be broadcasted in round 5. This is useful above all for locking and donation transactions: you must always lock/donate in the exact round you have signalled the funds.
Both --check_round and --check_phase have to be entered additionally to --wait. Otherwise, if the period has not been reached the transaction will simply abort.
Take into account that for the transactions to actually be signed and broadcasted you always must include the --sign --send options. This is a security measure to avoid unwanted transactions.
pacli proposal vote PROPOSAL VOTE [ --change_address CHANGE_ADDRESS --confirm --wait] [--sign --send]
Mandatory for dry run and to actually send the vote:
- PROPOSAL: Proposal to donate to; ID, short ID, label or part of description (see Show Decks and Proposals).
- VOTE: positive ("yes") or negative ("no").
Mandatory to actually send the vote (see above):
- --sign: sign voting transaction
- --send: broadcast voting transaction
Optional:
- CHANGE_ADDRESS: Change address for the coins remaining from the transaction. Take into account that voting transactions only consume fees (P2TH and transaction fee). If not given, the address from where the voting TX was conducted, is used.
--confirm waits until the voting transaction got confirmed.
pacli proposal get_votes PROPOSAL
Mandatory:
- PROPOSAL_ID: Proposal transaction to donate to.
pacli donation signal PROPOSAL AMOUNT --dest_label=DONOR_LABEL [ --dest_address=DONOR_ADDRESS --change_address CHANGEADDRESS / --change_label CHANGE_LABEL --sign --send --wait --check_round=ROUND ]
Mandatory:
- PROPOSAL: Proposal to signal for.
- AMOUNT: Amount in coins to signal availability.
The donor address can be entered in two different ways:
- DONOR_LABEL: The label (name) you assigned to your Donor Address. This must be an address the donor controls. This is an easier variant of the dest_address command.
- DONOR_ADDRESS: The Donation Address where the coins should be transferred. The address cannot be used for other donations to the same proposal.
Mandatory to actually send the signalling transaction (see above):
- --sign: sign signalling transaction
- --send: broadcast signalling transaction
Optional:
- CHANGE_ADDRESS: Change address (address for change coins, default: address used to send).
- CHANGE_LABEL: Label of the change address (easier way)
- --wait will conduct the transaction in the next suitable signalling period. You must leave the computer on for that.
Basic command:
pacli donation signal PROPOSAL AMOUNT DONOR_LABEL --sign --send --wait
This will send the signalling transaction in the next suitable round. Consider a dry run (without --sign, --send and --wait) before so you can spot potential errors.
pacli donation lock PROPOSAL [ --amount=AMOUNT --reserve=RESERVE_AMOUNT --reserve_address=RESERVE_ADDRESS / --reserve_label=RESERVE_LABEL --change_address=CHANGE_ADDRESS / --change_label=CHANGE_LABEL --manual_timelock=TIMELOCK --sign --send --wait --check_round=ROUND --new_inputs]
Mandatory:
- PROPOSAL: Proposal to donate to.
Mandatory to actually lock the funds (see above):
- --sign: sign locking transaction
- --send: broadcast locking transaction
Optional:
- RESERVE_ADDRESS: The reserve address is used to reserve a slot in the next round (see description here). It must be different to the Donor Address you specified in the Signalling Transaction and other donor addresses you used for this proposal.
- RESERVE_LABEL: Instead of entering the address you can use the label of the address with the --reserve_label option.
- RESERVE_AMOUNT: The amount to reserve.
- AMOUNT: Amount of coins to lock. If not given, automatically the slot value is used - in this case make sure you have enough balance on this address to fill it (if the balance is less than the slot, the whole balance minus fees is used).
- TIMELOCK: Normally the timelock is calculated automatically but you also can specify a value manually. Take into account that for the donation to be valid it must be locked until the last block of the working period of the Proposer.
- CHANGE_ADDRESS: Change address (default: address used to send) for remaining coins not used in the transaction.
- CHANGE_LABEL: Simple mode, uses the label instead of the address.
- --new_inputs allows to use other funds on the address than the inputs of the Signalling/Reserve transaction.
- --wait will conduct the transaction in the next suitable locking period. You must leave the computer on for that.
Basic command:
pacli donation lock PROPOSAL_ID --sign --send --wait --new_inputs
This will send the locking transaction in the next suitable round. Consider a dry run (without --sign, --send and --wait) before so you can spot potential errors. If you add --new_inputs at the end you make sure that the transaction is conducted even if you moved funds from the donor address, as long as you have enough balance at this address.
pacli donation release PROPOSAL [ --amount=AMOUNT --reserve=RESERVE_AMOUNT --reserve_address=RESERVE_ADDRESS / --reserve_label=RESERVE_LABEL --change_address=CHANGEADDRESS --sign --send --wait --check_round=ROUND --new_inputs]
Mandatory:
- PROPOSAL: The proposal to donate to.
Mandatory to actually send the donation (--send cannot be reverted!):
- --sign: sign donation transaction
- --send: broadcast donation transaction
Optional:
- CHANGE_ADDRESS: Change address (default: address used to send).
- RESERVE_ADDRESS: The reserve address is used to reserve a slot in the next round (see description here). It must be different to the Donor Address you specified in the Signalling Transaction and other donor addresses you used for this proposal.
- RESERVE_LABEL: Instead of entering the address you can use the label of the address with the --reserve_label option.
- RESERVE_AMOUNT: The amount to reserve.
- AMOUNT: Amount of coins to donate. If not given, automatically the slot value is used - in this case make sure you have enough balance on this address to fill it (if the balance is less than the slot, the whole balance minus fees is used).
- CHANGE_ADDRESS: Change address (default: address used to send) for remaining coins not used in the transaction.
- CHANGE_LABEL: Simple mode, uses the label instead of the address.
- --new_inputs allows to use other funds on the address than the inputs of the Signalling/Reserve transaction. Note: In the donation release transaction this means that you don't use the funds you locked in the LockingTransaction.
- --wait will conduct the transaction in the next suitable donation period. You must leave the computer on for that.
Basic command:
pacli donation release PROPOSAL --sign --send --wait
This will send the donation release transaction in the next suitable round. Consider a dry run (without --sign, --send and --wait) before so you can spot potential errors.
Donors and Proposers can claim PoD tokens after the end of the Final Distribution Period. They must set their donor or proposer address as their main address before. The default behaviour is that the tokens are sent to this address.
For donors, the command is:
pacli donation claim_reward PROPOSAL [ --receiver RECEIVER --payment PAYMENTS --verify --sign --send ]
For proposers, who want to claim tokens for the missing donations, the command is:
pacli donation claim_reward PROPOSAL --proposer [ --receiver RECEIVER --payment PAYMENTS --verify --sign --send ]
Mandatory:
- PROPOSAL_ID: ID (transaction id) of the proposal you donated for (or are the issuer).
Mandatory to actually create the tokens ("issue the cards"):
- --sign: sign card issue transaction
- --send: broadcast card issue transaction
Optional:
- PAYMENTS: If you want to make a payment (or various) with the tokens you claim, you can specify here the amount of each of them. The sum of the amounts cannot be higher than the reward corresponding to your slot. If there are tokens left, they are issued to your donor/proposer address.
- RECEIVER: List of the receivers of the payments specified in PAYMENTS. The length of the list of receivers must be equal to the length of the list of payment amounts.
- DONATION_TXID: Transaction ID of the donation.
Basic command for donors:
pacli donation claim_reward PROPOSAL_ID --sign --send
This will send the cards to your donor address. If the distribution hasn't finished yet, then the command will terminate with an error. After one confirmation, you can see them on your address with the card balances command (see below).
pacli card balances DECK_ID
Retrieves the balances of all addresses for a token. It works with regular PeerAssets tokens (e.g. Voting Tokens) and with PoD tokens. Take into account that if you claimed or received tokens and the transaction was not confirmed, the tokens will not be shown here.
pacli proposal info PROPOSAL
Gives some information about the proposal transaction. Still rudimentary and technical, mainly for debugging.
pacli proposal state PROPOSAL
Gives information about the state of a proposal, for example the blocks where the slot allocation rounds begin, and the number and values of donations. Also still rudimentary and technical.
This command accepts, apart from the ID and an assigned label, also two more options: a substring of the proposal description, and the short ID (first 16 characters of the ID) of the Proposal.
pacli proposal my_donation_states PROPOSAL
Shows all donation states (which contain all transaction related to a donation: signalling, locking and release transaction) of the current active address.
pacli proposal all_donation_states PROPOSAL
Shows all donation states for a proposal, regardless of the address.
pacli proposal list DECK
Shows all proposals and the periods where there are in (see codes below).
pacli proposal get_votes PROPOSAL
Shows the number of votes in both rounds (if available).
pacli proposal current_period PROPOSAL
Shows the current period of a proposal.
pacli proposal all_periods PROPOSAL
Shows all periods and phases of a proposal.
pacli address show_all
Shows all addresses with labels saved in the keyring and their balance. (Does not show private nor public keys.)
NOTE: This command needs gnome-keyring as a dependency, so for now it is Linux/Unix-only. The Extended Tools provide an alternative.
pacli address my_votes DECK_ID
Shows all votes to all proposals made from a certain address.
pacli donation show_slot PROPOSAL [ --satoshi ]
Shows the slot of your donation, i.e. the optimal amount to donate to maximize the token reward. The amount is shown regularly in coins, unless you use the --satoshi flag, then it's shown in satoshi (minimal units).
NOTE: For show_slot to work, the donor address (i.e. the address to where you sent coins in a Signalling transaction) must be your main address. You can use set_main to change the main address at any time (see section "Address").
pacli donation check_tx TXID
Gives information about a donation, locking, signalling or voting transaction or a proposal creation.
The Proposal Lifecycle is the period between the submission of a Proposal and the completion, i.e. when the requested funds were donated.
For each period there is a code, consisting in a letter, from A to E, and a number. The letters refer to Distribution Periods (epochs). For example, B is the distribution period where the Initial Vote and the initial slot allocation rounds take place, and D is the distribution period with the Final Vote and the Final Slot Allocation.
The letters have the following significance: A - Periods before the first cycle. B - First Voting/Donation Epoch: Distribution Period with the Initial Vote and Initial Slot Allocation. C - Working periods (this phase lasts normally several distribution periods). D - Second Voting/Donation Epoch: Distribution Period Period with the Final Vote, Donation Release and Final Slot Allocation. E - After the second cycle.
- Period A0: Before the proposal submission (blockchain is probably not completely synced).
- Period A1: Before the distribution start of the Initial Phase.
- Period B0: Before the distribution start of the Initial Phase (security period).
- Period B1: Voting Round 1.
- Period B10, 20, 30, 40: Initial Slot Distribution, Signalling Phase round 1-4.
- Period B11, 21, 31, 41: Initial Slot Distribution, Locking Phase round 1-4.
- Period C0: Working phase (no voting nor slot distribution ongoing).
- Period D0: Before the distribution start of the Final Phase (security period).
- Period D1: Voting Round 2.
- Period D2: Donation Release Period.
- Period D10, 20, 30, 40: Final Slot Distribution, Signalling Phase round 1-4.
- Period D11, 21, 31, 41: Final Slot Distribution, Donation Phase.
- Period D50: Remaining period of Final Phase.
- Period E0. All distribution phases concluded.