lukechilds
/
docs
mirror of https://github.com/lukechilds/docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

docs: clean out BNS Stacks v1 content, replace with updated BNS overview

build/deps-updates
Aaron Blankstein 4 years ago
committed by Aaron Blankstein
parent
b4f95d7f77
commit
56a94586af
13 changed files with 298 additions and 1809 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 75
      src/pages/naming-services/architecture.md
  2. 168
      src/pages/naming-services/choose-name.md
  3. 114
      src/pages/naming-services/comparison.md
  4. 110
      src/pages/naming-services/create-namespace.md
  5. 100
      src/pages/naming-services/did.md
  6. 127
      src/pages/naming-services/forks.md
  7. 103
      src/pages/naming-services/manage-names.md
  8. 80
      src/pages/naming-services/namespaces.md
  9. 331
      src/pages/naming-services/overview.md
  10. 104
      src/pages/naming-services/register-name.md
  11. 248
      src/pages/naming-services/resolve-name.md
  12. 307
      src/pages/naming-services/subdomains-tutorial.md
  13. 240
      src/pages/naming-services/subdomains.md

75
src/pages/naming-services/architecture.md
View File

@ -1,75 +0,0 @@
---
title: Blockstack naming service (BNS)
description: The BNS node is the heart of the system. It is responsible for building up and replicating global name state.
---
## Understand the Architecture
The BNS node is the heart of the system. It is responsible for building up
and replicating global name state.
There are three parts to BNS that developers should be aware of. They are:
- **[The BNS indexer](https://github.com/blockstack/blockstack-search-indexer)**. This module crawls the blockchain and builds
up its name database. BNS indexers do not contain any private or sensitive
state, and can be deployed publicly. We maintain a fleet of them at
`https://node.blockstack.org:6263` for developers to use to get started.
- **The BNS API**. This module gives
developers a _stable RESTful API_ for interacting with the BNS network.
We provide one for developers to experiment with at `https://core.blockstack.org`.
- **BNS clients**. These communicate with the BNS API module in order to
resolve names. Internally, they generate and send transactions to register
and modify names.
The [BNS indexer](https://github.com/blockstack/blockstack-search-indexer) and BNS API comprise the **BNS node**. An architectural schematic appears below.
```
+-------------------------------------------------------+
RESTful | +----------------+ +--------------------+ |
+--------+ API | | | private API | | |
| client |<------------>| BNS API module |<----------->| BNS indexer module | |
+--------+ | | | | | |
| | +----------------+ | +----------------+ | |
| | | | name database | | |
| | | +----------------+ | |
| | +--------------------+ |
| | BNS node ^ |
| +------------------------------------------|------------+
| |
| v
| blockchain transactions +--------------------+
+------------------------------------------------->| blockchain peer |
+--------------------+
```
The above diagram depicts the BNS architecture. Clients talk to the BNS API module to resolve names, and generate and send blockchain transactions to register and modify names. The API module talks to the indexer module and gives clients a stable, Web-accessible interface for resolving names. The indexer module reads the blockchain via a blockchain peer, over the blockchain's peer network.
Stacks Blockchain currently implements the API module and indexer module as separate
daemons (`blockstack api` and `blockstack-core`, respectively). However, this
is an implementation detail, and may change in the future.
The [BNS indexer](https://github.com/blockstack/blockstack-search-indexer) implements the blockchain consensus rules and network protocols.
Its main responsibility is to build up and replicate all of the name state. It does
not have any public APIs of its own.
The BNS API modules allows users and developers to resolve names via a RESTful
interface. Resolution can be done with vanilla `curl` or `wget`.
BNS applications should use the BNS API module for name resolution.
They should not attempt to talk to a BNS indexer directly, because its API is not stable and is not meant
for consumption by any other process except for the API module.
Registering and managing names require generating and sending blockchain
transactions, which requires running a BNS client.
- The [Stacks CLI](https://www.npmjs.com/package/@stacks/cli) gives developers low-level
control over resolving, registering, and managing names.
Developers who want to make their own client programs that do not use
the reference client library code should read the
[BNS transaction wire format](/core/wire-format) document for generating and
sending their own transactions.
The examples in this document focus on resolving names using `curl`. We refer
the reader to client-specific documentation for registering and managing names.

168
src/pages/naming-services/choose-name.md
View File

@ -1,168 +0,0 @@
---
title: Choose a name
description: This section explains how to choose and create a namespace.
---
## Intended uses for a namespace
The intention is that each application can create its own BNS
namespace for its own purposes. Applications can use namespaces for things like:
- Giving users a SSO system, where each user registers their public key under a
username. Blockstack applications do this with names in the `.id` namespace,
for example.
- Providing a subscription service, where each name is a 3rd party that provides
a service for users to subscribe to. For example, names in
`.podcast` point to podcasts that users of the [DotPodcast](https://dotpodcast.co) app can subscribe to.
- Implementing software licenses, where each name corresponds to an access key.
Unlike conventional access keys, access keys implemented as names
can be sold and traded independently. The licensing fee (paid as a name
registration) would be set by the developer and sent to a developer-controlled
blockchain address.
Names within a namespace can serve any purpose the developer wants. The ability
to collect registration fees for 1 year after creating the namespace not only
gives developers the incentive to get users to participate in the app, but also
gives them a way to measure economic activity.
Developers can query individual namespaces and look up names within them using
the BNS API.
## List all namespaces in existence
See [reference](https://core.blockstack.org/#namespace-operations-get-all-namespaces).
```bash
$ curl https://core.blockstack.org/v1/namespaces
[
"id",
"helloworld",
"podcast"
]
```
## List all names within a namespace
See [reference](https://core.blockstack.org/#namespace-operations-get-all-namespaces).
```bash
$ curl https://core.blockstack.org/v1/namespaces/id/names?page=0
[
"0.id",
"0000.id",
"000000.id",
"000001.id",
"00000111111.id",
"000002.id",
"000007.id",
"0011sro.id",
"007_007.id",
"00n3w5.id",
"00r4zr.id",
"00w1k1.id",
"0101010.id",
"01jack.id",
"06nenglish.id",
"08.id",
"0cool_f.id",
"0dadj1an.id",
"0nelove.id",
"0nename.id"
...
]
```
Each page returns a batch of 100 names.
## Get the Cost to Register a Namespace
See [reference](https://core.blockstack.org/#price-checks-get-namespace-price).
```bash
$ curl https://core.blockstack.org/v1/prices/namespaces/test
{
"satoshis": 40000000
}
```
If you want to register a namespace, please see the [namespace creation section](/core/naming/namespaces).
## Getting the Current Consensus Hash
See [https://core.blockstack.org/#blockchain-operations-get-consensus-hash](reference).
```bash
$ curl -sL https://core.blockstack.org/v1/blockchains/bitcoin/consensus
{
"consensus_hash": "98adf31989bd937576aa190cc9f5fa3a"
}
```
A recent consensus hash is required to create a `NAMESPACE_PREORDER` transaction. The reference
BNS clients do this automatically. See the [transaction format](/core/wire-format)
document for details on how the consensus hash is used to construct the transaction.
## Create a namespace
### There are four steps to creating a namespace:
#### Step 1: Send a `NAMESPACE_PREORDER` transaction
This is the first step. This registers the _salted hash_ of the namespace with BNS nodes, and burns the
requisite amount of cryptocurrency. In addition, it proves to the BNS nodes that user has honored the
BNS consensus rules by including a recent _consensus hash_ in the transaction (see the section on
[BNS forks](#bns-forks) for details).
-> See `NAMESPACE_PREORDER` ([live example](https://www.blocktrail.com/BTC/tx/5f00b8e609821edd6f3369ee4ee86e03ea34b890e242236cdb66ef6c9c6a1b28)).
#### Step 2: Send a `NAMESPACE_REVEAL` transaction
This is the second step. This reveals the salt and the namespace ID (pairing it with its
`NAMESPACE_PREORDER`), it reveals how long names last in this namespace before
they expire or must be renewed, and it sets a _price function_ for the namespace
that determines how cheap or expensive names its will be. The price function takes
a name in this namespace as input, and outputs the amount of cryptocurrency the
name will cost (i.e. by examining how long the name is, and whether or not it
has any vowels or non-alphabet characters). The namespace creator
has the option to collect name registration fees for the first year of the
namespace's existence by setting a _namespace creator address_.
-> See `NAMESPACE_REVEAL` ([live example](https://www.blocktrail.com/BTC/tx/ab54b1c1dd5332dc86b24ca2f88b8ca0068485edf0c322416d104c5b84133a32)).
#### Step 3: Seed the namespace with `NAME_IMPORT` transactions
Once the namespace has been revealed, the user has the option to populate it with a set of
names. Each imported name is given both an owner and some off-chain state.
This step is optional---namespace creators are not required to import names.
-> See `NAME_IMPORT` ([live example](https://www.blocktrail.com/BTC/tx/c698ac4b4a61c90b2c93dababde867dea359f971e2efcf415c37c9a4d9c4f312)).
#### Step 4: Send a `NAMESPACE_READY` transaction
This is the final step of the process. It _launches_ the namespace, which makes it available to the
public. Once a namespace is ready, anyone can register a name in it if they
pay the appropriate amount of cryptocurrency (according to the price funtion
revealed in step 2).
-> See `NAMESPACE_READY` ([live example](https://www.blocktrail.com/BTC/tx/2bf9a97e3081886f96c4def36d99a677059fafdbd6bdb6d626c0608a1e286032)).
The reason for the `NAMESPACE_PREORDER/NAMESPACE_REVEAL` pairing is to prevent
frontrunning. The BNS consensus rules require a `NAMESPACE_REVEAL` to be
paired with a previous `NAMESPACE_PREORDER` sent within the past 24 hours.
If it did not do this, then a malicious actor could watch the blockchain network
and race a victim to claim a namespace.
Namespaces are created on a first-come first-serve basis. If two people try to
create the same namespace, the one that successfully confirms both the
`NAMESPACE_PREORDER` and `NAMESPACE_REVEAL` wins. The fee burned in the
`NAMESPACE_PREORDER` is spent either way.
Once the user issues the `NAMESPACE_PREORDER` and `NAMESPACE_REVEAL`, they have
1 year before they must send the `NAMESPACE_READY` transaction. If they do not
do this, then the namespace they created disappears (along with all the names
they imported).
Developers wanting to create their own namespaces should read the [namespace creation section](/core/naming/namespaces) document. It is highly recommended that
developers request individual support before creating their own space, given the large amount of
cryptocurrency at stake.

114
src/pages/naming-services/comparison.md
View File

@ -1,114 +0,0 @@
---
title: Feature comparison
description: This page describes some other naming systems in comparison to Blockstack.
---
## Introduction
BNS is not the only naming system in wide-spread use, nor is it the only
decentralized naming system that implements human-readable, globally-unique, and
strongly-owned names. This page describes some other naming systems in
comparison to Blockstack:
## Blockstack vs DNS
Blockstack and DNS both implement naming systems, but in fundamentally
different ways. Blockstack _can be used_ for resolving host names to IP
addresses, but this is not its default use-case. The [Blockstack Naming
Service](/core/naming/introduction) (BNS) instead behaves
more like a decentralized
[LDAP](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol) system for
resolving user names to user data.
While DNS and BNS handle different problems, they share some terminology and
serialization formats. However, it is important to recognize that this is the
_only_ thing they have in common---BNS has fundamentally different semantics
than DNS:
- **Zone files**: Blockstack stores a DNS zone file for each name. However,
the semantics of a BNS zone file are nothing like the semantics of a DNS zone
file---the only thing they have in common is their format.
A "standard" Blockstack zone files only have `URI` and `TXT` resource records
that point to the user's application data. Moreover, a Blockstack ID has a
_history_ of zone files, and historic zone files can alter the way in which a
Blockstack ID gets resolved (DNS has no such concept). It is conceivable that an advanced
user could add `A` and `AAAA` records to their Blockstack ID's zone file,
but these are not honored by any Blockstack software at this time.
- **Subdomains**: Blockstack has the concept of a subdomain, but it is
semantically very different from a DNS subdomain. In Blockstack, a subdomain
is a Blockstack ID whose state and transaction history are anchored to the
blockchain, but stored within an on-chain Blockstack ID's zone file history.
Unlike DNS subdomains, a BNS subdomain has
its own owner and is a first-class BNS name---all subdomains are resolvable,
and only the subdomain's owner can update the subdomain's records. The only thing BNS subdomains and DNS
subdomains have in common is the name format (e.g. `foo.bar.baz` is a subdomain
of `bar.baz` in both DNS and BNS).
More details can be found in the [Blockstack vs
DNS](/core/naming/comparison) document. A feature
comparison can be found at the end of the [Blockstack Naming
Service](/core/naming/introduction) document.
## Blockstack vs Namecoin
Namecoin also implements a decentralized naming service on top of a blockchain,
just like BNS. In fact, early versions of Blockstack were built on Namecoin.
However, [it was discovered](https://www.usenix.org/node/196209) that Namecoin's
merged mining with Bitcoin regularly placed it under the _de facto_ control of a single
miner. This prompted a re-architecting of the system to be _portable_ across
blockchains, so that if Blockstack's underlying blockchain (currently Bitcoin)
ever became insecure, the system could migrate to a more secure blockchain.
A feature comparison can be found at the end of the [Blockstack Naming
Service](/core/naming/introduction) document.
## Blockstack vs ENS
ENS also implements a decentralized naming system on top of a blockchain, but as
a smart contract on Ethereum. Like BNS, ENS is geared towards resolving names
to off-chain state (ENS names resolve to a hash, for example). Moreover, ENS is
geared towards providing programmatic control over names with Turing-complete
on-chain resolvers.
BNS has a fundamentally different relationship with blockchains than ENS.
Whereas ENS tries to use on-chain logic as much as possible, BNS
tries to use the blockchain as little as possible. BNS only uses it to store a
database log for name operations (which are interpreted with an off-chain BNS
node like Stacks Blockchain). BNS name state and BNS subdomains reside entirely
off-chain in the Atlas network. This has allowed BNS to migrate from blockchain
to blockchain in order to survive individual blockchain failures, and this has
allowed BNS developers to upgrade its consensus rules without having to get the
blockchain's permission (see the [virtualchain
paper](https://blockstack.org/virtualchain.pdf) for details).
## Summary feature comparison
The following feature table provides a quick summary how BNS differs from other naming systems
| Feature | BNS | [ENS](https://ens.domains/) | DNS | [Namecoin](https://namecoin.org/) |
| ---------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------- | ------- | --------------------------------- |
| Globally unique names | X | X | X | X |
| Human-readable names | X | X | X | X |
| Strongly-owned names | X | X | | X |
| Names are enumerable | X | | | X |
| Registration times | 1-2 hours | ~1 week | ~1 day | 1-2 hours |
| Subdomain registration times | 1 hour (instant with [#750](https://github.com/blockstack/blockstack-core/issues/750)) | varies | instant | ~1 hour |
| Anyone can make a TLD/namespace | X | [1] | | [1] |
| TLD/Namespace owners get registration fees | X | | X | |
| TLD/Namespace can be seeded with initial names | X | | X | |
| Portable across blockchains | X | | N/A | |
| Off-chain names | X | | N/A | |
| Off-chain name state | X | X | N/A | |
| Name provenance | X | X | | X |
| [DID](http://identity.foundation) support | X | | | |
| Turing-complete namespace rules | | X | X | |
| Miners are rewarded for participating | [1] | | N/A | X |
[1] Requires support in higher-level applications. These systems are not aware
of the existence of namespaces/TLDs at the protocol level.
[2] Stacks Blockchain destroys the underlying blockchain token to pay for
registration fees when there is no pay-to-namespace-creator address set in the
name's namespace. This has the effect of making the blockchain miners' holdings
slightly more valuable.

110
src/pages/naming-services/create-namespace.md
View File

@ -1,110 +0,0 @@
---
title: Creating a Namespace
description: Learn how to create a namespace in the Blockstack Naming Service.
---
## Introduction
Making a namespace is very expensive. Given the large amount of cryptocurrency at stake in name creation, developers
wanting to create their own namespaces should read [Understand Namespaces](/core/naming/namespaces) first. You should
also read this document thoroughly before creating a namespace.
## Creation process
There are four steps to creating a namespace.
### Step 1. Send a `NAMESPACE_PREORDER` transaction
This step registers the _salted hash_ of the namespace with BNS nodes, and burns the requisite amount of cryptocurrency.
Additionally, this step proves to the BNS nodes that user has honored the BNS consensus rules by including a recent
_consensus hash_ in the transaction (see the section on [BNS forks](#bns-forks) for details).
### Step 2. Send a `NAMESPACE_REVEAL` transaction
This second step reveals the salt and the namespace ID (pairing it with its
`NAMESPACE_PREORDER`). It reveals how long names last in this namespace before
they expire or must be renewed, and it sets a _price function_ for the namespace
that determines how cheap or expensive names its will be.
The price function takes a name in this namespace as input, and outputs the amount of cryptocurrency the name will cost.
The function does this by examining how long the name is, and whether or not it has any vowels or non-alphabet characters.
The namespace creator has the option to collect name registration fees for the first year of the namespace's existence by
setting a _namespace creator address_.
### Step 3. Seed the namespace with `NAME_IMPORT` transactions
Once a namespace is revealed, the user has the option to populate it with a set of
names. Each imported name is given both an owner and some off-chain state.
This step is optional; Namespace creators are not required to import names.
### Step 4. Send a `NAMESPACE_READY` transaction
The final step of the process _launches_ the namespace and makes the namespace available to the
public. Once a namespace is launched, anyone can register a name in it if they
pay the appropriate amount of cryptocurrency. Again, the appropriate amount is according to the price function
revealed in step 2.
## Consensus rules and competition for namespaces
Namespaces are created on a first-come first-serve basis. The BNS consensus rules require a `NAMESPACE_REVEAL` to be
paired with a previous `NAMESPACE_PREORDER` sent within the past 24 hours. If two people try to create the same namespace,
the one that successfully confirms both the `NAMESPACE_PREORDER` and `NAMESPACE_REVEAL` wins. The fee burned in the
`NAMESPACE_PREORDER` is spent either way.
Once a user issues the `NAMESPACE_PREORDER` and `NAMESPACE_REVEAL`, they have 1 year before they must send the `NAMESPACE_READY`
transaction. If they do not do this, then the namespace they created disappears (along with all the names they imported).
Pairing the `NAMESPACE_PREORDER` and `NAMESPACE_REVEAL` steps is designed to prevent frontrunning. Frontrunning is a
practice where name registrar uses insider information to register domains for the purpose of re-selling them or earning
revenue from them. By registering the domains, the registrar locks out other potential registrars. Thus, through this
pairing, a malicious actor cannot watch the blockchain network and race a victim to claim a namespace.
## Explore the namespace creation history
If you would like to navigate a namespace history, you can. To do this, do the following:
1. Query a Stacks Blockchain server for a particular name.
The format to query the Stacks Blockchain server is:
`https://core.blockstack.org/v1/namespaces/NAMESPACE`
For example, the `https://core.blockstack.org/v1/namespaces/id` query returns this transaction history:
```json
{
"address": "1KdDvp1DJ4EYUZc8savutRN4vv1ZwvGfQf",
"base": 4,
"block_number": 373601,
"buckets": "[6, 5, 4, 3, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]",
"coeff": 250,
"history": {
"373601": [
{
"address": "1KdDvp1DJ4EYUZc8savutRN4vv1ZwvGfQf",
"block_number": 373601,
"burn_address": "1111111111111111111114oLvT2",
"consensus_hash": "17ac43c1d8549c3181b200f1bf97eb7d",
"op": "*",
"op_fee": 4000000000,
"opcode": "NAMESPACE_PREORDER",
"preorder_hash": "9f1ad5039dbdabc2d98a87486ae1c478f03cd564",
"sender": "76a914cc4c07c0ef988b7bae982ce1ece51615258a15e388ac",
"sender_pubkey": "047c7f6d1f71780ccd373a7d2a020a1aeb7d47639e86fe951f5ba23a9ca8d6f7cfb03ed7ca411b22fa5244b9998d27d9c7bf7f0603f1997d1c7b3dc5a9b342c554",
"token_fee": "0",
"token_units": "BTC",
"txid": "5f00b8e609821edd6f3369ee4ee86e03ea34b890e242236cdb66ef6c9c6a1b28",
"vtxindex": 178
}
]
}
}
```
2. Copy a `txid` (transaction id) from the json.
For example, the `NAMESPACE_PREORDER` in this case has a `txid` of `5f00b8e609821edd6f3369ee4ee86e03ea34b890e242236cdb66ef6c9c6a1b28`.
3. Provide the id in a query to a blockchain explorer such as [Blockchain.com](https://www.blockchain.com/) or similar.
For example, a search on Blockchain returns this [page of information](https://www.blockchain.com/btc/tx/5f00b8e609821edd6f3369ee4ee86e03ea34b890e242236cdb66ef6c9c6a1b28).

100
src/pages/naming-services/did.md
View File

@ -1,100 +0,0 @@
---
title: Decentralized Identifiers (DIDs)
description: BNS nodes are compliant with the emerging Decentralized Identity Foundation protocol specification for decentralized identifiers.
---
## Introduction
BNS nodes are compliant with the emerging
[Decentralized Identity Foundation](http://identity.foundation) protocol
specification for decentralized identifiers (DIDs).
Each name in BNS has an associated DID. The DID format for BNS is:
```bash
did:stack:v0:{address}-{index}
```
Where:
- `{address}` is an on-chain public key hash (e.g. a Bitcoin address).
- `{index}` refers to the `nth` name this address created.
For example, the DID for `personal.id` is
`did:stack:v0:1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV-0`, because the name
`personal.id` was the first-ever name created by
`1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV`.
As another example, the DID for `jude.id` is `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-1`.
Here, the address `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` had created one earlier
name in history prior to this one (which happens to be `abcdefgh123456.id`).
The purpose of a DID is to provide an eternal identifier for a public key.
The public key may change, but the DID will not.
Stacks Blockchain implements a DID method of its own
in order to be compatible with other systems that use DIDs for public key resolution.
In order for a DID to be resolvable, all of the following must be true for a
name:
- The name must exist
- The name's zone file hash must be the hash of a well-formed DNS zone file
- The DNS zone file must be present in the BNS [Atlas Network](/core/atlas/overview)
- The DNS zone file must contain a `URI` resource record that points to a signed
JSON Web Token
- The public key that signed the JSON Web Token (and is included with it) must
hash to the address that owns the name
Not all names will have DIDs that resolve to public keys. However, names created by the [Blockstack
Browser](https://github.com/blockstack/blockstack-browser) will have DIDs that
do.
Developers can programmatically resolve DIDs via the Python API:
```python
>>> import blockstack
>>> blockstack.lib.client.resolve_DID('did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-1', hostport='https://node.blockstack.org:6263')
{'public_key': '020fadbbcea0ff3b05f03195b41cd991d7a0af8bd38559943aec99cbdaf0b22cc8'}
```
A RESTful API is under development.
# DID Encoding for Subdomains
Every name and subdomain in BNS has a DID. The encoding is slightly different
for subdomains, so the software can determine which code-path to take.
- For on-chain BNS names, the `{address}` is the same as the Bitcoin address
that owns the name. Currently, both version byte 0 and version byte 5
addresses are supported (i.e. addresses starting with `1` or `3`, meaning `p2pkh` and
`p2sh` addresses).
- For off-chain BNS subdomains, the `{address}` has version byte 63 for
subdomains owned by a single private key, and version byte 50 for subdomains
owned by a m-of-n set of private keys. That is, subdomain DID addresses start
with `S` or `M`, respectively.
The `{index}` field for a subdomain's DID is distinct from the `{index}` field
for a BNS name's DID, even if the same created both names and subdomains.
For example, the name `abcdefgh123456.id` has the DID `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-0`,
because it was the first name created by `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg`.
However, `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` _also_ created `jude.statism.id`
as its first subdomain name. The DID for `jude.statism.id` is
`did:stack:v0:SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i-0`. Note that the address
`SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i` encodes the same public key hash as the address
`16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` (the only difference between these two
strings is that the first is base58check-encoded with version byte 0, and the
second is encoded with version byte 63).
You can see this play out in practice with the following code snippit:
```py
>>> import blockstack
>>> blockstack.lib.client.get_name_record('jude.statism.id', hostport='https://node.blockstack.org:6263')['address']
u'16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg'
>>> import virtualchain
>>> virtualchain.address_reencode('16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg', version_byte=63)
'SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i'
>>> blockstack.lib.client.resolve_DID('did:stack:v0:SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i-0', hostport='https://node.blockstack.org:6263')
{'public_key': '020fadbbcea0ff3b05f03195b41cd991d7a0af8bd38559943aec99cbdaf0b22cc8'}
```

127
src/pages/naming-services/forks.md
View File

@ -1,127 +0,0 @@
---
title: BNS forks
description: Learn about forks within the context of the BNS.
---
## Introduction
BNS effectively uses a public blockchain to store a database log. A BNS peer
bootstraps itself by downloading and replaying the database log from the
blockchain, and in doing so, will calculate the same name database state as
every other (honest) BNS peer that has the same view of the blockchain.
Crucially, BNS is built on top of a public blockchain that is _unaware_ of BNS's existence.
This means that the blockchain peers do not validate BNS transactions. Instead,
the BNS peer needs to do so, and must know how to _reject_ both invalid transactions
as well as well-formed transactions from dishonest peers (i.e. peers that do not
follow the same consensus rules).
BNS nodes do not directly communicate with one another--by design, the set of
BNS peers is not enumerable. The only shared communication medium between BNS
peers is the blockchain.
To identify and reject invalid and malicious transactions without the blockchain's help,
the log of name operations embedded in the blockchain is constructed as a
[fork\*-consistent](http://www.scs.stanford.edu/~jinyuan/bft2f.pdf) database
log. Fork\*-consistency is a [consistency
model](https://en.wikipedia.org/wiki/Consistency_model) whereby the state
replicas in all of the nodes exhibit the following properties:
- Each correct peer maintains a history of well-formed, valid state operations. In this
case, each correct BNS node maintains a copy of the history blockchain transactions
that encoded well-formed, valid name operations.
- Each honest peer's history contains the sequence of all operations that it
sent. That is, a user's BNS peer's transaction log will contain the sequence of all valid
transactions that the user's client wrote to the blockchain.
- If two peers accept operations _op_ and _op'_ from the same correct client,
then both of their logs will have the both operations in the same order. If
_op'_ was accepted before _op_, then both peers' logs are identical up to _op'_.
In BNS, this means that if two peers both accept a given transaction, then it
means that they have accepted the same sequence of prior transactions.
This means that unlike with blockchains,
there can be _multiple long-lived conflicting forks_ of the BNS database log.
However, due to fork\*-consistency, a correct BNS peer will only process _one_
of these forks, and will _ignore_ transactions from peers in other forks. In other words,
fork\*-consistency partitions the set of BNS peers into different **fork-sets**,
where all peers in a fork-set process each other's transactions, but the
completely ignore peers in other fork-sets.
BNS nodes identify which fork set they belong to using a **consensus hash**. The
consensus hash is a cryptographic digest of a node's operation
history. Each BNS peer calculates a new consensus hash each time it processes a
new block, and stores the history of consensus hashes for each block it
processed.
Two honest BNS peers can quickly determine if they are in the same fork-set by querying
each other's consensus hashes for a given block. If they match, then they are
in the same fork-set (assming no hash collisions).
A BNS client executes a name operation on a specific fork-set by including a
recent consensus hash from that fork-set in the blockchain transaction.
At the same time, the BNS consensus rules state that a transaction can only be
accepted if it included a recent valid consensus hash.
This means that all BNS nodes in the client's desired fork-set will accept
the transaction, and all other BNS nodes not in the fork-set will ignore it.
You can see where the consensus hash is included in blockchain transactions by reading
the [transaction wire format](/core/wire-format) document.
## Fork-set Selection
The blockchain linearizes the history of transactions, which means that
in general, there exists a fork-set for each distinct set of BNS
consensus rules. For example, the Stacks Blockchain [2016 hard fork](https://github.com/blockstack/blockstack-core/blob/master/release_notes/changelog-0.14.md)
and [2017 hard fork](https://github.com/blockstack/blockstack-core/blob/master/release_notes/changelog-0.17.md) both introduced new consensus
rules, which means at the time of this writing there are three possible fork-sets:
the pre-2016 fork-set, the 2016-2017 fork-set, and the post-2017 fork-set.
The [public BNS nodes](https://node.blockstack.org:6263) are always running
in the fork-set with the latest consensus rules.
BNS clients are incentivized to communicate with peers in the fork-set that has
the most use, since this fork-set's name database will encode name/state
bindings that are the most widely-accepted and understood by users.
To identify this fork-set, a BNS client needs to learn one of
its recent consensus hashes. Once it has a recent consensus hash, it can
query an _untrusted_ BNS node for a copy of
its name database, and use the consensus hash to verify that the name database
was used to generate it.
How does a BNS node determine whether or not a consensus hash corresponds to the
most widely-used fork-set? There are two strategies:
- Determine whether or not a _characteristic transaction_ was accepted by the
widely-used fork-set. If a client knows that a specific transaction belongs to
the widely-used fork-set and not others, then they can use the consensus hash to
efficiently determine whether or not a given node belongs to this fork-set.
- Determine how much "economic activity" exists in a fork-set by inspecting
the blockchain for burned cryptocurrency tokens. Namespace and name
registrations are structured in a way that sends cryptocurrency tokens to either
a well-known burn address, or to an easily-queried pay-to-namespace-creator
address.
Both strategies rely on the fact that the consensus hash is calculated as a
[Merkle skip-list](https://github.com/blockstack/blockstack-core/issues/146)
over the BNS node's accepted transactions. A client can use a consensus hash to
determine whether or not a transaction _T_ was accepted by a node with _O(log
n)_ time and space complexity. We call the protocol for resolving a consensus hash to a specific transaction
**Simplified Name Verification** (SNV). See our [paper on the subject](https://blockstack.org/virtualchain_dccl16.pdf)
for details of how SNV works under the hood.
If the client has a consensus hash and knows of a characteristic transaction in the widely-used fork-set,
it can use SNV to determine whether or not a node belongs to the fork-set that accepted it.
If the client knows about multiple conflicting consensus hashes,
they can still use SNV to determine which one corresponds
to the most-used fork-set. To do so, the client would use a
[blockchain explorer](https://explorer.blockstack.org) to find the
list of transactions that burned cryptocurrency tokens. Each of these
transactions will be treated as potential characteristic transactions:
the client would first select the subset of transactions that are well-formed
BNS transactions, and then use SNV to determine which of them correspond to which
consensus hashes. The client chooses the consensus hash that corresponds
to the fork-set with the highest cumulative burn.
Work is currently underway to automate this process.

103
src/pages/naming-services/manage-names.md
View File

@ -1,103 +0,0 @@
---
title: Manage BNS Names
description: This section teaches you how to manage your namespace.
---
## Overview of management
Once you register a BNS name, you have the power to change its zone file hash,
change its public key hash, destroy it (i.e. render it unresolvable),
or renew it. The BNS consensus rules ensure that _only_ you, as the owner of
the name's private key, have the ability to carry out these operations.
Each of these operations are executed by sending a specially-formatted
blockchain transaction to the blockchain, which BNS nodes read and process.
The operations are listed below:
| Transaction Type | Description |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NAME_UPDATE` | This changes the name's zone file hash. Any 20-byte string is allowed. |
| `NAME_TRANSFER` | This changes the name's public key hash. In addition, the current owner has the option to atomically clear the name's zone file hash (so the new owner won't "receive" the zone file). |
| `NAME_REVOKE` | This renders a name unresolvable. You should do this if your private key is compromised. |
| `NAME_RENEWAL` | This pushes back the name's expiration date (if it has one), and optionally both sets a new zone file hash and a new public key hash. |
The reference BNS clients---
[blockstack.js](https://github.com/blockstack/blockstack.js) and the [Blockstack
Browser](https://github.com/blockstack/blockstack-browser)---can handle creating
and sending all of these transactions for you.
## Transaction types
### NAME_UPDATE
See [live example](https://www.blocktrail.com/BTC/tx/e2029990fa75e9fc642f149dad196ac6b64b9c4a6db254f23a580b7508fc34d7).
A `NAME_UPDATE` transaction changes the name's zone file hash. You would send
one of these transactions if you wanted to change the name's zone file contents.
For example, you would do this if you want to deploy your own [Gaia
hub](https://github.com/blockstack/gaia) and want other people to read from it.
A `NAME_UPDATE` transaction is generated from the name, a recent [consensus
hash](#bns-forks), and the new zone file hash. The reference clients gather
this information automatically. See the [transaction format](/core/wire-format)
document for details on how to construct this transaction.
### NAME_TRANSFER
See [live example](https://www.blocktrail.com/BTC/tx/7a0a3bb7d39b89c3638abc369c85b5c028d0a55d7804ba1953ff19b0125f3c24).
A `NAME_TRANSFER` transaction changes the name's public key hash. You would
send one of these transactions if you wanted to:
- Change your private key
- Send the name to someone else
When transferring a name, you have the option to also clear the name's zone
file hash (i.e. set it to `null`).
This is useful for when you send the name to someone else, so the
recipient's name does not resolve to your zone file.
The `NAME_TRANSFER` transaction is generated from the name, a recent [consensus
hash](#bns-forks), and the new public key hash. The reference clients gather
this information automatically. See the [transaction format](/core/wire-format)
document for details on how to construct this transaction.
### NAME_REVOKE
See [live example](https://www.blocktrail.com/BTC/tx/eb2e84a45cf411e528185a98cd5fb45ed349843a83d39fd4dff2de47adad8c8f).
A `NAME_REVOKE` transaction makes a name unresolvable. The BNS consensus rules
stipulate that once a name is revoked, no one can change its public key hash or
its zone file hash. The name's zone file hash is set to `null` to prevent it
from resolving.
You should only do this if your private key is compromised, or if you want to
render your name unusable for whatever reason. It is rarely used in practice.
The `NAME_REVOKE` operation is generated using only the name. See the
[transaction format](/core/wire-format) document for details on how to construct
it.
### NAME_RENEWAL
See [live example](https://www.blocktrail.com/BTC/tx/e543211b18e5d29fd3de7c0242cb017115f6a22ad5c6d51cf39e2b87447b7e65).
Depending in the namespace rules, a name can expire. For example, names in the
`.id` namespace expire after 2 years. You need to send a `NAME_RENEWAL` every
so often to keep your name.
A `NAME_RENEWAL` costs both transaction fees and registration fees. You will
pay the registration cost of your name to the namespace's designated burn address when you
renew it. You can find this fee using the `/v1/prices/names/{name}` endpoint.
When a name expires, it enters a month-long "grace period" (5000 blocks). It
will stop resolving in the grace period, and all of the above operations will
cease to be honored by the BNS consensus rules. You may, however, send a
`NAME_RENEWAL` during this grace period to preserve your name.
If your name is in a namespace where names do not expire, then you never need to
use this transaction.
When you send a `NAME_RENEWAL`, you have the option of also setting a new public
key hash and a new zone file hash. See the [transaction format](/core/wire-format)
document for details on how to construct this transaction.

80
src/pages/naming-services/namespaces.md
View File

@ -1,80 +0,0 @@
---
title: Understand Namespaces
description: Namespaces are the top-level naming objects in BNS.
---
## Introduction
Namespaces are the top-level naming objects in BNS.
They control a few properties about the names within them:
- How expensive they are to register
- How long they last before they have to be renewed
- Who (if anyone) receives the name registration fees
- Who is allowed to seed the namespace with its initial names.
At the time of this writing, by far the largest BNS namespace is the `.id`
namespace. Names in the `.id` namespace are meant for resolving user
identities. Short names in `.id` are more expensive than long names, and have
to be renewed by their owners every two years. Name registration fees are not
paid to anyone in particular---they are instead sent to a "black hole" where
they are rendered unspendable (the intention is to discourage ID squatters).
Unlike DNS, _anyone_ can create a namespace and set its properties. Namespaces
are created on a first-come first-serve basis, and once created, they last
forever.
However, creating a namespace is not free. The namespace creator must _burn_
cryptocurrency to do so. The shorter the namespace, the more cryptocurrency
must be burned (i.e. short namespaces are more valuable than long namespaces).
For example, it cost Blockstack PBC 40 BTC to create the `.id` namespace in 2015
(in transaction
`5f00b8e609821edd6f3369ee4ee86e03ea34b890e242236cdb66ef6c9c6a1b281`).
Namespaces can be between 1 and 19 characters long, and are composed of the
characters `a-z`, `0-9`, `-`, and `_`.
## Namespace Organization
BNS names are organized into a global name hierarchy. There are three different
layers in this hierarchy related to naming:
- **Namespaces**. These are the top-level names in the hierarchy. An analogy
to BNS namespaces are DNS top-level domains. Existing BNS namespaces include
`.id`, `.podcast`, and `.helloworld`. All other names belong to exactly one
namespace. Anyone can create a namespace, but in order for the namespace
to be persisted, it must be _launched_ so that anyone can register names in it.
Namespaces are not owned by their creators.
- **BNS names**. These are names whose records are stored directly on the
blockchain. The ownership and state of these names are controlled by sending
blockchain transactions. Example names include `verified.podcast` and
`muneeb.id`. Anyone can create a BNS name, as long as the namespace that
contains it exists already. The state for BNS names is usually stored in the [Atlas
network](/core/atlas/overview).
- **BNS subdomains**. These are names whose records are stored off-chain,
but are collectively anchored to the blockchain. The ownership and state for
these names lives within the [Atlas network](/core/atlas/overview). While BNS
subdomains are owned by separate private keys, a BNS name owner must
broadcast their subdomain state. Example subdomains include `jude.personal.id`
and `podsaveamerica.verified.podcast`. Unlike BNS namespaces and names, the
state of BNS subdomains is _not_ part of the blockchain consensus rules.
A feature comparison matrix summarizing the similarities and differences
between these name objects is presented below:
| Feature | **Namespaces** | **BNS names** | **BNS Subdomains** |
| -------------------------------------- | -------------- | ------------- | ------------------ |
| Globally unique | X | X | X |
| Human-meaningful | X | X | X |
| Owned by a private key | | X | X |
| Anyone can create | X | X | [1] |
| Owner can update | | X | [1] |
| State hosted on-chain | X | X | |
| State hosted off-chain | | X | X |
| Behavior controlled by consensus rules | X | X | |
| May have an expiration date | | X | |
[1] Requires the cooperation of a BNS name owner to broadcast its transactions

331
src/pages/naming-services/overview.md
View File

@ -1,25 +1,15 @@
---
title: Overview
description: 'Blockstack naming service (BNS)'
description: 'Blockstack naming system (BNS)'
---
# Blockstack Naming Service (BNS)
# Blockstack Naming System (BNS)
This document gives an overview of how the Blockstack Naming Service work. This
section introduces you to BNS and explains the following concepts:
The ([Stacks Node](https://github.com/blockstack/blockstack-core))
repository is the reference implementation of the Blockstack Naming Service.
## What is BNS
The Blockstack Naming Service (BNS) is a network system that binds names
The Blockstack Naming System (BNS) is a network system that binds names
to off-chain state without relying on any central points of control.
It does so by embedding a log of its control-plane messages within a public blockchain, like Bitcoin.
Each BNS peer determines the state of each name by indexing these specially-crafted
transactions. In doing so, each peer independently calculates the same global
name state.
The Stacks V1 blockchain implemented BNS through first-order name operations.
In Stacks V2, BNS is instead implemented through a smart-contract loaded
during the genesis block.
Names in BNS have three properties:
@ -29,30 +19,24 @@ Names in BNS have three properties:
- **Names are strongly-owned.** Only the name's owner can change the state it
resolves to. Specifically, a name is owned by one or more ECDSA private keys.
Internally, a BNS node implements a replicated name database. Each BNS node keeps itself
synchronized to all of the other ones in the world, so queries on one BNS node
will be the same on other nodes. BNS nodes allow a name's owner to bind
up to 40Kb of off-chain state to their name, which will be replicated to all
BNS nodes via the [Atlas network](/core/atlas/overview).
BNS nodes extract the name database log from an underlying blockchain (Blockstack
Core currently uses Bitcoin, and had used Namecoin in the past).
BNS uses the blockchain to establish a shared "ground truth" for the system: as long as
two nodes have the same view of the blockchain, then they will build up the same
database.
The Stacks blockchain insures that each node's BNS view is
synchronized to all of the other nodes in the world, so queries on one
node will be the same on other nodes. Stacks blockchain nodes allow a
name's owner to bind up to 40Kb of off-chain state to their name,
which will be replicated to all other Stacks blockchain nodes via a P2P network.
The biggest consequence for developers is that in BNS, reading name state is
fast and cheap but writing name state is slow and expensive. This is because
registering and modifying names requires one or more transactions to be sent to
the underlying blockchain, and BNS nodes will not process them until they are
sufficiently confirmed. Users and developers need to acquire and spend
the requisite cryptocurrency (i.e. Bitcoin) to send BNS transactions.
the requisite cryptocurrency (STX) to send BNS transactions.
## Motivation behind naming services
## Motivation behind naming systems
We rely on naming systems in everyday life, and they play a critical
role in many different applications. For example, when you look up a
friend on social media, you are using the platform's naming service to resolve
friend on social media, you are using the platform's naming system to resolve
their name to their profile. When you look up a website, you are using the
Domain Name Service to
resolve the hostname to its host's IP address. When you check out a Git branch, you
@ -113,12 +97,11 @@ layers in this hierarchy related to naming:
blockchain. The ownership and state of these names are controlled by sending
blockchain transactions. Example names include `verified.podcast` and
`muneeb.id`. Anyone can create a BNS name, as long as the namespace that
contains it exists already. The state for BNS names is usually stored in the [Atlas
network](/core/atlas/overview).
contains it exists already.
- **BNS subdomains**. These are names whose records are stored off-chain,
but are collectively anchored to the blockchain. The ownership and state for
these names lives within the [Atlas network](/core/atlas/overview). While BNS
these names lives within the P2P network data. While BNS
subdomains are owned by separate private keys, a BNS name owner must
broadcast their subdomain state. Example subdomains include `jude.personal.id`
and `podsaveamerica.verified.podcast`. Unlike BNS namespaces and names, the
@ -140,3 +123,285 @@ between these name objects is presented below:
| May have an expiration date | | X | |
[1] Requires the cooperation of a BNS name owner to broadcast its transactions
## Namespaces
Namespaces are the top-level naming objects in BNS.
They control a few properties about the names within them:
- How expensive they are to register
- How long they last before they have to be renewed
- Who (if anyone) receives the name registration fees
- Who is allowed to seed the namespace with its initial names.
At the time of this writing, by far the largest BNS namespace is the `.id`
namespace. Names in the `.id` namespace are meant for resolving user
identities. Short names in `.id` are more expensive than long names, and have
to be renewed by their owners every two years. Name registration fees are not
paid to anyone in particular---they are instead sent to a "black hole" where
they are rendered unspendable (the intention is to discourage ID squatters).
Unlike DNS, _anyone_ can create a namespace and set its properties. Namespaces
are created on a first-come first-serve basis, and once created, they last
forever.
However, creating a namespace is not free. The namespace creator must _burn_
cryptocurrency to do so. The shorter the namespace, the more cryptocurrency
must be burned (i.e. short namespaces are more valuable than long namespaces).
For example, it cost Blockstack PBC 40 BTC to create the `.id` namespace in 2015
(in transaction
`5f00b8e609821edd6f3369ee4ee86e03ea34b890e242236cdb66ef6c9c6a1b281`).
Namespaces can be between 1 and 19 characters long, and are composed of the
characters `a-z`, `0-9`, `-`, and `_`.
## Subdomains
BNS names are strongly-owned because the owner of its private key can generate
valid transactions that update its zone file hash and owner. However, this comes at the
cost of requiring a name owner to pay for the underlying transaction in the
blockchain. Moreover, this approach limits the rate of BNS name registrations
and operations to the underlying blockchain's transaction bandwidth.
BNS overcomes this with subdomains. A **BNS subdomain** is a type of
BNS name whose state and owner are stored outside of the blockchain,
but whose existence and operation history are anchored to the
blockchain. Like their on-chain counterparts, subdomains are globally
unique, strongly-owned, and human-readable. BNS gives them their own
name state and public keys. Unlike on-chain names, subdomains can be
created and managed cheaply, because they are broadcast to the BNS
network in batches. A single blockchain transaction can send up to 120
subdomain operations.
This is achieved by storing subdomain records in the BNS name zone files.
An on-chain name owner broadcasts subdomain operations by encoding them as
`TXT` records within a DNS zone file. To broadcast the zone file,
the name owner sets the new zone file hash with a `NAME_UPDATE` transaction and
replicates the zone file. This, in turn, replicates all subdomain
operations it contains, and anchors the set of subdomain operations to
an on-chain transaction. The BNS node's consensus rules ensure that only
valid subdomain operations from _valid_ `NAME_UPDATE` transactions will ever be
stored.
For example, the name `verified.podcast` once wrote the zone file hash `247121450ca0e9af45e85a82e61cd525cd7ba023`,
which is the hash of the following zone file:
```bash
$TTL 3600
1yeardaily TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxeWVhcmRhaWx5CiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMXllYXJkYWlseS9oZWFkLmpzb24iCg=="
2dopequeens TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAyZG9wZXF1ZWVucwokVFRMIDM2MDAKX2h0dHAuX3RjcCBVUkkgMTAgMSAiaHR0cHM6Ly9waC5kb3Rwb2RjYXN0LmNvLzJkb3BlcXVlZW5zL2hlYWQuanNvbiIK"
10happier TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMGhhcHBpZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMGhhcHBpZXIvaGVhZC5qc29uIgo="
31thoughts TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMXRob3VnaHRzCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzF0aG91Z2h0cy9oZWFkLmpzb24iCg=="
359 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNTkKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8zNTkvaGVhZC5qc29uIgo="
30for30 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMGZvcjMwCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzBmb3IzMC9oZWFkLmpzb24iCg=="
onea TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiBvbmVhCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vb25lYS9oZWFkLmpzb24iCg=="
10minuteteacher TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMG1pbnV0ZXRlYWNoZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMG1pbnV0ZXRlYWNoZXIvaGVhZC5qc29uIgo="
36questionsthepodcastmusical TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNnF1ZXN0aW9uc3RoZXBvZGNhc3RtdXNpY2FsCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzZxdWVzdGlvbnN0aGVwb2RjYXN0bXVzaWNhbC9oZWFkLmpzb24iCg=="
_http._tcp URI 10 1 "https://dotpodcast.co/"
```
Each `TXT` record in this zone file encodes a subdomain-creation.
For example, `1yeardaily.verified.podcast` resolves to:
```json
{
"address": "1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH",
"blockchain": "bitcoin",
"last_txid": "d87a22ebab3455b7399bfef8a41791935f94bc97aee55967edd5a87f22cce339",
"status": "registered_subdomain",
"zonefile_hash": "e7acc97fd42c48ed94fd4d41f674eddbee5557e3",
"zonefile_txt": "$ORIGIN 1yeardaily\n$TTL 3600\n_http._tcp URI 10 1 \"https://ph.dotpodcast.co/1yeardaily/head.json\"\n"
}
```
This information was extracted from the `1yeardaily` `TXT` resource record in the zone
file for `verified.podcast`.
### Subdomain Lifecycle
Note that `1yeardaily.verified.podcast` has a different public key
hash (address) than `verified.podcast`. A BNS node will only process a
subsequent subdomain operation on `1yeardaily.verified.podcast` if it includes a
signature from this address's private key. `verified.podcast` cannot generate
updates; only the owner of `1yeardaily.verified.podcast can do so`.
The lifecycle of a subdomain and its operations is shown in Figure 2.
```
subdomain subdomain subdomain
creation update transfer
+----------------+ +----------------+ +----------------+
| cicero | | cicero | | cicero |
| owner="1Et..." | signed | owner="1Et..." | signed | owner="1cJ..." |
| zf0="7e4..." |<--------| zf0="111..." |<--------| zf0="111..." |<---- ...
| seqn=0 | | seqn=1 | | seqn=2 |
| | | sig="xxxx" | | sig="xxxx" |
+----------------+ +----------------+ +----------------+
| | |
| off-chain | |
~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~|~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ...
| on-chain | |
V V (zone file hash ) V
+----------------+ +----------------+ +----------------+
| res_publica.id | | jude.id | | res_publica.id |
| NAME_UPDATE |<--------| NAME_UPDATE |<--------| NAME_UPDATE |<---- ...
+----------------+ +----------------+ +----------------+
blockchain blockchain blockchain
block block block
Figure 2: Subdomain lifetime with respect to on-chain name operations. A new
subdomain operation will only be accepted if it has a later "sequence=" number,
and a valid signature in "sig=" over the transaction body. The "sig=" field
includes both the public key and signature, and the public key must hash to
the previous subdomain operation's "addr=" field.
The subdomain-creation and subdomain-transfer transactions for
"cicero.res_publica.id" are broadcast by the owner of "res_publica.id".
However, any on-chain name ("jude.id" in this case) can broadcast a subdomain
update for "cicero.res_publica.id".
```
Subdomain operations are ordered by sequence number, starting at 0. Each new
subdomain operation must include:
- The next sequence number
- The public key that hashes to the previous subdomain transaction's address
- A signature from the corresponding private key over the entire subdomain
operation.
If two correctly-signed but conflicting subdomain operations are discovered
(i.e. they have the same sequence number), the one that occurs earlier in the
blockchain's history is accepted. Invalid subdomain operations are ignored.
Combined, this ensures that a BNS node with all of the zone files with a given
subdomain's operations will be able to determine the valid sequence of
state-transitions it has undergone, and determine the current zone file and public
key hash for the subdomain.
### Subdomain Creation and Management
Unlike an on-chain name, a subdomain owner needs an on-chain name owner's help
to broadcast their subdomain operations. In particular:
- A subdomain-creation transaction can only be processed by the owner of the on-chain
name that shares its suffix. For example, only the owner of `res_publica.id`
can broadcast subdomain-creation transactions for subdomain names ending in
`.res_publica.id`.
- A subdomain-transfer transaction can only be broadcast by the owner of the
on-chain name that created it. For example, the owner of
`cicero.res_publica.id` needs the owner of `res_publica.id` to broadcast a
subdomain-transfer transaction to change `cicero.res_publica.id`'s public key.
- In order to send a subdomain-creation or subdomain-transfer, all
of an on-chain name owner's zone files must be present in the Atlas network.
This lets the BNS node prove the _absence_ of any conflicting subdomain-creation and
subdomain-transfer operations when processing new zone files.
- A subdomain update transaction can be broadcast by _any_ on-chain name owner,
but the subdomain owner needs to find one who will cooperate. For example,
the owner of `verified.podcast` can broadcast a subdomain-update transaction
created by the owner of `cicero.res_publica.id`.
That said, to create a subdomain, the subdomain owner generates a
subdomain-creation operation for their desired name
and gives it to the on-chain name owner.
Once created, a subdomain owner can use any on-chain name owner to broadcast a
subdomain-update operation. To do so, they generate and sign the requisite
subdomain operation and give it to an on-chain name owner, who then packages it
with other subdomain operations into a DNS zone file and broadcasts it to the network.
If the subdomain owner wants to change the address of their subdomain, they need
to sign a subdomain-transfer operation and give it to the on-chain name owner
who created the subdomain. They then package it into a zone file and broadcast
it.
### Subdomain Registrars
Because subdomain names are cheap, developers may be inclined to run
subdomain registrars on behalf of their applications. For example,
the name `personal.id` is used to register Blockstack application users without
requiring them to spend any Bitcoin.
We supply a reference implementation of a [BNS Subdomain
Registrar](https://github.com/blockstack/subdomain-registrar) to help
developers broadcast subdomain operations. Users would still own their
subdomain names; the registrar simply gives developers a convenient
way for them to register and manage them in the context of a
particular application.
# BNS and DID Standards
BNS names are compliant with the emerging
[Decentralized Identity Foundation](http://identity.foundation) protocol
specification for decentralized identifiers (DIDs).
Each name in BNS has an associated DID. The DID format for BNS is:
```bash
did:stack:v0:{address}-{index}
```
Where:
- `{address}` is an on-chain public key hash (e.g. a Bitcoin address).
- `{index}` refers to the `nth` name this address created.
For example, the DID for `personal.id` is
`did:stack:v0:1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV-0`, because the name
`personal.id` was the first-ever name created by
`1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV`.
As another example, the DID for `jude.id` is `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-1`.
Here, the address `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` had created one earlier
name in history prior to this one (which happens to be `abcdefgh123456.id`).
The purpose of a DID is to provide an eternal identifier for a public key.
The public key may change, but the DID will not.
Stacks Blockchain implements a DID method of its own
in order to be compatible with other systems that use DIDs for public key resolution.
In order for a DID to be resolvable, all of the following must be true for a
name:
- The name must exist
- The name's zone file hash must be the hash of a well-formed DNS zone file
- The DNS zone file must be present in the Stacks node's data.
- The DNS zone file must contain a `URI` resource record that points to a signed
JSON Web Token
- The public key that signed the JSON Web Token (and is included with it) must
hash to the address that owns the name
Not all names will have DIDs that resolve to public keys. However, names created by standard tooling
will have DIDs that do.
A RESTful API is under development.
## DID Encoding for Subdomains
Every name and subdomain in BNS has a DID. The encoding is slightly different
for subdomains, so the software can determine which code-path to take.
- For on-chain BNS names, the `{address}` is the same as the Bitcoin address
that owns the name. Currently, both version byte 0 and version byte 5
addresses are supported (i.e. addresses starting with `1` or `3`, meaning `p2pkh` and
`p2sh` addresses).
- For off-chain BNS subdomains, the `{address}` has version byte 63 for
subdomains owned by a single private key, and version byte 50 for subdomains
owned by a m-of-n set of private keys. That is, subdomain DID addresses start
with `S` or `M`, respectively.
The `{index}` field for a subdomain's DID is distinct from the `{index}` field
for a BNS name's DID, even if the same created both names and subdomains.
For example, the name `abcdefgh123456.id` has the DID `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-0`,
because it was the first name created by `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg`.
However, `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` _also_ created `jude.statism.id`
as its first subdomain name. The DID for `jude.statism.id` is
`did:stack:v0:SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i-0`. Note that the address
`SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i` encodes the same public key hash as the address
`16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` (the only difference between these two
strings is that the first is base58check-encoded with version byte 0, and the
second is encoded with version byte 63).

104
src/pages/naming-services/register-name.md
View File

@ -1,104 +0,0 @@
---
title: Register a name
description: This section explains registering BNS names and provides instructions for methods you can use to understand the cost of namespace registration.
---
## Understand registration
Registering a BNS name costs cryptocurrency. This cost comes from two sources:
- **Transaction fees:** These are the fees imposed by the cost of storing the
transaction data to the blockchain itself. They are independent of BNS, since
all of the blockchain's users are competing to have their transactions included
in the next block. The blockchain's miners receive the transaction fee.
- **Registration fees:** Each BNS namespace imposes an _additional_ fee on how
much a name costs. The registration fee is sent to the namespace creator
during the first year that a namespace exists, and is sent to a burn address
afterwards. The registration fee is different for each name and is
determined by the namespace itself, but can be queried in advance by the user.
Registering a name takes two transactions. They are:
- **`NAME_PREORDER` transaction**: This is the first transaction to be sent.
It tells all BNS nodes the _salted hash_ of the BNS name, and it pays the
registration fee to the namespace owner's designated address (or the burn
address). In addition, it proves to the BNS nodes that the client knows about
the current state of the system by including a recent _consensus hash_
in the transaction (see the section on [BNS forks](#bns-forks) for details).
- **`NAME_REGISTRATION` transaction**: This is the second transaction to be
sent. It reveals the salt and the name to all BNS nodes, and assigns the name
an initial public key hash and zone file hash
The reason this process takes two transactions is to prevent front-running.
The BNS consensus rules stipulate that a name can only be registered if its
matching preorder transaction was sent in the last 24 hours. Because a name
must be preordered before it is registered, someone watching the blockchain's
peer network cannot race a victim to claim the name they were trying to
register (i.e. the attacker would have needed to send a `NAME_PREORDER`
transaction first, and would have had to have sent it no more than 24 hours
ago).
Registering a name on top of the Bitcoin blockchain takes 1-2 hours. This is
because you need to wait for the `NAME_PREORDER` transaction to be sufficiently
confirmed before sending the `NAME_REGISTRATION` transaction. The BNS nodes
only register the name once both transactions have at least 6 confirmations
(which itself usually takes about an hour).
Names are registered on a first-come first-serve basis.
If two different people try to register the same name at the same time, the
person who completes the two-step process _earliest_ will receive the name. The
other person's `NAME_REGISTRATION` transaction will be ignored, since it will
not be considered valid at this point. The registration fee paid by the
`NAME_PREORDER` will be lost. However, this situation is rare in practice---
as of early 2018, we only know of one confirmed instance in the system's 3+ years
of operation.
Fully-qualified names can be between 3 and 37 characters long, and consist of
the characters `a-z`, `0-9`, `+`, `-`, `_`, and `.`. This is to prevent
[homograph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack).
`NAME_REGISTRATION` transactions that do not conform to this requirement will be
ignored.
## Getting a Name's Registration Fee
-> See [reference](https://core.blockstack.org/#price-checks-get-name-price).
```bash
$ curl -sL https://core.blockstack.org/v1/prices/names/helloworld.id | jq -r ".name_price"
{
"btc": 2.5e-05,
"satoshis": 2500
}
```
Note the use of `jq -r` to select the `"name_price"` field. This API
endpoint may return other ancilliary data regarding transaction fee estimation,
but this is the only field guaranteed by this specification to be present.
## Getting the Current Consensus Hash
-> See [reference](https://core.blockstack.org/#blockchain-operations-get-consensus-hash).
```bash
$ curl -sL https://core.blockstack.org/v1/blockchains/bitcoin/consensus
{
"consensus_hash": "98adf31989bd937576aa190cc9f5fa3a"
}
```
The consensus hash must be included in the `NAME_PREORDER` transaction. The BNS
clients do this automatically. See the [transaction format document](/core/wire-format)
for details as to how to include this in the transaction.
## Registering a Name
Registration happens through a BNS client, such as the [Blockstack
Browser](https://github.com/blockstack/blockstack-browser) or
[blockstack.js](https://github.com/blockstack/blockstack.js).
The reference BNS clients manage a local Bitcoin wallet, calculate transaction fees
dynamically and automatically, and broadcast both the `NAME_PREORDER` and
`NAME_REGISTRATION` transactions at the right times.
-> If you want to make your own registration client, you should see the [transaction format](/core/wire-format) document.

248
src/pages/naming-services/resolve-name.md
View File

@ -1,248 +0,0 @@
---
title: Resolve a name
description: This section explains resolving BNS names and provides instructions for methods you can use to accomplish namespace resolution.
---
## Understand resolution
BNS names are bound to both public keys and to about 40Kb of off-chain state.
The off-chain state is encoded as a [DNS zone file](https://en.wikipedia.org/wiki/Zone_file),
which contains routing information for discovering the user's Blockstack data
(such as their profile and app data, which are hosted in the [Gaia storage
system](https://github.com/blockstack/gaia)).
The blockchain is not used to store this information directly. Instead, the
blockchain stores the _public key hash_ and the _zone file hash_. When
indexing the blockchain, each BNS node builds a database with
three columns: all the on-chain BNS names that have been registered, each
name's public key hash, and each name's zone file's hash.
In addition, each BNS node maintains the _transaction history_ of each name.
A developer can resolve a name to any configuration it was in at any prior
point in time.
Below is an example name table pulled from a live BNS node:
| Name | Public key hash | Zone File Hash |
| --------------------------------- | ------------------------------------ | ------------------------------------------ |
| `ryan.id` | `15BcxePn59Y6mYD2fRLCLCaaHScefqW2No` | `a455954b3e38685e487efa41480beeb315f4ec65` |
| `muneeb.id` | `1J3PUxY5uDShUnHRrMyU6yKtoHEUPhKULs` | `37aecf837c6ae9bdc9dbd98a268f263dacd00361` |
| `jude.id` | `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` | `b6e99200125e70d634b17fe61ce55b09881bfafd` |
| `verified.podcast` | `1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH` | `6701ce856620d4f2f57cd23b166089759ef6eabd` |
| `cicero.res_publica.id` | `1EtE77Aa5AA8etzF2irk56vvkS4v7rZ7PE` | `7e4ac75f9d79ba9d5d284fac19617497433b832d` |
| `podsaveamerica.verified.podcast` | `1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH` | `0d6f090db8945aa0e60759f9c866b17645893a95` |
In practice, the zone file hash is the `RIPEMD160` hash of the `SHA256` hash of
the zone file, and the public key is the `base58check`-encoded `RIPEMD160` hash
of the double-`SHA256` hash of the ECDSA public key (i.e. a Bitcoin address).
The BNS consensus rules ensure that
a BNS name can only be registered if it is not already taken, and that only the
user who owns the name's private key can change its public key hash or zone file
hash. This means that a name's public key and zone file can be stored anywhere,
since they can be authenticated using the hashes discovered by indexing the
blockchain under the BNS consensus rules.
BNS nodes implement a decentralized storage system for zone files called the
[Atlas network](/core/atlas/overview). In this system, BNS nodes eagerly replicate
all the zone files they know about to one another, so that eventually every BNS
node has a full replica of all zone files.
The public keys for names are stored off-chain in [Gaia](https://github.com/blockstack/gaia).
The user controls where their public keys are hosted using the zone file
contents (if they are hosted online anywhere at all).
Developers can query this table via the BNS API. The API offers routes
to do the following:
## Look up a name's public key and zone file ([reference](https://core.blockstack.org/#name-querying-get-name-info))
```bash
$ curl https://core.blockstack.org/v1/names/muneeb.id
{
"address": "1J3PUxY5uDShUnHRrMyU6yKtoHEUPhKULs",
"blockchain": "bitcoin",
"expire_block": 599266,
"last_txid": "7e16e8688ca0413a398bbaf16ad4b10d3c9439555fc140f58e5ab4e50793c476",
"status": "registered",
"zonefile": "$ORIGIN muneeb.id\n$TTL 3600\n_http._tcp URI 10 1 \"https://gaia.blockstack.org/hub/1J3PUxY5uDShUnHRrMyU6yKtoHEUPhKULs/0/profile.json\"\n",
"zonefile_hash": "37aecf837c6ae9bdc9dbd98a268f263dacd00361"
}
```
Note that the `zonefile` field is given with the off-chain data that hashes
to the `zonefile_hash` field.
## List all names the node knows about ([reference](https://core.blockstack.org/#name-querying-get-all-names))
```bash
$ curl https://core.blockstack.org/v1/names?page=0
[
"judecn.id",
"3.id",
"4.id",
"8.id",
"e.id",
"h.id",
"5.id",
"9.id",
"i.id",
"l.id",
"p.id",
"w.id",
"ba.id",
"df.id",
...
]
```
Each page returns 100 names. While no specific ordering is mandated by the
protocol, the reference implementation orders names by their order of creation
in the blockchain.
## Look up the history of states a name was in ([reference](https://core.blockstack.org/#name-querying-name-history))
```bash
$ curl https://core.blockstack.org/v1/names/patrickstanley.id/history
{
"445838": [
{
"address": "1occgbip7tFDXX9MvzQhcnTUUjcVX2dYK",
"block_number": 445838,
"burn_address": "1111111111111111111114oLvT2",
"consensus_hash": "7b696b6f4060b792d41912068944d73b",
"op": "?",
"op_fee": 25000,
"opcode": "NAME_PREORDER",
"preorder_hash": "26bf7874706ac761afdd403ed6b3b9578fb01a34",
"sender": "76a91408d0dd44c1f0a3a4f0957ae95901929d7d66d55788ac",
"sender_pubkey": "039a8948d339ecbff44cf426cb85d90fce876f1658d385cdc47f007f279be626ea",
"txid": "6730ae09574d5935ffabe3dd63a9341ea54fafae62fde36c27738e9ee9c4e889",
"vtxindex": 40
}
],
"445851": [
{
"address": "17CbHgTgBG3kLedXNneEKBkCTgW2fyrnUD",
"block_number": 445838,
"consensus_hash": null,
"first_registered": 445851,
"importer": null,
"importer_address": null,
"last_creation_op": "?",
"last_renewed": 445851,
"name": "patrickstanley.id",
"name_hash128": "683a3e1ee5f0296833c56e481cf41b77",
"namespace_block_number": 373601,
"namespace_id": "id",
"op": ":",
"op_fee": 25000,
"opcode": "NAME_REGISTRATION",
"preorder_block_number": 445838,
"preorder_hash": "26bf7874706ac761afdd403ed6b3b9578fb01a34",
"revoked": false,
"sender": "76a9144401f3be5311585ea519c1cb471a8dc7b02fd6ee88ac",
"sender_pubkey": "039a8948d339ecbff44cf426cb85d90fce876f1658d385cdc47f007f279be626ea",
"transfer_send_block_id": null,
"txid": "55b8b42fc3e3d23cbc0f07d38edae6a451dfc512b770fd7903725f9e465b2925",
"value_hash": null,
"vtxindex": 54
}
],
"445873": [
{
"address": "17CbHgTgBG3kLedXNneEKBkCTgW2fyrnUD",
"block_number": 445838,
"consensus_hash": "18b8d69f0182b89ccb1aa536f83be18a",
"first_registered": 445851,
"importer": null,
"importer_address": null,
"last_creation_op": "?",
"last_renewed": 445851,
"name": "patrickstanley.id",
"name_hash128": "683a3e1ee5f0296833c56e481cf41b77",
"namespace_block_number": 373601,
"namespace_id": "id",
"op": "+",
"op_fee": 25000,
"opcode": "NAME_UPDATE",
"preorder_block_number": 445838,
"preorder_hash": "26bf7874706ac761afdd403ed6b3b9578fb01a34",
"revoked": false,
"sender": "76a9144401f3be5311585ea519c1cb471a8dc7b02fd6ee88ac",
"sender_pubkey": "039a8948d339ecbff44cf426cb85d90fce876f1658d385cdc47f007f279be626ea",
"transfer_send_block_id": null,
"txid": "dc478659fc684a1a6e1e09901971e82de11f4dfe2b32a656700bf9a3b6030719",
"value_hash": "02af0ef21161ad06b0923106f40b994b9e4c1614",
"vtxindex": 95
}
],
"445884": [
{
"address": "1GZqrVbamkaE6YNveJFWK6cDrCy6bXyS6b",
"block_number": 445838,
"consensus_hash": "18b8d69f0182b89ccb1aa536f83be18a",
"first_registered": 445851,
"importer": null,
"importer_address": null,
"last_creation_op": "?",
"last_renewed": 445851,
"name": "patrickstanley.id",
"name_hash128": "683a3e1ee5f0296833c56e481cf41b77",
"namespace_block_number": 373601,
"namespace_id": "id",
"op": ">>",
"op_fee": 25000,
"opcode": "NAME_TRANSFER",
"preorder_block_number": 445838,
"preorder_hash": "26bf7874706ac761afdd403ed6b3b9578fb01a34",
"revoked": false,
"sender": "76a914aabffa6dd90d731d3a349f009323bb312483c15088ac",
"sender_pubkey": null,
"transfer_send_block_id": 445875,
"txid": "7a0a3bb7d39b89c3638abc369c85b5c028d0a55d7804ba1953ff19b0125f3c24",
"value_hash": "02af0ef21161ad06b0923106f40b994b9e4c1614",
"vtxindex": 16
}
]
}
```
All of the above information is extracted from the blockchain. Each top-level
field encodes the states the name transitioned to at the given block height (e.g.
445838, 445851, 445873, adn 445884). At each block height, the name's zone file
hashes are returned in the order they were discovered in the blockchain.
Each name state contains a lot of ancillary data that is used internally by
other API calls and client libraries. The relevant fields for this document's
scope are:
- `address`: This is the base58check-encoded public key hash.
- `name`: This is the name queried.
- `value_hash`: This is the zone file hash.
- `opcode`: This is the type of transaction that was processed.
- `txid`: This is the transaction ID in the underlying blockchain.
The name's _entire_ history is returned. This includes the history of the name
under its previous owner, if the name expired and was reregistered.
## Look up the list of names owned by a given public key hash
See [reference](https://core.blockstack.org/#name-querying-get-names-owned-by-address).
```bash
$ curl https://core.blockstack.org/v1/addresses/bitcoin/16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg
{
"names": [
"judecn.id",
"patrickstanley1.id",
"abcdefgh123456.id",
"duckduckgo_tor.id",
"jude.id",
"blockstacknewyear2017.id",
"jude.statism.id"
]
}
```
Note that this API endpoint includes names and
[subdomains](#bns-subdomains).

307
src/pages/naming-services/subdomains-tutorial.md
View File

@ -1,307 +0,0 @@
---
title: Subdomain registrar
description: Learn how to create, register, and run a subdomain registrar.
---
## Introduction
Subdomains allow us to provide names to end users cheaply (and quickly).
## Strong subdomain ownership
For those who are new to this concept, it's a model where domains can
permanently, cryptographically delegate subdomains to particular keys,
relinquishing their ability to revoke the names or change the name
resolution details.
These names will be indicated with an `.`, e.g., `foo.bar.id`
## Overall Design
We can do this today with a special indexer & resolver endpoint and
without any changes to the core protocol.
We can do this by having a zone file record for each subdomain _i_
containing the following information:
1. An owner address _addr_
2. A sequence number _N_
3. A zonefile
4. A signature _S_ of the above
The signature _S_i_ must be verifiable with the address in the
*(N-1)*th entry for subdomain _i_.
## Zonefile Format
For now, the resolver will use an _TXT_ record per subdomain to define
this information. The entry name will be `$(subdomain)`.
We'll use the format of [RFC 1464](https://tools.ietf.org/html/rfc1464)
for the TXT entry. We'll have the following strings with identifiers:
1. **parts** : this specifies the number of pieces that the
zonefile has been chopped into. TXT strings can only be 255 bytes,
so we chop up the zonefile.
2. **zf{n}**: part _n_ of the zonefile, base64 encoded
3. **owner**: the owner address delegated to operate the subdomain
4. **seqn**: the sequence number
5. **sig**: signature of the above data.
```bash
$ORIGIN bar.id
$TTL 3600
pubkey TXT "pubkey:data:0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
registrar URI 10 1 "bsreg://foo.com:8234"
aaron TXT "owner=33VvhhSQsYQyCVE2VzG3EHa9gfRCpboqHy" "seqn=0" "parts=1" "zf0=JE9SSUdJTiBhYXJvbgokVFRMIDM2MDAKbWFpbiBVUkkgMSAxICJwdWJrZXk6ZGF0YTowMzAyYWRlNTdlNjNiMzc1NDRmOGQ5Nzk4NjJhNDlkMDBkYmNlMDdmMjkzYmJlYjJhZWNmZTI5OTkxYTg3Mzk4YjgiCg=="
```
The `registrar` entry indicates how to contact the registrar service
for clients of the domain wishing to register or modify their entry.
### Operations per Zonefile
At 4kb zonefile size, we can only fit around 20 updates per zonefile.
## Domain Operator Endpoint
The directory `subdomain_registrar/` contains our code for running a
subdomain registrar. It can be executed by running:
```bash
$ blockstack-subdomain-registrar start foo.id
```
Here, `foo.id` is the domain for which subdomains will be associated.
### Configuration and Registration Files
Configuration of the subdomain registrar is done through `~/.blockstack_subdomains/config.ini`
The sqlite database which stores the registrations is located alongside the config `~/.blockstack_subdomains/registrar.db`.
You can change the location of the config file (and the database), by setting the environment variable `BLOCKSTACK_SUBDOMAIN_CONFIG`
### Register Subdomain
Subdomain registrations can be submitted to this endpoint using a REST
API.
```bash
POST /register
```
The schema for registration is:
```json
{
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "([a-z0-9-_+]{3,36})$"
},
"owner_address": {
"type": "string",
"pattern": schemas.OP_ADDRESS_PATTERN
},
"zonefile": {
"type": "string",
"maxLength": blockstack_constants.RPC_MAX_ZONEFILE_LEN
}
},
"required": ["name", "owner_address", "zonefile"],
"additionalProperties": True
}
```
The registrar will:
1. Check if the subdomain `foo` exists already on the domain.
2. Add the subdomain to the queue.
On success, this returns `202` and the message
```json
{ "status": "true", "message": "Subdomain registration queued." }
```
When the registrar wakes up to prepare a transaction, it packs the queued
registrations together and issues an `UPDATE`.
### Check subdomain registration status
A user can check on the registration status of their name via querying the
registrar.
This is an API call:
```
GET /status/{subdomain}
```
The registrar checks if the subdomain has propagated (i.e., the
registration is completed), in which case the following is returned:
```json
{ "status": "Subdomain already propagated" }
```
Or, if the subdomain has already been submitted in a transaction:
```json
{
"status": "Your subdomain was registered in transaction 09a40d6ea362608c68da6e1ebeb3210367abf7aa39ece5fd57fd63d269336399 -- it should propagate on the network once it has 6 confirmations."
}
```
If the subdomain still hasn't been submitted yet:
```json
{ "status": "Subdomain is queued for update and should be announced within the next few blocks." }
```
If an error occurred trying to submit the `UPDATE` transaction, this endpoint will return an error
message in the `"error"` key of a JSON object.
### Updating Entries
The subdomain registrar does not currently support updating subdomain entries.
## Resolver Behavior
When a lookup like `foo.bar.id` hits the resolver, the resolver will need to:
1. Lookup the zonefile history of `bar.id`
2. Fetch all these zonefiles and filter by operations on `foo`
3. Verify that all `foo` operations are correct
4. Return the latest record for foo
5. Do a profile lookup for `foo.bar.id` by fetching the URLs in the entry.
_Note_, this spec does not define a priority order for fetching those URLs.
### Supported Core / Resolver Endpoints
Generally, domain endpoints are not aware of subdomains (only endpoints
aware of subdomains is `/v1/users/<foo.bar.tld>`,
`/v1/names/<foo.bar.tld>`, and `/v1/addresses/bitcoin/<foo.bar.tld>`)
The endpoints which _are_ subdomain aware are marked as such in
[api-specs.md].
This means that search is _not_ yet supported.
The lookups work just like normal -- it returns the user's
profile object:
```bash
$ curl -H "Authorization: bearer blockstack_integration_test_api_password" -H "Origin: http://localhost:3000" http://localhost:16268/v1/users/bar.foo.id -v -s | python -m json.tool
* Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 16268 (#0)
> GET /v1/users/bar.foo.id HTTP/1.1
> Host: localhost:16268
> User-Agent: curl/7.50.1
> Accept: */*
> Authorization: bearer blockstack_integration_test_api_password
> Origin: http://localhost:3000
>
* HTTP 1.0, assume close after body
< HTTP/1.0 200 OK
< Server: SimpleHTTP/0.6 Python/2.7.12+
< Date: Thu, 03 Aug 2017 14:39:16 GMT
< content-type: application/json
< Access-Control-Allow-Origin: *
<
{ [66 bytes data]
* Closing connection 0
{
"bar": {
"@type": "Person",
"description": "Lorem Ipsum Bazorem"
}
}
```
Name info lookups are also supported
```bash
$ curl -H "Authorization: bearer XXXX" -H "Origin: http://localhost:3000" http://localhost:6270/v1/names/created_equal.self_evident_truth.id -s | python -m json.tool
{
"address": "1AYddAnfHbw6bPNvnsQFFrEuUdhMhf2XG9",
"blockchain": "bitcoin",
"expire_block": -1,
"last_txid": "0bacfd5a3e0ec68723d5948d6c1a04ad0de1378c872d45fa2276ebbd7be230f7",
"satus": "registered_subdomain",
"zonefile_hash": "48fc1b351ce81cf0a9fd9b4eae7a3f80e93c0451",
"zonefile_txt": "$ORIGIN created_equal\n$TTL 3600\n_https._tcp URI 10 1 \"https://www.cs.princeton.edu/~ablankst/created_equal.json\"\n_file URI 10 1 \"file:///tmp/created_equal.json\"\n"
}
```
### Subdomain Caching
A resolver _caches_ a subdomain's state by keeping a database of all
the current subdomain records. This database is automatically updated
when a new zonefile for a particularly domain is seen by the resolver
(this is performed lazily).
### Testing Subdomain Registrar and Resolution
You can run a subdomain registrar and resolver with blockstack-core in
regtest mode as follows:
```bash
IMAGE=$(docker run -dt -p 3000:3000 -p 6270:6270 -p 16269:16269 -p 18332:18332 -e BLOCKSTACK_TEST_CLIENT_RPC_PORT=6270 -e BLOCKSTACK_TEST_CLIENT_BIND=0.0.0.0 -e BLOCKSTACK_TEST_BITCOIND_ALLOWIP=172.17.0.0/16 quay.io/blockstack/integrationtests:master blockstack-test-scenario --interactive 2 blockstack_integration_tests.scenarios.browser_env)
```
Once you see `Test finished; doing checks` in that container's logs, the
registrar has started and is ready to accept requests. (We recommend
following the docker instructions below for running this test in
Docker, as it will fetch the source code for the registrar and set the
correct environment variables for it to run).
Once this environment has started, you can issue a registration request from curl:
```bash
curl -X POST -H 'Content-Type: application/json' --data '{"zonefile": "$ORIGIN baz\n$TTL 3600\n_file URI 10 1 \"file:///tmp/baz.profile.json\"\n", "name": "baz", "owner_address": "14x2EMRz1gf16UzGbxZh2c6sJg4A8wcHLD"}' http://localhost:3000/register/
```
This registers `baz.foo.id` -- you can check the registrar's status with
```bash
curl http://localhost:3000/status/baz
```
The API endpoints `/v1/users/<foo.bar.tld>`,
`/v1/names/<foo.bar.tld>`, and `/v1/addresses/bitcoin/<foo.bar.tld>` all work, so if you query the core API, you'll get a response.
For example:
```bash
curl http://localhost:6270/v1/names/baz.foo.id | python -m json.tool
```
Will return:
```json
{
"address": "1Nup2UcbVuVoDZeZCtR4vjSkrvTi8toTqc",
"blockchain": "bitcoin",
"expire_block": -1,
"last_txid": "43bbcbd8793cdc52f1b0bd2713ed136f4f104a683a9fd5c89911a57a8c4b28b6",
"satus": "registered_subdomain",
"zonefile_hash": "e7e3aada18c9ac5189f1c54089e987f58c0fa51e",
"zonefile_txt": "$ORIGIN bar\n$TTL 3600\n_file URI 10 1 \"file:///tmp/baz.profile.json\"\n"
}
```
### Running an interactive testing environment with the Subdomain Registrar service
Follow the [instructions here](https://github.com/blockstack/blockstack-core/blob/master/integration_tests/README.md) to download the regtesting Docker image.
Since the subdomain registrar service runs on port 3000, we need to do two things to expose this endpoint to interact with it from the browser:
- Open port 3000 with `-p 3000:3000`
Here's the full command you'd run to start the interactive testing scenario:
```bash
IMAGE=$(docker run -dt -p 3000:3000 -p 6270:6270 -p 16269:16269 -p 18332:18332 -e BLOCKSTACK_TEST_CLIENT_RPC_PORT=6270 -e BLOCKSTACK_TEST_CLIENT_BIND=0.0.0.0 -e BLOCKSTACK_TEST_BITCOIND_ALLOWIP=172.17.0.0/16 quay.io/blockstack/integrationtests:master blockstack-test-scenario --interactive 2 blockstack_integration_tests.scenarios.browser_env)
```

240
src/pages/naming-services/subdomains.md
View File

@ -1,240 +0,0 @@
---
title: Subdomains
description: This section explains BNS subdomains and provides instructions for methods you can use to work with them.
---
## Overview of subdomains
BNS names are strongly-owned because the owner of its private key can generate
valid transactions that update its zone file hash and owner. However, this comes at the
cost of requiring a name owner to pay for the underlying transaction in the
blockchain. Moreover, this approach limits the rate of BNS name registrations
and operations to the underlying blockchain's transaction bandwidth.
BNS overcomes this with subdomains. A **BNS subdomain** is a type of BNS name whose state
and owner are stored outside of the blockchain, but whose existence and
operation history are anchored to the
blockchain. In the example table in the [Resolving BNS
Names](#resolving-bns-names) section, the names `cicero.res_publica.id` and
`podsaveamerica.verified.podcast` are subdomains.
Like their on-chain counterparts, subdomains are globally
unique, strongly-owned, and human-readable. BNS gives them their own name state
and public keys.
Unlike on-chain names, subdomains can be created and managed
cheaply, because they are broadcast to the
BNS network in batches. A single blockchain transaction can send up to 120
subdomain operations.
This is achieved by storing subdomain records in the [Atlas Network](/core/atlas/overview).
An on-chain name owner broadcasts subdomain operations by encoding them as
`TXT` records within a DNS zone file. To broadcast the zone file,
the name owner sets the new zone file hash with a `NAME_UPDATE` transaction and
replicates the zone file via Atlas. This, in turn, replicates all subdomain
operations it contains, and anchors the set of subdomain operations to
an on-chain transaction. The BNS node's consensus rules ensure that only
valid subdomain operations from _valid_ `NAME_UPDATE` transactions will ever be
stored.
For example, the name `verified.podcast` once wrote the zone file hash `247121450ca0e9af45e85a82e61cd525cd7ba023`,
which is the hash of the following zone file:
```bash
$ curl -sL https://core.blockstack.org/v1/names/verified.podcast/zonefile/247121450ca0e9af45e85a82e61cd525cd7ba023 | jq -r '.zonefile'
$ORIGIN verified.podcast
$TTL 3600
1yeardaily TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxeWVhcmRhaWx5CiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMXllYXJkYWlseS9oZWFkLmpzb24iCg=="
2dopequeens TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAyZG9wZXF1ZWVucwokVFRMIDM2MDAKX2h0dHAuX3RjcCBVUkkgMTAgMSAiaHR0cHM6Ly9waC5kb3Rwb2RjYXN0LmNvLzJkb3BlcXVlZW5zL2hlYWQuanNvbiIK"
10happier TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMGhhcHBpZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMGhhcHBpZXIvaGVhZC5qc29uIgo="
31thoughts TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMXRob3VnaHRzCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzF0aG91Z2h0cy9oZWFkLmpzb24iCg=="
359 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNTkKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8zNTkvaGVhZC5qc29uIgo="
30for30 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMGZvcjMwCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzBmb3IzMC9oZWFkLmpzb24iCg=="
onea TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiBvbmVhCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vb25lYS9oZWFkLmpzb24iCg=="
10minuteteacher TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMG1pbnV0ZXRlYWNoZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMG1pbnV0ZXRlYWNoZXIvaGVhZC5qc29uIgo="
36questionsthepodcastmusical TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNnF1ZXN0aW9uc3RoZXBvZGNhc3RtdXNpY2FsCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzZxdWVzdGlvbnN0aGVwb2RjYXN0bXVzaWNhbC9oZWFkLmpzb24iCg=="
_http._tcp URI 10 1 "https://dotpodcast.co/"
```
Each `TXT` record in this zone file encodes a subdomain-creation.
For example, `1yeardaily.verified.podcast` resolves to:
```bash
$ curl https://core.blockstack.org/v1/names/1yeardaily.verified.podcast
{
"address": "1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH",
"blockchain": "bitcoin",
"last_txid": "d87a22ebab3455b7399bfef8a41791935f94bc97aee55967edd5a87f22cce339",
"status": "registered_subdomain",
"zonefile_hash": "e7acc97fd42c48ed94fd4d41f674eddbee5557e3",
"zonefile_txt": "$ORIGIN 1yeardaily\n$TTL 3600\n_http._tcp URI 10 1 \"https://ph.dotpodcast.co/1yeardaily/head.json\"\n"
}
```
This information was extracted from the `1yeardaily` `TXT` resource record in the zone
file for `verified.podcast`.
## Subdomain Lifecycle
Note that `1yeardaily.verified.podcast` has a different public key
hash (address) than `verified.podcast`. A BNS node will only process a
subsequent subdomain operation on `1yeardaily.verified.podcast` if it includes a
signature from this address's private key. `verified.podcast` cannot generate
updates; only the owner of `1yeardaily.verified.podcast can do so`.
The lifecycle of a subdomain and its operations is shown in Figure 2.
```
subdomain subdomain subdomain
creation update transfer
+----------------+ +----------------+ +----------------+
| cicero | | cicero | | cicero |
| owner="1Et..." | signed | owner="1Et..." | signed | owner="1cJ..." |
| zf0="7e4..." |<--------| zf0="111..." |<--------| zf0="111..." |<---- ...
| seqn=0 | | seqn=1 | | seqn=2 |
| | | sig="xxxx" | | sig="xxxx" |
+----------------+ +----------------+ +----------------+
| | |
| off-chain | |
~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~|~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ...
| on-chain | |
V V (zone file hash ) V
+----------------+ +----------------+ +----------------+
| res_publica.id | | jude.id | | res_publica.id |
| NAME_UPDATE |<--------| NAME_UPDATE |<--------| NAME_UPDATE |<---- ...
+----------------+ +----------------+ +----------------+
blockchain blockchain blockchain
block block block
Figure 2: Subdomain lifetime with respect to on-chain name operations. A new
subdomain operation will only be accepted if it has a later "sequence=" number,
and a valid signature in "sig=" over the transaction body. The "sig=" field
includes both the public key and signature, and the public key must hash to
the previous subdomain operation's "addr=" field.
Thesubdomain-creation and subdomain-transfer transactions for
"cicero.res_publica.id" are broadcast by the owner of "res_publica.id".
However, any on-chain name ("jude.id" in this case) can broadcast a subdomain
update for "cicero.res_publica.id".
```
Subdomain operations are ordered by sequence number, starting at 0. Each new
subdomain operation must include:
- The next sequence number
- The public key that hashes to the previous subdomain transaction's address
- A signature from the corresponding private key over the entire subdomain
operation.
If two correctly-signed but conflicting subdomain operations are discovered
(i.e. they have the same sequence number), the one that occurs earlier in the
blockchain's history is accepted. Invalid subdomain operations are ignored.
Combined, this ensures that a BNS node with all of the zone files with a given
subdomain's operations will be able to determine the valid sequence of
state-transitions it has undergone, and determine the current zone file and public
key hash for the subdomain.
## Resolving Subdomains
Developers interact with subdomains the same way they interact with names.
Using the BNS API, a developer can:
### Look up a subdomain's public key and zone file ([reference](https://core.blockstack.org/#name-querying-get-name-info))
```bash
$ curl https://core.blockstack.org/v1/names/aaron.personal.id
{
"address": "1PwztPFd1s2STMv4Ntq6UPBdYgHSBr5pdF",
"blockchain": "bitcoin",
"last_txid": "85e8273b0a38d3e9f0af7b4b72faf0907de9f4616afc101caac13e7bbc832394",
"status": "registered_subdomain",
"zonefile_hash": "a6dda6b74ffecf85f4a162627d8df59577243813",
"zonefile_txt": "$ORIGIN aaron.personal.id\n$TTL 3600\n_https._tcp URI 10 1 \"https://gaia.blockstack.org/hub/1PwztPFd1s2STMv4Ntq6UPBdYgHSBr5pdF/profile.json\"\n"
}
```
### Look up a subdomain's transaction history ([reference](https://core.blockstack.org/#name-querying-name-history))
```bash
$ curl https://core.blockstack.org/v1/names/aaron.personal.id/history
{
"509981": [
{
"address": "1PwztPFd1s2STMv4Ntq6UPBdYgHSBr5pdF",
"block_number": 509981,
"domain": "personal.id",
"name": "aaron.personal.id",
"sequence": 0,
"txid": "85e8273b0a38d3e9f0af7b4b72faf0907de9f4616afc101caac13e7bbc832394",
"value_hash": "a6dda6b74ffecf85f4a162627d8df59577243813",
"zonefile": "JE9SSUdJTiBhYXJvbi5wZXJzb25hbC5pZAokVFRMIDM2MDAKX2h0dHBzLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vZ2FpYS5ibG9ja3N0YWNrLm9yZy9odWIvMVB3enRQRmQxczJTVE12NE50cTZVUEJkWWdIU0JyNXBkRi9wcm9maWxlLmpzb24iCg=="
}
]
}
```
### Look up the list of names and subdomains owned by a given public key hash ([reference](https://core.blockstack.org/#name-querying-get-names-owned-by-address))
```bash
$ curl https://core.blockstack.org/v1/addresses/bitcoin/1PwztPFd1s2STMv4Ntq6UPBdYgHSBr5pdF
{
"names": [
"aaron.personal.id"
]
}
```
## Subdomain Creation and Management
Unlike an on-chain name, a subdomain owner needs an on-chain name owner's help
to broadcast their subdomain operations. In particular:
- A subdomain-creation transaction can only be processed by the owner of the on-chain
name that shares its suffix. For example, only the owner of `res_publica.id`
can broadcast subdomain-creation transactions for subdomain names ending in
`.res_publica.id`.
- A subdomain-transfer transaction can only be broadcast by the owner of the
on-chain name that created it. For example, the owner of
`cicero.res_publica.id` needs the owner of `res_publica.id` to broadcast a
subdomain-transfer transaction to change `cicero.res_publica.id`'s public key.
- In order to send a subdomain-creation or subdomain-transfer, all
of an on-chain name owner's zone files must be present in the Atlas network.
This lets the BNS node prove the _absence_ of any conflicting subdomain-creation and
subdomain-transfer operations when processing new zone files.
- A subdomain update transaction can be broadcast by _any_ on-chain name owner,
but the subdomain owner needs to find one who will cooperate. For example,
the owner of `verified.podcast` can broadcast a subdomain-update transaction
created by the owner of `cicero.res_publica.id`.
That said, to create a subdomain, the subdomain owner generates a
subdomain-creation operation for their desired name
and gives it to the on-chain name owner.
The on-chain name owner then uses Atlas to
broadcast it to all other BNS nodes.
Once created, a subdomain owner can use any on-chain name owner to broadcast a
subdomain-update operation. To do so, they generate and sign the requisite
subdomain operation and give it to an on-chain name owner, who then packages it
with other subdomain operations into a DNS zone file
and sends them all out on the Atlas network.
If the subdomain owner wants to change the address of their subdomain, they need
to sign a subdomain-transfer operation and give it to the on-chain name owner
who created the subdomain. They then package it into a zone file and broadcast
it.
## Subdomain Registrars
Because subdomain names are cheap, developers may be inclined to run
subdomain registrars on behalf of their applications. For example,
the name `personal.id` is used to register Blockstack application users without
requiring them to spend any Bitcoin.
We supply a reference implementation of a [BNS Subdomain Registrar](https://github.com/blockstack/subdomain-registrar)
to help developers broadcast subdomain operations. Users would still own their
subdomain names; the registrar simply gives developers a convenient way for them
to register and manage them in the context of a particular application.
Please see the [tutorial on running a subdomain registrar](/core/naming/tutorial_subdomains) for
details on how to use it.
Write Preview
Loading…
Cancel
Save