basic readme

README.md

@@ -1,66 +1,67 @@
-## Foundry
+# On-Chain Auctions Library
 
-**Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.**
+*Modular, extensible and well documented auctions written in Solidity*
 
-Foundry consists of:
+## Why Auctions Matter in Web3?
 
--   **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.
+Auctions are a core mechanism for determining fair market prices, allocating scarce digital assets, and fostering open participation. In web3, trustless, on-chain auctions bring transparency, security, and efficiency—empowering anyone, anywhere to participate without intermediaries.  
+Auctions are everywhere in web3, from NFT sales to MEV, but there's no library that provides teams with base implementations they can extend.
 
-## Documentation
+## Current Implementations
 
-https://book.getfoundry.sh/
+* [English Auction](src/EnglishAuction.sol): A classic ascending-price auction that allows bids until a deadline and extends time to prevent last-second sniping. Built with extensibility hooks for custom increments, bidder whitelists, and unique asset-transfer logic.
 
-## Usage
+## Installation
 
-### Build
+### Foundry
 
-```shell
-$ forge build
+```bash
+forge install ggonzalez94/base-auctions
 ```
 
-### Test
+Add `@base-auctions/=lib/base-auctions/src/` in `remappings.txt`.
 
-```shell
-$ forge test
-```
+## Usage
 
-### Format
+Once installed, you can use the contracts in the library by importing them:
 
-```shell
-$ forge fmt
-```
+```solidity
+pragma solidity ^0.8.20;
 
-### Gas Snapshots
+import {EnglishAuction} from "@base-auctions/EnglishAuction.sol";
 
-```shell
-$ forge snapshot
-```
+contract MyAuction is EnglishAuction {
+    address public winnerAssetRecipient;
 
-### Anvil
+    constructor(
+        address _seller,
+        uint256 _reservePrice,
+        uint256 _duration,
+        uint256 _extensionThreshold,
+        uint256 _extensionPeriod
+    ) EnglishAuction(_seller, _reservePrice, _duration, _extensionThreshold, _extensionPeriod) {}
 
-```shell
-$ anvil
+    // Here you would normally transfer the actual asset to the winner(e.g. the NFT)
+    function _transferAssetToWinner(address winner) internal override {
+        winnerAssetRecipient = winner;
+    }
+}
 ```
 
-### Deploy
+## Contributing
 
-```shell
-$ forge script script/Counter.s.sol:CounterScript --rpc-url <your_rpc_url> --private-key <your_private_key>
-```
+We welcome contributions from the community! If you have ideas for new auction types, improvements to the existing code, or better tooling and documentation, please open an issue or submit a PR.
 
-### Cast
+## Roadmap
 
-```shell
-$ cast <subcommand>
-```
+These are some of the next auctions we plan to implement, but it's very early and we're open to suggestions.
 
-### Help
+* [ ] Dutch Auction
+* [ ] Sealed-Bid Auction
+* [ ] Vickrey Auction (Second-Price Sealed-Bid Auction)
+* [ ] Reverse Auction
+* [ ] All-pay auction (also known as a Tullock contest)
 
-```shell
-$ forge --help
-$ anvil --help
-$ cast --help
-```
+## Disclaimer
+
+This code has not been audited and is provided "as is". While we've taken care to write well-documented, secure code, you use this software at your own risk.