Resolvers

Warning: This document is currently in DRAFT status and therefore may change rapidly and significantly. Do not build production-ready apps based on it yet!

Resolvers return blockchain data via multiple protocols. Currently, two protocols are defined the spec: HTTP(S) (as a RESTful API), and DNS.

The spec adheres to the Guiding Principles outlined in the Appendix.

Table of Contents

• HTTP RESTful API (Draft)
  • Reading and writing to blockchains
  • Resolver information
• DNS API (Draft)
  • TLDs for existing blockchain
  • Records for blockchains
  • metaTLDs (optional)
• Appendix
  • Guiding Principles for resolver API

HTTP RESTful API

All operations are performed via the URL path and query string.

All possible queries that can be performed on a blockchain (both read, write, and delete operations) conform to the following structure:

/{version}/{chain|resolver}/{resource}/{property}/{operation}{resp_format}?{args}

Examples:

https://api.example.com/v1/namecoin/key/id%2Fbob
https://api.example.com/v1/bitcoin/addr/MywyjpyBbFTsHkevcoYnSaifShG2Et8R3S
https://api.example.com/v1/namecoin/key/id%2Fclinton/transfer?to_addr=ea3df...
http://api.example.com/v1/resolver/fingerprint

Unless marked Optional, all parts are required:

• {version}: Specifies the API version. This value should be v1 for now.
• {chain|resolver}: Specifies the full name of the blockchain, or request resolver-specific information.
• {resource}: Blockchains can support different resources that can be queried, but most support the same types of resources. For example, all blockchains (by definition) have a blocks resource. Examples: blocks, txn, txns, addr, key, accounts, contracts.
• {property} (Optional): Specifies a property of a {resource}. Depending on the resource being queried, this can be used to refer to different things. Properties MUST be URL encoded! Example queries:
  • /v1/namecoin/blocks/height - The height of the blockchain (positive integer).
  • /v1/namecoin/addr/MywyjpyBbFTsHkevcoYnSaifShG2Et8R3S - Return information about this address.
• {operation} (Optional): Perform some action on a {resource} or a {property} of a resource. Example queries:
  • /v1/namecoin/key/d%2Fgreatwebsite/transfer - Transfer the key (in this case the domain greatwebsite.bit) to a new owner (specified by {args}).
• {resp_format} (Optional): The response format. Default response format is JSON. Resolvers MUST support .json and MAY support other formats. Examples:
  • /v1/namecoin/blocks/height.xml - Return response in XML instead of JSON.
• {args} (Optional): The URL-encoded arguments to some {operation}. Examples:
  • /v1/namecoin/key/d%2Fgreatwebsite/transfer?to_addr=MywyjpyBbFTsHkevcoYnSaifShG2Et8R3S - Transfers greatwebsite.bit to the owner at the specified address on the Namecoin blockchain.

### Typical resources and operations across blockchains

TBD: actual specs. Can infer from examples.

Data being written SHOULD be placed into the body of the request, following standard POST semantics.

### Resolver-specific information

Resolver-specific functionality MAY be provided should resolvers choose to provide resolver-specific information.

For example, a resolver can provide its TLS fingerprint like so:

• /v1/resolver/fingerprint

TBD: Specify possible resources and their response format.

DNS API (Draft)

TLDs for existing blockchain

If a blockchain has a specification for supporting domain resolution, resolvers MUST support resolving A records for blockchain-associated TLDs if the blockchain has one. Resolvers SHOULD support all of the DNS record types of the blockchain that it supports.

Existing blockchain TLDs are listed below:

TLD	Blockchain
.bit	Namecoin (spec)
.p2p	KeyID aka BitShares DNS (spec)
.eth	Ethereum (spec doesn't exist yet, probably will follow Namecoin)

Note: blockchains should choose TLDs that do not conflict with any existing ICANN TLDs (and ICANN should do the same).

Resolvers conforming to this spec MAY support the .dns metaTLD, and return all queries to this TLD with an A record specifying the resolver's public facing IP address.

Records for blockchains

DNS Record	Blockchain use
TLSA	TBD: fill this in

metaTLDs

metaTLDs are TLDs that resolve to the IP of the resolver itself.

## Appendix #### Guiding Principles for resolver API

1. Agnosticism to maximum extent possible. It would be a detriment to blockchain innovation for us to assume there is a "best" blockchain for doing key/value mappings. That is why this spec supports key/value lookups in a blockchain-agnostic manner. For unique features found only in one blockchain, the API should be designed in a generic way that can be adaptable to other blockchains should they implement said feature.
2. Maximize both simplicity and usability. Start with a simple, solid foundation and build off of it as necessary. Simple requests should have simple formats. Complicated requests should express that complexity in a way that builds off of the simple foundation.
   • In cases where ambiguity exists about the right design decision, both approaches should be implemented and tested in the real-world. Real-world feedback will determine how to proceed.
3. Maximize security and privacy. The API must be queriable over a MITM-proof channel. It must be flexible enough to support arbitrary security protocols and cryptography. To the maximum extent possible, the API should be stateless, and must not leak any unnecessary information or metadata about the connection.
4. All design decisions must have justifications. This improves the quality of the spec by encouraging discussion, and promotes transparency. [1]