Python client to Fullcount contract

.gitignore

@@ -16,3 +16,11 @@ Cargo.lock
 # Foundry stuff
 out/
 cache/
+
+# Brownie stuff
+build/
+
+# Python stuff
+venv/
+.venv/
+.fullcount/

README.md

@@ -1,66 +1,46 @@
-## Foundry
+# Fullcount.xyz
 
-**Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.**
+This repository contains all code related to the Fullcount.xyz autonomous, web3, baseball game.
 
-Foundry consists of:
+## Smart contracts
 
--   **Forge**: Ethereum testing framework (like Truffle, Hardhat and DappTools).
--   **Cast**: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data.
--   **Anvil**: Local Ethereum node, akin to Ganache, Hardhat Network.
--   **Chisel**: Fast, utilitarian, and verbose solidity REPL.
+### Development
 
-## Documentation
+Fullcount uses [Foundry](https://book.getfoundry.sh/) to build and test smart contracts.
 
-https://book.getfoundry.sh/
+We use the [`fullcount` CLI](python/README.md) to deploy and run operations related to the `Fullcount` contract.
 
-## Usage
-
-### Build
+#### Build
 
 ```shell
 $ forge build
 ```
 
-### Test
+#### Test
 
 ```shell
 $ forge test
 ```
 
-### Format
+#### Format
 
 ```shell
 $ forge fmt
 ```
 
-### Gas Snapshots
+#### Gas Snapshots
 
 ```shell
 $ forge snapshot
 ```
 
-### Anvil
-
-```shell
-$ anvil
-```
-
-### Deploy
-
-```shell
-$ forge script script/Counter.s.sol:CounterScript --rpc-url <your_rpc_url> --private-key <your_private_key>
-```
+#### Deployment and operations
 
-### Cast
+Please see [the README for the Fullcount Python client](python/README.md).
 
-```shell
-$ cast <subcommand>
-```
+## Frontend
 
-### Help
+## Game balance and tuning
 
-```shell
-$ forge --help
-$ anvil --help
-$ cast --help
-```
+The [Python client](python/README.md) contains utilities that we use to help tune and balance the
+game across versions.

fullcount_theory/.gitignore → python/.gitignore

@@ -176,4 +176,6 @@ pyrightconfig.json
 # End of https://www.toptal.com/developers/gitignore/api/python
 
 # Virtual environments
-.fullcount_theory/
+venv/
+.venv/
+.fullcount/

python/README.md

@@ -0,0 +1,101 @@
+# Python client for Fullcount.xyz
+
+This directory contains the Python client library for Fullcount.xyz.
+
+All on-chain interactions rely on the existence of `forge` build artifacts in the repository root
+directory -- the client uses the latest ABI, bytecode, etc. from the `out/` directory created
+by `forge build`.
+
+## Installation
+
+To install in a Python environment, run the following commands *from this directory*:
+
+```bash
+export BROWNIE_LIB=1
+pip install -e .
+```
+
+## Usage
+
+The Python client is based on [`brownie`](https://github.com/eth-brownie/brownie).
+
+### In Python
+
+To import the contract into your own code:
+
+```python
+from fullcount.Fullcount import Fullcount
+```
+
+To deploy a fresh instance of the contract:
+
+```python
+from brownie import network, ZERO_ADDRESS
+from fullcount.Fullcount import Fullcount
+
+network.connect("<insert network name here>")
+
+sender = network.accounts.load("<path to account keyfile>", "<account password>")
+
+contract = Fullcount(None)
+contract.deploy(0, 0, ZERO_ADDRESS, 300, {"from": sender})
+```
+
+To interact with an existing deployment:
+
+```python
+from brownie import network
+from fullcount.Fullcount import Fullcount
+
+network.connect("<insert network name here>")
+
+contract = Fullcount("<deployed contract address>")
+print("Number of sessions on contract: ", contract.num_sessions())
+```
+
+### CLI
+
+```
+fullcount -h
+```
+
+## Development
+
+If you want to install developer dependencies:
+
+```bash
+export BROWNIE_LIB=1
+pip install -e .[dev]
+```
+
+To regenerate the Python interface to the `Fullcount` contract:
+
+```bash
+moonworm generate-brownie -o fullcount -p ../ -n Fullcount --foundry
+```
+
+To regenerate the Python interface to the `BeerLeagueBallers` NFT contract:
+
+```bash
+moonworm generate-brownie -o fullcount -p ../ --foundry -n BeerLeagueBallers --sol-filename Players.sol
+```
+
+### Randomness
+
+The `fulltest randomness` command allows you to see the random `uint256` that would be sampled from any
+two nonces.
+
+For example, to check the `uint256` sampled from the pitcher nonce `2384902384` and the batter nonce `98290483902842390482`,
+you would run:
+
+```bash
+fullcount randomness -n 2384902384 -N 98290483902842390482
+```
+
+This produces:
+
+```
+$ fullcount randomness -n 2384902384 -N 98290483902842390482
+Nonce 1: 2384902384, Nonce 2: 98290483902842390482, Denominator: 10000
+Random sample: 6727
+```