End-to-End Blockstack Identity and Profile Management
By the end of this post, you’ll know how to use Blockstack’s CLI to update your information. And have a richer understanding of Blockstack internals.
My cousin’s name is Dan. His favored handle is danvk — 5 letters. Onename, which allows easy registry of a Blockstack identity, only allows 6+ letter reservations, because short, memorable identities cost upwards of $10 per name to register. My handle, dougvk (6 letters), was easily secured via the website. However, I couldn’t just let my cousin’s name go. I had to manually create a 5-character identity via the CLI, which is what the remainder of this article will be about. So I went down the Blockstack rabbit hole to learn how to manage shorter names. 20 tabs, 1 whitepaper, and 8 hours later, I figured it all out.
Blockstack, like a good drug dealer, makes it easy to get into their system and purchase a name. Aside from waiting for 6 bitcoin confirmations, ~60 minutes, I had danvk.id purchased within ten minutes of downloading the CLI. The instructions linked here get you there. But also — like a good drug dealer — Blockstack eventually makes you want to do the harder shit. You know, because it feels good. What did I want? I wanted https://onename.com/danvk to show a profile just like mine. Why did I want it? Because my parents didn’t love me enough. Classic.
Blockstack overview
Before we get the the hard shit, a quick overview of how Blockstack links registered names to profiles should help. I was totally lost after registering my name, so I went to their whitepaper to clarify. This picture maps out all you need to understand:
Blockstack registers names (like danvk.id) on the Bitcoin blockchain. Since the chain is public, everyone can verify ownership of a name. The registration includes a hash of a file, called a zone file. You control what the zone file says, e.g. “you can find my profile hosted at this address on IPFS”. All of this information is protected with public/private keypairs. If you lose the keypair, then you lose ownership of the name, because you can no longer update the registry on the Bitcoin blockchain.
When you use the CLI to register a name, like danvk.id, you must pay approximately .002 bitcoin to a Blockstack address. As long as you followed the Blockstack protocol, the network confirms your transaction and you owne whatever name you requested in the output script of the transaction. Here’s my danvk.id transaction on the Bitcoin blockchain. The script includes your public key and a hash of your zone file. Together, this triplet (name, public key, hash(zone file)) is your registry of property on the Blockstack network. All you had to do is burn 200,000 satoshis forever!
This zone file acts just like DNS: you control it, and you make it point to the internet address of whatever danvk.id wants you to see. As long as I control the private key that matches the public key associated with danvk.id, I can update the contents of the zone file. In this case, I need it to point to a simple JSON blob with my cousin’s info. I decided to upload the JSON blob to IPFS, but you can use any carrier you want as long as the URL is publicly available. The map above shows Dropbox, GitHub, Amazon S3 as potential places to host your JSON blob.
Ok, on to the hard part. The steps are as follows:
- Install the CLI and register your ID. I’m assuming you got this far.
- Create the profile according to a specific JSON schema and sign it
- Upload the profile to a public service (like IPFS)
- Update the zone file with the URL of the public profile
2. Create and sign the profile
You can create a JSON profile and sign it with blockstack sign_profile. This signs the file with your ‘data private key’. When you set up the Blockstack CLI, 3 private/public keypairs are generated: owner, payment, data. When you register identities, the CLI pays with your ‘payment’ keypair, but registers ownership with your ‘owner’ keypair. Finally, any data that you want to attest to as yours, you must sign with your ‘data’ keypair. Run blockstack wallet to check this out — here’s mine:
Good thing is, you don’t need to know any of this, just use the sign_profile comand(although in a previous version of this post I did things the hard way, copy-pasting my data private key into a script). See the output below for how I created the signed version of danvk.id's profile. I use python -m json.tool for pretty-printing the JSON — feel free to leave that part out.
Once you have the signed profile, you can make sure it decrypts successfully by running blockstack verify_profile danvk.id /tmp/danvk.signed.json. That should output the JSON that you sent in.
3. Upload the file
I chose IPFS to host. Other options include uploading the file to GitHub as a gist. Or any other platform with public file hosting.
Simple instructions for IPFS:
- download the distro (I was amd64+darwin since I’m on a Mac)
- follow the install instructions
- run the ipfs daemon, add the file to IPFS, and get the URL
~ % ipfs add /tmp/danvk.signed.json
added QmQJJokN8cwVg7gMLB6p6ztTbj6Twe3sQmeAehCEUwHpwo danvk.signed.json4. Update your Zone File
Armed with the URL to the signed profile, we can use the CLI to update the zone file for danvk.id. When you register a name with the CLI, you get a default zone file. Run blockstack lookup <name>.id to find yours. Mine was
{...
"zonefile": "$ORIGIN danvk.id\n$TTL 3600\npubkey TXT \"pubkey:data:0243a3ff5442367e3efd3d81a9fd9366bb3d0315ceb4e417bdc0c0c27bb30379b7\"\n_file URI 10 1 \"file:///Users/dougvk/.blockstack/storage-disk/ mutable/danvk.id\"\n_https._tcp URI 10 1 \"https://www.dropbox.com/blockstack/danvk.id\"\n_https._tcp URI 10 1 \"https://blockstack-server-profiles.s3.amazonaws.com/danvk.id\"\n_https._tcp URI 10 1 \"http s://blockstack.s3.amazonaws.com/danvk.id\"\n_dht._udp URI 10 1 \"dht+udp://2c69d1ef889dd918c91aee95ce6bee152f9b9834\"\n"...}
After removing all the escapes and replacing\n's with newlines, you should have something that looks like this, after making sure to change yours to suit your name and URL from the previous step. I saved mine as /tmp/danvk.zonefile:
Finally, use the blockstack update command to update your zonefile. This costs some bitcoin to get the transaction on the Bitcoin blockchain. The process should look like this (make sure to select option G):
Use the transaction hash to keep track of the update (or blockstack info). After waiting ~60 minutes or for 6 confirmations, you should have your new profile ready and raring to go! Here’s danvk.id. You can also use blockstack lookup danvk.id to show your new profile!
Below are the URLs I used to cobble together an End-to-end understanding of Blockstack. Especially useful was reading their whitepaper. My highlights and annotations are below, hosted by Evernote.
References
https://forum.blockstack.org/t/generating-a-profile-json/527/2
https://forum.blockstack.org/t/zone-file-contents-and-blockstack-update-command/616
