naming-Tutorials & Cookbooks

FROM：https://docs.blockstack.org/core/naming/tutorial_subdomains.html

子域名允许我们向最终用户提供廉价(且快速)的名称。本教程向您解释如何创建、注册和运行子域名注册器，它包含以下部分:

强子域名的所有权
总体设计
Zonefile格式
--- 操作每个Zonefile
域名操作端点
--- 配置和注册文件
--- 注册子域名
--- 检查子域名注册状态
--- 更新的数据
解析行为
--- 支持核心/解析器端点
--- 子域名缓存
--- 测试子域名注册器和解决方案
--- 使用子域名注册服务运行交互式测试环境

强子域名的所有权

对于那些不熟悉这个概念的人来说，它是一个域名可以永久地、以密码方式将子域委托给特定密钥的模型，从而放弃了它们撤销名称或更改名称解析详细信息的能力。
这些名称将用一个。来表示，例如，foo.bar.id

总体设计

我们今天可以使用一个特殊的索引器和解析器端点来实现这一点，而不需要对核心协议做任何更改。
我们可以做到这一点，有一个区域文件记录为每个子域名i包含以下信息:
1.一个所有者地址地址
2.一个序号N
3.一个zonefile
4.一个上面的签名S

签名S_i必须使用子域名i的第(N-1)个条目中的地址进行验证。

Zonefile格式

目前，解析器将为每个子域名使用TXT记录来定义此信息。条目名称将是$(子域名)。
我们将对TXT条目使用RFC 1464格式。我们将有以下字符串与标识符:

1. parts : 这指定了zonefile被分割成的块的数量。TXT字符串只能是255个字节，所以我们分割了zonefile。
   2.zf{n}: zonefile的第n部分，base64编码
   3.owner: 委托操作子域名的所有者地址
   4.seqn: 序列号
   5.sig: 上述数据的签名。

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=="

注册表条目指示如何为希望注册或修改其条目的域的客户联系注册表服务。

操作每个Zonefile

在4kb的zonefile大小上，我们只能为每个zonefile容纳大约20个更新。

域名操作端点

目录subdomain_registry/包含运行子域名注册器的代码。可以通过运行:

$ blockstack-subdomain-registrar start foo.id

在这里,foo.id是子域名关联的域名。

配置和注册文件

子域名注册器的配置是通过

~/.blockstack_subdomains/config.ini

存储注册的sqlite数据库位于配置旁边

~/.blockstack_subdomains/registrar.db

通过设置环境变量BLOCKSTACK_SUBDOMAIN_CONFIG，可以更改配置文件(和数据库)的位置

子域名注册

可以使用REST API将子域名注册提交到此端点。

POST /register

注册模式为:

{
'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
}

注册器将做以下处理:
1.检查子域foo是否已经存在于该域中。
2.将子域名添加到队列中。

如果成功，将返回202和消息

{"status": "true", "message": "Subdomain registration queued."}

当注册器醒来准备事务时，它将排队的注册打包在一起并发出更新。

检查子域名注册状态

用户可以通过查询注册中心来检查其域名的注册状态。
这是一个API调用:

GET /status/{subdomain}

注册器检查子域是否已传播(即，登记已完成)，在这种情况下，会返回以下资料:

{"status": "Subdomain already propagated"}

或者，如果子域名已经在事务中提交:

{"status": "Your subdomain was registered in transaction 09a40d6ea362608c68da6e1ebeb3210367abf7aa39ece5fd57fd63d269336399 -- it should propagate on the network once it has 6 confirmations."}

如果子域名还没有提交:

{"status": "Subdomain is queued for update and should be announced within the next few blocks."}

如果试图提交更新事务时发生错误，该端点将在JSON对象的“error”键中返回一条错误消息。

更新的条目

子域名注册器目前不支持更新子域名条目。

解析行为

当像foo.bar.id这样的查找时触发击解析器，解析器需要:
1.查找bar.id的zonefile历史记录
2.获取所有这些zonefile并通过foo上的操作进行过滤
3.验证所有foo操作都是正确的
4.返回foo的最新记录
5.通过获取条目中的url查找foo.bar.id。注意，这个规范没有为获取这些url定义优先级顺序。

支持核心/解析器端点

通常，域端点不知道子域名(只有端点能意识到子域名/v1/users/<foo.bar.tld>, /v1/names/<foo.bar.tld>，/v1/addresses/bitcoin/<foo.bar.tld>)。子域名感知的端点被标记为[api-spec.md]。

这意味着还不支持搜索。
查找工作就像正常-它返回用户的配置文件对象:

$ 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"
  }
  }

还支持名称信息查找(这应该支持使用blockstack对登录进行身份验证。，但我需要再次检查)。

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": "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"
}

子域名缓存

解析器通过保存所有当前子域记录的数据库来缓存子域名的状态。当解析器看到特定域的新zonefile时(这是延迟执行的)，该数据库将自动更新。

测试子域名注册器和解决方案

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)

一旦测试完成;在检查容器的日志时，注册器已经启动并准备接受请求。(我们建议按照下面的docker指令在docker中运行这个测试，因为它将为注册器获取源代码，并为它设置正确的运行环境变量)。

一旦该环境启动，您可以从curl发出注册请求:

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/

这个注册器baz.foo.id -你可以用它来检查注册员的状态

curl http://localhost:3000/status/baz
API端点/v1/users/<foo.bar.tld>, /v1/names/<foo.bar.tld>, 和 /v1/addresses/bitcoin/<foo.bar.tld>都起作用；因此，如果您查询核心API，您将得到一个响应。

例如:

curl http://localhost:6270/v1/names/baz.foo.id | python -m json.tool

将返回:

{
"address": "1Nup2UcbVuVoDZeZCtR4vjSkrvTi8toTqc",
"blockchain": "bitcoin",
"expire_block": -1,
"last_txid": "43bbcbd8793cdc52f1b0bd2713ed136f4f104a683a9fd5c89911a57a8c4b28b6",
"satus": "registered_subdomain",
"zonefile_hash": "e7e3aada18c9ac5189f1c54089e987f58c0fa51e",
"zonefile_txt": "TTL 3600\n_file URI 10 1 "file:///tmp/baz.profile.json"\n"
}

使用子域名注册服务运行交互式测试环境

按照这里的说明下载regtesting Docker映像。

由于子域名注册服务运行在端口3000上，我们需要做两件事来公开这个端点，以便从浏览器与它交互:

• 用-p 3000:3000打开端口3000
  下面是启动交互式测试场景时运行的完整命令:

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)