Skip to content

Commit

Permalink
refactor(docs): add citations
Browse files Browse the repository at this point in the history
  • Loading branch information
@sambacha
sambacha committed May 24, 2024
1 parent b2a58c7 commit 2e93d1c
Show file tree
Hide file tree
Showing 25 changed files with 2,209 additions and 1,078 deletions.
122 changes: 59 additions & 63 deletions docs/Developers/interface.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,21 @@ description: Primary Market Auction and Settlement contract interface
---

# Summary Interfaces
- [Auctioneer](#auctioneer-interface)
- [Settlement](#settlementhouse-interface)
- [Bidder](#bidder-interface)

- [Auctioneer](#auctioneer-interface)
- [Settlement](#settlementhouse-interface)
- [Bidder](#bidder-interface)

# Auctioneer Interface

[Git Source](https://github.com/manifoldfinance/open-bidder-contracts/blob/main/src/interfaces/IAuctioneer.sol)

**Inherits:**
ERC6909, Ownable2Step
**Inherits:** ERC6909, Ownable2Step

*Implements an auction mechanism for selling block space.*
_Implements an auction mechanism for selling block space._

## Structs

Check warning on line 20 in docs/Developers/interface.md

View workflow job for this annotation

GitHub Actions / spellcheck 

Unknown word (Structs)

### Auction

```solidity
Expand All @@ -40,6 +42,7 @@ struct BidderInfo {
```

## State Variables

### maxBidder

```solidity
Expand All @@ -58,63 +61,54 @@ WETH public immutable WETH9;
address public accountant;
```


### maxBids

```solidity
uint256 public maxBids = 50;
```


### minGasAmount

```solidity
uint120 public minGasAmount = 20000;
```


### operator

```solidity
address public operator;
```


### IdMap

```solidity
mapping(address bidder => uint8 id) public IdMap;
```


### bidderMap

```solidity
mapping(uint8 id => address bidder) public bidderMap;
```


### auctions

```solidity
mapping(uint256 slot => Auction) public auctions;
```


### slotsCount

```solidity
uint256 public slotsCount;
```


### slotsAuctioned

```solidity
mapping(uint256 index => uint256 slot) public slotsAuctioned;
```


### bidCount

```solidity
Expand All @@ -125,86 +119,85 @@ mapping(uint256 slot => uint256 count) public bidCount;

### bid

*Bid function for bidders to submit manual bids.*

_Bid function for bidders to submit manual bids._

```solidity
function bid(uint256 slot, uint256[] memory packedBids) external;
```

**Parameters**

|Name|Type|Description|
|----|----|-----------|
|`slot`|`uint256`|The auction slot.|
|`packedBids`|`uint256[]`|Array of packed bids|
| Name | Type | Description |
| ------------ | ----------- | -------------------- |
| `slot` | `uint256` | The auction slot. |
| `packedBids` | `uint256[]` | Array of packed bids |

### getBidderInfo

*Retrieve information about a bidder after auction settlement.*

_Retrieve information about a bidder after auction settlement._

```solidity
function getBidderInfo(uint256 slot, address bidder) external view returns (uint120 itemsBought, uint128 amountOwed);
```

**Parameters**

|Name|Type|Description|
|----|----|-----------|
|`slot`|`uint256`|The slot identifier of the auction.|
|`bidder`|`address`|The address of the bidder for whom information is requested.|
| Name | Type | Description |
| -------- | --------- | ------------------------------------------------------------ |
| `slot` | `uint256` | The slot identifier of the auction. |
| `bidder` | `address` | The address of the bidder for whom information is requested. |

**Returns**

|Name|Type|Description|
|----|----|-----------|
|`itemsBought`|`uint120`|The number of items bought by the bidder in the specified auction.|
|`amountOwed`|`uint128`|The amount owed by the bidder for the items bought in the specified auction. Requirements: - The auction must have been settled. - The provided `bidder` address must be valid and have participated in the auction.|

| Name | Type | Description |
| ------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `itemsBought` | `uint120` | The number of items bought by the bidder in the specified auction. |
| `amountOwed` | `uint128` | The amount owed by the bidder for the items bought in the specified auction. Requirements: - The auction must have been settled. - The provided `bidder` address must be valid and have participated in the auction. |

### packBid

*Packed Bid details into a uint256 for submission.*

_Packed Bid details into a uint256 for submission._

```solidity
function packBid(uint128 bidPrice, uint120 itemsToBuy, uint8 bidderId) external pure returns (uint256 packedBid);
```

**Parameters**

|Name|Type|Description|
|----|----|-----------|
|`bidPrice`|`uint128`|Price per item.|
|`itemsToBuy`|`uint120`|Items to buy in the auction.|
|`bidderId`|`uint8`|Id for bidder|
| Name | Type | Description |
| ------------ | --------- | ---------------------------- |
| `bidPrice` | `uint128` | Price per item. |
| `itemsToBuy` | `uint120` | Items to buy in the auction. |
| `bidderId` | `uint8` | Id for bidder |

**Returns**

|Name|Type|Description|
|----|----|-----------|
|`packedBid`|`uint256`|for auction submission|
| Name | Type | Description |
| ----------- | --------- | ---------------------- |
| `packedBid` | `uint256` | for auction submission |

### calcAverageBid

*Calculate average bid price for the last n auctions*

_Calculate average bid price for the last n auctions_

```solidity
function calcAverageBid(uint256 numAuctions) external view returns (uint128 avBidPrice);
```

**Parameters**

|Name|Type|Description|
|----|----|-----------|
|`numAuctions`|`uint256`|Number of auctions to average for|
| Name | Type | Description |
| ------------- | --------- | --------------------------------- |
| `numAuctions` | `uint256` | Number of auctions to average for |

**Returns**

|Name|Type|Description|
|----|----|-----------|
|`avBidPrice`|`uint128`|for last n auctions|

| Name | Type | Description |
| ------------ | --------- | ------------------- |
| `avBidPrice` | `uint128` | for last n auctions |

## Events

### AuctionSettled

```solidity
Expand Down Expand Up @@ -242,6 +235,7 @@ event AuctionRefund(uint256 indexed slot);
```

## Errors

### InvalidId

```solidity
Expand Down Expand Up @@ -303,12 +297,13 @@ error BidderAlreadyExists(address bidder);
```

# SettlementHouse Interface
[Git Source](https://github.com/manifoldfinance/open-bidder-contracts/blob/main/src/interfaces/ISettlement.sol)

*A contract for managing bundles of transactions for a futures token.*
[Git Source](https://github.com/manifoldfinance/open-bidder-contracts/blob/main/src/interfaces/ISettlement.sol)

_A contract for managing bundles of transactions for a futures token._

## Structs

Check warning on line 305 in docs/Developers/interface.md

View workflow job for this annotation

GitHub Actions / spellcheck 

Unknown word (Structs)

### Bundle

```solidity
Expand All @@ -320,6 +315,7 @@ struct Bundle {
```

## State Variables

### futuresToken

```solidity
Expand All @@ -330,32 +326,32 @@ IERC6909 public immutable futuresToken;

### submitBundle


```solidity
function submitBundle(uint256 slot, uint256 amountOfGas, bytes32[] calldata bundleHashes) external;
```


# Bidder Interface

[Git Source](https://github.com/manifoldfinance/open-bidder-contracts/blob/main/src/interfaces/IBidder.sol)

## Functions
### getBid

*Get the bid from a bidder for a specific slot and round.*
### getBid

_Get the bid from a bidder for a specific slot and round._

```solidity
function getBid(uint256 slot) external view returns (uint256[] memory packedBids);
```

**Parameters**

|Name|Type|Description|
|----|----|-----------|
|`slot`|`uint256`|The auction slot.|
| Name | Type | Description |
| ------ | --------- | ----------------- |
| `slot` | `uint256` | The auction slot. |

**Returns**

|Name|Type|Description|
|----|----|-----------|
|`packedBids`|`uint256[]`|Array of bids (in a packed format). uint256(uint128(bidPrice),uint120(itemsToBuy),uint8(bidderId))|
| Name | Type | Description |
| ------------ | ----------- | -------------------------------------------------------------------------------------------------- |
| `packedBids` | `uint256[]` | Array of bids (in a packed format). uint256(uint128(bidPrice),uint120(itemsToBuy),uint8(bidderId)) |
4 changes: 2 additions & 2 deletions docs/Developers/mainnet.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@ description:
Mainnet information for node operators, validators, builders, and searchers.
---

- [Live auction dashboard](https://mainnet-auction-dashboard.securerpc.com/)
- [L2 Blockchain explorer](https://mainnet-blockscout.securerpc.com/)
- [Live auction dashboard](https://mainnet-auction-dashboard.securerpc.com/)
- [L2 Blockchain explorer](https://mainnet-blockscout.securerpc.com/)

## Node Operators

Expand Down
39 changes: 25 additions & 14 deletions docs/Developers/sdk.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,34 @@ sidebar_position: 1
title: Auction SDK
---

XGA auction winners are granted future block space via a token, which is used with submission of transactions for inclusion in the beta block. Budding bidders can register themselves with the protocol to participate in beta block auctions. Thereupon custom implementations will be required to bid and submit transactions. Technical details are provided herein.
XGA auction winners are granted future block space via a token, which is used
with submission of transactions for inclusion in the beta block. Budding bidders
can register themselves with the protocol to participate in beta block auctions.
Thereupon custom implementations will be required to bid and submit
transactions. Technical details are provided herein.

Technical Overview:
- [Bidding](#bidding):
- [Connect to L2 RPC](#l2-rpc)
- [Bridge eth to L2](#l1-bridge)
- [Understand auction contracts](#auction-contracts)
- [Deploy custom bidding strategy contract](#bidder-contracts)
- [Submitting bundles](#submitting-bundles):
- [Beta Bundle RPC](#beta-bundle-rpc)
- [Bundle JSON Requests and Responses](#bundle-json-requests-and-responses)

- [Bidding](#bidding):
- [Connect to L2 RPC](#l2-rpc)
- [Bridge eth to L2](#l1-bridge)
- [Understand auction contracts](#auction-contracts)
- [Deploy custom bidding strategy contract](#bidder-contracts)
- [Submitting bundles](#submitting-bundles):
- [Beta Bundle RPC](#beta-bundle-rpc)
- [Bundle JSON Requests and Responses](#bundle-json-requests-and-responses)

Full working examples are available for:
- [Zero latency open bidder contract](https://github.com/manifoldfinance/open-bidder-contracts/)
- [Bundle submissions](https://github.com/MEV-Protocol/beta-bundles-py)

- [Zero latency open bidder contract](https://github.com/manifoldfinance/open-bidder-contracts/)
- [Bundle submissions](https://github.com/MEV-Protocol/beta-bundles-py)

# Bidding

## L2 RPC

- **L2 RPC:**

- Description: L2 Node RPC
- URL:
[https://xga-api.securerpc.com/v1](https://xga-api.securerpc.com/v1)
Expand All @@ -36,7 +45,7 @@ Full working examples are available for:
[https://holesky-api.securerpc.com/l2](https://holesky-api.securerpc.com/l2/)
- Methods: eth\_\*
- ChainId: 42169

## L1 Bridge

Fund L2 address by sending ETH to the L1 bridge address.
Expand Down Expand Up @@ -133,7 +142,8 @@ After an auction is closed, bidders can query their bid results:

## Bidder Contracts

A minimal viable bidder is provided below. [A more sophisticated fill or kill open bidder contract is provided](https://github.com/manifoldfinance/open-bidder-contracts/).
A minimal viable bidder is provided below.
[A more sophisticated fill or kill open bidder contract is provided](https://github.com/manifoldfinance/open-bidder-contracts/).

```solidity
/// SPDX-License-Identifier: UPL-1.0
Expand Down Expand Up @@ -178,7 +188,9 @@ contract MockBidder {
# Submitting bundles

## Beta Bundle RPC

- **Beta bundle RPC:**

- Description: Beta bundle submission RPC
- URL:
[https://mainnet-auction.securerpc.com/](https://mainnet-auction.securerpc.com/)
Expand All @@ -198,7 +210,6 @@ contract MockBidder {
- `slot`: slot number e.g. "11282389"
- ChainId: 17000


## Bundle JSON Requests and Responses

### Example JSON request
Expand Down
Loading

0 comments on commit 2e93d1c

Please sign in to comment.