Skip to content

Commit

Permalink
chore(evm-embeds): just gen-embeds + more docs
Browse files Browse the repository at this point in the history
  • Loading branch information
Unique-Divine committed Jan 16, 2025
1 parent 13a1275 commit 5be2439
Show file tree
Hide file tree
Showing 11 changed files with 148 additions and 105 deletions.
43 changes: 42 additions & 1 deletion x/evm/embeds/HACKING.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
# x/evm/embeds/HACKING.md

- [Building Outputs](#building-outputs)
- [Precompile Solidity Documentation](#precompile-solidity-documentation)
- [Comments](#comments)
- [NatSpec Fields](#natspec-fields)
- [Solidity Conventions](#solidity-conventions)

## Building Outputs

Workhorse command
Expand Down Expand Up @@ -67,5 +73,40 @@ Best practice: Include at the top of each contract or interface file.
States the author of the contract.
Best practice: Optional, but can be useful in larger projects.

## Solidity Conventions

### State Mutability

State mutability defines how a function interacts with the blockchain state. Always explicitly declare non-default state mutability keywords for clarity and correctness.

1. `view` : For stateful queries
- Reads state, but cannot modify it.
- Use for getters or queries.

```solidity
function getBalance(address account) external view returns (uint256);
```

2. `pure` : For stateless queries
- Neither reads nor modifies state.
- Use for calculations or logic relying only on inputs.

```solidity
function add(uint256 a, uint256 b) external pure returns (uint256);
```

3. `nonpayable` : (Default) State mutating operation
- Modifies state but cannot receive Ether.
- Default if no mutability is specified.

```solidity
function updateBalance(address account, uint256 amount) external;
```

4. `payable` : State mutating operation that can receive Ether (NIBI)
- Can receive Ether and may modify state.
- Use for deposits or payments.

###
```solidity
function deposit() external payable;
```
6 changes: 3 additions & 3 deletions x/evm/embeds/abi/IFunToken.json
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@
"type": "tuple"
}
],
"stateMutability": "nonpayable",
"stateMutability": "view",
"type": "function"
},
{
Expand Down Expand Up @@ -119,7 +119,7 @@
"type": "tuple"
}
],
"stateMutability": "nonpayable",
"stateMutability": "view",
"type": "function"
},
{
Expand Down Expand Up @@ -237,7 +237,7 @@
"type": "tuple"
}
],
"stateMutability": "nonpayable",
"stateMutability": "view",
"type": "function"
}
]

Large diffs are not rendered by default.

6 changes: 3 additions & 3 deletions x/evm/embeds/artifacts/contracts/IFunToken.sol/IFunToken.json
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@
"type": "tuple"
}
],
"stateMutability": "nonpayable",
"stateMutability": "view",
"type": "function"
},
{
Expand Down Expand Up @@ -123,7 +123,7 @@
"type": "tuple"
}
],
"stateMutability": "nonpayable",
"stateMutability": "view",
"type": "function"
},
{
Expand Down Expand Up @@ -241,7 +241,7 @@
"type": "tuple"
}
],
"stateMutability": "nonpayable",
"stateMutability": "view",
"type": "function"
}
],
Expand Down

Large diffs are not rendered by default.

Large diffs are not rendered by default.

Large diffs are not rendered by default.

Large diffs are not rendered by default.

Large diffs are not rendered by default.

113 changes: 52 additions & 61 deletions x/evm/embeds/contracts/ERC20Minter.sol
Original file line number Diff line number Diff line change
Expand Up @@ -6,66 +6,57 @@ import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Burnable.sol";
import "@openzeppelin/contracts/access/Ownable.sol";

/**
* @dev {ERC20} token, including:
*
* - an "owner" that can mint tokens
* - ability for holders to burn (destroy) their tokens
*
* The contract owner is set automatically in the constructor as the
* deployer due to "Ownable".
*
* The Context contract is inherited indirectly through "ERC20" and "Ownable".
*/
/// @dev {ERC20} token, including:
///
/// - an "owner" that can mint tokens
/// - ability for holders to burn (destroy) their tokens
///
/// The contract owner is set automatically in the constructor as the
/// deployer due to "Ownable".
///
/// The Context contract is inherited indirectly through "ERC20" and "Ownable".
contract ERC20Minter is ERC20, ERC20Burnable, Ownable {
uint8 private _decimals;

/**
* @dev Grants "owner" status to the account that deploys the contract and
* customizes tokens decimals.
*
* See {ERC20-constructor}.
*/
constructor(string memory name, string memory symbol, uint8 decimals_)
ERC20(name, symbol) {
_setupDecimals(decimals_);
}

/**
* @dev Sets `_decimals` as `decimals_ once at Deployment'
*/
function _setupDecimals(uint8 decimals_) private {
_decimals = decimals_;
}

/**
* @dev Overrides the `decimals()` method with custom `_decimals`
*/
function decimals() public view virtual override returns (uint8) {
return _decimals;
}

/**
* @dev Creates `amount` new tokens for `to`.
*
* See {ERC20-_mint}.
*
*/
function mint(address to, uint256 amount) public virtual onlyOwner {
_mint(to, amount);
}

/**
* @dev Destroys `amount` new tokens for `to`. Suitable when the contract owner
* should have authority to burn tokens from an account directly, such as in
* the case of regulatory compliance, or actions selected via
* decentralized governance.
*
* See {ERC20-_burn}.
*
*/
function burnFromAuthority(address from, uint256 amount) public virtual onlyOwner {
_burn(from, amount);
}

uint8 private _decimals;

/// @dev Grants "owner" status to the account that deploys the contract and
/// customizes tokens decimals.
///
/// See {ERC20-constructor}.
constructor(
string memory name,
string memory symbol,
uint8 decimals_
) ERC20(name, symbol) {
_setupDecimals(decimals_);
}

/// @dev Sets `_decimals` as `decimals_ once at Deployment'
function _setupDecimals(uint8 decimals_) private {
_decimals = decimals_;
}

/// @dev Overrides the `decimals()` method with custom `_decimals`
function decimals() public view virtual override returns (uint8) {
return _decimals;
}

/// @dev Creates `amount` new tokens for `to`.
///
/// See {ERC20-_mint}.
function mint(address to, uint256 amount) public virtual onlyOwner {
_mint(to, amount);
}

/// @dev Destroys `amount` new tokens for `to`. Suitable when the contract owner
/// should have authority to burn tokens from an account directly, such as in
/// the case of regulatory compliance, or actions selected via
/// decentralized governance.
///
/// See {ERC20-_burn}.
function burnFromAuthority(
address from,
uint256 amount
) public virtual onlyOwner {
_burn(from, amount);
}
}
61 changes: 36 additions & 25 deletions x/evm/embeds/contracts/IFunToken.sol
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,11 @@ IFunToken constant FUNTOKEN_PRECOMPILE = IFunToken(FUNTOKEN_PRECOMPILE_ADDRESS);

import "./NibiruEvmUtils.sol";

/// @dev Implements the functionality for sending ERC20 tokens and bank
/// @notice Implements the functionality for sending ERC20 tokens and bank
/// coins to various Nibiru accounts using either the Nibiru Bech32 address
/// using the "FunToken" mapping between the ERC20 and bank.
interface IFunToken is INibiruEvm {
/// @dev sendToBank sends ERC20 tokens as coins to a Nibiru base account
/// @notice sendToBank sends ERC20 tokens as coins to a Nibiru base account
/// @param erc20 - the address of the ERC20 token contract
/// @param amount - the amount of tokens to send
/// @param to - the receiving Nibiru base account address as a string
Expand All @@ -32,54 +32,65 @@ interface IFunToken is INibiruEvm {
string bankDenom;
}

/// @notice Method "balance" returns the ERC20 balance and Bank Coin balance
/// of some fungible token held by the given account.
function balance(
address who,
address funtoken
)
external
view
returns (
uint256 erc20Balance,
uint256 bankBalance,
FunToken memory token,
NibiruAccount memory whoAddrs
);

/// @notice Method "bankBalance" returns the Bank Coin balance of some
/// fungible token held by the given account.
function bankBalance(
address who,
string calldata bankDenom
) external returns (uint256 bankBalance, NibiruAccount memory whoAddrs);
)
external
view
returns (uint256 bankBalance, NibiruAccount memory whoAddrs);

/// @notice Method "whoAmI" performs address resolution for the given address
/// string
/// @param who Ethereum hexadecimal (EVM) address or nibi-prefixed Bech32
/// (non-EVM) address
/// @return whoAddrs Addresses of "who" in EVM and non-EVM formats
function whoAmI(
string calldata who
) external returns (NibiruAccount memory whoAddrs);
) external view returns (NibiruAccount memory whoAddrs);

/**
* @dev sendToEvm transfers the caller's bank coin `denom` to its ERC-20 representation on the EVM side.
* The `to` argument must be either an Ethereum hex address (0x...) or a Bech32 address.
*
* The underlying logic mints (or un-escrows) the ERC-20 tokens to the `to` address if
* the funtoken mapping was originally minted from a coin.
*
* @param bankDenom The bank denom of the coin to send from the caller to the EVM side.
* @param amount The number of coins to send.
* @param to The Ethereum hex or bech32 address receiving the ERC-20.
* @return sentAmount The number of ERC-20 tokens minted or un-escrowed.
*/
/// @notice sendToEvm transfers the caller's Bank Coins specified by `denom`
/// to the corresponding ERC-20 representation on the EVM side. The `to`
/// argument must be either an Ethereum hex address (0x...) or a Bech32
/// address.
///
/// The underlying logic mints (or un-escrows) the ERC-20 tokens to the `to` address if
/// the funtoken mapping was originally minted from a coin.
///
/// @param bankDenom The bank denom of the coin to send from the caller to the EVM side.
/// @param amount The number of coins to send.
/// @param to The Ethereum hex or bech32 address receiving the ERC-20.
/// @return sentAmount The number of ERC-20 tokens minted or un-escrowed.
function sendToEvm(
string calldata bankDenom,
uint256 amount,
string calldata to
) external returns (uint256 sentAmount);

/**
* @dev bankMsgSend performs a `cosmos.bank.v1beta1.MsgSend` from the caller
* into the Cosmos side, akin to running the standard `bank` module's send operation.
*
* @param to The recipient address (hex or bech32).
* @param bankDenom The bank coin denom to send.
* @param amount The number of coins to send.
* @return success True if the bank send succeeded, false otherwise.
*/
/// @notice bankMsgSend performs a `cosmos.bank.v1beta1.MsgSend` transaction
/// message to transfer Bank Coin funds to the given address.
///
/// @param to The recipient address (hex or bech32).
/// @param bankDenom The bank coin denom to send.
/// @param amount The number of coins to send.
/// @return success True if the bank send succeeded, false otherwise.
function bankMsgSend(
string calldata to,
string calldata bankDenom,
Expand Down

0 comments on commit 5be2439

Please sign in to comment.