Skip to content

Commit 6c9b06d

Browse files
zomglingszomglings
committed
Updated README
1 parent b23e851 commit 6c9b06d

File tree

7 files changed

+2112
-39
lines changed

7 files changed

+2112
-39
lines changed

‎README.md

+289-5
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,293 @@
1-
# Moonstream Engine
1+
# moonstream-to/web3
22

3-
The API to Moonstream's Game and Economic Engine.
3+
This repository is home to [Moonstream](https://moonstream.to)'s smart contracts. It also contains
4+
a command-line interfaces to those smart contracts.
45

5-
We are in the process of splitting up this repository. The smart contracts and the API server will go into separate repositories under the https://github.com/moonstream-to organization.
6+
## Contracts
67

7-
We will update this documentation once the split is complete.
8+
This repository contains many contracts. Some are immutable and others are implemented using the
9+
[EIP-2535 Diamond, Multi-Facet Proxy standard](https://eips.ethereum.org/EIPS/eip-2535).
10+
11+
Implementation contracts programmed under the EIP-2535 scheme are suffixed with the word `Facet`. These implementation
12+
contracts can be used as part of any `DELEGATECALL` proxy setup.
13+
14+
Wherever possible, we aim to provide immutable, non-proxy implementations of our contracts. If this repository
15+
doesn't contain an immutable implementation of the contract you are interested in, please either [create an
16+
issue](https://github.com/moonstream-to/web3/issues/new) for it or add a comment or reaction to an issue that already exists.
17+
This will help us prioritize the immutable implementations.
18+
19+
We start with proxy implementations as this helps us develop our contracts in an iterative manner using
20+
user feedback. If you have feedback for us, [we are listening](https://discord.gg/K56VNUQGvA)!
21+
22+
### Terminus
23+
24+
Terminus is an access control protocol based on the [ERC-1155 Multi Token standard](https://eips.ethereum.org/EIPS/eip-1155).
25+
26+
<table>
27+
<tr>
28+
<th></th>
29+
<th>Immutable or Upgradable</th>
30+
<th>Deployment</th>
31+
<th>CLI</th>
32+
<th>Solidity interface</th>
33+
<th>ABI</th>
34+
</tr>
35+
<tr>
36+
<td><a href="./contracts/terminus/TerminusFacet.sol"><pre>TerminusFacet</pre></a></td>
37+
<td>Upgradable</td>
38+
<td><pre>web3cli core terminus-gogogo</pre></td>
39+
<td><pre>web3cli terminus</pre></td>
40+
<td><a href="./contracts/interfaces/ITerminus.sol"><pre>ITerminus</pre></a></td>
41+
<td><a href="./abi/TerminusFacet.json"><pre>abi/TerminusFacet.json</pre></a></td>
42+
</tr>
43+
</table>
44+
45+
### Dropper
46+
47+
Dropper is a contract that allows you to distribute tokens to your users, with *them* submitting the
48+
transactions to claim those tokens.
49+
50+
It can distribute ERC20 tokens, ERC721 tokens, and ERC1155 tokens. It can also be used to mint Terminus
51+
tokens using an authorized claim workflow.
52+
53+
<table>
54+
<tr>
55+
<th></th>
56+
<th>Immutable or Upgradable</th>
57+
<th>Deployment</th>
58+
<th>CLI</th>
59+
<th>Solidity interface</th>
60+
<th>ABI</th>
61+
</tr>
62+
<tr>
63+
<td><a href="./contracts/Dropper/DropperFacet.sol"><pre>DropperFacet</pre></a></td>
64+
<td>Upgradable</td>
65+
<td><pre>web3cli core dropper-gogogo</pre></td>
66+
<td><pre>web3cli dropper</pre></td>
67+
<td><a href="./contracts/interfaces/IDropper.sol"><pre>IDropper</pre></a></td>
68+
<td><a href="./abi/DropperFacet.json"><pre>abi/DropperFacet.json</pre></a></td>
69+
</tr>
70+
<tr>
71+
<td><a href="./contracts/Dropper.sol"><pre>Dropper (legacy version)</pre></a></td>
72+
<td>Immutable</td>
73+
<td><pre>web3cli dropper-v1 deploy</pre></td>
74+
<td><pre>web3cli dropper-v1</pre></td>
75+
<td>n/a</td>
76+
<td><a href="./abi/Dropper.json"><pre>abi/Dropper.json</pre></a></td>
77+
</tr>
78+
</table>
79+
80+
### Lootbox
81+
82+
Fully on-chain lootboxes that bundle together multiple tokens. These are implemented as Terminus tokens.
83+
Lootboxes come in two varieties - deterministic and random.
84+
85+
Random lootboxes use decentralized, verifiable randomness to randomize the items that players receive when they open the lootbox.
86+
87+
<table>
88+
<tr>
89+
<th></th>
90+
<th>Immutable or Upgradable</th>
91+
<th>Deployment</th>
92+
<th>CLI</th>
93+
<th>Solidity interface</th>
94+
<th>ABI</th>
95+
</tr>
96+
<tr>
97+
<td><a href="./contracts/Lootbox.sol"><pre>Lootbox</pre></a></td>
98+
<td>Immutable</td>
99+
<td><pre>web3cli lootbox deploy</pre></td>
100+
<td><pre>web3cli lootbox</pre></td>
101+
<td><a href="./contracts/interfaces/ILootbox.sol"><pre>ILootbox</pre></a></td>
102+
<td><a href="./abi/Lootbox.json"><pre>abi/Lootbox.json</pre></a></td>
103+
</tr>
104+
</table>
105+
106+
### Crafting
107+
108+
A fully on-chain crafting mechanic. Administrators of this contract can create recipes - specifying inputs
109+
and outputs.
110+
111+
Players can use those recipes by providing inputs in order to produce outputs.
112+
113+
<table>
114+
<tr>
115+
<th></th>
116+
<th>Immutable or Upgradable</th>
117+
<th>Deployment</th>
118+
<th>CLI</th>
119+
<th>Solidity interface</th>
120+
<th>ABI</th>
121+
</tr>
122+
<tr>
123+
<td><a href="./contracts/crafting/facets/CraftingFacet.sol"><pre>CraftingFacet</pre></a></td>
124+
<td>Upgradable</td>
125+
<td><pre>web3cli core crafting-gogogo</pre></td>
126+
<td><pre>web3cli crafting</pre></td>
127+
<td><a href="./contracts/interfaces/ICrafting.sol"><pre>ICrafting</pre></a></td>
128+
<td><a href="./abi/CraftingFacet.json"><pre>abi/CraftingFacet.json</pre></a></td>
129+
</tr>
130+
</table>
131+
132+
### Garden of Forking Paths
133+
134+
Garden of Forking Paths is a multiplayer choose your own adventure mechanic.
135+
136+
Players stake their NFTs into sessions on the Garden of Forking Paths contract. These NFTs can navigate through
137+
different stages in their current session by choosing paths at each stage. They can earn different rewards
138+
based on the paths they choose.
139+
140+
<table>
141+
<tr>
142+
<th></th>
143+
<th>Immutable or Upgradable</th>
144+
<th>Deployment</th>
145+
<th>CLI</th>
146+
<th>Solidity interface</th>
147+
<th>ABI</th>
148+
</tr>
149+
<tr>
150+
<td><a href="./contracts/mechanics/garden-of-forking-paths/GardenOfForkingPaths.sol"><pre>GOFPFacet</pre></a></td>
151+
<td>Upgradable</td>
152+
<td><pre>web3cli core gofp-gogogo</pre></td>
153+
<td><pre>web3cli gofp</pre></td>
154+
<td><a href="./contracts/interfaces/IGOFP.sol"><pre>IGOFP</pre></a></td>
155+
<td><a href="./abi/GOFPFacet.json"><pre>abi/GOFPFacet.json</pre></a></td>
156+
</tr>
157+
</table>
158+
159+
### Inventory
160+
161+
This implements a fully on-chain inventory system for ERC721 tokens. It allows ERC721 contracts to treat
162+
the blockchain about the source of truth of the state of each token.
163+
164+
Administrators can define the inventory slots that an NFT collection (ERC721 contract) admits. They can
165+
specify which items (ERC20 tokens, ERC721 tokens, ERC1155 tokens) are equippable in each slot.
166+
167+
NFT owners can equip and unequip valid items from each slot.
168+
169+
Games can use the items equipped in a character's inventory to determine their abilities in-game.
170+
171+
<table>
172+
<tr>
173+
<th></th>
174+
<th>Immutable or Upgradable</th>
175+
<th>Deployment</th>
176+
<th>CLI</th>
177+
<th>Solidity interface</th>
178+
<th>ABI</th>
179+
</tr>
180+
<tr>
181+
<td><a href="./contracts/inventory/InventoryFacet.sol"><pre>InventoryFacet</pre></a></td>
182+
<td>Upgradable</td>
183+
<td><pre>web3cli core inventory-gogogo</pre></td>
184+
<td><pre>web3cli inventory</pre></td>
185+
<td><a href="./contracts/inventory/IInventory.sol"><pre>IInventory</pre></a></td>
186+
<td><a href="./abi/InventoryFacet.json"><pre>abi/InventoryFacet.json</pre></a></td>
187+
</tr>
188+
</table>
189+
190+
### StatBlock
191+
192+
`StatBlock` is an on-chain registry for token stats/attributes. Games can publish attribute scores for
193+
various tokens in their economy and these can be used by on-chain and off-chain mechanics to determine
194+
the in-game properites of the in-game representations of those tokens.
195+
196+
<table>
197+
<tr>
198+
<th>Contract name</th>
199+
<th>Immutable or Upgradable</th>
200+
<th>Deployment</th>
201+
<th>CLI</th>
202+
<th>Solidity interface</th>
203+
<th>ABI</th>
204+
</tr>
205+
<tr>
206+
<td><a href="./contracts/stats/StatBlock.sol"><pre>StatBlock</pre></a></td>
207+
<td>Immutable</td>
208+
<td><pre>web3cli statblock deploy</pre></td>
209+
<td><pre>web3cli statblock</pre></td>
210+
<td><a href="./contracts/stats/IStatBlock.sol"><pre>IStatBlock</pre></a></td>
211+
<td><a href="./abi/StatBlock.json"><pre>abi/StatBlock.json</pre></a></td>
212+
</tr>
213+
</table>
214+
215+
## Structure
216+
217+
### Smart contracts
218+
219+
All smart contracts can be found in the [`contracts/`](./contracts/) directory.
220+
221+
Currently, we use [`brownie`](https://github.com/eth-brownie/brownie) to compile and interact with our
222+
smart contracts.
223+
224+
All external dependencies are registered in [`brownie-config.yaml`](./brownie-config.yaml). To learn more
225+
about how to use `brownie`, read the [`brownie` documentation](https://eth-brownie.readthedocs.io/en/latest/).
226+
227+
If you want to help us add [`hardhat`](https://hardhat.org/) or [`foundry`](https://github.com/foundry-rs/foundry)
228+
support, your contributions will be very welcome.
229+
230+
231+
### Command-line interface: `web3cli`
232+
233+
This repository also defines a command-line interface, `web3cli`, to Moonstream smart contracts. `web3cli`
234+
is set up to use the `brownie` build artifacts produced by `brownie compile`. It is intended to be used
235+
*from this repository*.
236+
237+
To install `web3cli`, you will need to set up a Python environment.
238+
239+
To do this, first [install Python 3](https://www.python.org/) (if you don't already have it installed),
240+
and create a virtual environment:
241+
242+
```bash
243+
python3 -m venv .web3
244+
```
245+
246+
Then, install `web3cli` by running the following command from the root of this repository:
247+
248+
```bash
249+
export BROWNIE_LIB
250+
pip install -e cli/
251+
```
252+
253+
Once this is finished:
254+
255+
```
256+
$ web3cli --help
257+
usage: web3cli [-h] {core,flows,dropper-v1,dropper,lootbox,erc20,erc721,drop,terminus,crafting,gofp,setup-drop,predicates,inventory,statblock} ...
258+
259+
dao: The command line interface to Moonstream DAO
260+
261+
positional arguments:
262+
{core,flows,dropper-v1,dropper,lootbox,erc20,erc721,drop,terminus,crafting,gofp,setup-drop,predicates,inventory,statblock}
263+
predicates Predicates for use with Moonstream game mechanics
264+
265+
options:
266+
-h, --help show this help message and exit
267+
```
268+
269+
### ABIs
270+
271+
The [`abi/`](./abi/) directory contains current ABIs for all the smart contracts in this repository. You
272+
can use these ABIs to generate interfaces to any deployed Moonstream contract.
273+
274+
275+
### Tests
276+
277+
All tests are currently in the [`cli/web3cli/`](./cli/web3cli/) directory. Just look for files matching
278+
`test_*.py`.
279+
280+
You can run tests using [`cli/test.sh`](./cli/test.sh). For example, to run Dropper tests, you would invoke
281+
the following command (from the root of this repo):
282+
283+
```bash
284+
cli/test.sh web3cli.test_dropper
285+
```
286+
287+
Tests are executed against a [local Ganache network](https://github.com/trufflesuite/ganache). You will need
288+
to use [Node JS](https://nodejs.org/en) to install Ganache:
289+
290+
```bash
291+
npm install --global ganache-cli
292+
```
8293

9-
In the mean time, you can view the [Moonstream documentation](https://docs.moonstream.to).

0 commit comments

Comments
 (0)