Nouns Builder Monorepo

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

• Mainnet
• Sepolia testnet

For an introduction to Nouns Builder and its concept, you can find further documentation here You can also find the nouns protocol code here.

Apps and packages in this repository include:

apps

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

packages

• analytics: shared analytics helpers
• auction-ui: auction UI package
• blocklist: OFAC/sanctions blocklist helpers
• constants: shared constants and config
• create-dao-ui: create DAO flow UI package
• create-proposal-ui: create proposal flow UI package
• dao-ui: DAO UI package
• eslint-config-custom: shared ESLint config
• feed-ui: feed UI package
• hooks: shared React hooks
• ipfs-service: IPFS upload and URL helpers
• proposal-ui: proposal UI package
• sdk: contract + subgraph SDK
• stores: shared state stores
• swap: swap utilities
• test-fixtures: shared test fixtures
• tsconfig: shared TypeScript configs
• types: shared TypeScript types
• ui: shared UI component package
• utils: shared utility helpers
• zord: design system components

@buildeross/* Package Ecosystem

This monorepo contains a comprehensive set of packages under the @buildeross namespace, designed to support Web3 application development:

Core Libraries

@buildeross/zord

• Modern design system and component library with Vanilla Extract
• Type-safe styling, theming support, and accessibility features
• The main UI foundation for BuilderOSS applications

@buildeross/sdk

• Comprehensive SDK for blockchain and GraphQL interactions
• Contract ABIs, subgraph queries, and EAS (Ethereum Attestation Service) integration
• Generated TypeScript types for type-safe API interactions

@buildeross/hooks

• Collection of React hooks for Web3 and UI functionality
• Includes hooks for NFT data, token balances, voting, and more
• Reusable logic across different applications

Utilities & Configuration

@buildeross/utils

• Shared utility functions for Web3 development
• Helpers for ENS, blockchain data parsing, and Wagmi integration
• Form validation schemas with Yup

@buildeross/constants

• Centralized configuration and constants
• Chain configurations, API endpoints, and application settings
• Shared across all applications in the ecosystem

@buildeross/types

• Shared TypeScript type definitions
• Chain types, proposal states, and common interfaces
• Ensures type consistency across the monorepo

Specialized Services

@buildeross/analytics

• Analytics integrations for Google Analytics, Segment, and Vercel
• Consistent tracking across BuilderOSS applications

@buildeross/blocklist

• Blockchain address blocklist functionality
• OFAC sanctions list integration for compliance

@buildeross/ipfs-service

• IPFS integration for decentralized file storage
• Image upload utilities and gateway management

Development Tools

@buildeross/eslint-config-custom

• Shared ESLint configuration with Next.js and Prettier integration

@buildeross/tsconfig

• TypeScript configurations for different project types
• Base, Next.js, and React library configurations

Installation

All packages are published to npm and can be installed individually:

# Core libraries
npm install @buildeross/zord
npm install @buildeross/sdk
npm install @buildeross/hooks

# Utilities & configuration
npm install @buildeross/utils
npm install @buildeross/constants
npm install @buildeross/types

# Specialized services
npm install @buildeross/analytics
npm install @buildeross/blocklist
npm install @buildeross/ipfs-service

# Development tools
npm install @buildeross/eslint-config-custom
npm install @buildeross/tsconfig

Quickstart

Get up and running

1. Clone this repo locally

2. Install pnpm

3. Add the required 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 as the main rpc node provider, transaction simulator (eth_simulateV1), and for NFT metadata and balances
• Etherscan to dynamically fetch abis
• Redis for caching layer

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):

ANVIL_FORK_URL=$RPC_URL
ANVIL_BLOCK_NUMBER=8305745

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

# etherscan
ETHERSCAN_API_KEY=<ETHERSCAN_API_KEY>

# alchemy key for browser RPC calls; lock it to your domains with an allowlist
NEXT_PUBLIC_ALCHEMY_API_KEY=<ALCHEMY_API_KEY>

# server-side alchemy auth (RPC, simulation, NFT/token data), sent as an
# `Authorization: Bearer` header, in order of preference:
# 1. a JWT signed with this key pair (see "Alchemy JWT auth" below)
ALCHEMY_JWT_PRIVATE_KEY=<PKCS8_PEM_PRIVATE_KEY>
ALCHEMY_JWT_KEY_ID=<ALCHEMY_KEY_ID>
# 2. a server-only key that allows requests without an Origin header
ALCHEMY_API_KEY=<ALCHEMY_API_KEY>
# 3. otherwise NEXT_PUBLIC_ALCHEMY_API_KEY, which only works if it isn't domain-locked

# redis for caching
REDIS_URL=<REDIS_URL>

Alchemy JWT auth

Server-side requests carry no Origin header, so they can't use the domain-locked public key. They authenticate with short-lived JWTs instead (Alchemy docs):

1. Generate an RSA key pair. The private key must be PKCS#8 (BEGIN PRIVATE KEY):

   openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out alchemy_private_key.pem
   openssl pkey -in alchemy_private_key.pem -pubout -out alchemy_public_key.pem
   

   A PKCS#1 key (BEGIN RSA PRIVATE KEY) can be converted with openssl pkcs8 -topk8 -nocrypt -in private_key.pem.

2. In the Alchemy dashboard, open the app, go to Security → Import Public Key, and paste alchemy_public_key.pem. Copy the generated Key ID.

3. Set ALCHEMY_JWT_PRIVATE_KEY to the private key PEM (multi-line, or with \n escapes) and ALCHEMY_JWT_KEY_ID to the key ID.

The server signs a 10-minute RS256 token and re-signs it shortly before it expires.

Running tests

The test suite is split into two types:

Unit Tests (no external dependencies)

Unit tests run quickly without requiring any external services. To run all unit tests:

pnpm test:unit

Or in watch mode:

pnpm test:watch

Integration Tests (requires Anvil fork)

Some tests (*.fork.test.tsx files) require a forked Ethereum network and use real contract interactions. To run these:

1. Install Anvil if you haven't already
2. Start Anvil in a separate terminal session from the root directory:

   pnpm run anvil

3. Run the integration tests:

   pnpm test:fork

Running All Tests

To run both unit and integration tests together:

pnpm test

Note: CI only runs unit tests for faster feedback. Integration tests should be run locally before submitting PRs.

Deployments

Client

The Nouns Builder client is deployed on Vercel. 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
• Ethereum Sepolia
• Base
• Base Sepolia
• Optimism

Contributions

Please refer to our contributions guideline on how best to contribute.

Questions?

Feel free to reach out to us via Discord