Counterparty Tutorial
Learn how to use the Counterparty (XCP) protocol and currency to issue cryptoassets and tokens.
This tutorial is a free crash-course on how to use the Counterparty protocol to issue, send, and trade cryptoassets using Bitcoin.
You don’t need to be a Level 10 Wizard to use Counterparty. I think you’ll find, through hands-on experience with the software, that it’s straight-forward.
On average, this tutorial takes 30–90 minutes from start to finish, depending on blocktimes. And each step is designed to be performed with a PC or laptop.
What You’ll Learn
By following this tutorial step-by-step, you can walkthrough and learn many of the most important features in Counterparty.
- How to Issue a Counterparty Asset
- How to Manage Asset Information
- How to Send and Receive Tokens
- How to Trade Tokens on the DEX
If you encounter any problems or need assistance, feel free to reach out to me personally on Twitter or on Telegram. I will help you, if I can.
Table of Contents
Introduction
Getting Started
Create a Wallet
Open Wallet
Fund Wallet
Issue Numeric Asset
Issue Additional Tokens
Lock Asset Issuance
Update Description
Transfer Asset
Burn BTC for XCP
Issue Named Asset
Issue Subasset
Buy/Sell on the DEX
Introduction
Sometimes known as a meta-layer, Counterparty is a protocol and cryptocurrency designed to exist on top of the Bitcoin blockchain.
By layering on top of the Bitcoin network, Counterparty does not reinvent the wheel by trying to make its own premium global blockchain. Instead, Counterparty’s P2P network is Bitcoin’s P2P network, Counterparty addresses are Bitcoin addresses, Counterparty transactions are Bitcoin transactions.
This allows Counterparty to focus on its strength: permissionless finance and tokenization. Now, let’s get into it!
Getting Started
We’ll be using what’s known as the “testnet” for this tutorial, so we can make mistakes without risking funds. Let’s get started by setting up a Counterparty-enabled bitcoin wallet.
Counterwallet is the most common Counterparty-enabled web wallet in use today. Its code is open source and it was originally coded by Counterparty’s founding team. Private keys and transaction signing is all handled “client side” which means that the “server side” has no access to your funds.
Noteworthy: If the Counterwallet software is not on a server you host, there is no way to know if the code has been modified in some way. You are trusting that the host has not updated their code to save your passphrase “server side”.
The Counterwallet used in this tutorial is wallet.counterwallet.io, but it is not the Counterwallet you necessarily have to use.
Create a Wallet
Step 1.
Visit: https://wallet.counterwallet.io/?testnet=1. Using this exact link will ensure that you are using the testnet and not mainnet.
Step 2.
Create your testnet wallet by clicking, “Create a Wallet”. This will cause a popup window to appear on your screen.
Step 3.
Save your auto-generated passphrase. Write it down and securely store it. Something like a password manager is fine for testnet wallets.
Step 4.
Check, “I have written down or otherwise securely stored my passphrase.”
Step 5.
Click “Continue”.
Step 6.
After clicking continue, you will be prompted to create a “Quick Access URL”. Personally, I skip this. Click through the prompts, depending on your choice.
The passphrase you saved is used to generate private keys. With it, you now have a bitcoin wallet and can use it login to Counterwallet.
Open Wallet
Step 1.
Type or paste your saved passphrase into the form and click “Open Wallet.”
Step 2.
Read and then accept or reject the Terms of Service. Why a ToS? Counterwallet’s are centralized, Counterparty is decentralized.
Step 3.
The first time you login, a welcome message appears. You can close it by clicking the “x” in the top right. Make sure testnet is in use.
Step 4. (Optional)
It’s a good idea, if this if your first time using Counterwallet, to logout and log back in again to be sure that you have saved your passphrase.
Fund Wallet
In order to do anything in Counterparty, you will need to create bitcoin transactions and therefore pay bitcoin fees. Let’s get some testnet BTC.
Step 1.
Copy your first address to your clip board, it will look like a regular bitcoin address, except it will start with the letter ‘m’.
Step 2.
Visit any bitcoin testnet faucet and paste in the address on your clipboard. This will take time to confirm.
Here is a list of faucets as of May 2018:
https://testnet.manu.backend.hamburg/faucet
https://testnet.coinfaucet.eu/en/
https://kuttler.eu/en/bitcoin/btc/faucet/
http://bitcoinfaucet.uo1.net/
http://tpfaucet.appspot.com/
You can monitor your transaction from your favorite blockchain explorer. You may have to refresh your balances page by clicking on another menu item and then back into “My Balances” or you can logout and in again.
Step 3.
Once your testnet faucet deposit confirms, it will be reflected as a non-zero BTC balance in your Counterwallet. Great!
Issue Numeric Asset
There are three types of assets: numeric, named, and subassets. Numerics do not require XCP, just a BTC tx fee. So, let’s go ahead and issue one now.
Step 1.
Click on the “Address Actions” button. And then, inside the dropdown, click on “Create a Token (Asset)”. This will prompt a popup window.
Step 2.
Pick a name. Numerics start with ‘A’ and are followed by 18–20 digits. They can be useful, if you need to issue a large number of assets or you prefer nondescript names. A random numeric name has been automatically chosen, but if you want you can request another numeric by clicking on the arrow.
Step 3. (Optional)
Giving your asset a description is optional. You can enter human-readable text, encoded text, a URL to a website, image or JSON file, it’s up to you.
Step 4.
How many tokens would you like to create for your asset? Enter it here. Zero is an option! You can issue more later, but you cannot update divisibility.
Divisible assets will have notation like BTC: 0.00000001. Tiny fractions of your token can be sent. If you uncheck this box, only whole numbers can be sent or traded, like 1, 2, 10. And amounts like 1.5 will not be possible.
Step 5.
Choose your BTC fee. Depending on your time preference, you may want to pay more or less for the bitcoin miner’s fee. I usually choose the lowest fee, unless I know competition for block space is high, at the time.
Step 6.
Review your selections before clicking, “Create Token.” You will not be able to undo this action, after you have clicked the button.
Step 7.
You will get a confirmation, if successful. Sometimes, you will encounter an error, if the Counterwallet is having intermittent issues.
Step 8.
Once your transaction confirms, your asset will appear in your wallet just like how BTC or XCP does. Congratulations, you’ve registered your first asset!
Issue Additional Tokens
We’ve got a new shiny asset, but what if we actually wanted 1000 tokens? As long as your asset is unlocked, you can issue more tokens.
If you are unsure, you should always start with a small number, or zero. You can always add more, but you cannot destroy tokens, at this time.
Step 1.
You’ll notice that each asset in your wallet has it’s own dropdown. Click on your numeric asset’s dropdown arrow and click, “Issue Additional”.
Step 2.
The form here is pretty self explanatory. Notice how we have to define a bitcoin fee again. You will always pay a small fee when taking an action.
Step 3.
Your additional tokens will be created once the transaction confirms. This can take time, depending on the network.
When a change is pending, you may notice a spinning wheel icon indicating that the balance is not yet confirmed.
Lock Asset Issuance
Depending on your use case, you may want to definitively lock your asset such that it’s clear to everyone on the network that there will never be more tokens.
Step 1.
Click on the dropdown menu for the asset you want to have locked. Click on “Lock Token Issuance”.
Step 2.
Although no bitcoin fee slider is shown with this prompt, you will pay a fee for taking this action. Click “Lock Token” only if you are certain.
Update Description
Creating new issuance or locking an asset’s issuance are useful functions, but less common than editing your description.
Step 1.
From the asset’s dropdown menu, click “Change Token Description”. You may be noticing a pattern, if you want to do something to an asset, just dropdown!
Step 2.
Enter your new description and click “Change Description”. Even if your token is locked, you will still be able to update your description.
One of the popular features of the Counterparty protocol is its support for enhanced asset info, which is a method for using JSON rather than text.
Send Tokens
You’ve gotten pretty good at managing your asset’s information. So, let’s get these tokens moving and out there in the world!
Step 1.
To simulate another user, let’s create a new address inside of our wallet by clicking on the “Create New Address” button. Choose “Regular Address”.
Step 2.
You can call your address whatever you like. Just know that, if you name your address, this name will only be saved on this Counterwallet, not others.
Step 3.
Highlight and copy the address of the new wallet to your clipboard. We will need it to send the tokens.
Step 4.
From the asset dropdown, choose “Send.”
Step 5.
Paste in the address from your clipboard and enter an amount of tokens you’d like to send. Be careful of the “MAX” button, as it will default to all you have.
Step 6. (Optional)
A memo is not a requirement to send tokens, with the exception of a few special circumstance, like if an exchange requires you to enter a memo.
You can see from the dropdown that there are two options, “Data memo” and “Plain text memo”. Just be aware this exists, select “No memo” for now.
Step 7.
As always, review your selections before clicking, “Send.” This action cannot be reversed. If the transaction is important, you may consider a high BTC fee.
Step 8.
If you get this screen, the send request was successful. You can now check your favorite blockchain explorer, if you want to track the progress.
Step 9.
Straight away, you should see the balance pending on the recipient address. Notice the asset is blue instead of orange/yellow, like it is at your first address. If you didn’t issue the asset, then it will show as blue to you.
Also notice, this recipient does not have any BTC or XCP. An address doesn’t need either to receive Counterparty tokens. They would, however, need BTC if they wanted to send their tokens away, in the future.
Transfer Asset
Let’s do something crazy and transfer ownership of the asset we created. This can be useful for interorganization restructuring or outright sales.
Step 1.
As always, click the asset dropdown. Click on “Transfer Ownership.”
Step 2.
Enter the address of our other address in the wallet that we just sent tokens to. Notice that this will send them ownership only, not any tokens we have.
Step 3.
Notice how, after the transfer, the colors indicate that the first address no longer owns the asset itself and it can only send tokens now.
The second address has gained the ability to manage the asset, but cannot issue new tokens, as the asset is locked forever, regardless of who owns it.
Burn BTC for XCP
To issue named assets, a 0.5 XCP registration fee needs to be paid. No one received this XCP, it is just taken out of circulation or “burned”.
To get XCP, we can burn BTC. This is a testnet only feature. The mainnet burn ended in 2014 and XCP is only available now through the open market.
Step 1.
On the first address we made, select “Burn for XCP” from the BTC dropdown.
Step 2.
As the fee is only 0.5 XCP for named assets and 0.25 XCP for subassets, you don’t need to burn much BTC to get XCP.
If you get an error like…
You may have to wait for your other txs to confirm. The red arrow in this image below points to the indicator that shows how many txs are pending.
Step 3.
Now, you should have some XCP available to use for registering asset names.
Issue Named Asset
The process for registering a named asset is identical to numeric asset names, except you should expect to pay 0.5 XCP.
Step 1–6.
Review the steps here. I won’t repeat them, you’re getting good at this!
Step 7.
Notice in the confirmation that 0.5 XCP will be deducted from your balance.
Step 8.
Ready to roll!
Issue Subasset
If you own a named asset, you can create subassets for a 0.25 XCP registration fee. The process is just like the numeric and named assets.
Step 1–6.
Review the steps here. I won’t repeat them, I doubt you need them now!
Buy/Sell on the DEX
A nice feature for small projects, just starting, is the DEX. Any token can be instantly and permissionlessly traded on the Counterparty DEX.
Step 1.
From the sidebar menu on the left, select “Exchanges” -> “Markets”. This is the homepage of the DEX.
Step 2.
Select a trading pair from the list or enter a trading pair in the box highlighted below in red. In this case, I am looking to trade TUTORIAL and XCP.
Step 3.
Once you have selected a trading pair, you will be brought to an order book just like how other exchanges work.
Step 4.
Create a sell order for any of the tokens you created as part of this tutorial. Here I am looking to sell 5 TUTORIAL for 1 XCP, making the price 0.2 XCP.
Step 5.
Once confirmed, this order will be available to anyone world wide that has XCP and wants to buy TUTORIAL for 0.2 XCP each.
Conclusion
Great job! If you’ve made it this far and have performed all these different tasks, you are now skilled at using Counterparty, especially Counterwallet. You have issued every type of asset and know how to manage their info and issuance, you can transfer assets, send them, and trade them. You’re a pro!
When you’re ready, a good way to “level up” is to fund a Counterwallet on mainnet using real BTC and XCP you acquired on an exchange. If you have more questions about how to get started, try out some of these chat rooms:
- Discord: Official Counterparty Discord
- Telegram: Counterparty DEX Group
Tutorial Bounty
If you’re STILL reading, reach out to me on Twitter or on Telegram and let me know the testnet address you used while following this tutorial and whether you found it useful or not, I’ll send you 500 BITCORN from my game Bitcorn Crops!
