Skip to content

Commit

Permalink
Update subgraph docs (#4)
Browse files Browse the repository at this point in the history 
- Update subgraph documentation and configuration
- Add and update scripts in `package.json` for various environments
- Upgrade dependencies
- Adjust subgraph build command name




---------

Signed-off-by: Mills <37815163+0xMillz@users.noreply.github.com>
  • Loading branch information
@0xMillz
0xMillz authored Dec 4, 2024
1 parent 6bdfa20 commit 9ef5f4b
Show file tree
Hide file tree
Showing 13 changed files with 352 additions and 525 deletions.
257 changes: 105 additions & 152 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,152 +1,105 @@
# Nouns Builder monorepo

This is Nouns Builder front-end mono-repo. You can find Nouns Builder deployed on:

- [Mainnet](//nouns.build)
- [Goerli testnet](//testnet.nouns.build)

For an introduction to Nouns Builder and its concept, you can find further [documentation here](https://docs.zora.co/docs/smart-contracts/nouns-builder/intro). You can also find [Nouns Protocol here](https://github.com/ourzora/nouns-protocol).

### Apps and packages in this repository include:

`apps`

- `web`: Nouns Builder front-end
- `subgraph`: Nouns Builder subgraph

`packages`

- `blocklist`: Package to check for sanctioned wallet addresses
- `analytics`: Shareable analytics package
- `zoralabs-zord`: Shareable ui components
- `eslint-config-custom`: `eslint` configurations (includes `eslint-config-next` and `eslint-config-prettier`)
- `tsconfig`: `tsconfig.json`s used throughout the monorepo
- `ipfs-service`: api to for image uploads to ipfs

## Quickstart

#### Get up and running

1. Clone this repo locally
2. [Install pnpm](https://pnpm.io/installation#using-corepack)

3. Add the required [environment variables](#environment-variables)

4. Install dependencies across all apps and packages

```
pnpm i
```

5. Once environment variables are defined, you can run the app in dev mode

```
pnpm dev
```

#### Linting and formatting

> Note: linting and prettier formatting are automatically run on pre-push hooks
To lint:

```
pnpm run lint
```

To format:

```
pnpm run format
```

To run type checks:

```
pnpm run type-check
```

#### To create and run a production build

```
> pnpm run build
> pnpm run start
```

## Environment variables

This app has several third party api keys that you need in order to run Builder:

- [alchemy](https://www.alchemy.com/) as the main rpc node provider in addition to mainnet forks for testing
- [tenderly](https://docs.tenderly.co/simulations-and-forks/simulation-api) in order to simulate transactions
- [etherscan](https://docs.etherscan.io/api-endpoints/contracts) to dyanamically fetch abis

We ask that you supply your own secrets locally for running in development environment. Non-secret environment variables are already included in the `.env` files in this repo.

Add the following variables to `.env.local` within this root directory (needed to run tests against a local anvil node):

```
#alchemy
PRIVATE_ALCHEMY_ID=<ALCHEMY_API_KEY>
ANVIL_FORK_URL=https://eth-mainnet.alchemyapi.io/v2/$PRIVATE_ALCHEMY_ID
ANVIL_BLOCK_NUMBER=8305745
```

Add the following variables to `apps/web/.env.local`:

```
#alchemy
NEXT_PUBLIC_TENDERLY_RPC_KEY=<ALCHEMY_API_KEY>
#tenderly
TENDERLY_ACCESS_KEY=<API_KEY>
TENDERLY_PROJECT=<PROJECT_NAME>
TENDERLY_USER=<ACCOUNT_NAME>
#etherscan (optional to run locally, this is for dynamically fetching abis in the custom transaction builder)
ETHERSCAN_API_KEY=<ETHERSCAN_API_KEY>
#optional zora api key
NEXT_PUBLIC_ZORA_API_KEY=
```

## Running tests

> Note: to run tests you need to [install anvil](https://github.com/foundry-rs/foundry/blob/master/README.md#installation).
Once anvil is installed, you can now locally run anvil (from the root directory in the monorepo) in a separate terminal session to start a local ethereum node:
`pnpm run anvil`

Now you can run the tests in a separate terminal session:
`pnpm run test`

You can also run the tests in watchmode, which will react to any source code or test files changing. To do that, run:
`pnpm run test:watch`

## Deployments

### Client

The Nouns Builder client is deployed on [Vercel](https://vercel.com/). Any pull requests will trigger a new preview deployment providing you with an environment to test out and preview changes.

### Subgraph

The Nouns Builder subgraph is deployed for the following networks:

- [Ethereum Mainnet](https://api.thegraph.com/subgraphs/name/neokry/nouns-builder-mainnet)
- [Ethereum Goerli](https://api.thegraph.com/subgraphs/name/neokry/nouns-builder-goerli)
- [Optimism Mainnet](https://api.thegraph.com/subgraphs/name/neokry/noun-builder-optimism-mainnet)
- [Optimism Goerli](https://api.thegraph.com/subgraphs/name/neokry/nouns-builder-optimism-goerli)
- [Zora Mainnet](https://api.goldsky.com/api/public/project_clkk1ucdyf6ak38svcatie9tf/subgraphs/nouns-builder-zora-mainnet/stable/gn)
- [Zora Goerli](https://api.goldsky.com/api/public/project_clkk1ucdyf6ak38svcatie9tf/subgraphs/nouns-builder-zora-testnet/stable/gn)
- [Base Mainnet](https://api.goldsky.com/api/public/project_clkk1ucdyf6ak38svcatie9tf/subgraphs/nouns-builder-base-mainnet/stable/g)
- [Base Goerli](https://api.studio.thegraph.com/query/49279/nouns-builder-base-goerli/version/latest)

## Contributions

Please refer to our [contributions guideline](/.github/contributing.md) on how best to contribute.

## Questions?

Feel free to reach out to us via [twitter](https://twitter.com/nounsbuilder), [discord](https://discord.gg/JpMKps2W), or via email at <opensource@zora.co>
# Nouns Builder Subgraph

## Index
- [Getting Started](#getting-started)
- [Step 1 - Install Dependencies](#step-1---install-dependencies)
- [Step 2 - Set Up a Personal Goldsky API Key](#step-2---set-up-a-personal-goldsky-api-key)
- [Step 3 - Log in with the API Key](#step-3---log-in-with-the-api-key)
- [Step 4 - Build the Subgraph from Source](#step-4---build-the-subgraph-from-source)
- [Step 5 - Deploy the Subgraph to Production](#step-5---deploy-the-subgraph-to-production)
- [Step 6 - Query the Subgraph](#step-6---query-the-subgraph)
- [Production Endpoints](#production-endpoints)
- [(DEPRECATED) Local Development with Docker Compose (TODO: fix - pnpm create:local step not working)](#local-development-with-docker-compose)

## Getting Started
👉 [Read the Goldsky docs](https://docs.goldsky.com/subgraphs/deploying-subgraphs)

The Nouns Builder subgraph supports eight networks:
- `ethereum`
- `ethereum-sepolia`
- `base`
- `base-sepolia`
- `optimism`
- `optimism-sepolia`
- `zora`
- `zora-sepolia`

### Step 1 - Install Dependencies
Navigate to the subgraph directory and run:
```bash
# FROM: ./apps/subgraph
pnpm install
```

### Step 2 - Set Up a Personal Goldsky API Key
1. Request to join the team account at [goldsky.com](https://goldsky.com).
2. Create an API key on your Settings page.
3. Install the Goldsky CLI:
```bash
curl https://goldsky.com | sh
```

### Step 3 - Log in with the API Key
Use the API key you created:
```bash
# FROM: ./apps/subgraph
goldsky login
```

### Step 4 - Build the Subgraph from Source
Run the following commands (these scripts are defined in `package.json`):
```bash
# FROM: ./apps/subgraph
pnpm prepare:<desired network>
pnpm codegen
pnpm build
```

This will generate types, build the subgraph, and create a local `subgraph.yaml` file.

### Step 5 - Deploy the Subgraph to Production

#### IMPORTANT:
**To avoid downtime during upgrades, maintain a backup subgraph. If issues arise, you can redirect traffic to the backup rather than waiting for redeployment or rollback, which can take hours.**

- The subgraph name follows the pattern `nouns-builder-<network>` regardless of version, don't clients do not need to be notified for non-breaking changes.
- Increase the `specVersion` at the top of `subgraph.yaml.mustache` for each new version.
- Use the **--tag** flag to alias `latest` with the current `specVersion`.
- If you are making breaking changes, make sure to notify clients first and provide a migration path.
**Always remember to tag!**
```bash
# FROM: ./apps/subgraph
# Example with specVersion 0.0.6
goldsky subgraph deploy nouns-builder-<network>/0.0.6 --path .
goldsky subgraph tag create nouns-builder-<network>/0.0.6 --tag latest
# API endpoint format will be: api.goldsky.com/api/public/<project name>/subgraphs/nouns-builder-ethereum-sepolia/latest/gn
```
### Step 6 - Query the Subgraph
You can now query the subgraph in the Goldsky GraphQL playground to test your changes. **Note: Full indexing may take several hours.**
## Production Endpoints
The subgraph is currently deployed to the following networks:
- [Ethereum](https://api.goldsky.com/api/public/project_cm33ek8kjx6pz010i2c3w8z25/subgraphs/nouns-builder-ethereum/latest/gn)
- [Ethereum Sepolia](https://api.goldsky.com/api/public/project_cm33ek8kjx6pz010i2c3w8z25/subgraphs/nouns-builder-ethereum-sepolia/latest/gn)
- [Optimism](https://api.goldsky.com/api/public/project_cm33ek8kjx6pz010i2c3w8z25/subgraphs/nouns-builder-optimism/latest/gn)
- TODO: [Optimism Sepolia](https://api.goldsky.com/api/public/project_cm33ek8kjx6pz010i2c3w8z25/subgraphs/nouns-builder-optimism-sepolia/latest/gn)
- TODO: [Zora](https://api.goldsky.com/api/public/project_cm33ek8kjx6pz010i2c3w8z25/subgraphs/nouns-builder-zora/latest/gn)
- TODO: [Zora Sepolia](https://api.goldsky.com/api/public/project_cm33ek8kjx6pz010i2c3w8z25/subgraphs/nouns-builder-zora-sepolia/latest/gn)
- TODO: [Base](https://api.goldsky.com/api/public/project_cm33ek8kjx6pz010i2c3w8z25/subgraphs/nouns-builder-base/latest/gn)
- TODO: [Base Sepolia](https://api.goldsky.com/api/public/project_cm33ek8kjx6pz010i2c3w8z25/subgraphs/nouns-builder-base-sepolia/latest/gn)
## (DEPRECATED) Local Development with Docker Compose (TODO: fix - pnpm create:local step not working)
- Generate the subgraph.yml file with `pnpm prepare:<desired network>`
- Generate types with `pnpm codegen`
- Build the subgraph with `pnpm build`
- Run the local graph node with `pnpm local:node`
- For Mac users on Apple Silicon, use a local image of `graphprotocol/graph-node` (see [instructions here](https://github.com/graphprotocol/graph-node/tree/master/docker)).
- Create the local subgraph with `pnpm create:local`
- Deploy changes to the local subgraph with `pnpm deploy-local`
6 changes: 2 additions & 4 deletions apps/subgraph/.env.example
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,7 @@
# Docker config

## For the Goerli testnet use goerli
## For local testing leave empty (docker compose file has defaults)
## Example: for Ethereum Sepolia the value is ethereum-sepolia
NETWORK_NAME=

## For Goerli use https://goerli.infura.io/v3/<your API key>
## For local testing leave empty
## Example: for Ethereum Sepolia the value is https://sepolia.infura.io/v3/<your API key>
NETWORK_RPC=
106 changes: 72 additions & 34 deletions apps/subgraph/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,51 +1,89 @@
# Nouns Builder Subgraph

This `README` is intended to provide app specific context.
## Getting Started
👉 [Read the Goldsky docs](https://docs.goldsky.com/subgraphs/deploying-subgraphs)

### App Dependencies
The Nouns Builder subgraph supports four networks:
- `ethereum`
- `ethereum-sepolia`
- `base`
- `optimism`
- `zora`

The Nouns Builder Subgraph is built on the Graph Protocol and includes the following dependencies:
### Step 1 - Install Dependencies
Navigate to the subgraph directory and run:
```bash
# FROM: ./apps/subgraph
pnpm install
```

### Step 2 - Set Up a Personal Goldsky API Key
1. Request to join the team account at [goldsky.com](https://goldsky.com).
2. Create an API key on your Settings page.
3. Install the Goldsky CLI:
```bash
curl https://goldsky.com | sh
```

- [@graphprotocol/graph-cli](https://www.npmjs.com/package/@graphprotocol/graph-cli) - cli for developing and testing subgraphs
- [@graphprotocol/graph-ts](https://www.npmjs.com/package/@graphprotocol/graph-ts) - core typescript library for writing subgraphs
### Step 3 - Log in with the API Key
Use the API key you created:
```bash
# FROM: ./apps/subgraph
goldsky login
```

### Chain Environment
### Step 4 - Build the Subgraph from Source
Run the following commands (these scripts are defined in `package.json`):
```bash
# FROM: ./apps/subgraph
pnpm prepare:<desired network>
pnpm codegen
pnpm build:subgraph
```

Nouns Builder subgraph currently supports two networks: `mainnet` and `goerli`. The environment variables indicated below dictate the network that the app interacts with.
This will generate types, build the subgraph, and create a local `subgraph.yaml` file.

You can swap out the environment variables as defined below to run the subgraph locally against mainnnet or testnet locally.
### Step 5 - Deploy the Subgraph to Production

```
# the default chain id defined in .env, to run against testnet
NETWORK_RPC=<TESTNET_RPC_ENDPOINT>
NETWORK_NAME=goerli
#### IMPORTANT:
**To avoid downtime during upgrades, maintain a backup subgraph. If issues arise, you can redirect traffic to the backup rather than waiting for redeployment or rollback, which can take hours.**

- The subgraph name follows the pattern `nouns-builder-<network>`, so clients won’t need to update their URI for minor version changes.
- Increase the `specVersion` at the top of `subgraph.yaml.mustache` for each new version.
- Use the **--tag** flag to alias `latest` with the current `specVersion`.

**Always remember to tag!**

```bash
# FROM: ./apps/subgraph
# Example with specVersion 0.0.6
# to run against mainnet locally
NETWORK_RPC=<MAINNET_RPC_ENDPOINT>
NETWORK_NAME=mainnet
goldsky subgraph deploy nouns-builder-<network>/0.0.6 --path .
goldsky subgraph tag create nouns-builder-<network>/0.0.6 --tag latest
# API endpoint format: api.goldsky.com/api/public/<project name>/subgraphs/nouns-builder-ethereum-sepolia/latest/gn
```

### Development
### Step 6 - Query the Subgraph

- create a `.env` file with the required environment variables
- generate types with `pnpm codegen`
- build the subgraph with `pnpm build`
- run the local graph node with `pnpm local-node`
- for M1 mac users you will need to use a local image of `graphprotocol/graph-node` [instructions here](https://github.com/graphprotocol/graph-node/tree/master/docker)
- create the local subgraph with `pnpm create-local`
- deploy changes to the local subgraph with `pnpm deploy-local`
You can now query the subgraph in the Goldsky GraphQL playground to test your changes. **Note: Full indexing may take several hours.**

### Deployment
## Production Endpoints

The subgraph is currently deployed for the following networks:
The subgraph is currently deployed to the following networks:

- [Ethereum Mainnet](https://api.thegraph.com/subgraphs/name/neokry/nouns-builder-mainnet)
- [Ethereum Goerli](https://api.thegraph.com/subgraphs/name/neokry/nouns-builder-goerli)
- [Optimism Mainnet](https://api.thegraph.com/subgraphs/name/neokry/noun-builder-optimism-mainnet)
- [Optimism Goerli](https://api.thegraph.com/subgraphs/name/neokry/nouns-builder-optimism-goerli)
- [Zora Mainnet](https://api.goldsky.com/api/public/project_clkk1ucdyf6ak38svcatie9tf/subgraphs/nouns-builder-zora-mainnet/stable/gn)
- [Zora Goerli](https://api.goldsky.com/api/public/project_clkk1ucdyf6ak38svcatie9tf/subgraphs/nouns-builder-zora-testnet/stable/gn)
- [Base Mainnet](https://api.goldsky.com/api/public/project_clkk1ucdyf6ak38svcatie9tf/subgraphs/nouns-builder-base-mainnet/stable/g)
- [Base Goerli](https://api.studio.thegraph.com/query/49279/nouns-builder-base-goerli/version/latest)
- [Ethereum](https://api.goldsky.com/api/public/<project name>/subgraphs/nouns-builder-ethereum/latest/gn)
- [Ethereum Sepolia](https://api.goldsky.com/api/public/<project name>/subgraphs/nouns-builder-ethereum-sepolia/latest/gn)
- [Optimism](https://api.goldsky.com/api/public/<project name>/subgraphs/nouns-builder-optimism/latest/gn)
- TODO: [Optimism Sepolia](https://api.goldsky.com/api/public/<project name>/subgraphs/nouns-builder-optimism-sepolia/latest/gn)
- TODO: [Zora](https://api.goldsky.com/api/public/<project name>/subgraphs/nouns-builder-zora/latest/gn)
- TODO: [Zora Sepolia](https://api.goldsky.com/api/public/<project name>/subgraphs/nouns-builder-zora-sepolia/latest/gn)
- TODO: [Base](https://api.goldsky.com/api/public/<project name>/subgraphs/nouns-builder-base/latest/gn)
- TODO: [Base Sepolia](https://api.goldsky.com/api/public/<project name>/subgraphs/nouns-builder-base-sepolia/latest/gn)

To deploy your own version edit the `deploy` script in `package.json` with your deployment information
## Local Development with Docker Compose
- Generate types with `pnpm codegen`
- Build the subgraph with `pnpm build:subgraph`
- Run the local graph node with `pnpm local-node`
- For Mac users on Apple Silicon, use a local image of `graphprotocol/graph-node` (see [instructions here](https://github.com/graphprotocol/graph-node/tree/master/docker)).
- Create the local subgraph with `pnpm create-local`
- Deploy changes to the local subgraph with `pnpm deploy-local`
Loading

1 comment on commit 9ef5f4b

@vercel
Copy link

@vercel vercel bot commented on 9ef5f4b Dec 4, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Successfully deployed to the following URLs:

nouns-builder – ./

nouns-builder-0xmillzs-projects-0d94d067.vercel.app
nouns-builder-xi.vercel.app
nouns-builder-git-staging-0xmillzs-projects-0d94d067.vercel.app

Please sign in to comment.