Skip to content
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

Jump to bottom

Move natspec to interfaces #40

Merged
merged 4 commits into from
Oct 17, 2023
Merged

Move natspec to interfaces #40

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4e60db3
move natspec to interfaces
gretzke Oct 17, 2023
3ee4da9
docs: forge foc
DhairyaSethi Oct 17, 2023
190f5de
chore: expand getVersion natspec
DhairyaSethi Oct 17, 2023
b609219
chore: expand getVersion natspec
DhairyaSethi Oct 17, 2023
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
6 changes: 5 additions & 1 deletion docs/src/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,11 @@ A default implementation is included and this contract will be proxy upgradable
- (mainnet): `forge script scripts/Deploy.s.sol --broadcast --verify --rpc-url $RPC_URL --private-key $PRIVATE_KEY --etherscan-api-key $ETHERSCAN_API_KEY`
- (testnet, goerli for example): `forge script scripts/Deploy.s.sol --broadcast --verify --rpc-url $RPC_URL --private-key $PRIVATE_KEY --verifier-url https://api-goerli.etherscan.io/api --chain-id 5`

4. Run `node scripts/util/extract.js <chainId>` to extract deployment information from forge broadcast output (broadcast/latest-run.json).
4. Run `node scripts/util/extract.js <chainId> [version = 1.0.0] [scriptName = Deploy.s.sol]` to extract deployment information from forge broadcast output (broadcast/latest-run.json).

## Reference Deployments

- Goerli [0x4f34BF3352A701AEc924CE34d6CfC373eABb186c](https://goerli.etherscan.io/address/0x4f34BF3352A701AEc924CE34d6CfC373eABb186c)

---

Expand Down
31 changes: 13 additions & 18 deletions docs/src/src/DefaultEmissionManager.sol/contract.DefaultEmissionManager.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
# DefaultEmissionManager
[Git Source](https://github.com/0xPolygon/pol-token/blob/a780764684dd1ef1ca70707f8069da35cddbd074/src/DefaultEmissionManager.sol)
[Git Source](https://github.com/0xPolygon/pol-token/blob/4e60db3944f1f433beb163a74034e19c0fc68cf0/src/DefaultEmissionManager.sol)

**Inherits:**
Ownable2StepUpgradeable, [IDefaultEmissionManager](/src/interfaces/IDefaultEmissionManager.sol/interface.IDefaultEmissionManager.md)

**Author:**
Polygon Labs (@DhairyaSethi, @gretzke, @qedk)
Polygon Labs (@DhairyaSethi, @gretzke, @qedk, @simonDos)

A default emission manager implementation for the Polygon ERC20 token contract on Ethereum L1

*The contract allows for a 1% mint *each* per year (compounded every year) to the stakeManager and treasury contracts*
*The contract allows for a 3% mint per year (compounded). 2% staking layer and 1% treasury*


## State Variables
### INTEREST_PER_YEAR_LOG2

```solidity
uint256 public constant INTEREST_PER_YEAR_LOG2 = 0.028569152196770894e18;
uint256 public constant INTEREST_PER_YEAR_LOG2 = 0.04264433740849372e18;
```


Expand Down Expand Up @@ -70,10 +70,6 @@ uint256 public startTimestamp;


### __gap
*This empty reserved space is put in place to allow future versions to add new
variables without shifting down storage in the inheritance chain.
See https://docs.openzeppelin.com/contracts/4.x/upgradeable#storage_gaps*


```solidity
uint256[48] private __gap;
Expand All @@ -97,10 +93,9 @@ function initialize(address token_, address owner_) external initializer;

### mint

Allows anyone to mint tokens to the stakeManager and treasury contracts based on current emission rates
allows anyone to mint tokens to the stakeManager and treasury contracts based on current emission rates

*Minting is done based on totalSupply diffs between the currentTotalSupply (maintained on POL, which includes any
previous mints) and the newSupply (calculated based on the time elapsed since deployment)*
*minting is done based on totalSupply diffs between the currentTotalSupply (maintained on POL, which includes any previous mints) and the newSupply (calculated based on the time elapsed since deployment)*


```solidity
Expand All @@ -109,12 +104,12 @@ function mint() external;

### inflatedSupplyAfter

Returns total supply from compounded emission after timeElapsed from startTimestamp (deployment)
returns total supply from compounded emission after timeElapsed from startTimestamp (deployment)

*interestRatePerYear = 1.02; 2% per year
*interestRatePerYear = 1.03; 3% per year
approximate the compounded interest rate using x^y = 2^(log2(x)*y)
where x is the interest rate per year and y is the number of seconds elapsed since deployment divided by 365 days in seconds
log2(interestRatePerYear) = 0.028569152196770894 with 18 decimals, as the interest rate does not change, hard code the value*
log2(interestRatePerYear) = 0.04264433740849372 with 18 decimals, as the interest rate does not change, hard code the value*


```solidity
Expand All @@ -124,18 +119,18 @@ function inflatedSupplyAfter(uint256 timeElapsed) public pure returns (uint256 s

|Name|Type|Description|
|----|----|-----------|
|`timeElapsed`|`uint256`|The time elapsed since startTimestamp|
|`timeElapsed`|`uint256`||

**Returns**

|Name|Type|Description|
|----|----|-----------|
|`supply`|`uint256`|total supply from compounded emission after timeElapsed|
|`supply`|`uint256`|inflatedSupply supply total supply from compounded emission after timeElapsed|


### getVersion

Returns the implementation version
returns the version of the contract


```solidity
Expand All @@ -145,6 +140,6 @@ function getVersion() external pure returns (string memory);

|Name|Type|Description|
|----|----|-----------|
|`<none>`|`string`|Version string|
|`<none>`|`string`|version version string|


25 changes: 12 additions & 13 deletions docs/src/src/PolygonEcosystemToken.sol/contract.PolygonEcosystemToken.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# PolygonEcosystemToken
[Git Source](https://github.com/0xPolygon/pol-token/blob/a780764684dd1ef1ca70707f8069da35cddbd074/src/PolygonEcosystemToken.sol)
[Git Source](https://github.com/0xPolygon/pol-token/blob/4e60db3944f1f433beb163a74034e19c0fc68cf0/src/PolygonEcosystemToken.sol)

**Inherits:**
ERC20Permit, AccessControlEnumerable, [IPolygonEcosystemToken](/src/interfaces/IPolygonEcosystemToken.sol/interface.IPolygonEcosystemToken.md)

**Author:**
Polygon Labs (@DhairyaSethi, @gretzke, @qedk)
Polygon Labs (@DhairyaSethi, @gretzke, @qedk, @simonDos)

This is the Polygon ERC20 token contract on Ethereum L1

Expand Down Expand Up @@ -44,7 +44,7 @@ address public constant PERMIT2 = 0x000000000022D473030F116dDEE9F6B43aC78BA3;
### mintPerSecondCap

```solidity
uint256 public mintPerSecondCap = 10e18;
uint256 public mintPerSecondCap = 13.37e18;
```


Expand Down Expand Up @@ -74,7 +74,7 @@ constructor(address migration, address emissionManager, address governance, addr

### mint

Mint token entrypoint for the emission manager contract
mint token entrypoint for the emission manager contract

*The function only validates the sender, the emission manager is responsible for correctness*

Expand All @@ -86,13 +86,13 @@ function mint(address to, uint256 amount) external onlyRole(EMISSION_ROLE);

|Name|Type|Description|
|----|----|-----------|
|`to`|`address`|Address to mint to|
|`amount`|`uint256`|Amount to mint|
|`to`|`address`|address to mint to|
|`amount`|`uint256`|amount to mint|


### updateMintCap

Update the limit of tokens that can be minted per second
update the limit of tokens that can be minted per second


```solidity
Expand All @@ -107,7 +107,7 @@ function updateMintCap(uint256 newCap) external onlyRole(CAP_MANAGER_ROLE);

### updatePermit2Allowance

Manages the default max approval to the permit2 contract
manages the default max approval to the permit2 contract


```solidity
Expand All @@ -122,7 +122,7 @@ function updatePermit2Allowance(bool enabled) external onlyRole(PERMIT2_REVOKER_

### allowance

The permit2 contract has full approval by default. If the approval is revoked, it can still be manually approved.
*The permit2 contract has full approval by default. If the approval is revoked, it can still be manually approved.*


```solidity
Expand All @@ -131,10 +131,9 @@ function allowance(address owner, address spender) public view override(ERC20, I

### getVersion

Returns the implementation version
returns the version of the contract

*This is to support our dev pipeline, and is present despite
this contract not being behind a proxy*
*this is to support our dev pipeline, and is present despite this contract not being behind a proxy*


```solidity
Expand All @@ -144,7 +143,7 @@ function getVersion() external pure returns (string memory);

|Name|Type|Description|
|----|----|-----------|
|`<none>`|`string`|Version string|
|`<none>`|`string`|version version string|


### _updatePermit2Allowance
Expand Down
58 changes: 23 additions & 35 deletions docs/src/src/PolygonMigration.sol/contract.PolygonMigration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# PolygonMigration
[Git Source](https://github.com/0xPolygon/pol-token/blob/a780764684dd1ef1ca70707f8069da35cddbd074/src/PolygonMigration.sol)
[Git Source](https://github.com/0xPolygon/pol-token/blob/4e60db3944f1f433beb163a74034e19c0fc68cf0/src/PolygonMigration.sol)

**Inherits:**
Ownable2StepUpgradeable, [IPolygonMigration](/src/interfaces/IPolygonMigration.sol/interface.IPolygonMigration.md)
Expand Down Expand Up @@ -35,10 +35,6 @@ bool public unmigrationLocked;


### __gap
*This empty reserved space is put in place to allow future versions to add new
variables without shifting down storage in the inheritance chain.
See https://docs.openzeppelin.com/contracts/4.x/upgradeable#storage_gaps*


```solidity
uint256[49] private __gap;
Expand Down Expand Up @@ -84,9 +80,9 @@ function setPolygonToken(address polygon_) external onlyOwner;

### migrate

This function allows for migrating MATIC tokens to POL tokens
this function allows for migrating MATIC tokens to POL tokens

*The function does not do any validation since the migration is a one-way process*
*the function does not do any validation since the migration is a one-way process*


```solidity
Expand All @@ -96,16 +92,14 @@ function migrate(uint256 amount) external;

|Name|Type|Description|
|----|----|-----------|
|`amount`|`uint256`|Amount of MATIC to migrate|
|`amount`|`uint256`|amount of MATIC to migrate|


### unmigrate

This function allows for unmigrating from POL tokens to MATIC tokens

*The function can only be called when unmigration is unlocked (lock updatable by governance)*
this function allows for unmigrating from POL tokens to MATIC tokens

*The function does not do any further validation, also note the unmigration is a reversible process*
*the function can only be called when unmigration is unlocked (lock updatable by governance)*


```solidity
Expand All @@ -115,16 +109,14 @@ function unmigrate(uint256 amount) external onlyUnmigrationUnlocked;

|Name|Type|Description|
|----|----|-----------|
|`amount`|`uint256`|Amount of POL to migrate|
|`amount`|`uint256`|amount of POL to migrate|


### unmigrateTo

This function allows for unmigrating POL tokens (from msg.sender) to MATIC tokens (to account)

*The function can only be called when unmigration is unlocked (lock updatable by governance)*
this function allows for unmigrating POL tokens (from msg.sender) to MATIC tokens (to account)

*The function does not do any further validation, also note the unmigration is a reversible process*
*the function can only be called when unmigration is unlocked (lock updatable by governance)*


```solidity
Expand All @@ -134,17 +126,15 @@ function unmigrateTo(address recipient, uint256 amount) external onlyUnmigration

|Name|Type|Description|
|----|----|-----------|
|`recipient`|`address`|Address to receive MATIC tokens|
|`amount`|`uint256`|Amount of POL to migrate|
|`recipient`|`address`|address to receive MATIC tokens|
|`amount`|`uint256`|amount of POL to migrate|


### unmigrateWithPermit

This function allows for unmigrating from POL tokens to MATIC tokens using an EIP-2612 permit
this function allows for unmigrating from POL tokens to MATIC tokens using an EIP-2612 permit

*The function can only be called when unmigration is unlocked (lock updatable by governance)*

*The function does not do any further validation, also note the unmigration is a reversible process*
*the function can only be called when unmigration is unlocked (lock updatable by governance)*


```solidity
Expand All @@ -156,18 +146,18 @@ function unmigrateWithPermit(uint256 amount, uint256 deadline, uint8 v, bytes32

|Name|Type|Description|
|----|----|-----------|
|`amount`|`uint256`|Amount of POL to migrate|
|`deadline`|`uint256`|Deadline for the permit|
|`amount`|`uint256`|amount of POL to migrate|
|`deadline`|`uint256`|deadline for the permit|
|`v`|`uint8`|v value of the permit signature|
|`r`|`bytes32`|r value of the permit signature|
|`s`|`bytes32`|s value of the permit signature|


### updateUnmigrationLock

Allows governance to lock or unlock the unmigration process
allows governance to lock or unlock the unmigration process

*The function does not do any validation since governance can update the unmigration process if required*
*the function does not do any validation since governance can update the unmigration process if required*


```solidity
Expand All @@ -177,12 +167,12 @@ function updateUnmigrationLock(bool unmigrationLocked_) external onlyOwner;

|Name|Type|Description|
|----|----|-----------|
|`unmigrationLocked_`|`bool`|New unmigration lock status|
|`unmigrationLocked_`|`bool`||


### getVersion

Returns the implementation version
returns the version of the contract


```solidity
Expand All @@ -192,16 +182,14 @@ function getVersion() external pure returns (string memory);

|Name|Type|Description|
|----|----|-----------|
|`<none>`|`string`|Version string|
|`<none>`|`string`|version version string|


### burn

Allows governance to burn `amount` of POL tokens

*This functions burns POL by sending to dead address*
allows governance to burn `amount` of POL tokens

*does not change totalSupply in the internal accounting of POL*
*this functions burns POL by sending to dead address*


```solidity
Expand All @@ -211,6 +199,6 @@ function burn(uint256 amount) external onlyOwner;

|Name|Type|Description|
|----|----|-----------|
|`amount`|`uint256`|Amount of POL to burn|
|`amount`|`uint256`|amount of POL to burn|


Loading