GEM Ether

gem-ether is a module that provide an easier way to interact with a smart contract deployed on one of the ethereum related network (mainnet, polygon, mumbai, rinkeby and so on...).

The main class of this module is Ether, it need a smart contract address and the relative smart contract json ABI on construction, from there, you can interact with the provided smart contract: send transaction, read property, listen for events and listen for receipt!

1. Initializing
2. Fetch Data from a contract
3. Send Transaction to a contract
   1. Connect the user
   2. Transaction signer
      1. SELF-SIGNED Transaction
      2. SERVER-SIGNED Transaction
   3. Wait confirmation
4. Parse the contract response
5. Ether utils

Initializing

To create an Ether instance connected with a deployed contract, you just need to provide the contract address and the contract json ABI.

import Ether from "gem-ether/dist"

const abi : JSON = // contract abi
const address : string = // contract address

const EtherContractInstance = new Ether(address, abi)

Fetch Data

To fetch data from a view or a public attribute, you don't need the user interaction.

const response = await EtherContractInstance.read('contractViewMethod', [...params])

if(response.error) 
  console.log( response.error )
else 
  console.log( response.value() )

If you want, you can use readValue that tries to read the value directly:

try {
  const value = await EtherContractInstance.readValue('contractViewMethod', [...params])
  console.log(value)
}
catch(e) {...}

Send Data

Connect the User

When initializing an Ether instance, you need to call the connect method. Here you can specify which provider you want to use. You can choose between our predefined:

• metamask
• walletConnect

or even specify a custom RPC url.

const provider = 'metamask' | 'walletConnect'

await EtherContractInstance.connect(provider)

Transaction Signer

When interacting with a smart contract, the user need to 'authorize' the transaction by signing it with its private key.

Normally the dapp won't store the user private key, instead the user makes requests using a provider that know its private key (like metamask or other wallet).

We named this type of transaction "SELF SIGNED TRANSACTION" and it's the default type of any transaction made with this library.

Another scenario could be, you need to trigger a smart contract functionality without any interaction, from a your wallet.

We named this type of transaction "SERVER SIGNED TRANSACTION" and you obviously need to provide the private key from which the transactions will be signed.

SELF SIGNED TRANSACTION

The normal transaction you're thinking of. User use metamask prompt, or some other wallet to sign the transaction with its private key, then send the transaction from that account.

const tx = await EtherContractInstance.send('contractMethod', [...params], {value, maxGas, ...})

if(tx.error) 
  console.log( tx.error )
else 
  console.log( tx.value() )

SERVER SIGNED TRANSACTION

Permit also to specify a private key if you want to send signed transaction from a your wallet while using a non browser environment with an rpc provider (like Infura). Generally client-side application don't want to do this! Never pass here your private key unless you are working server-side or you need to send a transaction from a your wallet, without metamask and without your physical confirmation.

The wallet must be your, you need the private key to do that and you must not ask for your users private key.

For example can be useful if you're developing an api that need to fully interact with ethereum, you can create a route that automatically trigger some smart contract method taking care of the transaction fee, without you physically confirm on metamask prompt.

Be cautious, the gas fee can go crazy some time! If you're using this method you probably want to add a check in your code, cause this don't need your confirmation and can lead to some unexpected cost.

Notice that even if you specify a private key as a signer, you need to call the send method passing "GEM_SIGNER" instead of "PROVIDER_SIGNER" to make a SERVER SIGNED TRANSACTION!

const abi : JSON = // contract abi
const address : string = // contract address
const privKey : string = // signer private key (hide this from your code)

const EtherContractInstance = new Ether(address, abi, privKey)
const tx = await EtherContractInstance.send('contractMethod', [...params], {value, maxGas, ...}, 'GEM_SIGNER')

if(tx.error) 
  console.log( tx.error )
else 
  console.log( tx.value() )

Wait Confirmation

You probably want to wait at least 5-6 confirmation or even more before updating your dapp, to avoid the risk of a block reversal.

...

if(tx.error) {
  // handle error
}
else {

  console.log('0 confirmation')

  await tx.wait(1)
  console.log('1 confirmation')

  await tx.wait(2)
  console.log('2 confirmation')
  
  // ...

}

Ether Utils

import Ether, { Utils } from "gem-ether/dist"

// Convert from ether to wei
Utils.toWei(1) = BigNumber(1000000000000000000)

// Convert from wei to ether
Utils.toWei("1000000000000000000") = "1"