# EVM Tokens (ERC-20)

<details>

<summary><mark style="color:purple;">Straight to the code!</mark></summary>

Instantiate Cryptum SDK first:

```javascript
const sdk = new CryptumSdk({
  environment: 'testnet',
  apiKey: 'YOUR-API-KEY',
})
```

### Create ERC20 token <a href="#create-erc20-token" id="create-erc20-token"></a>

#### `sdk.token.create(opts)`

The smart contract used in this deployment is already precompiled in Cryptum. For more details, you can see the source code here `./contracts/TokenERC20.sol`.

* `opts.wallet` (Wallet) (**required**) - wallet creating the token.
* `opts.name` (string) (**required**) - token name.
* `opts.symbol` (string) (**required**) - token symbol.
* `opts.decimals` (number) (**required**) - token decimal places.
* `opts.amount` (string) (**required**) - token amount to be first minted. (this is in largest unit ether)
* `opts.protocol` (string) (**required**) - [EVMs only](https://github.com/blockforce-official/cryptum-sdk/blob/master/docs/protocols.md#ethereum-based-blockchains-evms).

This function returns the transaction hash from the blockchain. This hash can be used later to retrieve the token address.

```javascript
const { hash } = await sdk.token.create({
  wallet,
  name: 'Token name',
  symbol: 'TOK',
  decimals: 18,
  amount: '1000000',
  protocol: 'ETHEREUM',
})
```

### Transfer tokens

#### `sdk.token.transfer(opts)`

Transfer native and ERC20 tokens.

* `opts.wallet` (Wallet) (**required**) - wallet transferring tokens.
* `opts.token` (string) (**required**) - token name if it's native, like BNB, CELO, ETH etc, or the token address for ERC20 tokens.
* `opts.amount` (string) (**required**) - token amount to be transferred. (this is in largest unit ether)
* `opts.destination` (string) (**required**) - destination address.
* `opts.protocol` (string) (**required**) - [EVMs only](https://github.com/blockforce-official/cryptum-sdk/blob/master/docs/protocols.md#ethereum-based-blockchains-evms).

This function returns the hash of this transferring transaction from the blockchain.

```javascript
// native token
const { hash } = await sdk.token.transfer({
  wallet,
  protocol: 'POLYGON',
  token: 'MATIC',
  destination: '0x31ec6686ee15...931b5e12cacb920e',
  amount: '17.44',
})
// custom ERC20 token
const { hash } = await sdk.token.transfer({
  wallet,
  protocol: 'AVAXCCHAIN',
  token: '0x1b5e12ca...1b5e12ca',
  destination: '0x31ec6686ee15...07A931b5e12cacb920e',
  amount: '9.129045',
})
```

### Mint tokens <a href="#mint-tokens" id="mint-tokens"></a>

#### `sdk.token.mint(opts)`

Mint ERC20 tokens.

**\*Obs: This method will only work for the tokens created with the method** [**sdk.token.create**](https://github.com/blockforce-official/cryptum-sdk/blob/master/docs/tokens/EVMs.md#deploy-erc20-token)**.**

* `opts.wallet` (Wallet) (**required**) - wallet minting tokens.
* `opts.token` (string) (**required**) - token address.
* `opts.amount` (string) (**required**) - token amount to be minted. (this is in largest unit ether considering the token decimal places)
* `opts.destination` (string) (**required**) - destination address.
* `opts.protocol` (string) (**required**) - [EVMs only](https://github.com/blockforce-official/cryptum-sdk/blob/master/docs/protocols.md#ethereum-based-blockchains-evms).

This function returns the hash of this minting transaction from the blockchain.

```javascript
const { hash } = await sdk.token.mint({
  wallet,
  protocol: 'CELO',
  token: '0x1b5e12ca...1b5e12ca',
  destination: '0x31ec6686ee1597...A931b5e12cacb920e',
  amount: '40',
})
```

### Burn tokens

#### `sdk.token.burn(opts)`

Burn ERC20 tokens.

**\*Obs: This method will only work for the tokens created with the method** [**sdk.token.create**](https://github.com/blockforce-official/cryptum-sdk/blob/master/docs/tokens/EVMs.md#deploy-erc20-token)**.**

* `opts.wallet` (Wallet) (**required**) - wallet burning tokens.
* `opts.token` (string) (**required**) - token address.
* `opts.amount` (string) (**required**) - token amount to be burnt. (this is in largest unit ether considering the token decimal places)
* `opts.protocol` (string) (**required**) - [EVMs only](https://github.com/blockforce-official/cryptum-sdk/blob/master/docs/protocols.md#ethereum-based-blockchains-evms).

This function returns the hash of this burning transaction from the blockchain.

```javascript
const { hash } = await sdk.token.burn({
  wallet,
  protocol: 'CELO',
  token: '0x1b5e12ca...1b5e12ca',
  amount: '8.23',
})
```

### Approve tokens

#### `sdk.token.approve(opts)`

Invoke method "approve" from ERC20-compatible smart contracts.

**\*Obs: This method will only work for the tokens compatible with ERC-20 standard.**

* `opts.wallet` (Wallet) (**required**) - wallet signing transaction that owns the tokens.
* `opts.token` (string) (**required**) - token address.
* `opts.amount` (string) (**required**) - token amount to be approved. (this is in largest unit ether considering the token decimal places)
* `opts.spender` (string) (**required**) - address allowed to withdraw tokens from this wallet.
* `opts.protocol` (string) (**required**) - [EVMs only](https://github.com/blockforce-official/cryptum-sdk/blob/master/docs/protocols.md#ethereum-based-blockchains-evms).

This function returns the hash of this burning transaction from the blockchain.

```javascript
const { hash } = await sdk.token.approve({
  wallet,
  protocol: 'CELO',
  token: '0x1b5e12ca...1b5e12ca',
  amount: '8.82',
  spender: '0x9377888...3342232'
})
```

</details>

### **Creating an ERC-20 token** <a href="#ethereum-celo-and-binance-smart-chain" id="ethereum-celo-and-binance-smart-chain"></a>

#### <mark style="color:purple;">Step 1</mark> <a href="#txcontroller.createtokendeploytransaction-opts" id="txcontroller.createtokendeploytransaction-opts"></a>

As with most actions performed using Cryptum, the first thing you need to do is create an instance of the SDK like this:

```javascript
const CryptumSdk = require('cryptum-sdk')

const sdk = new CryptumSdk({
  environment: 'testnet',  // 'testnet', 'mainnet'
  apiKey: "YOUR-API-KEY-HERE",
})
```

#### <mark style="color:purple;">Step 2</mark>

Now you must have or create a Wallet object using the SDK. This wallet will be used to send transactions to the blockchain in order to create your token, so make sure it has enough funds to perform all the desired interactions.

```javascript
const wallet = await sdk.wallet.generateWallet({
    protocol: 'ETHEREUM',
    mnemonic: 'lorem ipsum dolor sit amet consectetur adipiscing elit ...',
    derivation: { account: 0, address: 0 }
})
```

#### <mark style="color:purple;">Step 3</mark> <a href="#erc20-token" id="erc20-token"></a>

Now we must call  the `sdk.token.create` function on the SDK. The smart contract used in this deployment is in the [contracts](https://github.com/blockforce-official/cryptum-sdk/blob/master/docs/contracts/TokenERC20.sol) directory, so you must pass as arguments the token name, token symbol, decimals (integer number) and the amount of total supply.

```javascript
const { hash } = await sdk.token.create({
    wallet,
    name: 'Token name',
    symbol: 'TOK',
    decimals: 18,
    amount: '1000000',
    protocol: 'ETHEREUM'
})
```

The function returns the transaction hash of the smart contract deployment to the blockchain. To use this new token you need its address which you can retrive it from like this:

```javascript
const { contractAddress } = await sdk.transaction.getTransactionReceiptByHash({
    protocol: 'ETHEREUM',
    hash: '0x000.....'
})
```

### Minting tokens

If you’re the owner of the token’s contract, you can mint extra tokens like this:

```javascript
const { hash } = await sdk.token.mint({
      wallet,
      token: '0x19......86B',  // token address
      destination: '0x0c3.....A342',  // destination address
      amount: '40',
      protocol: 'ETHEREUM'
})
```

### Burning tokens <a href="#burning-tokens" id="burning-tokens"></a>

Unlike minting, anybody can burn the tokens they own.

```javascript
const { hash } = await sdk.token.burn({
      wallet,
      token: '0x19......86B',  // token address
      amount: '40',
      protocol: 'ETHEREUM'
})
```

### Transferring tokens <a href="#transfer-tokens" id="transfer-tokens"></a>

To transfer tokens between accounts, follow this guideline:

```javascript
const { hash } = await sdk.token.transfer({
      wallet,
      token: '0x19......86B',  // token address
      destination: '0x0c3.....A342',  // destination address
      amount: '40',
      protocol: 'ETHEREUM'
})
```

Besides ERC20-based tokens, you also can transfer native tokens by passing the native token symbol instead of the token address. Depending on the protocol you're using there are the supported native tokens that you can transfer:

* `"ETH`" for protocol ETHEREUM;
* `"CELO", "cUSD", "cEUR"` for protocol CELO;
* `"BNB"` for protocol BSC;
* `"MATIC"` for protocol POLYGON;
* `"AVAX"` for protocol AVAXCCHAIN;
* `"CWN"` for protocol STRATUS;

```javascript
const { hash } = await sdk.token.transfer({
      wallet,
      token: 'ETH',  // token address
      destination: '0x0c3.....A342',  // destination address
      amount: '0.037',
      protocol: 'ETHEREUM'
})
```