From 4e60db3944f1f433beb163a74034e19c0fc68cf0 Mon Sep 17 00:00:00 2001
From: gretzke <daniel@gretzke.de>
Date: Tue, 17 Oct 2023 18:52:23 +0200
Subject: [PATCH 1/4] move natspec to interfaces

---
 src/DefaultEmissionManager.sol             | 23 ++-----
 src/PolygonEcosystemToken.sol              | 20 ++-----
 src/PolygonMigration.sol                   | 41 +++----------
 src/interfaces/IDefaultEmissionManager.sol | 35 +++++++++--
 src/interfaces/IPolygonEcosystemToken.sol  | 57 +++++++++++++++---
 src/interfaces/IPolygonMigration.sol       | 70 +++++++++++++++++++---
 6 files changed, 160 insertions(+), 86 deletions(-)

diff --git a/src/DefaultEmissionManager.sol b/src/DefaultEmissionManager.sol
index c28b555..e7d4e72 100644
--- a/src/DefaultEmissionManager.sol
+++ b/src/DefaultEmissionManager.sol
@@ -11,12 +11,11 @@ import {PowUtil} from "./lib/PowUtil.sol";
 /// @title Default Emission Manager
 /// @author Polygon Labs (@DhairyaSethi, @gretzke, @qedk, @simonDos)
 /// @notice A default emission manager implementation for the Polygon ERC20 token contract on Ethereum L1
-/// @dev The contract allows for a 3% mint per year (compounded). 2% stakeManager(Hub) and 1% treasury
+/// @dev The contract allows for a 3% mint per year (compounded). 2% staking layer and 1% treasury
 /// @custom:security-contact security@polygon.technology
 contract DefaultEmissionManager is Ownable2StepUpgradeable, IDefaultEmissionManager {
     using SafeERC20 for IPolygonEcosystemToken;
 
-    // log2(3%pa continuously compounded emission per year) in 18 decimals, see _inflatedSupplyAfter
     uint256 public constant INTEREST_PER_YEAR_LOG2 = 0.04264433740849372e18;
     uint256 public constant START_SUPPLY = 10_000_000_000e18;
     address private immutable DEPLOYER;
@@ -54,9 +53,7 @@ contract DefaultEmissionManager is Ownable2StepUpgradeable, IDefaultEmissionMana
         _transferOwnership(owner_);
     }
 
-    /// @notice Allows anyone to mint tokens to the stakeManager and treasury contracts based on current emission rates
-    /// @dev 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)
+    /// @inheritdoc IDefaultEmissionManager
     function mint() external {
         uint256 currentSupply = token.totalSupply(); // totalSupply after the last mint
         uint256 newSupply = inflatedSupplyAfter(
@@ -77,28 +74,16 @@ contract DefaultEmissionManager is Ownable2StepUpgradeable, IDefaultEmissionMana
         migration.unmigrateTo(stakeManager, stakeManagerAmt);
     }
 
-    /// @notice Returns total supply from compounded emission after timeElapsed from startTimestamp (deployment)
-    /// @param timeElapsed The time elapsed since startTimestamp
-    /// @dev 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.04264433740849372 with 18 decimals, as the interest rate does not change, hard code the value
-    /// @return supply total supply from compounded emission after timeElapsed
+    /// @inheritdoc IDefaultEmissionManager
     function inflatedSupplyAfter(uint256 timeElapsed) public pure returns (uint256 supply) {
         uint256 supplyFactor = PowUtil.exp2((INTEREST_PER_YEAR_LOG2 * timeElapsed) / 365 days);
         supply = (supplyFactor * START_SUPPLY) / 1e18;
     }
 
-    /// @notice Returns the implementation version
-    /// @return Version string
+    /// @inheritdoc IDefaultEmissionManager
     function getVersion() external pure returns (string memory) {
         return "1.1.0";
     }
 
-    /**
-     * @dev 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
-     */
     uint256[48] private __gap;
 }
diff --git a/src/PolygonEcosystemToken.sol b/src/PolygonEcosystemToken.sol
index d06b996..ac4b765 100644
--- a/src/PolygonEcosystemToken.sol
+++ b/src/PolygonEcosystemToken.sol
@@ -15,7 +15,7 @@ contract PolygonEcosystemToken is ERC20Permit, AccessControlEnumerable, IPolygon
     bytes32 public constant CAP_MANAGER_ROLE = keccak256("CAP_MANAGER_ROLE");
     bytes32 public constant PERMIT2_REVOKER_ROLE = keccak256("PERMIT2_REVOKER_ROLE");
     address public constant PERMIT2 = 0x000000000022D473030F116dDEE9F6B43aC78BA3;
-    uint256 public mintPerSecondCap = 13.37e18; // 13.37 POL tokens per second. will limit emission in ~23 years
+    uint256 public mintPerSecondCap = 13.37e18;
     uint256 public lastMint;
     bool public permit2Enabled;
 
@@ -41,10 +41,7 @@ contract PolygonEcosystemToken is ERC20Permit, AccessControlEnumerable, IPolygon
         _updatePermit2Allowance(true);
     }
 
-    /// @notice Mint token entrypoint for the emission manager contract
-    /// @dev The function only validates the sender, the emission manager is responsible for correctness
-    /// @param to Address to mint to
-    /// @param amount Amount to mint
+    /// @inheritdoc IPolygonEcosystemToken
     function mint(address to, uint256 amount) external onlyRole(EMISSION_ROLE) {
         uint256 timeElapsedSinceLastMint = block.timestamp - lastMint;
         uint256 maxMint = timeElapsedSinceLastMint * mintPerSecondCap;
@@ -54,29 +51,24 @@ contract PolygonEcosystemToken is ERC20Permit, AccessControlEnumerable, IPolygon
         _mint(to, amount);
     }
 
-    /// @notice Update the limit of tokens that can be minted per second
-    /// @param newCap the amount of tokens in 18 decimals as an absolute value
+    /// @inheritdoc IPolygonEcosystemToken
     function updateMintCap(uint256 newCap) external onlyRole(CAP_MANAGER_ROLE) {
         emit MintCapUpdated(mintPerSecondCap, newCap);
         mintPerSecondCap = newCap;
     }
 
-    /// @notice Manages the default max approval to the permit2 contract
-    /// @param enabled If true, the permit2 contract has full approval by default, if false, it has no approval by default
+    /// @inheritdoc IPolygonEcosystemToken
     function updatePermit2Allowance(bool enabled) external onlyRole(PERMIT2_REVOKER_ROLE) {
         _updatePermit2Allowance(enabled);
     }
 
-    /// @notice The permit2 contract has full approval by default. If the approval is revoked, it can still be manually approved.
+    /// @dev The permit2 contract has full approval by default. If the approval is revoked, it can still be manually approved.
     function allowance(address owner, address spender) public view override(ERC20, IERC20) returns (uint256) {
         if (spender == PERMIT2 && permit2Enabled) return type(uint256).max;
         return super.allowance(owner, spender);
     }
 
-    /// @notice Returns the implementation version
-    /// @dev This is to support our dev pipeline, and is present despite
-    /// this contract not being behind a proxy
-    /// @return Version string
+    /// @inheritdoc IPolygonEcosystemToken
     function getVersion() external pure returns (string memory) {
         return "1.1.0";
     }
diff --git a/src/PolygonMigration.sol b/src/PolygonMigration.sol
index 9cc05a4..8a0ab5b 100644
--- a/src/PolygonMigration.sol
+++ b/src/PolygonMigration.sol
@@ -43,9 +43,7 @@ contract PolygonMigration is Ownable2StepUpgradeable, IPolygonMigration {
         polygon = IERC20(polygon_);
     }
 
-    /// @notice This function allows for migrating MATIC tokens to POL tokens
-    /// @dev The function does not do any validation since the migration is a one-way process
-    /// @param amount Amount of MATIC to migrate
+    /// @inheritdoc IPolygonMigration
     function migrate(uint256 amount) external {
         emit Migrated(msg.sender, amount);
 
@@ -53,10 +51,7 @@ contract PolygonMigration is Ownable2StepUpgradeable, IPolygonMigration {
         polygon.safeTransfer(msg.sender, amount);
     }
 
-    /// @notice This function allows for unmigrating from POL tokens to MATIC tokens
-    /// @dev The function can only be called when unmigration is unlocked (lock updatable by governance)
-    /// @dev The function does not do any further validation, also note the unmigration is a reversible process
-    /// @param amount Amount of POL to migrate
+    /// @inheritdoc IPolygonMigration
     function unmigrate(uint256 amount) external onlyUnmigrationUnlocked {
         emit Unmigrated(msg.sender, msg.sender, amount);
 
@@ -64,11 +59,7 @@ contract PolygonMigration is Ownable2StepUpgradeable, IPolygonMigration {
         matic.safeTransfer(msg.sender, amount);
     }
 
-    /// @notice This function allows for unmigrating POL tokens (from msg.sender) to MATIC tokens (to account)
-    /// @dev The function can only be called when unmigration is unlocked (lock updatable by governance)
-    /// @dev The function does not do any further validation, also note the unmigration is a reversible process
-    /// @param recipient Address to receive MATIC tokens
-    /// @param amount Amount of POL to migrate
+    /// @inheritdoc IPolygonMigration
     function unmigrateTo(address recipient, uint256 amount) external onlyUnmigrationUnlocked {
         emit Unmigrated(msg.sender, recipient, amount);
 
@@ -76,14 +67,7 @@ contract PolygonMigration is Ownable2StepUpgradeable, IPolygonMigration {
         matic.safeTransfer(recipient, amount);
     }
 
-    /// @notice This function allows for unmigrating from POL tokens to MATIC tokens using an EIP-2612 permit
-    /// @dev The function can only be called when unmigration is unlocked (lock updatable by governance)
-    /// @dev The function does not do any further validation, also note the unmigration is a reversible process
-    /// @param amount Amount of POL to migrate
-    /// @param deadline Deadline for the permit
-    /// @param v v value of the permit signature
-    /// @param r r value of the permit signature
-    /// @param s s value of the permit signature
+    /// @inheritdoc IPolygonMigration
     function unmigrateWithPermit(
         uint256 amount,
         uint256 deadline,
@@ -98,32 +82,21 @@ contract PolygonMigration is Ownable2StepUpgradeable, IPolygonMigration {
         matic.safeTransfer(msg.sender, amount);
     }
 
-    /// @notice Allows governance to lock or unlock the unmigration process
-    /// @dev The function does not do any validation since governance can update the unmigration process if required
-    /// @param unmigrationLocked_ New unmigration lock status
+    /// @inheritdoc IPolygonMigration
     function updateUnmigrationLock(bool unmigrationLocked_) external onlyOwner {
         emit UnmigrationLockUpdated(unmigrationLocked_);
         unmigrationLocked = unmigrationLocked_;
     }
 
-    /// @notice Returns the implementation version
-    /// @return Version string
+    /// @inheritdoc IPolygonMigration
     function getVersion() external pure returns (string memory) {
         return "1.0.0";
     }
 
-    /// @notice Allows governance to burn `amount` of POL tokens
-    /// @dev This functions burns POL by sending to dead address
-    /// @dev does not change totalSupply in the internal accounting of POL
-    /// @param amount Amount of POL to burn
+    /// @inheritdoc IPolygonMigration
     function burn(uint256 amount) external onlyOwner {
         polygon.safeTransfer(0x000000000000000000000000000000000000dEaD, amount);
     }
 
-    /**
-     * @dev 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
-     */
     uint256[49] private __gap;
 }
diff --git a/src/interfaces/IDefaultEmissionManager.sol b/src/interfaces/IDefaultEmissionManager.sol
index 8c5cc1b..02182c8 100644
--- a/src/interfaces/IDefaultEmissionManager.sol
+++ b/src/interfaces/IDefaultEmissionManager.sol
@@ -3,18 +3,45 @@ pragma solidity 0.8.21;
 
 import {IPolygonEcosystemToken} from "./IPolygonEcosystemToken.sol";
 
+/// @title Default Emission Manager
+/// @author Polygon Labs (@DhairyaSethi, @gretzke, @qedk, @simonDos)
+/// @notice A default emission manager implementation for the Polygon ERC20 token contract on Ethereum L1
+/// @dev The contract allows for a 3% mint per year (compounded). 2% staking layer and 1% treasury
+/// @custom:security-contact security@polygon.technology
 interface IDefaultEmissionManager {
+    /// @notice emitted when new tokens are minted
+    /// @param amount the amount of tokens minted
+    /// @param caller the caller of the mint function
+    event TokenMint(uint256 amount, address caller);
+
+    /// @notice thrown when a zero address is supplied during deployment
     error InvalidAddress();
 
-    event TokenMint(uint256 amount, address caller);
+    /// @notice allows anyone to mint tokens to the stakeManager and treasury contracts based on current emission rates
+    /// @dev 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)
+    function mint() external;
 
-    function getVersion() external pure returns (string memory version);
+    /// @return log2(3%pa continuously compounded emission per year) in 18 decimals, see _inflatedSupplyAfter
+    function INTEREST_PER_YEAR_LOG2() external view returns (uint256);
 
+    /// @return the start supply of the POL token in 18 decimals
+    function START_SUPPLY() external view returns (uint256);
+
+    /// @return polygonEcosystemToken address of the POL token
     function token() external view returns (IPolygonEcosystemToken polygonEcosystemToken);
 
+    /// @return timestamp timestamp of initialisation of the contract, when emission starts
     function startTimestamp() external view returns (uint256 timestamp);
 
-    function mint() external;
-
+    /// @notice returns total supply from compounded emission after timeElapsed from startTimestamp (deployment)
+    /// @param timeElapsedInSeconds the time elapsed since startTimestamp
+    /// @return inflatedSupply supply total supply from compounded emission after timeElapsed
+    /// @dev 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.04264433740849372 with 18 decimals, as the interest rate does not change, hard code the value
     function inflatedSupplyAfter(uint256 timeElapsedInSeconds) external pure returns (uint256 inflatedSupply);
+
+    /// @return version the implementation version
+    function getVersion() external pure returns (string memory version);
 }
diff --git a/src/interfaces/IPolygonEcosystemToken.sol b/src/interfaces/IPolygonEcosystemToken.sol
index 9547b6e..6a3280e 100644
--- a/src/interfaces/IPolygonEcosystemToken.sol
+++ b/src/interfaces/IPolygonEcosystemToken.sol
@@ -5,24 +5,67 @@ import {IERC20Permit} from "openzeppelin-contracts/contracts/token/ERC20/extensi
 import {IERC20} from "openzeppelin-contracts/contracts/token/ERC20/IERC20.sol";
 import {IAccessControlEnumerable} from "openzeppelin-contracts/contracts/access/AccessControlEnumerable.sol";
 
+/// @title Polygon ERC20 token
+/// @author Polygon Labs (@DhairyaSethi, @gretzke, @qedk, @simonDos)
+/// @notice This is the Polygon ERC20 token contract on Ethereum L1
+/// @dev The contract allows for a 1-to-1 representation between $POL and $MATIC and allows for additional emission based on hub and treasury requirements
+/// @custom:security-contact security@polygon.technology
 interface IPolygonEcosystemToken is IERC20, IERC20Permit, IAccessControlEnumerable {
+    /// @notice emitted when the mint cap is updated
+    /// @param oldCap the old mint cap
+    /// @param newCap the new mint cap
     event MintCapUpdated(uint256 oldCap, uint256 newCap);
+
+    /// @notice emitted when the permit2 integration is enabled/disabled
+    /// @param enabled whether the permit2 integration is enabled or not
     event Permit2AllowanceUpdated(bool enabled);
 
+    /// @notice thrown when a zero address is supplied during deployment
     error InvalidAddress();
+
+    /// @notice thrown when the mint cap is exceeded
+    /// @param maxMint the maximum amount of tokens that can be minted
+    /// @param mintRequested the amount of tokens that were requested to be minted
     error MaxMintExceeded(uint256 maxMint, uint256 mintRequested);
 
-    function mintPerSecondCap() external view returns (uint256 currentMintPerSecondCap);
+    /// @notice mint token entrypoint for the emission manager contract
+    /// @param to address to mint to
+    /// @param amount amount to mint
+    /// @dev The function only validates the sender, the emission manager is responsible for correctness
+    function mint(address to, uint256 amount) external;
 
-    function getVersion() external pure returns (string memory version);
+    /// @notice update the limit of tokens that can be minted per second
+    /// @param newCap the amount of tokens in 18 decimals as an absolute value
+    function updateMintCap(uint256 newCap) external;
 
-    function lastMint() external view returns (uint256 lastMintTimestamp);
+    /// @notice manages the default max approval to the permit2 contract
+    /// @param enabled If true, the permit2 contract has full approval by default, if false, it has no approval by default
+    function updatePermit2Allowance(bool enabled) external;
 
-    function permit2Enabled() external view returns (bool isPermit2Enabled);
+    /// @return the role that allows minting of tokens
+    function EMISSION_ROLE() external view returns (bytes32);
 
-    function mint(address to, uint256 amount) external;
+    /// @return the role that allows updating the mint cap
+    function CAP_MANAGER_ROLE() external view returns (bytes32);
 
-    function updateMintCap(uint256 newCap) external;
+    /// @return the role that allows revoking the permit2 approval
+    function PERMIT2_REVOKER_ROLE() external view returns (bytes32);
 
-    function updatePermit2Allowance(bool enabled) external;
+    /// @return the address of the permit2 contract
+    function PERMIT2() external view returns (address);
+
+    /// @return currentMintPerSecondCap the current amount of tokens that can be minted per second
+    /// @dev 13.37 POL tokens per second. will limit emission in ~23 years
+    function mintPerSecondCap() external view returns (uint256 currentMintPerSecondCap);
+
+    /// @return lastMintTimestamp the timestamp of the last mint
+    function lastMint() external view returns (uint256 lastMintTimestamp);
+
+    /// @return isPermit2Enabled whether the permit2 default approval is currently active
+    function permit2Enabled() external view returns (bool isPermit2Enabled);
+
+    /// @notice returns the version of the contract
+    /// @return version version string
+    /// @dev this is to support our dev pipeline, and is present despite this contract not being behind a proxy
+    function getVersion() external pure returns (string memory version);
 }
diff --git a/src/interfaces/IPolygonMigration.sol b/src/interfaces/IPolygonMigration.sol
index 78ec75f..014142e 100644
--- a/src/interfaces/IPolygonMigration.sol
+++ b/src/interfaces/IPolygonMigration.sol
@@ -3,30 +3,84 @@ pragma solidity 0.8.21;
 
 import {IERC20} from "openzeppelin-contracts/contracts/token/ERC20/IERC20.sol";
 
+/// @title Polygon Migration
+/// @author Polygon Labs (@DhairyaSethi, @gretzke, @qedk)
+/// @notice This is the migration contract for Matic <-> Polygon ERC20 token on Ethereum L1
+/// @dev The contract allows for a 1-to-1 conversion from $MATIC into $POL and vice-versa
+/// @custom:security-contact security@polygon.technology
 interface IPolygonMigration {
-    error UnmigrationLocked();
-    error InvalidAddressOrAlreadySet();
-    error InvalidAddress();
-
+    /// @notice emitted when MATIC are migrated to POL
+    /// @param account the account that migrated MATIC
+    /// @param amount the amount of MATIC that was migrated
     event Migrated(address indexed account, uint256 amount);
+
+    /// @notice emitted when POL are unmigrated to MATIC
+    /// @param account the account that unmigrated POL
+    /// @param recipient the account that received MATIC
+    /// @param amount the amount of POL that was unmigrated
     event Unmigrated(address indexed account, address indexed recipient, uint256 amount);
+
+    /// @notice emitted when the unmigration is enabled/disabled
+    /// @param lock whether the unmigration is enabled or not
     event UnmigrationLockUpdated(bool lock);
 
-    function unmigrationLocked() external view returns (bool isUnmigrationLocked);
+    /// @notice thrown when a user attempts to unmigrate while unmigration is locked
+    error UnmigrationLocked();
 
-    function polygon() external view returns (IERC20 polygonEcosystemToken);
+    /// @notice thrown when an invalid POL token address is supplied or the address is already set
+    error InvalidAddressOrAlreadySet();
 
-    function getVersion() external pure returns (string memory version);
+    /// @notice thrown when a zero address is supplied during deployment
+    error InvalidAddress();
 
+    /// @notice this function allows for migrating MATIC tokens to POL tokens
+    /// @param amount amount of MATIC to migrate
+    /// @dev the function does not do any validation since the migration is a one-way process
     function migrate(uint256 amount) external;
 
+    /// @notice this function allows for unmigrating from POL tokens to MATIC tokens
+    /// @param amount amount of POL to migrate
+    /// @dev the function can only be called when unmigration is unlocked (lock updatable by governance)
+    /// @dev the function does not do any further validation, also note the unmigration is a reversible process
     function unmigrate(uint256 amount) external;
 
+    /// @notice this function allows for unmigrating POL tokens (from msg.sender) to MATIC tokens (to account)
+    /// @param recipient address to receive MATIC tokens
+    /// @param amount amount of POL to migrate
+    /// @dev the function can only be called when unmigration is unlocked (lock updatable by governance)
+    /// @dev the function does not do any further validation, also note the unmigration is a reversible process
     function unmigrateTo(address recipient, uint256 amount) external;
 
+    /// @notice this function allows for unmigrating from POL tokens to MATIC tokens using an EIP-2612 permit
+    /// @param amount amount of POL to migrate
+    /// @param deadline deadline for the permit
+    /// @param v v value of the permit signature
+    /// @param r r value of the permit signature
+    /// @param s s value of the permit signature
+    /// @dev the function can only be called when unmigration is unlocked (lock updatable by governance)
+    /// @dev the function does not do any further validation, also note the unmigration is a reversible process
     function unmigrateWithPermit(uint256 amount, uint256 deadline, uint8 v, bytes32 r, bytes32 s) external;
 
-    function updateUnmigrationLock(bool unmigrationLocked_) external;
+    /// @notice allows governance to lock or unlock the unmigration process
+    /// @param unmigrationLocked new unmigration lock status
+    /// @dev the function does not do any validation since governance can update the unmigration process if required
+    function updateUnmigrationLock(bool unmigrationLocked) external;
 
+    /// @notice allows governance to burn `amount` of POL tokens
+    /// @param amount amount of POL to burn
+    /// @dev this functions burns POL by sending to dead address
+    /// @dev does not change totalSupply in the internal accounting of POL
     function burn(uint256 amount) external;
+
+    /// @return maticToken the MATIC token address
+    function matic() external view returns (IERC20 maticToken);
+
+    /// @return polygonEcosystemToken the POL token address
+    function polygon() external view returns (IERC20 polygonEcosystemToken);
+
+    /// @return isUnmigrationLocked whether the unmigration is locked or not
+    function unmigrationLocked() external view returns (bool isUnmigrationLocked);
+
+    /// @return version the implementation version
+    function getVersion() external pure returns (string memory version);
 }

From 3ee4da9443e606c82ab5580d6571193eee9b546c Mon Sep 17 00:00:00 2001
From: DhairyaSethi <55102840+DhairyaSethi@users.noreply.github.com>
Date: Tue, 17 Oct 2023 22:39:00 +0530
Subject: [PATCH 2/4] docs: forge foc

---
 docs/src/README.md                            |   6 +-
 .../contract.DefaultEmissionManager.md        |  31 ++--
 .../contract.PolygonEcosystemToken.md         |  25 ++-
 .../contract.PolygonMigration.md              |  58 +++----
 .../interface.IDefaultEmissionManager.md      |  92 +++++++++-
 .../interface.IPolygonEcosystemToken.md       | 154 +++++++++++++++--
 .../interface.IPolygonMigration.md            | 161 +++++++++++++++---
 .../src/lib/PowUtil.sol/library.PowUtil.md    |   2 +-
 8 files changed, 418 insertions(+), 111 deletions(-)

diff --git a/docs/src/README.md b/docs/src/README.md
index 335b989..d2f0533 100644
--- a/docs/src/README.md
+++ b/docs/src/README.md
@@ -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)
 
 ---
 
diff --git a/docs/src/src/DefaultEmissionManager.sol/contract.DefaultEmissionManager.md b/docs/src/src/DefaultEmissionManager.sol/contract.DefaultEmissionManager.md
index 5c89766..983ad44 100644
--- a/docs/src/src/DefaultEmissionManager.sol/contract.DefaultEmissionManager.md
+++ b/docs/src/src/DefaultEmissionManager.sol/contract.DefaultEmissionManager.md
@@ -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;
 ```
 
 
@@ -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;
@@ -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
@@ -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
@@ -124,19 +119,17 @@ 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
-
 
 ```solidity
 function getVersion() external pure returns (string memory);
@@ -145,6 +138,6 @@ function getVersion() external pure returns (string memory);
 
 |Name|Type|Description|
 |----|----|-----------|
-|`<none>`|`string`|Version string|
+|`<none>`|`string`|version the implementation version|
 
 
diff --git a/docs/src/src/PolygonEcosystemToken.sol/contract.PolygonEcosystemToken.md b/docs/src/src/PolygonEcosystemToken.sol/contract.PolygonEcosystemToken.md
index 2ead38b..d8a8ca1 100644
--- a/docs/src/src/PolygonEcosystemToken.sol/contract.PolygonEcosystemToken.md
+++ b/docs/src/src/PolygonEcosystemToken.sol/contract.PolygonEcosystemToken.md
@@ -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
 
@@ -44,7 +44,7 @@ address public constant PERMIT2 = 0x000000000022D473030F116dDEE9F6B43aC78BA3;
 ### mintPerSecondCap
 
 ```solidity
-uint256 public mintPerSecondCap = 10e18;
+uint256 public mintPerSecondCap = 13.37e18;
 ```
 
 
@@ -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*
 
@@ -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
@@ -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
@@ -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
@@ -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
@@ -144,7 +143,7 @@ function getVersion() external pure returns (string memory);
 
 |Name|Type|Description|
 |----|----|-----------|
-|`<none>`|`string`|Version string|
+|`<none>`|`string`|version version string|
 
 
 ### _updatePermit2Allowance
diff --git a/docs/src/src/PolygonMigration.sol/contract.PolygonMigration.md b/docs/src/src/PolygonMigration.sol/contract.PolygonMigration.md
index 4ecd2a1..2226b90 100644
--- a/docs/src/src/PolygonMigration.sol/contract.PolygonMigration.md
+++ b/docs/src/src/PolygonMigration.sol/contract.PolygonMigration.md
@@ -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)
@@ -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;
@@ -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
@@ -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
@@ -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
@@ -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
@@ -156,8 +146,8 @@ 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|
@@ -165,9 +155,9 @@ function unmigrateWithPermit(uint256 amount, uint256 deadline, uint8 v, bytes32
 
 ### 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
@@ -177,13 +167,11 @@ function updateUnmigrationLock(bool unmigrationLocked_) external onlyOwner;
 
 |Name|Type|Description|
 |----|----|-----------|
-|`unmigrationLocked_`|`bool`|New unmigration lock status|
+|`unmigrationLocked_`|`bool`||
 
 
 ### getVersion
 
-Returns the implementation version
-
 
 ```solidity
 function getVersion() external pure returns (string memory);
@@ -192,16 +180,14 @@ function getVersion() external pure returns (string memory);
 
 |Name|Type|Description|
 |----|----|-----------|
-|`<none>`|`string`|Version string|
+|`<none>`|`string`|version the implementation version|
 
 
 ### 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
@@ -211,6 +197,6 @@ function burn(uint256 amount) external onlyOwner;
 
 |Name|Type|Description|
 |----|----|-----------|
-|`amount`|`uint256`|Amount of POL to burn|
+|`amount`|`uint256`|amount of POL to burn|
 
 
diff --git a/docs/src/src/interfaces/IDefaultEmissionManager.sol/interface.IDefaultEmissionManager.md b/docs/src/src/interfaces/IDefaultEmissionManager.sol/interface.IDefaultEmissionManager.md
index 47515b3..b6f083a 100644
--- a/docs/src/src/interfaces/IDefaultEmissionManager.sol/interface.IDefaultEmissionManager.md
+++ b/docs/src/src/interfaces/IDefaultEmissionManager.sol/interface.IDefaultEmissionManager.md
@@ -1,21 +1,64 @@
 # IDefaultEmissionManager
-[Git Source](https://github.com/0xPolygon/pol-token/blob/a780764684dd1ef1ca70707f8069da35cddbd074/src/interfaces/IDefaultEmissionManager.sol)
+[Git Source](https://github.com/0xPolygon/pol-token/blob/4e60db3944f1f433beb163a74034e19c0fc68cf0/src/interfaces/IDefaultEmissionManager.sol)
+
+**Author:**
+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 3% mint per year (compounded). 2% staking layer and 1% treasury*
 
 
 ## Functions
-### getVersion
+### mint
+
+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)*
 
 
 ```solidity
-function getVersion() external pure returns (string memory version);
+function mint() external;
 ```
 
+### INTEREST_PER_YEAR_LOG2
+
+
+```solidity
+function INTEREST_PER_YEAR_LOG2() external view returns (uint256);
+```
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`<none>`|`uint256`|log2(3%pa continuously compounded emission per year) in 18 decimals, see _inflatedSupplyAfter|
+
+
+### START_SUPPLY
+
+
+```solidity
+function START_SUPPLY() external view returns (uint256);
+```
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`<none>`|`uint256`|the start supply of the POL token in 18 decimals|
+
+
 ### token
 
 
 ```solidity
 function token() external view returns (IPolygonEcosystemToken polygonEcosystemToken);
 ```
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`polygonEcosystemToken`|`IPolygonEcosystemToken`|address of the POL token|
+
 
 ### startTimestamp
 
@@ -23,23 +66,56 @@ function token() external view returns (IPolygonEcosystemToken polygonEcosystemT
 ```solidity
 function startTimestamp() external view returns (uint256 timestamp);
 ```
+**Returns**
 
-### mint
+|Name|Type|Description|
+|----|----|-----------|
+|`timestamp`|`uint256`|timestamp of initialisation of the contract, when emission starts|
+
+
+### inflatedSupplyAfter
+
+returns total supply from compounded emission after timeElapsed from startTimestamp (deployment)
+
+*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.04264433740849372 with 18 decimals, as the interest rate does not change, hard code the value*
 
 
 ```solidity
-function mint() external;
+function inflatedSupplyAfter(uint256 timeElapsedInSeconds) external pure returns (uint256 inflatedSupply);
 ```
+**Parameters**
 
-### inflatedSupplyAfter
+|Name|Type|Description|
+|----|----|-----------|
+|`timeElapsedInSeconds`|`uint256`|the time elapsed since startTimestamp|
+
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`inflatedSupply`|`uint256`|supply total supply from compounded emission after timeElapsed|
+
+
+### getVersion
 
 
 ```solidity
-function inflatedSupplyAfter(uint256 timeElapsedInSeconds) external pure returns (uint256 inflatedSupply);
+function getVersion() external pure returns (string memory version);
 ```
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`version`|`string`|the implementation version|
+
 
 ## Events
 ### TokenMint
+emitted when new tokens are minted
+
 
 ```solidity
 event TokenMint(uint256 amount, address caller);
@@ -47,6 +123,8 @@ event TokenMint(uint256 amount, address caller);
 
 ## Errors
 ### InvalidAddress
+thrown when a zero address is supplied during deployment
+
 
 ```solidity
 error InvalidAddress();
diff --git a/docs/src/src/interfaces/IPolygonEcosystemToken.sol/interface.IPolygonEcosystemToken.md b/docs/src/src/interfaces/IPolygonEcosystemToken.sol/interface.IPolygonEcosystemToken.md
index 05e5357..5cb040e 100644
--- a/docs/src/src/interfaces/IPolygonEcosystemToken.sol/interface.IPolygonEcosystemToken.md
+++ b/docs/src/src/interfaces/IPolygonEcosystemToken.sol/interface.IPolygonEcosystemToken.md
@@ -1,68 +1,188 @@
 # IPolygonEcosystemToken
-[Git Source](https://github.com/0xPolygon/pol-token/blob/a780764684dd1ef1ca70707f8069da35cddbd074/src/interfaces/IPolygonEcosystemToken.sol)
+[Git Source](https://github.com/0xPolygon/pol-token/blob/4e60db3944f1f433beb163a74034e19c0fc68cf0/src/interfaces/IPolygonEcosystemToken.sol)
 
 **Inherits:**
 IERC20, IERC20Permit, IAccessControlEnumerable
 
+**Author:**
+Polygon Labs (@DhairyaSethi, @gretzke, @qedk, @simonDos)
+
+This is the Polygon ERC20 token contract on Ethereum L1
+
+*The contract allows for a 1-to-1 representation between $POL and $MATIC and allows for additional emission based on hub and treasury requirements*
+
 
 ## Functions
-### mintPerSecondCap
+### mint
+
+mint token entrypoint for the emission manager contract
+
+*The function only validates the sender, the emission manager is responsible for correctness*
 
 
 ```solidity
-function mintPerSecondCap() external view returns (uint256 currentMintPerSecondCap);
+function mint(address to, uint256 amount) external;
 ```
+**Parameters**
 
-### getVersion
+|Name|Type|Description|
+|----|----|-----------|
+|`to`|`address`|address to mint to|
+|`amount`|`uint256`|amount to mint|
+
+
+### updateMintCap
+
+update the limit of tokens that can be minted per second
 
 
 ```solidity
-function getVersion() external pure returns (string memory version);
+function updateMintCap(uint256 newCap) external;
 ```
+**Parameters**
 
-### lastMint
+|Name|Type|Description|
+|----|----|-----------|
+|`newCap`|`uint256`|the amount of tokens in 18 decimals as an absolute value|
+
+
+### updatePermit2Allowance
+
+manages the default max approval to the permit2 contract
 
 
 ```solidity
-function lastMint() external view returns (uint256 lastMintTimestamp);
+function updatePermit2Allowance(bool enabled) external;
 ```
+**Parameters**
 
-### permit2Enabled
+|Name|Type|Description|
+|----|----|-----------|
+|`enabled`|`bool`|If true, the permit2 contract has full approval by default, if false, it has no approval by default|
+
+
+### EMISSION_ROLE
 
 
 ```solidity
-function permit2Enabled() external view returns (bool isPermit2Enabled);
+function EMISSION_ROLE() external view returns (bytes32);
 ```
+**Returns**
 
-### mint
+|Name|Type|Description|
+|----|----|-----------|
+|`<none>`|`bytes32`|the role that allows minting of tokens|
+
+
+### CAP_MANAGER_ROLE
 
 
 ```solidity
-function mint(address to, uint256 amount) external;
+function CAP_MANAGER_ROLE() external view returns (bytes32);
 ```
+**Returns**
 
-### updateMintCap
+|Name|Type|Description|
+|----|----|-----------|
+|`<none>`|`bytes32`|the role that allows updating the mint cap|
+
+
+### PERMIT2_REVOKER_ROLE
 
 
 ```solidity
-function updateMintCap(uint256 newCap) external;
+function PERMIT2_REVOKER_ROLE() external view returns (bytes32);
 ```
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`<none>`|`bytes32`|the role that allows revoking the permit2 approval|
 
-### updatePermit2Allowance
+
+### PERMIT2
 
 
 ```solidity
-function updatePermit2Allowance(bool enabled) external;
+function PERMIT2() external view returns (address);
+```
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`<none>`|`address`|the address of the permit2 contract|
+
+
+### mintPerSecondCap
+
+*13.37 POL tokens per second. will limit emission in ~23 years*
+
+
+```solidity
+function mintPerSecondCap() external view returns (uint256 currentMintPerSecondCap);
+```
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`currentMintPerSecondCap`|`uint256`|the current amount of tokens that can be minted per second|
+
+
+### lastMint
+
+
+```solidity
+function lastMint() external view returns (uint256 lastMintTimestamp);
+```
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`lastMintTimestamp`|`uint256`|the timestamp of the last mint|
+
+
+### permit2Enabled
+
+
+```solidity
+function permit2Enabled() external view returns (bool isPermit2Enabled);
 ```
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`isPermit2Enabled`|`bool`|whether the permit2 default approval is currently active|
+
+
+### getVersion
+
+returns the version of the contract
+
+*this is to support our dev pipeline, and is present despite this contract not being behind a proxy*
+
+
+```solidity
+function getVersion() external pure returns (string memory version);
+```
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`version`|`string`|version string|
+
 
 ## Events
 ### MintCapUpdated
+emitted when the mint cap is updated
+
 
 ```solidity
 event MintCapUpdated(uint256 oldCap, uint256 newCap);
 ```
 
 ### Permit2AllowanceUpdated
+emitted when the permit2 integration is enabled/disabled
+
 
 ```solidity
 event Permit2AllowanceUpdated(bool enabled);
@@ -70,12 +190,16 @@ event Permit2AllowanceUpdated(bool enabled);
 
 ## Errors
 ### InvalidAddress
+thrown when a zero address is supplied during deployment
+
 
 ```solidity
 error InvalidAddress();
 ```
 
 ### MaxMintExceeded
+thrown when the mint cap is exceeded
+
 
 ```solidity
 error MaxMintExceeded(uint256 maxMint, uint256 mintRequested);
diff --git a/docs/src/src/interfaces/IPolygonMigration.sol/interface.IPolygonMigration.md b/docs/src/src/interfaces/IPolygonMigration.sol/interface.IPolygonMigration.md
index 33e29ac..ebc7a11 100644
--- a/docs/src/src/interfaces/IPolygonMigration.sol/interface.IPolygonMigration.md
+++ b/docs/src/src/interfaces/IPolygonMigration.sol/interface.IPolygonMigration.md
@@ -1,85 +1,202 @@
 # IPolygonMigration
-[Git Source](https://github.com/0xPolygon/pol-token/blob/a780764684dd1ef1ca70707f8069da35cddbd074/src/interfaces/IPolygonMigration.sol)
+[Git Source](https://github.com/0xPolygon/pol-token/blob/4e60db3944f1f433beb163a74034e19c0fc68cf0/src/interfaces/IPolygonMigration.sol)
 
+**Author:**
+Polygon Labs (@DhairyaSethi, @gretzke, @qedk)
 
-## Functions
-### unmigrationLocked
+This is the migration contract for Matic <-> Polygon ERC20 token on Ethereum L1
 
+*The contract allows for a 1-to-1 conversion from $MATIC into $POL and vice-versa*
 
-```solidity
-function unmigrationLocked() external view returns (bool isUnmigrationLocked);
-```
 
-### polygon
+## Functions
+### migrate
 
+this function allows for migrating MATIC tokens to POL tokens
 
-```solidity
-function polygon() external view returns (IERC20 polygonEcosystemToken);
-```
-
-### getVersion
+*the function does not do any validation since the migration is a one-way process*
 
 
 ```solidity
-function getVersion() external pure returns (string memory version);
+function migrate(uint256 amount) external;
 ```
+**Parameters**
 
-### migrate
-
+|Name|Type|Description|
+|----|----|-----------|
+|`amount`|`uint256`|amount of MATIC to migrate|
 
-```solidity
-function migrate(uint256 amount) external;
-```
 
 ### 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)*
+
+*the function does not do any further validation, also note the unmigration is a reversible process*
+
 
 ```solidity
 function unmigrate(uint256 amount) external;
 ```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`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)*
+
+*the function does not do any further validation, also note the unmigration is a reversible process*
+
 
 ```solidity
 function unmigrateTo(address recipient, uint256 amount) external;
 ```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`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
+
+*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*
+
 
 ```solidity
 function unmigrateWithPermit(uint256 amount, uint256 deadline, uint8 v, bytes32 r, bytes32 s) external;
 ```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`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
+
+*the function does not do any validation since governance can update the unmigration process if required*
+
 
 ```solidity
-function updateUnmigrationLock(bool unmigrationLocked_) external;
+function updateUnmigrationLock(bool unmigrationLocked) external;
 ```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`unmigrationLocked`|`bool`|new unmigration lock status|
+
 
 ### burn
 
+allows governance to burn `amount` of POL tokens
+
+*this functions burns POL by sending to dead address*
+
+*does not change totalSupply in the internal accounting of POL*
+
 
 ```solidity
 function burn(uint256 amount) external;
 ```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`amount`|`uint256`|amount of POL to burn|
+
+
+### matic
+
+
+```solidity
+function matic() external view returns (IERC20 maticToken);
+```
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`maticToken`|`IERC20`|the MATIC token address|
+
+
+### polygon
+
+
+```solidity
+function polygon() external view returns (IERC20 polygonEcosystemToken);
+```
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`polygonEcosystemToken`|`IERC20`|the POL token address|
+
+
+### unmigrationLocked
+
+
+```solidity
+function unmigrationLocked() external view returns (bool isUnmigrationLocked);
+```
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`isUnmigrationLocked`|`bool`|whether the unmigration is locked or not|
+
+
+### getVersion
+
+
+```solidity
+function getVersion() external pure returns (string memory version);
+```
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`version`|`string`|the implementation version|
+
 
 ## Events
 ### Migrated
+emitted when MATIC are migrated to POL
+
 
 ```solidity
 event Migrated(address indexed account, uint256 amount);
 ```
 
 ### Unmigrated
+emitted when POL are unmigrated to MATIC
+
 
 ```solidity
 event Unmigrated(address indexed account, address indexed recipient, uint256 amount);
 ```
 
 ### UnmigrationLockUpdated
+emitted when the unmigration is enabled/disabled
+
 
 ```solidity
 event UnmigrationLockUpdated(bool lock);
@@ -87,18 +204,24 @@ event UnmigrationLockUpdated(bool lock);
 
 ## Errors
 ### UnmigrationLocked
+thrown when a user attempts to unmigrate while unmigration is locked
+
 
 ```solidity
 error UnmigrationLocked();
 ```
 
 ### InvalidAddressOrAlreadySet
+thrown when an invalid POL token address is supplied or the address is already set
+
 
 ```solidity
 error InvalidAddressOrAlreadySet();
 ```
 
 ### InvalidAddress
+thrown when a zero address is supplied during deployment
+
 
 ```solidity
 error InvalidAddress();
diff --git a/docs/src/src/lib/PowUtil.sol/library.PowUtil.md b/docs/src/src/lib/PowUtil.sol/library.PowUtil.md
index e252a75..a22ec86 100644
--- a/docs/src/src/lib/PowUtil.sol/library.PowUtil.md
+++ b/docs/src/src/lib/PowUtil.sol/library.PowUtil.md
@@ -1,5 +1,5 @@
 # PowUtil
-[Git Source](https://github.com/0xPolygon/pol-token/blob/a780764684dd1ef1ca70707f8069da35cddbd074/src/lib/PowUtil.sol)
+[Git Source](https://github.com/0xPolygon/pol-token/blob/4e60db3944f1f433beb163a74034e19c0fc68cf0/src/lib/PowUtil.sol)
 
 
 ## Functions

From 190f5de3e13212a20a3dba608ba5c7eb9aff1667 Mon Sep 17 00:00:00 2001
From: DhairyaSethi <55102840+DhairyaSethi@users.noreply.github.com>
Date: Tue, 17 Oct 2023 22:42:00 +0530
Subject: [PATCH 3/4] chore: expand getVersion natspec

---
 .../contract.DefaultEmissionManager.md                        | 4 +++-
 .../src/src/PolygonMigration.sol/contract.PolygonMigration.md | 4 +++-
 .../interface.IDefaultEmissionManager.md                      | 4 +++-
 .../IPolygonMigration.sol/interface.IPolygonMigration.md      | 4 +++-
 4 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/docs/src/src/DefaultEmissionManager.sol/contract.DefaultEmissionManager.md b/docs/src/src/DefaultEmissionManager.sol/contract.DefaultEmissionManager.md
index 983ad44..e5ddb24 100644
--- a/docs/src/src/DefaultEmissionManager.sol/contract.DefaultEmissionManager.md
+++ b/docs/src/src/DefaultEmissionManager.sol/contract.DefaultEmissionManager.md
@@ -130,6 +130,8 @@ function inflatedSupplyAfter(uint256 timeElapsed) public pure returns (uint256 s
 
 ### getVersion
 
+returns the version of the contract
+
 
 ```solidity
 function getVersion() external pure returns (string memory);
@@ -138,6 +140,6 @@ function getVersion() external pure returns (string memory);
 
 |Name|Type|Description|
 |----|----|-----------|
-|`<none>`|`string`|version the implementation version|
+|`<none>`|`string`|version version string|
 
 
diff --git a/docs/src/src/PolygonMigration.sol/contract.PolygonMigration.md b/docs/src/src/PolygonMigration.sol/contract.PolygonMigration.md
index 2226b90..c53a57b 100644
--- a/docs/src/src/PolygonMigration.sol/contract.PolygonMigration.md
+++ b/docs/src/src/PolygonMigration.sol/contract.PolygonMigration.md
@@ -172,6 +172,8 @@ function updateUnmigrationLock(bool unmigrationLocked_) external onlyOwner;
 
 ### getVersion
 
+returns the version of the contract
+
 
 ```solidity
 function getVersion() external pure returns (string memory);
@@ -180,7 +182,7 @@ function getVersion() external pure returns (string memory);
 
 |Name|Type|Description|
 |----|----|-----------|
-|`<none>`|`string`|version the implementation version|
+|`<none>`|`string`|version version string|
 
 
 ### burn
diff --git a/docs/src/src/interfaces/IDefaultEmissionManager.sol/interface.IDefaultEmissionManager.md b/docs/src/src/interfaces/IDefaultEmissionManager.sol/interface.IDefaultEmissionManager.md
index b6f083a..91fe00a 100644
--- a/docs/src/src/interfaces/IDefaultEmissionManager.sol/interface.IDefaultEmissionManager.md
+++ b/docs/src/src/interfaces/IDefaultEmissionManager.sol/interface.IDefaultEmissionManager.md
@@ -101,6 +101,8 @@ function inflatedSupplyAfter(uint256 timeElapsedInSeconds) external pure returns
 
 ### getVersion
 
+returns the version of the contract
+
 
 ```solidity
 function getVersion() external pure returns (string memory version);
@@ -109,7 +111,7 @@ function getVersion() external pure returns (string memory version);
 
 |Name|Type|Description|
 |----|----|-----------|
-|`version`|`string`|the implementation version|
+|`version`|`string`|version string|
 
 
 ## Events
diff --git a/docs/src/src/interfaces/IPolygonMigration.sol/interface.IPolygonMigration.md b/docs/src/src/interfaces/IPolygonMigration.sol/interface.IPolygonMigration.md
index ebc7a11..4166aea 100644
--- a/docs/src/src/interfaces/IPolygonMigration.sol/interface.IPolygonMigration.md
+++ b/docs/src/src/interfaces/IPolygonMigration.sol/interface.IPolygonMigration.md
@@ -166,6 +166,8 @@ function unmigrationLocked() external view returns (bool isUnmigrationLocked);
 
 ### getVersion
 
+returns the version of the contract
+
 
 ```solidity
 function getVersion() external pure returns (string memory version);
@@ -174,7 +176,7 @@ function getVersion() external pure returns (string memory version);
 
 |Name|Type|Description|
 |----|----|-----------|
-|`version`|`string`|the implementation version|
+|`version`|`string`|version string|
 
 
 ## Events

From b609219c45058e6f2fdb5495abf94f494ff5678b Mon Sep 17 00:00:00 2001
From: DhairyaSethi <55102840+DhairyaSethi@users.noreply.github.com>
Date: Tue, 17 Oct 2023 22:43:25 +0530
Subject: [PATCH 4/4] chore: expand getVersion natspec

---
 src/interfaces/IDefaultEmissionManager.sol | 3 ++-
 src/interfaces/IPolygonMigration.sol       | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/interfaces/IDefaultEmissionManager.sol b/src/interfaces/IDefaultEmissionManager.sol
index 02182c8..9e5b069 100644
--- a/src/interfaces/IDefaultEmissionManager.sol
+++ b/src/interfaces/IDefaultEmissionManager.sol
@@ -42,6 +42,7 @@ interface IDefaultEmissionManager {
     /// log2(interestRatePerYear) = 0.04264433740849372 with 18 decimals, as the interest rate does not change, hard code the value
     function inflatedSupplyAfter(uint256 timeElapsedInSeconds) external pure returns (uint256 inflatedSupply);
 
-    /// @return version the implementation version
+    /// @notice returns the version of the contract
+    /// @return version version string
     function getVersion() external pure returns (string memory version);
 }
diff --git a/src/interfaces/IPolygonMigration.sol b/src/interfaces/IPolygonMigration.sol
index 014142e..fb69b42 100644
--- a/src/interfaces/IPolygonMigration.sol
+++ b/src/interfaces/IPolygonMigration.sol
@@ -81,6 +81,7 @@ interface IPolygonMigration {
     /// @return isUnmigrationLocked whether the unmigration is locked or not
     function unmigrationLocked() external view returns (bool isUnmigrationLocked);
 
-    /// @return version the implementation version
+    /// @notice returns the version of the contract
+    /// @return version version string
     function getVersion() external pure returns (string memory version);
 }