v1 Architecture

[barlock]

Overview

Hyperlane's goal is to allow for user friendly static-hosted websites to be served via a distributed storage provider (IPFS initially). While providing friendly domain names for users, it also gives developers flexibility to perform expected DevOps dances like blue/green deploys, dark launches, timed releases, split testing, and slow rollouts to name a few.

Hyperlane:

• is a collection of ens smart contract resolvers
• is a handle cli to make updates easy
• is DevOps and a-b, split testing friendly
• has user friendly domain names
• is distributed, resilient, never going down
• is a static web server (maybe)
• is a gateway to ipfs (maybe)
• allows for custom domains
• uses TLS (https)

How it works

ENS Resolvers

All of the "magic" happens in these bespoke resolvers. ENS is similar to DNS in that you have nested domains *.*.eth where every nested level is it's own smart contract. Smart contracts are programmable! See where this is going?

The hyperlane ens resolvers allows developers to choose which revision of their site is sent to users with smart contracts. For the most part, these resolvers will be standardized and provided by hyperlane, but community developers with the right motivation could create their own or contribute back new features. In fact, this allows more complex features to be added to the platform progressively as all you need to do is upgrade existing resolvers.

The default resolver will perform the following:

• All new revisions will be stored permanently in a subdomain following <rev_number>.*.hyperlane.eth
  • These revisions will be accessible permanently at <rev_number>.*.hyperlane.io
  • revision 0 will, by default, point to an "instruction/it works" page with getting started for quick onboarding.
• The top level domain *.hyperlane.eth will be the "public" version that will default to latest revision
• top level domain can be overridden with another smart contract for more advanced configuration
  • This is how things like b/g deploys, split testing, and rollouts can be done across revisions
• Custom alias/subdomains can be made for revisions
  • Allows for human readable routing and abstractions, like creating a "blue" and a "green" alias that the top level router knows how to handle

CLI

A CLI (likely installed as a global npm dependency) will be provided to act as an abstraction away from the smart contract setup and implementation. Assuming a robust and feature rich set of default smart contracts, your average user will only need to register a subdomain of hyperlane.eth by deploying a set of contracts that they will own, and then interacting with them.

The CLI will provide that interface while allowing advanced usages of forking and overwriting default contract behavior.

Upgradability and migrations across cli/smart contract versions will be important to take into consideration.

Possible Examples:

Deploy a new version of your website from your build directory

$ hyperlane publish ./build/out

Change which alias gets default traffic

$ hyperlane set-public-alias green

Perform a blue green deploy, with a contract set to use the alias green instead of latest

# Publish new version aliased as `blue`
$ hyperlane publish ./build/out --alias blue
# run your integration tests
$ yarn integration blue.websitename.hyperlane.io
# swap your blue and green alias so that the newly deployed `blue` is now `green`
$ hyperlane swap-alias blue green

The Gateway

Edit: Still under investigation if needed, eth.show and .luxe domains might be able to solve this natively.

The gateway's goal is to fill a hole in the existing ecosystem. Natively, browsers don't know how to handle

When a user visits a hyperlane website the gateway will:

1. Map the host to a ENS record.
   • Either via subdomains or a _dnslink DNS text entry for custom domains
   • Cloudflare as _dnslink inspiration
2. Resolve the ENS record to a content hash, eg. /ipfs/QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco.
3. Proxies the request through an IPFS gateway.
   • Likely infura at first, moving to nearby self-hosted caching node later for speed

For immutable content types (js, css, images) a file with a format like bundle.<contentHash>.js or with a query bundle.js?hash=<contentHash> will be short circuited to the IPFS gateway.

[hadasz]

Hey, good write up. A few questions:
-What is the process for storing new revisions in their associated sub domains? Is this done automatically? What entails a new revision?
-Why are smart contracts needed here? What is the justification for including the mainnet in this process?
-How, exactly, will the smart contract map revisions to their subdomains? Based off this line, The hyperlane gateway functionally allows developers to choose which revision of their site (defined by a top level ipfs folder content hash) with smart contracts., it seems like the smart contract will store a mapping of revision to ipfs hash. Is that correct?

[barlock]

Some background: The smart contracts are ENS resolvers. Their role is to map an ens record to a contentHash EIP-1577.

After pitching this to john in person and seeing your questions I'm realizing that I'm telling the story wrong, so I'm going to rewrite the OP. BUT:

What is the process for storing new revisions in their associated sub domains?

Interacting with the ENS resolver/smart contract. Not sure what the ABI is, but it will probably be something like resolver.publishRevision(contentHash).

Is this done automatically?

The CLI is an interface for this. So what I imagine the CLI doing is something like:

$ hyperlane publish ./build/out

This will publish the ./build/out directory to IPFS and call whatever the abi is resolver.publishRevision(contentHash)

What entails a new revision?

Any change to the static content

Why are smart contracts needed here?

It's how ENS works. Every "domain" is a smart contract that either resolves to a value and can nest (every level of the domain path is a new smart contract) to another smart contract to handle the lower path. Check the ENS introduction

What is the justification for including the mainnet in this process?

Also just how ENS works. Now, why am I using ENS? It's the evolving standard for how this is going to work. Sense writing originally, I've discovered https://eth.show which is, if not exactly, the gateway I described above. @humbitious didn't like the idea of "needing to hit mainnet for every request" but you can do a few things to limit the load like cache results (with a ttl like normal dns) or, all of these functions to resolve are views so you don't necessarily need a whole node to do the calculations, the js evm can run it so long as it has the state, drizzle/truffle does this for .call. The "right" way to cache it isn't perfectly clear to me yet. I need to play with a few implementations and check speed/memory.

How, exactly, will the smart contract map revisions to their subdomains?

Let me try to answer this with an example. Let me know if this isn't clear still. Let's assume we have a website, named foo, with 3 revisions. We're using simple logic where the main resolver will send the latest version. I believe there will be 4 smart contracts here, but I need to double check if it could be done with one. (only about 90% clear on ens resolver implementations).

Here's a mapping of possible ways to get to your website:

URL	ens	note
1.foo.hyperlane.io	1.foo.hyperlane.eth	user sees revision 1
2.foo.hyperlane.io	2.foo.hyperlane.eth	user sees revision 2
3.foo.hyperlane.io	3.foo.hyperlane.eth	user sees revision 3
foo.hyperlane.io	foo.hyperlane.eth	user sees revision 3

Another thing we can do is map foo.hyperlane.io to a custom domain name, say foo.io. To do that, we'd need to create a dns txt record on _dnslink.foo.io to point to foo.hyperlane.eth and a CNAME of foo.iotofoo.hyperlane.io` and the gateway will do the mapping based on that standard.

it seems like the smart contract will store a mapping of revision to ipfs hash. Is that correct?

Yes, the smart contract(s) will contain a bunch of mappings actually that, through ENS, instructs the gateway which files to serve.

[humbitious]

Do any of the other alternatives use mainnet smart contracts to handle the conditionals like, if parameter x then give back IPFS hash y, else z?

"Smart contracts are programmable! See where this is going?"

[barlock]

I haven't been able to find anyone attempting to write ENS resolvers with this complex of logic.

The reference contract that people use is just a key-value mapping.

The ENS spec also doesn't include parameters to be passed down. This current architecture and existing gateways don't support that, but I have thought it could be nea, powerful, and also backwards compatible.