ENS+IPFS ❤ DevOps - Static Websites on the Distributed Web

Usage ∙ Packages ∙ API ∙ Contributing ∙ License

Soy is a collection of smart contracts and tools to enable you to build your site on the distributed web. By virtue of using ENS and IPFS your content will be quickly accessible all over the world without having to set up or manage any infrastructure.

Already have an ENS resolver? Add .soy to the end to see it in your browser! Check out [web3studio.eth.soy][web3studio.eth.soy]

Usage

Install

# Yarn
$ yarn add --dev soy-core
NPM
$ npm install --save-dev soy-core

Configure

Create a new soy instance and give it any Web3 provider.

const Soy = require('soy-core');
const HDWalletProvider = require('truffle-hdwallet-provider');
const mnemonic = process.env.WALLET_MNEMONIC; const infuraApiKey = process.env.INFURAAPIKEY; const infuraNetwork = process.env.INFURA_NETWORK; const provider = new HDWalletProvider(   mnemonic,   https://${infuraNetwork}.infura.io/v3/${infuraApiKey} );
const soy = new Soy(provider);

Scripting

Scripting with Soy usually looks something like this. This is an example of creating a new Soy instance and using it to register a domain and publish the contenthash for the site.

const Soy = require('soy-core');
const Web3 = require('web3');
const HDWalletProvider = require('truffle-hdwallet-provider');
// Change these paremeters or pass them in as env variables const mnemonic = process.env.WALLET_MNEMONIC; const infuraApiKey = process.env.INFURAAPIKEY; const infuraNetwork = process.env.INFURA_NETWORK || 'rinkeby'; const contentHash = '/ipfs/QmVyYoFQ8KDLMUWhzxTn24js9g5BiC6QX3ZswfQ56T7A5T'; const domain = 'soyexample.test';
var provider = new HDWalletProvider(   mnemonic,   https://${infuraNetwork}.infura.io/v3/${infuraApiKey} );
(async () => {   const web3 = new Web3(provider);   const accounts = await web3.eth.getAccounts();   const owner = accounts[0];
const soy = new Soy(provider, { from: owner });
const resolver = await soy.registerDomain(domain);   const revision = await resolver.publishRevision(contentHash);
console.log(Revision ${revision} published by Soy!); })().catch(console.log);

View Your Beautiful Site

Once you have ENS set up to point to an ipfs hash, simply add .soy to the ENS domain in your browser. For example, web3studio.eth becomes [web3studio.eth.soy][web3studio.eth.soy].

Packages

Soy consists of a bunch of tools that make hosting distributed web sites easy. They are:

[soy-contracts][soy-contracts]

Contracts contains the source of the solidity contracts and a low level interface for interactions via [truffle-contract][truffle-contract].

For more information, see [soy-contracts][soy-contracts]'s main page.

[soy-gateway][soy-gateway]

The gateway is the source code behind eth.soy. It's a shim to enable browsers to support distributed file systems over ENS until browsers can handle this natively.

For more information, see [soy-gateway][soy-gateway]'s main page.

[soy-core][soy-core]

The core project contains a friendly js interface to interacting with the deployed contracts of [soy-contracts][soy-contracts] enabling you to get your content out there with ease.

API

Classes

Ens

Soy's ENS resolver which caches all results per domain's TTL set by it's resolver.

Resolver

A nod specific resolver

Soy

Soy is the best interface for Soy's smart contracts. It provides an easily scriptable interface for any deployment pattern.

Ens

Soy's ENS resolver which caches all results per domain's TTL set by it's resolver.

Kind: global class

• Ens

- [new Ens(provider, [registryAddress])](#newEnsnew) - .resolver(domain) ⇒ Promise.<SoyPublicResolver> - .getContentHash(domain) ⇒ Promise.<string>

new Ens(provider, [registryAddress])

Constructor

| Param | Type | Description | | ----------------- | ------------------- | ------------------------------------------------- | | provider | Object | A web3@1 provider, defaults to localhost | | [registryAddress] | string | An optional registry address for bespoke networks |

Example (Get the `contenthash` for a domain)

const siteHash = soy.ens.getContentHash('web3studio.eth');

ens.resolver(domain) ⇒ Promise.<SoyPublicResolver>

Gets a resolver contract instance for a registered ENS domain

Kind: instance method of Ens Returns: Promise.<SoyPublicResolver> - Resolver for a domain

| Param | Type | Description | | ------ | ------------------- | ------------------------------- | | domain | string | ENS domain (eg: web3studio.eth) |

ens.getContentHash(domain) ⇒ Promise.<string>

Resolves the contenthash for an ENS domain

Kind: instance method of Ens Returns: Promise.<string> - The contenthash for the ENS domain

| Param | Type | Description | | ------ | ------------------- | ------------------------------- | | domain | string | ENS domain (eg: web3studio.eth) |

Resolver

A nod specific resolver

Kind: global class

• Resolver

- new Resolver(domain, resolver) - [.publishRevision(contentHash, [alias], [txOps])](#Resolver+publishRevision) ⇒ Promise.<number> - .contenthash() ⇒ Promise.<string>

new Resolver(domain, resolver)

Create a unique contract instance with common params filled in. Wraps all methods of SoyPublicResolver and by extension the base PublicResolver without the need to specify a namehashed domain and tedious unit conversions.

truffle-contract is used to generate the interface. For more detailed explanations, see their docs

| Param | Type | Description | | -------- | ------------------------------ | ------------------- | | domain | string | ens domain | | resolver | SoyPublicResolver | A resolver contract |

resolver.publishRevision(contentHash, [alias], [txOps]) ⇒ Promise.<number>

Publishes the content hash as a revision

Kind: instance method of Resolver Returns: Promise.<number> - The revision number

| Param | Type | Description | | ----------- | ------------------- | ------------------------------------- | | contentHash | string | Content hash to publish for your site | | [alias] | string | alias to set for this hash | | [txOps] | Object | web3 transactions options object |

resolver.contenthash() ⇒ Promise.<string>

Get the current contenthash

Kind: instance method of Resolver Returns: Promise.<string> - current resolver content hash

Soy

Soy is the best interface for Soy's smart contracts. It provides an easily scriptable interface for any deployment pattern.

Kind: global class Properties

| Name | Type | Description | | ---- | ----------------- | ---------------------------------------------------------------------------- | | ens | ENS | ENS resolver utility | | web3 | Web3 | web3.js instance | | ipfs | IPFS | ipfs-http-client instance |

• Soy

- [new Soy(provider, [options])](#newSoynew) - [.uploadToIPFSAndPublish(path, domain, [options])](#Soy+uploadToIPFSAndPublish) ⇒ Promise.<{hash: string, rev: number}> - .resolver(domain) ⇒ Promise.<Resolver> - .registerDomain(domain) ⇒ Promise.<Resolver>

new Soy(provider, [options])

Create a new soy instance

| Param | Type | Description | | ------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------ | | provider | Web3.Provider | A Web3 provider instance | | [options] | Object | Soy instance options | | [options.registryAddress] | string | An address for a deployed ENS registry | | [options.resolverAddress] | string | An address for a deploy SoyPublicResolver | | [...options.txOps] | Object | Default transaction arguments passed to web3 |

soy.uploadToIPFSAndPublish(path, domain, [options]) ⇒ Promise.<{hash: string, rev: number}>

Upload the contents of a directory to ipfs and publishes the root folder's hash as a revision

Kind: instance method of Soy Returns: Promise.<{hash: string, rev: number}> - - The hash published and it's revision number

| Param | Type | Description | | --------- | ------------------- | ----------------------------------------------------------------------------------------------- | | path | string | Path to the directory | | domain | string | ENS domain to publish a revision | | [options] | Object | IPFS options |

soy.resolver(domain) ⇒ Promise.<Resolver>

With a registered domain, get a resolver instance for a specific node

Kind: instance method of Soy Returns: Promise.<Resolver> - - A resolver instance

| Param | Type | Description | | ------ | ------------------- | ----------------------- | | domain | string | The domain for the node |

Example (Publish a revision of your site)

const resolver = await soy.resolver('example.madewith.eth');
await resolver.publishRevision(   '/ipfs/QmVyYoFQ8KDLMUWhzxTn24js9g5BiC6QX3ZswfQ56T7A5T' );

soy.registerDomain(domain) ⇒ Promise.<Resolver>

Registers a new domain and sets it's resolver to Soy's PublicResolver contract. This will only need to be done once per (sub)domain

If you haven't done so yet, you will need to purchase a domain. We recommend using My Ether Wallet. Domain auctions will last a week.

Kind: instance method of Soy Returns: Promise.<Resolver> - a resolver instance

| Param | Type | Description | | ------ | ------------------- | ---------------------------- | | domain | string | a new ENS domain to register |

Example (Register an ENS Domain with Soy)

const resolver = await soy.registerDomain('example.madewith.eth');

Contributing

Please read through our [contributing guidelines][contributing]. Included are directions for coding standards, and notes on development.

License

[Apache 2.0][license]

[soy-contracts]: https://github.com/ConsenSys/web3studio-soy/tree/master/packages/soy-contracts [soy-gateway]: https://github.com/ConsenSys/web3studio-soy/tree/master/packages/soy-gateway [soy-core]: https://github.com/ConsenSys/web3studio-soy/tree/master/packages/soy-core [license]: https://github.com/ConsenSys/web3studio-soy/blob/master/packages/soy-core/LICENSE [contributing]: https://github.com/ConsenSys/web3studio-soy/blob/master/packages/soy-core/CONTRIBUTING.md [truffle-contract]: https://github.com/trufflesuite/truffle/tree/next/packages/truffle-contract [web3studio.eth.soy]: https://web3studio.eth.soy