soy-core

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

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.INFURA_API_KEY;
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.INFURA_API_KEY;
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.

Packages

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

soy-contracts

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

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

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's main page.

soy-core

The core project contains a friendly js interface to interacting with the deployed contracts of 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])
  • .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]) ⇒ 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])
  • .uploadToIPFSAndPublish(path, domain, [options]) ⇒ 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. Included are directions for coding standards, and notes on development.

License

Apache 2.0