Polywrap Version Registry (PWVR) URIs

Today @Jure and I spoke about how the Polywrap URI standards / syntax will change with the addition of the Polywrap Version Registry. After doing some additional research, I’d like to present our findings to the group.

Polywrap Version Registry Details

In the Polywrap Version Registry (PWVR) contracts, the following hierarchical identifiers are used:

  • Domain Registry: Domain name system, such as “ENS”
  • Organization: Organization within the domain registry, such as “uniswap.eth”
  • Package: Package within the organization, such as “swap”
  • Version: Version of a package, such as “1.2.3”

Putting them all together, in order to identify a single package within the registry, you must specify <domain> + <organization> + <package> + <version>.

For example, /ens/uniswap.eth/swap@1.2.3 would have all necessary identifiers to lookup a polywrap package.

NOTE: the characters used to separate the identifiers above ("/", “@”) is still TBD. They should comply with The URI Standard, or whatever extension we specify on-top of the base standard.

Current Polywrap URI Standard

Currently, a Polywrap URI support 3 different identifiers based on The URI standard:
<protocol>://<authority>/<path>

  • Protocol / Scheme: The resolution protocol to be used. For Polywrap, we use w3:// (Web3API). After the source-code gets rebranded, this will likely become wrap://.
  • Authority: The authority that dictates how to lookup the URI’s path. For example /ens/, /ipfs/ and /fs/ are 3 URI authorities that can be supported with the Polywrap client given you’ve configured the corresponding plugins (which implement the uri-resolver interface).
  • Path: A path that specifies where to find the Polywrap package. For example domain.eth would be a valid path that the /ens/ authority could lookup.

Some example URIs using the Polywrap URI Standard:
w3://ens/domain.eth
w3://ens/sub.domain.eth
w3://ens/rinkeby/sub.domain.eth
w3://ipfs/Qma5utYHSgP9zatDjByeUULDk4efAMxSB5mKs7GaD5woJj
w3://fs/home/directory/polywrap/build

In order to help improve the developer experience, some parts of the URIs can be optional. Currently w3:// is optional, and if no network is specified after /ens/ mainnet is assumed.

PWVR URIs Implementation

Let’s now look at how we can support the PWVR’s functionality, using the existing Polywrap URI Standard.

We need to be able to account for:

  • Registry deployments on multiple chains.
  • All package identifiers (domain registry, organization, package, version).
  • Sane defaults, allowing for an easier developer experience.

After looking into a few options, my suggestion is the following:

  1. Support wrap as a new URI authority.
  2. Support /wrap/<network>/ as an optional identifier so you can address registry deployments on other chains. Default is Ethereum mainnet.
  3. Package identifiers will be appended to the URI’s path /wrap/<domain>/<organization>/<package>=<version>. For example /wrap/ens/uniswap.eth/swap=1.1.1 would be valid. Here in order to support versions, we’re using the = character. The = character is a reserved character when used within a URI’s path (see The URI Standard).
  4. The /wrap/ can be made a “sane default” if the = character is used within the path AND the first path segment found (after an optional /<network>/) is an identifier of a supported Domain Registry (ex: /ens/).

An example URI might look like:

  • wrap://wrap/mainnet/ens/domain.eth/package=1.2.3

And when utilizing the “sane defaults”, the developer experience could look like:

  • /wrap/mainnet/ens/domain.eth/package=1.2.3
  • /mainnet/ens/domain.eth/package=1.2.3
  • /ens/domain.eth/package=1.2.3

NOTE: All of the above are equivalent to the first example wrap://wrap/mainnet/ens/domain.eth/package=1.2.3.

The above additions to the standard should not effect existing URIs, as described in the Current Polywrap URI Standard section.

References

The URI Standard - https://www.ietf.org/rfc/rfc2396.txt
Naming Authorities in the Java Security Service Module - Naming Authority