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
# Yarn
$ yarn add --dev soy-core
# NPM
$ npm install --save-dev soy-coreCreate 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 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);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.
Soy consists of a bunch of tools that make hosting distributed web sites easy. They are:
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.
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.
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.
- 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.
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>
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');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) |
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) |
A nod specific resolver
Kind: global class
- Resolver
- new Resolver(domain, resolver)
- .publishRevision(contentHash, [alias], [txOps]) ⇒
Promise.<number> - .contenthash() ⇒
Promise.<string>
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 |
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 |
Get the current contenthash
Kind: instance method of Resolver
Returns: Promise.<string> - current resolver content hash
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>
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 |
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');Please read through our contributing guidelines. Included are directions for coding standards, and notes on development.