What is Polywrap?
Polywrap is a cross-chain development platform that enables easy integration of web3 protocols into any application. It's a middleware that makes it possible for software on any device, written in any language, to readfrom and write data to web3 protocols running as smart contracts on any supported blockchain.
At Blockwatch Data, we are working on tools that make it easier for Tezos developers to interact with the Tezos blockchain. Polywrap is a great choice of middleware to do so. Polywrap-powered apps download lightweight WebAssembly (WASM) modules from IPFS at runtime and execute GraphQL requests directly inside the app. Developers no longer have to deal with the differences and details of wallets, transactions, or data formats of each blockchain.
To support Tezos in Polywrap, we've built a core Tezos plugin and a set of Polywrappers for different dapps and smart contracts such as Tezos Domains, Harbinger Oracles, Hic et Nunc, and QuipuSwap. We provide these examples to show teams building on Tezos how to build their own Polywrappers for their projects, which allows any developer to easily interface with their project from within any application.

Why Polywrap

The way Web3 works today is that developers import custom SDKs from DeFi, NFT, or DAO protocols directly into their apps and ship these SDKs on deployment. This approach, inherited from Web2 workflows, creates several drawbacks for a decentralized trust-less system:
  • traditional SDKs are limited to a specific programming language so that devs are locked to the SDK's choice
  • the web2 model of importing dependencies at the library/source-code level has proven to be insecure and bulky
  • current web3 SDKs are incompatible across blockchains and it is unnecessarily complicated for an app developer to interact with different APIs for reading account states, talking to wallets, sending transactions etc.

How Polywrap works

Polywrap turns Web3 protocol clients into dynamically loadable WASM modules with a standardized and discoverable GraphQL interface. Modules, also called Polywrappers, are loaded into web3 apps via a chain of trust starting at an on-chain name resolution system like ENS or Tezos Domains where a module's name and content hash are registered. After lookup, the compiled Polywrapper is loaded from a trust-less content delivery system like IPFS.
On-chain name registry and content hash are trust anchors that improve app security while WASM serves as a common abstraction layer to separate development language from host language.
Polywrappers can be written in any language that compiles to WASM (AssemblyScript and Typescript are supported, Rust and Go are in preparation). A host app interacts with a Polywrapper by executing GraphQL requests to either query or mutate the state of a web3 protocol. It's important to know that as of now Polywrappers are entirely state-less: all state is stored on-chain and the Polywrapper just forwards read and write operations in the correct format.

Polywrap Architecture

Polywrap supports WASM modules and native Typescript plugins to extend its functionality to multiple blockchains.
Plugins are blockchain clients that provide core functionality to interact with a chain such as reading data and sending transactions via its native RPC interface. Plugins are implemented in JavaScript/TypeScript and loaded into a Web3 host application directly.
Modules are wrappers for Web3 protocols that are deployed as WASM binaries which can be loaded on-demand by an application. Each module wraps a specific contract (or family of contracts) such as a DeFi DEX or an NFT marketplace.
Modules are versioned and are deployed on IPFS using IPFS directories. For example, our Harbinger module supporting a simple query interface looks as follows when deployed:
$ ipfs ls /ipfs/QmWrsFgVjawH33gktoymKWSFidxHRTWtTnRZabGweXLVDw/harbinger
bafybeidlwyircp4hyizvtmhg6mccfhp2r2kw2svppzmyz56odskkkysymu 85269 query.wasm
bafybeihfimo47a7okgxvozuouacofy2pwk6qgtmun6ka5sq243de6ef77m 4653 schema.graphql
bafybeic5e7p6vd6jxrzvwwkyb43qglexndtj26bjk7prb3hk62ahmbwqc4 127 web3api.build.yaml
bafybeigaathap3brzmb6m76so6xrg6d4ckuxgwktcmkjahe3cbtzxpdwme 260 web3api.yaml
Each deployed Polywrap module consists of multiple files, one or two WASM files with compiled code for query and mutation functions, a GraphQL interface definition, and Polywrap configuration files. To load the module into from a single URI, Polywrap uses IPFS directories, i.e. immutable containers that link to their content. The IPFS directory hash may be used directly for loading the module or can be registered as metadata on a Tezos or ENS domain such as e.g. w3://ens/v2.uniswap.web3api.eth. Both options are supported by our core Polywrap plugin for Tezos.
Polywrappers describe their interface with a GraphQL schema definition that provides types and parameters for contract calls to a Web3 protocol. All business logic to read state and prepare/send contract calls (e.g. buy a Tezos domain or swap on Quipswap) is implemented within the WASM module.
Polywrap distinguishes between functions that either query the protocol's state (which may result in reading on-chain storage or calling on-chain or off-chain views) and functions that mutate a protocol's state by sending contract calls. Query and mutation functions are hosted in two different Polywrappers. From the side of a host app all interactions with a Polywrapper look like regular (async) function calls. Internally, Polywrap calls into the WASM modules to handle protocol-specific logic including the construction of transactions and their signing process behind the scenes.