soy-core

    1.1.0 • Public • Published



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

    UsagePackagesAPIContributingLicense

    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

    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

    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

    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

    Keywords

    Install

    npm i soy-core

    DownloadsWeekly Downloads

    2

    Version

    1.1.0

    License

    Apache-2.0

    Unpacked Size

    53.5 kB

    Total Files

    15

    Last publish

    Collaborators

    • web3studio-bot
    • hadasz
    • barlock
    • breakpointer