Skip to content

Doc update #101

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
DSCmatter wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Doc update #101

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
168 changes: 116 additions & 52 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,72 +1,136 @@
# Clowder

> Fun fact: "Clowder" is the collective noun for cats.
A minimalistic platform for creating and managing Contribution Accounting Tokens (CATs).

Clowder is a minimalistic platform allowing anyone to create [CATs (Contribution Accounting Tokens)](https://docs.stability.nexus/about-us/the-stable-order/cats).
## Overview

CATs are fungible tokens (e.g. ERC20 tokens) that are used to track the value of contributions to a project by members of a decentralized organization. CATs have the following characteristics:
Clowder enables anyone to create CATs, which are fungible tokens designed to track the value of contributions to projects within decentralized organizations. The name "Clowder" is derived from the collective noun for cats.

1. The initial supply of tokens is zero.
2. The user who deploys the token contract is its initial owner.
3. The contract may have multiple owners and owners may grant ownership to others.
4. All owners have permission to mint tokens.
5. There is an optional maximum supply of tokens, above which minting is forbidden.
6. There is a threshold supply of tokens, below which minting is unrestricted.
7. There is a maximum supply expansion rate that is enforced when the supply exceeds the threshold.
8. Owners have permission to permanently reduce the maximum supply of tokens and the threshold supply of tokens.
9. Owners have permission to permanently reduce the maximum supply expansion rate.
10. Transfers of tokens may be restricted to accounts that already have tokens, in order to keep the tokens circulating only among members of a project.
11. Owners may permanently disable the transfer restriction.
For more information about CATs, visit the [official documentation](https://docs.stability.nexus/about-us/the-stable-order/cats).

The platform's frontend has the following pages:
## CAT Token Characteristics

- **Landing Page**: This page has a "Create CAT" button (which redirects to the *CAT Creation Page*), a text field for the user to input a CAT contract address, and a "Use CAT" button (which redirects to the *CAT Page* for the CAT contract input in the text field).
- **CAT Page**: This page reads from the URL the address of the token contract and allows users to interact with the respective token contract. It shows parameters and variables of the token contract such as current supply, maximum supply, threshold supply, maximum expansion rate, and transfer restriction. For owners who have connected their wallets, it also shows fields and buttons to mint tokens and to modify the parameters of the token contract.
- **Create CAT Page**: This page shows a form where the user can input the constructor parameters for the desired CAT and a "Deploy CAT" button that calls the factory contract to deploy the CAT with the desired parameters.
- **My CATs Page**: This page lists all token contracts owned by the user who connected their wallet.
CATs are ERC20-compatible tokens with the following key features:

The platform's frontend is built with Next.js, TailwindCSS, and ShadCN UI.
1. **Zero Initial Supply**: Tokens begin with no initial supply.
2. **Owner-Based Management**: The deployer becomes the initial owner with multi-owner support.
3. **Minting Permissions**: All owners have permission to mint new tokens.
4. **Supply Controls**:
- Optional maximum supply cap
- Threshold supply below which minting is unrestricted
- Maximum supply expansion rate enforced above the threshold
5. **Governance Flexibility**: Owners can permanently reduce maximum supply, threshold supply, and expansion rates.
6. **Transfer Restrictions**: Optional restriction of transfers to existing token holders to maintain member-only circulation.
7. **Permanent Restriction Removal**: Owners can permanently disable transfer restrictions.

The platform has no backend. The list of token contracts owned by each address is stored in the factory contract.
## Platform Features

---
### Frontend Pages

## Local Setup Instructions
**Landing Page**
- Create new CAT tokens
- Access existing CAT contracts by address
- Quick navigation to CAT management interface

To set up Clowder locally, follow these steps:
**CAT Page**
- View token contract parameters and variables
- Display current supply, maximum supply, threshold supply, and expansion rate
- Show transfer restriction status
- Owner-specific interface for minting and parameter modification

1. **Clone the Repository**
Clone this repository to your local machine:
```bash
git clone https://github.com/your-username/clowder.git
cd clowder
2. Install Dependencies
Install the required packages using your preferred package manager:
**Create CAT Page**
- Interactive form for constructor parameters
- Direct deployment through factory contract

bash
Copy
npm install
# or
yarn install
**My CATs Page**
- Comprehensive list of all owned token contracts
- Wallet-connected user view

3. Set Up Environment Variables
Create a .env file in the root directory of the project and add the following environment variable:
NEXT_PUBLIC_PROJECT_ID=your-project-id
### Technical Stack

4. Obtain Your Project ID
To get the your-project-id value for NEXT_PUBLIC_PROJECT_ID, follow these steps:
Go to https://cloud.reown.com/.
Create an account or log in if you already have one.
Create a new project within the dashboard.
Once the project is created, locate your project key (this might be labeled as "Project ID" or "API Key").
Copy this key and paste it into your .env file as the value for NEXT_PUBLIC_PROJECT_ID.
- **Frontend Framework**: Next.js
- **Styling**: TailwindCSS
- **UI Components**: ShadCN UI
- **Architecture**: Serverless (no backend required)
- **Storage**: On-chain storage via factory contract

5. Run the Development Server
Start the local development server:
## Local Development Setup

npm run dev
# or
yarn dev
### Prerequisites

- Node.js and npm (or yarn)
- Git

Your application should now be running on http://localhost:3000.
### Installation

1. Clone the repository:
```bash
git clone https://github.com/StabilityNexus/Clowder.git
cd Clowder
```

2. Install dependencies:
```bash
npm install
# or
yarn install
```

3. Configure environment variables:

Create a `.env` file in the root directory:
```
NEXT_PUBLIC_PROJECT_ID=your-project-id
```

Comment on lines +81 to +85
Copy link

@coderabbitai coderabbitai bot Dec 13, 2025

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Add language tags to fenced code blocks. (Lines 82-85, 104-111)

This fixes MD040 and improves rendering.

 Create a `.env` file in the root directory:
-```
+```env
 NEXT_PUBLIC_PROJECT_ID=your-project-id

...

- +text
Clowder/
├── contracts/ # Smart contract source files
├── test/ # Contract test suites
├── web/ # Next.js frontend application
├── .github/ # GitHub Actions workflows
└── hardhat.config.js

Also applies to: 104-111

🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

82-82: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
In README.md around lines 81-85 and 104-111, the fenced code blocks are missing
language tags which triggers MD040 and affects rendering; update the first block
(the .env example) to use ```env and update the directory tree block to use
```text (or ```bash/```text) so both fenced blocks include appropriate language
identifiers; apply the same change to any other identical blocks in the file.

4. Obtain your Project ID:
- Navigate to [https://cloud.reown.com/](https://cloud.reown.com/)
- Create an account or sign in
- Create a new project
- Copy the Project ID from your project dashboard
- Add it to your `.env` file

5. Start the development server:
```bash
npm run dev
# or
yarn dev
```

The application will be available at [http://localhost:3000](http://localhost:3000).
Comment on lines 61 to 100
Copy link

@coderabbitai coderabbitai bot Dec 13, 2025

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

# First, find and read the README.md file
find . -name "README.md" -type f | head -5

Repository: StabilityNexus/Clowder

Length of output: 93

🏁 Script executed:

# Check the structure of the repository to understand the layout
git ls-files | grep -E "(package\.json|README)" | head -20

Repository: StabilityNexus/Clowder

Length of output: 119

🏁 Script executed:

# Get line count and content around lines 61-108 of README.md
wc -l README.md

Repository: StabilityNexus/Clowder

Length of output: 79

🏁 Script executed:

# Read lines 61-110 of README.md to verify the exact content and see line 108
sed -n '61,110p' README.md

Repository: StabilityNexus/Clowder

Length of output: 1072

🏁 Script executed:

# Read the root package.json to check if scripts proxy to web/ or if they're for the web app
cat package.json | head -50

Repository: StabilityNexus/Clowder

Length of output: 333

🏁 Script executed:

# Check if web/ is mentioned earlier in the README and understand the structure
sed -n '1,65p' README.md

Repository: StabilityNexus/Clowder

Length of output: 2326

🏁 Script executed:

# Read the complete root package.json to see the scripts section
cat package.json

Repository: StabilityNexus/Clowder

Length of output: 333

🏁 Script executed:

# Check the web/package.json to see what it contains
cat web/package.json | head -40

Repository: StabilityNexus/Clowder

Length of output: 1219

The installation instructions at lines 72-98 will not work as written. The root package.json is a hardhat project for smart contracts and has no dev script defined. The Next.js frontend lives in web/ with its own package.json and scripts. Users following the current instructions will either install the wrong dependencies or encounter errors when trying to run npm run dev from the root.

Revise the installation steps to explicitly state:

-2. Install dependencies:
-```bash
-npm install
-# or
-yarn install
-```
+2. Install dependencies in the `web/` directory:
+```bash
+cd web
+npm install
+# or
+yarn install
+```

And similarly for the dev server step:

-5. Start the development server:
-```bash
-npm run dev
-# or
-yarn dev
-```
+5. Start the development server (from the `web/` directory):
+```bash
+npm run dev
+# or
+yarn dev
+```
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

82-82: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
In README.md around lines 61 to 100, the current installation instructions run
npm/yarn and npm run dev from the repository root which is incorrect because the
root package.json is a hardhat project; update the steps to explicitly switch
into the web/ directory before installing dependencies and before starting the
dev server (i.e., replace the generic "Install dependencies" and "Start the
development server" steps with instructions that run cd web, then npm install or
yarn install, and then cd web (or remain there) and run npm run dev or yarn
dev), and ensure the examples clearly state they must be executed from the web/
directory.


## Project Structure

```
Clowder/
├── contracts/ # Smart contract source files
├── test/ # Contract test suites
├── web/ # Next.js frontend application
├── .github/ # GitHub Actions workflows
└── hardhat.config.js
```

## Smart Contract Development

The project uses Hardhat for smart contract development and testing. Key configuration files:

- `hardhat.config.js`: Hardhat configuration
- `contracts/`: Solidity smart contracts
- `test/`: Contract test files

## Contributing

Contributions are welcome. Please ensure all tests pass before submitting pull requests.

## License

Please refer to the repository for license information.

## Links

- [CAT Documentation](https://docs.stability.nexus/about-us/the-stable-order/cats)
- [Reown Cloud](https://cloud.reown.com/)

## Support

For issues and questions, please use the GitHub Issues section of this repository.