Nouns.biz

Nouns DAO Contracts & Events #

A guide to interacting with Nouns DAO and Nounish projects using Nerman.js.

Nerman.js - a Nouns SDK #

Nerman.js is a type-safe Nouns SDK that provides simple and well-documented access to the Nouns DAO contracts, as well as other Nounish projects both on-chain and off-chain. Nerman.js can be used in TypeScript or vanilla JavaScript projects, was built with Ethers.js, and works with any JSON RPC API url. We recommend Alchemy for their excellent service and generous free tier.

We will explore some common Nerman.js use cases below - to view all projects and events supported please see the Nerman.js Documentation.

You can install Nerman.js with NPM:

npm install nerman

Nouns DAO Contracts #

All Nouns DAO contracts and solidity code can be found in the Nouns DAO Monorepo. Instantiating Nerman and listening to Nouns DAO events is easy, here is an example:

import * as nerman from "nerman";

const Nouns = new nerman.Nouns( JSON_RPC_API_URL );

Nouns.on("AuctionCreated", (data : nerman.EventData.AuctionCreated)) {

	// data.id // id of noun token being auctioned
	// data.startTime // auction start time
	// data.endTime // auction end time - unless extended with more bids
	// data.event // an ethers.Event object will lots of useful data in it
	
});

Most Nouns DAO contracts use a proxy pattern (see ERC1967Proxy) to allow for future upgrades. Users generally interact with the proxy contracts, which point to the actual code implementation.

Users can interact with all contracts on Etherscan, and there are many Nouns DAO Front End Clients to interact with things like governance and auctions.

Nouns DAO - Core Logic / Governance Contracts #

These contracts handle Nouns DAO's governance activity, including creating and voting on proposals. They are a fork of Compound's GovernorBravoDelegate and have new functionality such as editing proposals, dynamic quorum, DAO fork mechanisms, gas refunds for voters, and an objection period for proposals that swing to a success at the last minute.

Main Contracts:

Deprecated Contracts:

Example Event

Nouns.on("ProposalCreatedWithRequirements", 
(data : nerman.EventData.ProposalCreatedWithRequirements)) {
    // data.id
    // data.proposer
    // data.signers
    // data.targets
    // data.values
    // data.signatures
    // data.calldatas
    // data.startBlock
    // data.endBlock
    // data.updatePeriodEndBlock
    // data.proposalThreshold
    // data.quorumVotes
    // data.description
    // data.event
});

Key Events

Nouns DAO - Executor / Treasury Contracts #

The Nouns DAO treasury holds all DAO assets and funds, like ETH, stETH, etc. ETH from auction bids is sent here, and when proposals pass the funds they request come directly from here. This contract is a fork of Compound's Timelock and is controlled by the Nouns governance contract (NounsDAOProxy).

Main Contracts:

Deprecated Contracts:

Key Events

Nouns DAO - Token / NFT Contracts #

The Nouns Token contract implements all standard ERC 721 functionality. This is where Nouns can be minted, transferred, burned, etc. This contract also handles vote delegation / checkpointing data for Nouns governance.

Main Contracts:

Example Event

Nouns.on("NounCreated", (data : nerman.EventData.NounCreated)) {
		 
    // data.id // the newly created Noun id
    // data.seed // the Nouns random seed, traits for art creation
	// data.event // all the associated Ethers event data
	
});

Key Events

Nouns DAO - Auction House Contracts #

This contract is a fork of Zora's Auction House. Every 24 hours this contract mints a new Nouns Token and trustlessly auctions it off. When the auction is complete anyone can settle it, sending the auction proceeds (ETH) to the Nouns treasury and minting the next Noun at the same time.

There will be one Noun, everyday, forever ... as long as Ethereum remains functional, and people paying attention to bid on Nouns and settle auctions.

Main Contracts:

Example Event

Nouns.on("AuctionBid", (data : nerman.EventData.AuctionBid)) {

    // data.id // the Noun ID being bid on
    // data.amount // the bid amount in wei
    // data.bidder // the account bidding
    // data.extended // boolean, if auction extended due to bid during endTime buffer
	// data.event // all the associated Ethers event data
	
});

Key Events

Nouns DAO - Art Contracts #

NounsSeeder.sol determines Noun traits during the minting process. Traits are determined using pseudo-random number generation.

NounsDescriptor.sol stores / renders Nouns SVG artwork, and encodes it in base 64 to include in the token URI.

Main Contracts:

Nouns DAO - Data Contracts #

This contract is used to publish events related to proposals, ie things related to proposal candidates and proposal feedback.

Main Contracts: NounsDAODataProxy.sol - Etherscan - Github NounsDAOData.sol - Etherscan - Github

Example Event

Nouns.on("FeedbackSent", (data : nerman.EventData.FeedbackSent)) {

	// data.msgSender // account feedback sent from
	// data.proposalId // id of proposal receiving feedback
	// data.support // feedback vote. Either FOR, AGAINST, or ABSTAIN.
	// data.reason // optional text providing feedback reasoning

});

Key Events

Nouns DAO - Fork Contracts #

These contracts are part of the NounsDAOLogicV3 ABI and add fork functionality to Nouns DAO, allowing Nouners to claim their share of the treasury and exit into a new Fork DAO.

The escrow contract is for Nouns to be sent to commit to a fork before it occurs. When enough Nouns are escrowed a new fork DAO can be deployed with ForkDAODeployer.

Main Contracts:

Example Event

Nouns.on('EscrowedToFork', (data : nerman.EventData.EscrowedToFork )) {
	// data.forkId
	// data.owner
	// data.tokenIds
	// data.reason
});

Key Events These events are all emitted from the NounsDAOProxy contract.

Nouns DAO - Payer Contracts #

TokenBuyer - a contract that swaps ETH for USDC asynchronously, helping the DAO pay proposal builders without volatility risk.

Streamer - a fork of Sablier, allowing the DAO to create streams and fund them asynchronously, e.g. using TokenBuyer.

Main Contracts: TokenBuyer - Etherscan - Github Streamer - Etherscan - Github

Key Events: ETHWithdrawn, SoldETH, buyETH

Propdates #

Propdates is a contract for Nouns proposers to update the community on their work.

Main Contracts: Propdates.sol - Etherscan - Github

Front End Clients: Propdates.wtf

Example Event

const propdates = new nerman.Propdates(Nouns.provider);

propdates.on("PostUpdate", (date : nerman.EventData.Propdates.PostUpdate) => {

	// data.propId // the nouns proposal id of current propdate
	// data.isCompleted // whether the proposal is marked complete
	// data.update // the update text content
	// data.event // ethers event data

});

//...

Foundation Governance Pool's #

Nouns governance pool allows Nouners to delegate their Nouns to a pool. The pool's Nouns vote is auctioned off for every proposal, with the highest bid determining how the pool votes.

Main Contracts: Foundation Governance Pool Proxy - Etherscan - Github

Front End Clients:

Example Event

const federationNounsPool = new nerman.FederationNounsPool(Nouns.provider);

federationNounsPool.on('BidPlaced', 
	(data : nerman.EventData.Federation.GovPool.BidPlaced)) {

	//data.dao - address of the dao
	//data.propId - proposal being bid on
	//data.support - The bidder's stance on the proposal. FOR, AGAINST, or ABSTAIN.
	//data.amount - The amount bid, in wei.
	//data.bidder - The bidder account address.
	//data.reason - The reason for the bid.
	
});

All Events BidPlaced, VoteCast

NounsNymz #

Noun Nyms is a protocol and webapp for using nounish pseudonyms.

Main Code:

Front End Clients:

Example Event

const nounsNymz = new nerman.NounsNymz();

nounsNymz.on('NewPost', async post => {

	// post.id // Post id.
	// post.title // Post title. Empty if it is a reply.
	// post.body // Post body.
	// post.timestamp // Post UTC timestamp.
	// post.userId // Poster id.
	// post.parentId // Parent post id.
	// post.depth // Number of replies in chain.
	// post.upvotes // List of upvotes.
	// post.root // Original post if the new post is a reply.
	// post.parent // Parent post if the new post is a reply.
	
});

All Events: NewPost

Lil Nouns DAO #

Lil Nouns is a fully functional DAO based on Nouns DAO contracts and lil versions of the Nouns artwork.

Main Contracts:

Fork DAO 0 #

Several forks have already been executed, and are now their own fully functioning DAOs. We currently have events implemented for Fork DAO 0.

Main Contracts:

const nounsForkToken = new nerman.NounsForkToken(Nouns.provider);
// key events: NounCreated, NounBurned
const nounsForkAuctionHouse = new nerman.NounsForkAuctionHouse(Nouns.provider);
// key events: AuctionCreated, AuctionBid, AuctionSettled
const nounsFork = new nerman.NounsFork(Nouns.provider);
// key events: ProposalCreated, ProposalCreatedWithRequirements, 
// VoteCasts, ProposalCanceled, ProposalQueued, ProposalExecuted

Fork DAO 1 #

Front End Clients: