Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/consensys/web3studio-soy
Static Websites on the Distributed Web
https://github.com/consensys/web3studio-soy
devops ens ipfs ipfs-gateway web3studio-soy
Last synced: about 2 months ago
JSON representation
Static Websites on the Distributed Web
- Host: GitHub
- URL: https://github.com/consensys/web3studio-soy
- Owner: Consensys
- Created: 2018-11-26T17:55:29.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2023-04-10T14:04:25.000Z (over 1 year ago)
- Last Synced: 2024-11-14T15:12:13.681Z (about 2 months ago)
- Topics: devops, ens, ipfs, ipfs-gateway, web3studio-soy
- Language: JavaScript
- Homepage: https://medium.com/web3studio/soy-is-the-secret-sauce-for-the-unstoppable-web-6e2c1f37430b
- Size: 549 KB
- Stars: 33
- Watchers: 14
- Forks: 5
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
Awesome Lists containing this project
README
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](https://ens.domains/) and
[IPFS](https://ipfs.io/) 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
```bash
# 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.
```js
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.
```js
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][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](#Ens)
- [new Ens(provider, [registryAddress])](#new_Ens_new)
- [.resolver(domain)](#Ens+resolver) ⇒ Promise.<SoyPublicResolver>
- [.getContentHash(domain)](#Ens+getContentHash) ⇒ 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)_
```js
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](#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](#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](#Resolver)
- [new Resolver(domain, resolver)](#new_Resolver_new)
- [.publishRevision(contentHash, [alias], [txOps])](#Resolver+publishRevision) ⇒ Promise.<number>
- [.contenthash()](#Resolver+contenthash) ⇒ Promise.<string>
#### new Resolver(domain, resolver)
Create a unique contract instance with common params filled in.
Wraps all methods of [SoyPublicResolver](https://github.com/ConsenSys/web3studio-soy/blob/master/packages/soy-contracts/contracts/SoyPublicResolver.sol)
and by extension the base [PublicResolver](https://github.com/ensdomains/resolvers/blob/master/contracts/PublicResolver.sol)
without the need to specify a namehashed domain and tedious unit conversions.
[`truffle-contract`](https://github.com/trufflesuite/truffle/tree/next/packages/truffle-contract)
is used to generate the interface. For more detailed explanations, see their
[docs](https://truffleframework.com/docs/truffle/getting-started/interacting-with-your-contracts)
| 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](#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](#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](#ens) resolver utility |
| web3 | Web3 | [web3.js](https://web3js.readthedocs.io/en/1.0/) instance |
| ipfs | IPFS | [ipfs-http-client](https://github.com/ipfs/js-ipfs-http-client#api) instance |
- [Soy](#Soy)
- [new Soy(provider, [options])](#new_Soy_new)
- [.uploadToIPFSAndPublish(path, domain, [options])](#Soy+uploadToIPFSAndPublish) ⇒ Promise.<{hash: string, rev: number}>
- [.resolver(domain)](#Soy+resolver) ⇒ [Promise.<Resolver>](#Resolver)
- [.registerDomain(domain)](#Soy+registerDomain) ⇒ [Promise.<Resolver>](#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](https://web3js.readthedocs.io/en/1.0/web3-eth.html#sendtransaction) 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](#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](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/FILES.md#addfromfs) |
#### soy.resolver(domain) ⇒ [Promise.<Resolver>](#Resolver)
With a registered domain, get a resolver instance for a specific node
**Kind**: instance method of [Soy](#Soy)
**Returns**: [Promise.<Resolver>](#Resolver) - - A resolver instance
| Param | Type | Description |
| ------ | ------------------- | ----------------------- |
| domain | string | The domain for the node |
**Example** _(Publish a revision of your site)_
```js
const resolver = await soy.resolver('example.madewith.eth');
await resolver.publishRevision(
'/ipfs/QmVyYoFQ8KDLMUWhzxTn24js9g5BiC6QX3ZswfQ56T7A5T'
);
```
#### soy.registerDomain(domain) ⇒ [Promise.<Resolver>](#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](https://www.myetherwallet.com/#ens).
Domain auctions will last a week.
**Kind**: instance method of [Soy](#Soy)
**Returns**: [Promise.<Resolver>](#Resolver) - a resolver instance
| Param | Type | Description |
| ------ | ------------------- | ---------------------------- |
| domain | string | a new ENS domain to register |
**Example** _(Register an ENS Domain with Soy)_
```js
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