ICON 2.0 SDK v0.2.3

View Source Icon.RPC.Request.Goloop (ICON 2.0 SDK v0.2.3)

This module defines the Goloop API request payloads.

Link to this section Summary

Types

method()

Supported methods.

Functions

call(identity, to, method, params \\ nil, options \\ [])

Builds a request for calling a readonly SCORE method with some optional params and options using a valid identity with a wallet.

deposit_shared_fee(identity, score_address, amount, options \\ [])

Builds a request for depositing ICX in loop (10¹⁸ loop = 1 ICX) into a SCORE for paying other user's fees when transacting with it (fee sharing).

estimate_step(identity, params, schema)

Builds a request for requesting the step limit estimation of a transaction.

get_balance(identity, address \\ nil)

Builds a request for getting the balance of an EOA or SCORE address. If the address is not provided, it uses the one in the identity.

get_block_by_hash(identity, hash)

Builds a request for getting a block by hash.

get_block_by_height(identity, height)

Builds a request for getting a block by height.

get_last_block(identity)

Builds request for getting the lastest block.

get_score_api(identity, address)

Builds a request for getting the API of a SCORE given its address.

get_total_supply(identity)

Builds a request for geting the total ICX supply.

get_transaction_by_hash(identity, tx_hash)

Builds a request for getting a transaction by tx_hash.

get_transaction_result(identity, tx_hash, options \\ [])

Builds a request for getting the transaction result given its tx_hash and some optional options.

install_score(identity, content, options \\ [])

Builds a request for deploying a new SCORE given its content.

send_message(identity, recipient, message, options \\ [])

Builds an message transfer to a given recipient.

transaction_call(identity, score, method, params \\ nil, options \\ [])

Builds a transaction for calling a SCORE method.

transfer(identity, recipient, amount, options \\ [])

Builds an ICX transfer transaction given a recipient address and the amount of ICX in loop (1 ICX = 10¹⁸ loop).

update_score(identity, score_address, content, options \\ [])

Builds a request for updating an existent SCORE given its address and content.

withdraw_shared_fee(identity, score_address, hash_or_amount \\ nil, options \\ [])

Builds a request for withdrawing, partially or totally, the shared fee deposited ICX in loop (10¹⁸ loop = 1 ICX) from a SCORE.

Link to this section Types

Link to this type

method()

View Source 
@type method() ::
  :get_last_block
  | :get_block_by_height
  | :get_block_by_hash
  | :get_balance
  | :call
  | :get_score_api
  | :get_total_supply
  | :get_transaction_result
  | :get_transaction_by_hash
  | :send_transaction
  | :send_transaction_and_wait
  | :wait_transaction_result
  | :estimate_step

Supported methods.

Link to this section Functions

Link to this function

call(identity, to, method, params \\ nil, options \\ [])

View Source 
@spec call(
  Icon.RPC.Identity.t(),
  Icon.Schema.Types.SCORE.t(),
  binary(),
  nil | map() | keyword(),
  keyword()
) :: {:ok, Icon.RPC.Request.t()} | {:error, Icon.Schema.Error.t()}

Builds a request for calling a readonly SCORE method with some optional params and options using a valid identity with a wallet.

Options:

  • schema - method's schema to validate params.

example

 Example

The following shows how build a call to the method getBalance in a SCORE:

iex> identity = Icon.RPC.Identity.new(private_key: "8ad9...")
iex> Icon.RPC.Request.Goloop.call(
...>   identity,
...>   "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32",
...>   "getBalance",
...>   %{address: "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32"},
...>   %{address: {:address, required: true}}
...> )
{
  :ok,
  %Icon.RPC.Request{
    method: "icx_call",
    options: ...,
    params: %{
      from: "hxfd7e4560ba363f5aabd32caac7317feeee70ea57",
      to: "hxfd7e4560ba363f5aabd32caac7317feeee70ea57",
      dataType: "call",
      data: %{
        method: "getBalance",
        params: %{
          address: "hx2e243ad926ac48d15156756fce28314357d49d83"
        }
      }
    }
  }
}
Link to this function

deposit_shared_fee(identity, score_address, amount, options \\ [])

View Source 
@spec deposit_shared_fee(
  Icon.RPC.Identity.t(),
  Icon.Schema.Types.SCORE.t(),
  Icon.Schema.Types.Loop.t(),
  keyword()
) :: {:ok, Icon.RPC.Request.t()} | {:error, Icon.Schema.Error.t()}

Builds a request for depositing ICX in loop (10¹⁸ loop = 1 ICX) into a SCORE for paying other user's fees when transacting with it (fee sharing).

Options:

  • timeout - Time in milliseconds to wait for the transaction result.
  • params - Extra transaction parameters for overriding the defaults.

example

 Example

The following builds a request for depositing ICX into a SCORE for fee sharing:

iex> identity = Icon.RPC.Identity.new(private_key: "8ad9...")
iex> Icon.RPC.Request.deposit_shared_fee(
...>   identity,
...>   "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32",
...>   1_000_000_000_000_000_000
...> )
{
  :ok,
  %Icon.RPC.Request{
    method: "icx_sendTransaction",
    options: ...,
    params: %{
      from: "hxfd7e4560ba363f5aabd32caac7317feeee70ea57",
      to: "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32",
      value: 1_000_000_000_000_000_000,
      nid: 1,
      nonce: 1641487595040282,
      timestamp: ~U[2022-01-06 16:46:35.042078Z],
      version: 3,
      dataType: :deposit,
      data: %{
        action: :add
      }
    }
  }
}
Link to this function

estimate_step(identity, params, schema)

View Source 
@spec estimate_step(Icon.RPC.Identity.t(), map(), Icon.Schema.t()) ::
  {:ok, Icon.RPC.Request.t()}

Builds a request for requesting the step limit estimation of a transaction.

Link to this function

get_balance(identity, address \\ nil)

View Source 
@spec get_balance(Icon.RPC.Identity.t(), nil | Icon.Schema.Types.Address.t()) ::
  {:ok, Icon.RPC.Request.t()} | {:error, Icon.Schema.Error.t()}

Builds a request for getting the balance of an EOA or SCORE address. If the address is not provided, it uses the one in the identity.

example

 Example

The following builds a request for getting the balance of the wallet doing the request:

iex> identity = Icon.RPC.Identity.new(private_key: "8ad9...")
iex> Icon.RPC.Request.get_balance(identity)
{
  :ok,
  %Icon.RPC.Request{
    method: "icx_getBalance",
    options: ...,
    params: %{
      address: "hxbe258ceb872e08851f1f59694dac2558708ece11"
    }
  }
}
Link to this function

get_block_by_hash(identity, hash)

View Source 
@spec get_block_by_hash(Icon.RPC.Identity.t(), Icon.Schema.Types.Hash.t()) ::
  {:ok, Icon.RPC.Request.t()} | {:error, Icon.Schema.Error.t()}

Builds a request for getting a block by hash.

example

 Example

The following builds a request to get a block by hash:

iex> identity = Icon.RPC.Identity.new()
iex> Icon.RPC.Request.get_block_by_hash(identity, "0x8e25acc5b5c74375079d51828760821fc6f54283656620b1d5a715edcc0770c6")
{
  :ok,
  %Icon.RPC.Request{
    method: "icx_getBlockByHash",
    options: ...,
    params: %{
      hash: "0x8e25acc5b5c74375079d51828760821fc6f54283656620b1d5a715edcc0770c6"
    }
  }
}
Link to this function

get_block_by_height(identity, height)

View Source 
@spec get_block_by_height(Icon.RPC.Identity.t(), Icon.Schema.Types.Integer.t()) ::
  {:ok, Icon.RPC.Request.t()} | {:error, Icon.Schema.Error.t()}

Builds a request for getting a block by height.

example

 Example

The following builds a request to get a block by height:

iex> identity = Icon.RPC.Identity.new()
iex> Icon.RPC.Request.get_block_by_height(identity, 42)
{
  :ok,
  %Icon.RPC.Request{
    method: "icx_getBlockByHeight",
    options: ...,
    params: %{
      height: 42
    }
  }
}
Link to this function

get_last_block(identity)

View Source 
@spec get_last_block(Icon.RPC.Identity.t()) :: {:ok, Icon.RPC.Request.t()}

Builds request for getting the lastest block.

example

 Example

The following builds a request to get the latest block:

iex> identity = Icon.RPC.Identity.new()
iex> Icon.RPC.Request.get_last_block(identity)
{
  :ok,
  %Icon.RPC.Request{
    method: "icx_getLastBlock",
    options: ...,
    params: %{}
  }
}
Link to this function

get_score_api(identity, address)

View Source 
@spec get_score_api(Icon.RPC.Identity.t(), Icon.Schema.Types.SCORE.t()) ::
  {:ok, Icon.RPC.Request.t()} | {:error, Icon.Schema.Error.t()}

Builds a request for getting the API of a SCORE given its address.

example

 Example

The following builds a request for getting the API of a SCORE:

iex> identity = Icon.RPC.Identity.new()
iex> Icon.RPC.Request.get_score_api(identity, "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32")
{
  :ok,
  %Icon.RPC.Request{
    method: "icx_getScoreApi",
    options: ...,
    params: %{
      address: "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32"
    }
  }
}
Link to this function

get_total_supply(identity)

View Source 
@spec get_total_supply(Icon.RPC.Identity.t()) :: {:ok, Icon.RPC.Request.t()}

Builds a request for geting the total ICX supply.

example

 Example

The following builds a request for getting the ICX total supply:

iex> identity = Icon.RPC.Identity.new()
iex> Icon.RPC.Request.get_total_supply(identity)
{
  :ok,
  %Icon.RPC.Request{
    method: "icx_getTotalSupply",
    options: ...,
    params: %{}
  }
}
Link to this function

get_transaction_by_hash(identity, tx_hash)

View Source 
@spec get_transaction_by_hash(Icon.RPC.Identity.t(), Icon.Schema.Types.Hash.t()) ::
  {:ok, Icon.RPC.Request.t()} | {:error, Icon.Schema.Error.t()}

Builds a request for getting a transaction by tx_hash.

example

 Example

The following builds a request for getting a transaction:

iex> identity = Icon.RPC.Identity.new()
iex> Icon.RPC.Request.get_transaction_by_hash(identity, "0xd579ce6162019928d874da9bd1dbf7cced2359a5614e8aa0bf7cf75f3770504b")
{
  :ok,
  %Icon.RPC.Request{
    method: "icx_getTransactionByHash",
    options: ...,
    params: %{
      txHash: "0xd579ce6162019928d874da9bd1dbf7cced2359a5614e8aa0bf7cf75f3770504b"
    }
  }
}
Link to this function

get_transaction_result(identity, tx_hash, options \\ [])

View Source 
@spec get_transaction_result(
  Icon.RPC.Identity.t(),
  Icon.Schema.Types.Hash.t(),
  keyword()
) ::
  {:ok, Icon.RPC.Request.t()} | {:error, Icon.Schema.Error.t()}

Builds a request for getting the transaction result given its tx_hash and some optional options.

Options:

  • timeout - Timeout in milliseconds for waiting for the result of the transaction.

example

 Example

The following builds a request for getting a transaction result:

iex> identity = Icon.RPC.Identity.new()
iex> Icon.RPC.Request.get_transaction_result(identity, "0xd579ce6162019928d874da9bd1dbf7cced2359a5614e8aa0bf7cf75f3770504b")
{
  :ok,
  %Icon.RPC.Request{
    method: "icx_getTransactionResult",
    options: ...,
    params: %{
      txHash: "0xd579ce6162019928d874da9bd1dbf7cced2359a5614e8aa0bf7cf75f3770504b"
    }
  }
}
Link to this function

install_score(identity, content, options \\ [])

View Source 
@spec install_score(
  Icon.RPC.Identity.t(),
  Icon.Schema.Types.BinaryData.t(),
  keyword()
) ::
  {:ok, Icon.RPC.Request.t()} | {:error, Icon.Schema.Error.t()}

Builds a request for deploying a new SCORE given its content.

Options:

  • timeout - Time in milliseconds to wait for the transaction result.
  • params - Extra transaction parameters for overriding the defaults.
  • content_type - MIME type of the SCORE contents. Defaults to application/zip.
  • on_install_params - Parameters for the function on_install/0.
  • on_install_schema - Schema for the parameters of the function on_install/0.

example

 Example

The following builds a request for deploying a SCORE:

iex> {:ok, content} = File.read("./my-contract.javac")
iex> identity = Icon.RPC.Identity.new(private_key: "8ad9...")
iex> Icon.RPC.Request.install_score(
...>   identity,
...>   content,
...>   on_install_params: %{
...>     address: "hxfd7e4560ba363f5aabd32caac7317feeee70ea57"
...>   },
...>   on_install_schema: %{
...>     address: {:address, required: true}
...>   }
...> )
{
  :ok,
  %Icon.RPC.Request{
    method: "icx_sendTransaction",
    options: ...,
    params: %{
      from: "hxfd7e4560ba363f5aabd32caac7317feeee70ea57",
      to: "cx0000000000000000000000000000000000000000",
      nid: 1,
      nonce: 1641487595040282,
      timestamp: ~U[2022-01-06 16:46:35.042078Z],
      version: 3,
      dataType: :deploy,
      data: %{
        content_type: "application/zip",
        content: <<70, 79, 82, 49, 0, ...>>,
        params: %{
          address: "hxfd7e4560ba363f5aabd32caac7317feeee70ea57"
        }
      }
    }
  }
}
Link to this function

send_message(identity, recipient, message, options \\ [])

View Source 
@spec send_message(
  Icon.RPC.Identity.t(),
  Icon.Schema.Types.Address.t(),
  binary(),
  keyword()
) :: {:ok, Icon.RPC.Request.t()} | {:error, Icon.Schema.Error.t()}

Builds an message transfer to a given recipient.

Options:

  • timeout - Time in milliseconds to wait for the transaction result.
  • params - Extra transaction parameters for overriding the defaults.

example

 Example

The following builds a request for sending a message to another address:

iex> identity = Icon.RPC.Identity.new(private_key: "8ad9...")
iex> Icon.RPC.Request.send_message(
...>   identity,
...>   "hx2e243ad926ac48d15156756fce28314357d49d83",
...>   "Hello world!"
...> )
{
  :ok,
  %Icon.RPC.Request{
    method: "icx_sendTransaction",
    options: ...,
    params: %{
      from: "hxfd7e4560ba363f5aabd32caac7317feeee70ea57",
      to: "hx2e243ad926ac48d15156756fce28314357d49d83",
      nid: 1,
      nonce: 1641487595040282,
      timestamp: ~U[2022-01-06 16:46:35.042078Z],
      version: 3,
      dataType: :message,
      data: "Hello world!"
    }
  }
}
Link to this function

transaction_call(identity, score, method, params \\ nil, options \\ [])

View Source 
@spec transaction_call(
  Icon.RPC.Identity.t(),
  Icon.Schema.Types.SCORE.t(),
  binary(),
  nil | map() | keyword(),
  keyword()
) :: {:ok, Icon.RPC.Request.t()} | {:error, Icon.Schema.Error.t()}

Builds a transaction for calling a SCORE method.

Options:

  • timeout - Time in milliseconds to wait for the transaction result.
  • params - Extra transaction parameters for overriding the defaults.
  • schema - Method parameters schema.

example

 Example

The following builds a request for calling the method transfer in a SCORE:

iex> identity = Icon.RPC.Identity.new(private_key: "8ad9...")
iex> Icon.RPC.Request.transaction_call(
...>   identity,
...>   "cx2e243ad926ac48d15156756fce28314357d49d83",
...>   "transfer",
...>   %{
...>     address: "hxfd7e4560ba363f5aabd32caac7317feeee70ea57",
...>     value: 1_000_000_000_000_000_000
...>   },
...>   schema: %{
...>     address: {:address, required: true},
...>     value: {:loop, required: true}
...>   }
...> )
{
  :ok,
  %Icon.RPC.Request{
    method: "icx_sendTransaction",
    options: ...,
    params: %{
      from: "hxfd7e4560ba363f5aabd32caac7317feeee70ea57",
      to: "cx2e243ad926ac48d15156756fce28314357d49d83",
      nid: 1,
      nonce: 1641487595040282,
      timestamp: ~U[2022-01-06 16:46:35.042078Z],
      version: 3,
      dataType: :call,
      data: %{
        method: "transfer",
        params: %{
          address: "hxfd7e4560ba363f5aabd32caac7317feeee70ea57",
          value: 1_000_000_000_000_000_000
        }
      }
    }
  }
}
Link to this function

transfer(identity, recipient, amount, options \\ [])

View Source 
@spec transfer(
  Icon.RPC.Identity.t(),
  Icon.Schema.Types.Address.t(),
  Icon.Schema.Types.Loop.t(),
  keyword()
) :: {:ok, Icon.RPC.Request.t()} | {:error, Icon.Schema.Error.t()}

Builds an ICX transfer transaction given a recipient address and the amount of ICX in loop (1 ICX = 10¹⁸ loop).

Options:

  • timeout - Time in milliseconds to wait for the transaction result.
  • params - Extra transaction parameters for overriding the defaults.

example

 Example

The following builds a request for sending 1 ICX to another wallet:

iex> identity = Icon.RPC.Identity.new(private_key: "8ad9...")
iex> Icon.RPC.Request.transfer(
...>   identity,
...>   "hx2e243ad926ac48d15156756fce28314357d49d83",
...>   1_000_000_000_000_000_000
...> )
{
  :ok,
  %Icon.RPC.Request{
    method: "icx_sendTransaction",
    options: ...,
    params: %{
      from: "hxfd7e4560ba363f5aabd32caac7317feeee70ea57",
      to: "hx2e243ad926ac48d15156756fce28314357d49d83",
      value: 1_000_000_000_000_000_000,
      nid: 1,
      nonce: 1641487595040282,
      timestamp: ~U[2022-01-06 16:46:35.042078Z],
      version: 3
    }
  }
}
Link to this function

update_score(identity, score_address, content, options \\ [])

View Source 
@spec update_score(
  Icon.RPC.Identity.t(),
  Icon.Schema.Types.SCORE.t(),
  Icon.Schema.Types.BinaryData.t(),
  keyword()
) :: {:ok, Icon.RPC.Request.t()} | {:error, Icon.Schema.Error.t()}

Builds a request for updating an existent SCORE given its address and content.

Options:

  • timeout - Time in milliseconds to wait for the transaction result.
  • params - Extra transaction parameters for overriding the defaults.
  • content_type - MIME type of the SCORE contents. Defaults to application/zip.
  • on_update_params - Parameters for the function on_update/0.
  • on_update_schema - Schema for the parameters of the function on_update/0.

example

 Example

The following builds a request for updating a SCORE:

iex> {:ok, content} = File.read("./my-updated-contract.javac")
iex> identity = Icon.RPC.Identity.new(private_key: "8ad9...")
iex> Icon.RPC.Request.update_score(
...>   identity,
...>   "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32",
...>   content,
...>   on_update_params: %{
...>     address: "hxfd7e4560ba363f5aabd32caac7317feeee70ea57"
...>   },
...>   on_update_schema: %{
...>     address: {:address, required: true}
...>   }
...> )
{
  :ok,
  %Icon.RPC.Request{
    method: "icx_sendTransaction",
    options: ...,
    params: %{
      from: "hxfd7e4560ba363f5aabd32caac7317feeee70ea57",
      to: "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32",
      nid: 1,
      nonce: 1641487595040282,
      timestamp: ~U[2022-01-06 16:46:35.042078Z],
      version: 3,
      dataType: :deploy,
      data: %{
        content_type: "application/zip",
        content: <<70, 79, 82, 49, 0, ...>>,
        params: %{
          address: "hxfd7e4560ba363f5aabd32caac7317feeee70ea57"
        }
      }
    }
  }
}
Link to this function

withdraw_shared_fee(identity, score_address, hash_or_amount \\ nil, options \\ [])

View Source 
@spec withdraw_shared_fee(
  Icon.RPC.Identity.t(),
  Icon.Schema.Types.SCORE.t(),
  nil | Icon.Schema.Types.Loop.t() | Icon.Schema.Types.Hash.t(),
  keyword()
) :: {:ok, Icon.RPC.Request.t()} | {:error, Icon.Schema.Error.t()}

Builds a request for withdrawing, partially or totally, the shared fee deposited ICX in loop (10¹⁸ loop = 1 ICX) from a SCORE.

There are three types of withdrawals:

  • Withdrawing a deposit by its hash.
  • Withdrawing a loop amount from the SCORE.
  • Withdrawing the whole deposit.

Options:

  • timeout - Time in milliseconds to wait for the transaction result.
  • params - Extra transaction parameters for overriding the defaults.

examples

 Examples

The following builds a request for withdrawing the whole deposit from the SCORE:

iex> identity = Icon.RPC.Identity.new(private_key: "8ad9...")
iex> Icon.RPC.Request.withdraw_shared_fee(
...>   identity,
...>   "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32"
...> )
{
  :ok,
  %Icon.RPC.Request{
    method: "icx_sendTransaction",
    options: ...,
    params: %{
      from: "hxfd7e4560ba363f5aabd32caac7317feeee70ea57",
      to: "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32",
      nid: 1,
      nonce: 1641487595040282,
      timestamp: ~U[2022-01-06 16:46:35.042078Z],
      version: 3,
      dataType: :deposit,
      data: %{
        action: :withdraw
      }
    }
  }
}

The following builds a request for withdrawing 1 ICX from the shared fee deposit:

iex> identity = Icon.RPC.Identity.new(private_key: "8ad9...")
iex> Icon.RPC.Request.withdraw_shared_fee(
...>   identity,
...>   "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32",
...>   1_000_000_000_000_000_000
...> )
{
  :ok,
  %Icon.RPC.Request{
    method: "icx_sendTransaction",
    options: ...,
    params: %{
      from: "hxfd7e4560ba363f5aabd32caac7317feeee70ea57",
      to: "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32",
      nid: 1,
      nonce: 1641487595040282,
      timestamp: ~U[2022-01-06 16:46:35.042078Z],
      version: 3,
      dataType: :deposit,
      data: %{
        action: :withdraw,
        amount: 1_000_000_000_000_000_000
      }
    }
  }
}

The following builds a request for withdrawing a specific deposit by hash:

iex> identity = Icon.RPC.Identity.new(private_key: "8ad9...")
iex> Icon.RPC.Request.withdraw_shared_fee(
...>   identity,
...>   "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32",
...>   "0xc71303ef8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"
...> )
{
  :ok,
  %Icon.RPC.Request{
    method: "icx_sendTransaction",
    options: ...,
    params: %{
      from: "hxfd7e4560ba363f5aabd32caac7317feeee70ea57",
      to: "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32",
      nid: 1,
      nonce: 1641487595040282,
      timestamp: ~U[2022-01-06 16:46:35.042078Z],
      version: 3,
      dataType: :deposit,
      data: %{
        action: :withdraw,
        id: "0xc71303ef8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"
      }
    }
  }
}