OneName

The decentralized identity system built on Bitcoin.

Table of Contents

Introduction
Profile Explorers
Viewing Profiles
Registering Users
Usernames
Profiles
Verification
Key-value Entries

Viewing profiles on a profile explorer

The URL pattern for viewing a profile on a profile explorer:

someonenameexplorer.com/<username>

The URL pattern for viewing a profile as raw JSON data:

someonenameexplorer.com/<username>.json

Current profile explorers

• onename.io

Usernames on Namecoin

Namecoin's key-value store has several namespaces. By convention, key entries that start with "d/" are interpreted as domain names. Likewise, those that start with "u/" are interpreted as OneName usernames.

When registering a username on Namecoin, prepend "u/" to the username and use that as your key in the key-value entry.

Regex: ^u/[a-z0-9_]{1,60}$

Example:

Username: someuser
Key: u/someuser

Full instructions for registering usernames on Namecoin can be found below.

Profile Format v0.2

Sample profile

{
    "name": { "formatted": "John Smith" },
    "avatar": { "url": "http://example.com/avatar.jpg" },
    "cover": { "url": "http://example.com/cover.jpg" },
    "location": { "formatted": "New York, NY" },
    "website": "http://example.com",
    "bio": "Just a guy with his head in the cloud.",
    "github": { "username": "someuser" },
    "facebook": { "username": "someuser" },
    "twitter": { "username": "someuser" },
    "linkedin": { "url": "http://www.linkedin.com/in/someuser" },
    "bitcoin": { "address": "1JwSSubhmg6iPtRjtyqhUYYH7bZg3Lfy1T" },
    "bitmessage": { "address": "BM-orkCbppXWSqPpAxnz6jnfTZ2djb5pJKDb" },
    "bitcoinotc": { "username": "someuser" },
    "pgp": {
        "fingerprint": "D34987E8FAD4AE18C8680B4604DE396333BDC0E1",
        "url": "https://s3.amazonaws.com/97p/pubkey.txt"
    },
    "orgs": [
        { "name": "Big Corp", "relationship": "Software Engineer", "url": "http://bigcorp.com" },
        { "url": "http://mypersonalblog.com" }
    ],
    "v": "0.2"
}

Linking an account on a social network or other service

For a OneName profile to be verified by a given account, the profile must reference that account in it's data and the account must also have a post that references the profile. This shows that the owners of each account are in fact the same person.

For example, to prove that you own both your OneName profile and your twitter account, you would tweet out a reference to your OneName profile and then include the URL to that tweet in your OneName profile data.

Steps required

1. Create a post (tweet, gist, facebook post, etc.) with a message that explicitly states that you are the owner of your OneName username.
2. Reference the post in your profile data, providing either the post's URL or an identifier that is globally unique on that website.

Message format

Messages must contain #verifymyonename and +<username>. Neither of these are case sensitive.

Sample posts:

1. #verifymyonename +someuser
2. I am +someuser on OneName #verifymyonename
3. I am +someuser on OneName #VerifyMyOneName

Linking a website/organization

For a OneName profile to be verified by a given website/organization, the profile must reference that site in it's data and the site must also include the profile in the list of users that it vouches for. This shows that the owner of the website/organization professes that the OneName user is indeed a part of the organization.

Steps required

1. Create a JSON file called onename.json and place it in the root directory of your website. List all the users that you would like to have that domain vouch for.
2. Make sure all of the users reference the site in the "orgs" section of their profile data.

onename.json file format

{
    "users": [
        { "username": "user1" },
        { "username": "user2" },
        { "username": "user3" }
    ]
}

This file is the equivalent of the domain vouching for the users listed.

Notes

1. Using the root directory is necessary to prevent false ownership on websites that allow users to upload files to their servers. It also provides a standard location for OneName crawlers to look.
2. Any proof you provide must be publicly and perpetually available. If you ever delete a post that provides proof of ownership of your OneName profile, that account will lose it's verified status.
3. Verification is a two-way process. That is, in order to be verified by a particular domain or account on a social network, two things must happen: (1) the account/site must reference/vouch for your OneName account (2) your OneName account must reference the account/site.

Services/Sites Currently Supported by Profile Explorers

• github
• facebook
• twitter
• linkedin
• instagram
• bitmessage
• bitcointalk
• bitcoinotc
• dribbble
• foursquare
• pinterest
• behance
• skype
• stackoverflow
• stackexchange
• googleplus
• flickr
• email

Registering username/profile pairs as key-value entries in Namecoin

You'll need either a desktop Namecoin client (Namecoin-Qt) or a UNIX Namecoin daemon. Instructions for building namecoind from source are here. Once you have a running version of either Namecoin-Qt or namecoind you will need to buy some namecoins (from exchanges like Kraken or BTC-e) and send them to yourself. Now you're ready to register new names:

1. issue a "name new" with the key (the username with "u/" prepended)
2. issue a "name first update" with the chunked profile

"Name new" operations

The "name new" operation is the first operation required to register a key-value pair on Namecoin (and by extension, a username/profile pair in accordance with the OneName protocol). This is the operation that communicates intent to register and use a given name. Without "name first update," however, the name registration is not complete.

Current cost: 0.01 NMC

"Name first update" operations

After the "name new" operation is complete, the "name first update" operation completes the name registration.

Current cost: 0.00 NMC

Chunking profiles

Key-value entries in Namecoin are limited to a maximum of 519 bytes.

As a result, profiles exceeding 519 bytes must be split into several linked components in order to be embedded in the blockchain.

To chunk a JSON object, simply do the following:

1. check if all the remaining data fits in one chunk
2. if not, choose an unregistered Namecoin key (e.g. "i/username-1" - this will be the key of the "next" chunk) and create an empty JSON object (the current chunk), then add a pointer from this chunk to the next one (e.g. "next": "i/username-1")
3. fill the JSON object with as many properties as possible
4. go back to 1

Note: we recommend not using the "u/" namespace for linked chunks.

Example:

The sample profile above could be chunked as follows:

"u/username"

{
    "next": "i/username-1"
    "name": { "formatted": "John Smith" },
    "location": { "formatted": "New York, NY" },
    "website": "http://example.com",
    "github": { "username": "someuser" },
    "facebook": { "username": "someuser" },
    "twitter": { "username": "someuser" },
    "bitcoin": { "address": "1JwSSubhmg6iPtRjtyqhUYYH7bZg3Lfy1T" },
    "bitmessage": { "address": "BM-orkCbppXWSqPpAxnz6jnfTZ2djb5pJKDb" },
    "pgp": {
        "fingerprint": "D34987E8FAD4AE18C8680B4604DE396333BDC0E1",
        "url": "https://s3.amazonaws.com/97p/pubkey.txt"
    },
    "v": "0.2",
}

"i/username-1"

{
    "avatar": { "url": "http://example.com/avatar.jpg" },
    "cover": { "url": "http://example.com/cover.jpg" },
    "bio": "Just a guy with his head in the cloud.",
    "linkedin": { "url": "http://www.linkedin.com/in/someuser" },
    "bitcoinotc": { "username": "someuser" },
    "orgs": [
        { "name": "Big Corp", "relationship": "Software Engineer", "url": "http://bigcorp.com" },
        { "url": "http://mypersonalblog.com" }
    ]
}