Transactions using the miner

Our guides

Get started

The first thing you might ask yourself is “Why should I use the miner to execute a transaction?” well in all fairness for normal use I would personally recommend to import the miner’s keystore into your wallet app and execute transactions the “easy” way (see ).

However, if you are (like me) interested in the technology or want to script some things, this article should provide you with the information you need.

Note: Feel free to check the post on controlling the miner if you want to check all available commands.

Note: The API specification is subject to change, this article will be updated accordingly.

There are two main methods of issuing commands to the miner, being JS (Java Script) Console mode which presents you with a CLI (Command Line Interface) where you can issue your commands and get direct feedback.
Or JSON-RPC mode, where the miner runs in the background and you can “post” commands by calling the REST API (JSON-RPC) with an external command line tool like curl or for example postman <link>

Before we continue our short journey into the world of manual transactions there are some gotcha’s that you will need to be aware of.

All numbers that indicate a value (for example value or gasPrice) are in Wei
JSON-RPC mode expects hexadecimal numbers, checkout <link>
JS Console mode allows you to use some convenient conversion functions from web3c for example the “toWei” function that takes a value in CPH and converts it into the *Wei unit of measure equivalent.

*Wei is the smallest denominator of CPH and 1.000.000.000.000.000.000 Wei is equal to 1 CPH, Wei is the “unit” that’s being used for all miner transaction variables that involve “value” for example gasPrice and (of course) value.

1. JS Console

Let start with an example in JS Console mode, this means that the miner is started with

				
					./start.sh 1

Since we can use Java Script, lets define our transaction as a variable where the structure is:

				
					var tx = {
    from: "<from address>", 
    to: "<to address>", 
    gas: <units of gas>, 
    gasPrice: <wei unit price of gas>, 
    value: web3c.toWei(<amount of CPH to send>, "cpher")
}

Let’s go over all the components in our transaction

from the address (also called account) that’s sending CPH
to the address (also called account) that’s receiving CPH
gas the maximum number of gas “units” that can be spend in order to execute the transaction, this attribute is not mandatory and defaults to 9000 when it is not set, note the word maximum, a transaction will never be able to spend MORE gas units than the number that is set here, it is of course allowed to spend LESS units of gas (and that’s usually the case).
gasPrice the “price” in Wei for each unit of gas, this attribute is not mandatory and defaults to a network determined “price” of gas. If you want to know what this price currently is then check out section 7.7 on miner commands
value the amount of CPH that you want to send from the from address to the to address in Wei, note that we used the web3c.toWei function here where we can enter an amount in CPH instead of Wei, making it a bit easier to work with.

A small sidenote on gas; You might be wondering what this “gas” and “gasPrice” is all about, well since Cypherium is a fully decentralized blockchain (the most decentralized PoW blockchain out there) we rely on miners to keep the network up and running (the miners perform the computations required to append blocks to the chain, execute smart contracts etc.) and they require some kind of compensation for their work and this is where the concept of gas comes in.
Each “computation” including a transaction requires a certain number of gas, just like a car requires a certain amount of gas in order to drive a certain distance (the more miles the more gas you need, as in the more computations the more gas you need)

Okay and what about gasPrice, well imagine that a miner can pick the tasks it’s wants to perform, a task that has a higher gasPrice will yield more earnings, so a transaction with a gasPrice that is set “higher” than the networks current default gasPrice it’s likely to be executed faster.

Note however that Cypherium is really fast, I would recommend to just use the network default for normal transactions because you probably won’t even notice the difference in speed (its almost instant) If you are building very complex smart contracts then you could start looking into the gas price, however that’s not relevant to the current article.

Okay now that we have discussed all the variables in our transaction lets make it a bit more concrete by filling it out.

				
					var tx = {
    from: "0xb01a2aee90fb20611f963475a17f2a738b9988aa", 
    to: "0xbf4f4cad7bcb72706e18b1aaa0d7dc16e6cc8662", 
    gas: 30000, 
    gasPrice: 18100000000, 
    value: web3c.toWei(1, "cpher")
}

Note that this would be equivalent to the transaction specified above

				
					var tx = {
    from: "0xb01a2aee90fb20611f963475a17f2a738b9988aa", 
    to: "0xbf4f4cad7bcb72706e18b1aaa0d7dc16e6cc8662", 
    gas: 30000, 
    gasPrice: 18100000000, 
    value: 1000000000000000000
}

Did you notice the large number for gasprice? Keep in mind that it’s in Wei so it’s actually very small.
Did you notice that we are using the toWei function from web3c here to convert CPH to the Wei unit of measure?

Okay now we are ready to submit the transaction onto the Cypherium network, in order to do so we need to execute the function personal.sendTransaction this function accepts the transaction (stored here in variable tx) as its first parameter and the passphrase of the account that is “sending” (the from address) as its second parameter.
The passphrase is required to “unlock” the sending account and the will be locked again after completion of the function call.

The structure is:

				
					personal.sendTransaction(<tx>, "<passphrase>")

Let’s fill it out (note that the used account is only for illustration purposes and that the passphrase is not secure):

				
					personal.sendTransaction(tx, "secret")

The console will return a transaction hash for example:
0xc5dda1fdb29d141b6c0d751387df3df59dae58bff9c4aa34c35defe0b65b7983

Note that the “official” CPH method of performing a transaction is slightly different since it requires you to first “unlock” your account first, making the transaction a two-step process

In that case the structure for step one (unlocking your sender/from account) is:

				
					personal.unlockAccount("<from address>", "<passphrase>", <duration>)

Let’s fill it out (note that the used account is only for illustration purposes and that the passphrase is not secure) and notice we didn’t bother to specify a period (thus the account remains unlocked for 300seconds/5 minutes):

				
					personal.unlockAccount ("0xb01a2aee90fb20611f963475a17f2a738b9988aa", "secret")

The seconds step in this official 2 step process is submitting the actual transaction, the structure is:

				
					cph.sendTransaction(<tx>)

Let’s fill it out:

				
					cph.sendTransaction(tx)

The console will return a transaction hash.

Let’s check the status of the transaction by issuing another command with structure:

				
					cph.getTransactionReceipt("<transaction hash>")

With our new transaction hash this becomes:

				
					>cph.getTransactionReceipt("0xc5dda1fdb29d141b6c0d751387df3df59dae58bff9c4aa34c35defe0b65b7983")

And returns:

				
					{
  blockHash: "0x362ee44b3957c83f6f9090be160e34aa0f56468dd8f9fa74c76698301883f0ce",
  blockNumber: 50840,
  contractAddress: null,
  cumulativeGasUsed: 21000,
  from: "0xb01a2aee90fb20611f963475a17f2a738b9988aa",
  gasUsed: 21000,
  logs: [],
  root: "0x6be31234c01f7398e803c19c6138b7f10bab20173058609ecda140620ddf0551",
  to: "0xbf4f4cad7bcb72706e18b1aaa0d7dc16e6cc8662",
  transactionHash: "0xc5dda1fdb29d141b6c0d751387df3df59dae58bff9c4aa34c35defe0b65b7983",
  transactionIndex: 0
}

And that’s it, your first transaction through the JS Console.

2. JSON-RPC

Now let’s try to do the same transaction through the REST API (JSON-RPC), I will be using curl for these examples.

The structure of the command is:

				
					curl -X POST -H "Content-Type: application/json" --data '{"id":"1", "method": "personal_sendTransaction", "params": [{ "from": "<from address>",  "to": "<to address>",  "gas": "<units of gas in hexadecimal>" , "gasPrice": "<wei unit price of gas in hexadecimal>", "value": "<amount of wei to send in hexadecimal>"}, "<sender passphrase>"]}' 0.0.0.0:8000

The part between the single quotes is the interesting bit, the fields are the same as the ones we specified in the JS Console tx variable and just like the JS equivalent passphrase unlocks the sender account for a single transaction.

However, note that gas, gasPrice and value are expected to be in Wei and in hexadecimal numbers
(note that gas and gasPrice are optional just like they were in the JS Console example)
Well, let’s just get on with it, in our previous example we used

				
					gas: 30000 and gasPrice: 18100000000

since these values are already in Wei, we can simply convert them to hexadecimal with an online tool (or if you are really smart, by heart) I’m using Rapidtables.com. And we get (note that I prepended the 0x part):

				
					gas: "0x7530" and gasPrice: "0x436D81500"

and now for the value part we had 1 CPH in Wei that equates to 1000000000000000000 and in hexadecimal we get:

				
					value: "0xDE0B6B3A7640000"

let’s fill it out:

				
					curl -X POST -H "Content-Type: application/json" --data '{"id":"1", "method": "personal_sendTransaction", "params": [{"from": "0xb01a2aee90fb20611f963475a17f2a738b9988aa",  "to": "0xbf4f4cad7bcb72706e18b1aaa0d7dc16e6cc8662",  "gas": "0x7530", "gasPrice": "0x436D81500", "value": "0xDE0B6B3A7640000"}, "secret"]}' 0.0.0.0:8000

And returns:

				
					{"jsonrpc":"2.0","id":"1","result":"0xd5a9ddf361eef5aa9722b733c5d0b59e85731fc0ebc5161abf1d3ce860c7818c"}

Note that the “official” CPH method of performing a transaction is slightly different since it requires you to first “unlock” your account first, making the transaction a two-step process.

In that case the structure for step one (unlocking your sender/from account) is:

				
					curl -X POST -H "Content-Type: application/json" --data '{"id":"1", "method": "personal_unlockAccount", "params": ["<from address>", "<passphrase>", <duration>]}' 0.0.0.0:8000

The first two parameters are probably no real surprise, note however that the third parameter is optional, it allows you to specify a period in seconds (the default is 300 seconds) where the account remains unlocked making this a “global” unlock, as in not just unlocked for a single transaction.

let’s fill it out (note that the used account is only for illustration purposes and that the passphrase is not secure) and notice we didn’t bother to specify a period (thus the account remains unlocked for 300seconds/5 minutes):

				
					curl -X POST -H "Content-Type: application/json" --data '{"id":"1", "method": "personal_unlockAccount", "params": ["0xb01a2aee90fb20611f963475a17f2a738b9988aa", "secret"]}' 0.0.0.0:8000

The seconds step in this official 2 step process is submitting the actual transaction, the structure is:

				
					curl -X POST -H "Content-Type: application/json" --data '{"id":"1", "method": "cph_sendTransaction", "params": [{ "from": "<from address>",  "to": "<to address>",  "gas": "<units of gas in hexadecimal>" , "gasPrice": "<wei unit price of gas in hexadecimal>", "value": "<amount of wei to send in hexadecimal>"}]}' 0.0.0.0:8000

let’s fill it out:

				
					curl -X POST -H "Content-Type: application/json" --data '{"id":"1", "method": "cph_sendTransaction", "params": [{"from": "0xb01a2aee90fb20611f963475a17f2a738b9988aa",  "to": "0xbf4f4cad7bcb72706e18b1aaa0d7dc16e6cc8662",  "gas": "0x7530", "gasPrice": "0x436D81500", "value": "0xDE0B6B3A7640000"}]}' 0.0.0.0:8000

The console will return a transaction hash.

				
					curl -X POST -H "Content-Type: application/json" --data '{"id":"1", "method": "cph_getTransactionReceipt", "params": ["<transaction hash>"]}' 0.0.0.0:8000

Let’s check the status of the transaction by issuing another command with structure:

with our new transaction hash this becomes:

				
					curl -X POST -H "Content-Type: application/json" --data '{"id":"1", "method": "cph_getTransactionReceipt", "params": ["0xd5a9ddf361eef5aa9722b733c5d0b59e85731fc0ebc5161abf1d3ce860c7818c"]}' 0.0.0.0:8000

And returns:

				
					{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "blockHash": "0xb0cc22cc3df64936b0544513ea7607bdb3fbba2fadc1f868724eeee3f02d1718",
    "blockNumber": "0xc7ec",
    "contractAddress": null,
    "cumulativeGasUsed": "0x5208",
    "from": "0xb01a2aee90fb20611f963475a17f2a738b9988aa",
    "gasUsed": "0x5208",
    "logs": [],
    "root": "0x7d57a4125f051fa2914c3746400cfa2054d486fd43bb2a1a09b5cdbc6e0f39cd",
    "to": "0xbf4f4cad7bcb72706e18b1aaa0d7dc16e6cc8662",
    "transactionHash": "0xd5a9ddf361eef5aa9722b733c5d0b59e85731fc0ebc5161abf1d3ce860c7818c",
    "transactionIndex": "0x0"
  }
}

Common errors messages

Intrinsic gas too low
Every transaction requires a “starting fee” so a fee before executing any code/transaction and a fee for every processed/stored byte on top of that. The error message means that your current settings for gas and gasPrice don’t even cover the “starting fee” or “intrinsic gas fee”

Transaction underpriced
This usually happens when you want to replace a transaction (with the same nonce) that has not been mined yet, in that case increase the gasPrice

Insufficient funds for gas * price + value
This error message occurs when you don’t have enough funds to cover the (gas * gasPrice) + value
it makes sense that you need to have a sufficient amount to cover the “value” you want to send however keep in mind that the units of gas you set with the gas parameter is a maximum (the transaction usually takes allot less than you would specify) however this maximum (gas * gasPrice) is actually reserved! So, if there is not enough CPH on your account to cover it (including the value of course) you will get this error message.

Transactions using the miner

Our guides

Get started

1. JS Console

2. JSON-RPC

Common errors messages

Getting Started

About

Downloads