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.
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>.
/email@example.com 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.
Currently, a Polywrap URI support 3 different identifiers based on The URI standard:
Protocol / Scheme: The resolution protocol to be used. For Polywrap, we use
w3://(Web3API). After the source-code gets rebranded, this will likely become
Authority: The authority that dictates how to lookup the URI’s path. For example
/fs/are 3 URI authorities that can be supported with the Polywrap client given you’ve configured the corresponding plugins (which implement the
Path: A path that specifies where to find the Polywrap package. For example
domain.ethwould be a valid path that the
/ens/authority could lookup.
Some example URIs using the Polywrap URI Standard:
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.
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:
wrapas a new URI authority.
/wrap/<network>/as an optional identifier so you can address registry deployments on other chains. Default is Ethereum mainnet.
- Package identifiers will be appended to the URI’s path
/wrap/<domain>/<organization>/<package>=<version>. For example
/wrap/ens/uniswap.eth/swap=1.1.1would be valid. Here in order to support versions, we’re using the
=character is a reserved character when used within a URI’s path (see The URI Standard).
/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:
An example URI might look like:
And when utilizing the “sane defaults”, the developer experience could look like:
NOTE: All of the above are equivalent to the first example
The above additions to the standard should not effect existing URIs, as described in the Current Polywrap URI Standard section.