Dapps for Beginners

Javascript API: Part 2

kennethkappler — Wed, 18 Feb 2015 16:41:56 +0000

In the previous tutorial we used some of the basic javascript functions available within the client to passively retreive information from the locally stored blockchain, in this tutorials we are going to examine the ways you can amend the blockchains state.

There is only one way to interact with the blockchain and that is by sending transactions. There are three main types which are important: transactions which send value, transactions which create contracts, and transactions which send data to those contracts.

Once again I have created a html template, with space for you to fill in the required javascript:




	
		
		JSAPI_1.html
		Back to Contents
		
	
	
		
			
				Transact Example
			
			
				
				
			
			
				
			
			
				Create a contract
			
			
				
			
			
				Send some coins
			
			
				

				

			
			
		
		
			Put in addresses prefixed with '0x' and hit 'Send transaction'

Copy paste the above into a html file, save it somewhere in your workspace and open it up in Alethzero. You should see something like this:

This form is setup for the three types of transactions listed above, and we are going to add the code which will allow it to work piece by piece.

The Javascript function we will be using throughout is web3.eth.transact() this function takes a JSON object as its argument and the JSON object has many possible attributes.

The only two attributes we need to concern ourselves with in our first transaction is are “to” and “value” which are the recipient address and the amount of ether we wish to send (this is calculated in its base unit ‘wei’). Transact is an asynchronous function and its callback returns various pieces of information (the point of which I will explain later).

Copy the below into our html template and open the web page in Alethzero:

function sendEther() {
web3.eth.transact({to: document.querySelector('#recipient').value ,value: document.querySelector('#value').value});
};

It should be fairly easy to see how this works, the transact function is being passed a json object with attributes ‘to’ and ‘value’ whose values are pulled from our form input. We could also include the attributes gas and gasprice, but these default to the total amount of ether available and the current mean price for gas on the network, which is sufficient for this example.

Copy and paste any address into the to box and as many wei as you wish to send in the amount (remember there are 10^18 wei in an ether). Hit transact. Hitting this button calls the function ‘sendEther’ which instructs the client to send a transaction to the network.

First you will see a warnign pop up from alethzero informing you that the web page has requested the client send a transaction. Click approve and you should see a transaction appear in the ‘pending’ pane if this has worked correctly. Make sure you mine a block to commit it to the chain and check the balances update correctly.

The next transaction we will perform is going to pass evm code to the blockchain, without a specified recipient, in order to create a new contract.

Before we do this we need some evm code to pass to the transaction. Fortunately our javascript api is capable of compiling solidity to byte code to be passed in an array. Firstly we will create a Javascript object containing code for our Solidity metaCoin. Add this to your html page:

var soliditySource = "contract metaCoin {\n"+
" mapping (address => uint) balances;\n" +
" function metaCoin() {\n" +
" balances[msg.sender] = 10000;\n" +
" }\n" +
" function send(address receiver, uint amount) {\n" +
" if (balances[msg.sender] < amount) return;\n" +
" balances[msg.sender] -= amount;\n" +
" balances[receiver] += amount;\n" +
" }\n" +
"}";

We have come across this code before and previously uploaded it to the blockchain using Alethzero’s transact pane. This time we will compile it in the browser and upload it as bytecode. The function for compiling from solidity is web3.eth.solidity() and when passed solidity code produces EVM bytecode.

You can try this now. Copy and paste the above into your html template. Reload the page in AZ and then go to the javascript console and type:

web3.eth.solidity(soliditySource)

This should return:

"0x60056011565b60ae8060326000396000f35b612710600033600160a060020a0316600052602052604060002081905550560060e060020a6000350480637bb98a6814601e578063d0679d3414602a57005b6024603d565b60006000f35b60366004356024356042565b60006000f35b5b600081565b80600033600160a060020a0316600052602052604060002054106063576067565b60aa565b80600033600160a060020a0316600052602052604060002090815403908190555080600083600160a060020a031660005260205260406000209081540190819055505b505056"

Now we have bytecode we can pass it as a paramenter in the transact function using the “code:” prefix like this:

web3.eth.transact({code: '0x60056011565b60ae8060326000396000f35b612710600033600160a060020a0316600052602052604060002081905550560060e060020a6000350480637bb98a6814601e578063d0679d3414602a57005b6024603d565b60006000f35b60366004356024356042565b60006000f35b5b600081565b80600033600160a060020a0316600052602052604060002054106063576067565b60aa565b80600033600160a060020a0316600052602052604060002090815403908190555080600083600160a060020a031660005260205260406000209081540190819055505b505056'})

This uploads our contract to the blockchain in the exact same way as inputting solidity into the transact pane. The above would create a callback which would return the address of the contract created.

Copy and paste the below into your html document:

function createSolidityContract() {
web3.eth.transact({code: web3.eth.solidity(soliditySource)});
};

This allows us to create a contract with one click from the browser window. You can use this method to compile and deploy any contract you want through the browser. You can also use web3.eth.serpent() to compile serpent code in the same way.

Try this now by opening up your html page in alethzero and clicking on the the ‘create solidity contract’ button – it will cause a pop-up warning that you are sending a transaction with zero wei to the network – approve it and you should see it appear in the pending pane.

In our previous examples we showed how it was possible to interact with contracts using the transact pane in alethzero by building a data array to pass to contracts. The Javascript API abstracts this process and allows you to call functions directly by creating a model of the contracts functions within the browser.

Firstly, we are going to model the contracts functions by defining an array of JSON objects corresponding to the functions our contract has. Each object represents a function of the contract and is made up of very specific attribute-value pairs. The first attribute is unsurprisingly ‘name’ and its value is case sensitive and must be of the format nameOfFunction(argumentType1, argumentType2,…) for our contract above it should look like this:

"name": "send(address,uint256)",

The Second attribute is ‘type’ inthis case a ‘function’ I will cover other types in a later tutorial:

"type": "function",

finally we need to define the inputs of the function as an array of objects (both of which have attributes ‘name’ and ‘type’):

"inputs": [
{
"name": "to",
"type": "address"
},
{
"name": "value",
"type": "uint256"
}
]

If our function returned a value we would also define “outputs” so that our javascript would know how to handle the data array passed back to the browser by the callback.

Putting this all together to create a javascript object describing our contract:

var contractDesc = [{
"name": "send(address,uint256)",
"type": "function",
"inputs": [
{
"name": "to",
"type": "address"
},
{
"name": "value",
"type": "uint256"
}
]
}];

Make careful note of the curly brackets indicating objects, and the square brackets indicating arrays. Now we have a description of our contracts function and the arguments it takes we can create a ‘contract’ object using web3.eth.contract() a function which takes two arguments, the first is the address of the contract as a 160bit hex string, the second is the contract description:

contract = web3.eth.contract(address, contractDesc);

Lets go back and amend our ‘createSolidityContract()’ function to also create this object:

var contractDesc = [{
"name": "send(address,uint256)",
"type": "function",
"inputs": [
{
"name": "to",
"type": "address"
},
{
"name": "value",
"type": "uint256"
}
]
}];

...

function createSolidityContract() {
var address = web3.eth.transact({code: web3.eth.solidity(soliditySource)});
contract = web3.eth.contract(address, contractDesc);
};

Here we have made a couple of important changes, firstly we have declared a new variable ‘address’ which is the value returned by the transact function which creates our contract. Secondly we declare a new global object ‘contract’ which is created when we pass the contract description object along with our contracts address to the web3.eth.contract function.

With our new contract object we can easily interact with the contract on the blockchain simply by calling the functions we have defined above. For example:

contract.send('0x878965387afd76fd008e7668','500')

Will send a transaction instructing the contract to send 500 coins to the account ‘0x878965387afd76fd008e7668’. We can easily setup a JS function which takes these arguments from our html form and passes them to the contract:

function dataTransaction() {
var receiverAddress = document.querySelector('#receiverAddress').value;
var amount = document.querySelector('#amount').value;
contract.send(receiverAddress, amount);
};

When executed this generates a larger pop-up window warning you that the client has received a request from the front end to send a transaction which includes data. It also clearly warns that the client does not understand what effect this data might have on the contracts state and that it might be far more profound than just a transfer of ether or some gas costs. You can safely ignore this message for now but in later tutorials I will show how you can generate documentation for your contract which will replace this warning with something more informative.

Check the state of your contract once a new block has been mined. You should see the changes to the state registering inside it.

This completes the tutorial on transactions, in the next JS api tutorial we will cover using ‘accessor’ functions, making calls to functions and sending other general commands to the client.

Contracts as databases

kennethkappler — Wed, 18 Feb 2015 13:34:07 +0000

Your contracts storage

Every contract on the blockchain has it’s own storage which only it can write to – and which it can control access to.

A contract’s storage is at its most basic a key-value store with 2^256 possible keys and 2^256 values. This makes for sufficient possible storage to create database structures of any type imaginable.

Solidity has several tools to for you to structure the storage of a contract as a relational database model. In the previous contract you used a mapping to store value associated with an address but this only one of many options.

In this tutorial we will cover the basic use of Structs, State variables and mappings which abstract the creation of complex rules for storing information.

Structs

Structs may be familiar to anyone who has used C type language before – essentially they are physical grouping of variables, stored under one reference:

struct coinwallet {
uint redCoin;
uint greenCoin;
}

This code defines a ‘type’ of struct but does not initialise an instance of it – this means that defining the struct doesn’t write anything to the contracts storage, in order to do this we have to declare an instance of the struct and then assign a value to its parameters:

coinWallet myWallet;
myWallet.redCoin = 500
myWallet.greenCoin = 250

this writes to storage addresses 0 and 1 respectively – try this contract in alethzero:

contract Test{
struct coinWallet {
uint redCoin;
uint greenCoin;
}
coinWallet myWallet;
function Test(){
myWallet.redCoin = 500;
myWallet.greenCoin = 250;
}
}

Note in the above how the underlying parameters of the myWallet variable are accessed by a dot operator on the myWallet instance of the coinWallet struct.

When used as a variable of finite size (ie: not in a mapping as used in our previous metaCoin contract) structs place things continuously in storage starting at key value ‘0x0’.

Mappings

Structs become far more interesting when used as datatypes for values inside of mappings.

Here is our very first metaCoin contract amended so that each user has two balances:

contract metaCoin {
struct coinWallet {
uint redCoin;
uint greenCoin;
}
mapping (address => coinWallet) balances;
function metaCoin() {
balances[msg.sender].redCoin = 10000;
balances[msg.sender].greenCoin = 5000;
}
function sendRed(address receiver, uint amount) {
if (balances[msg.sender].redCoin < amount) return;
balances[msg.sender].redCoin -= amount;
balances[receiver].redCoin += amount;
}
function sendGreen(address receiver, uint amount) {
if (balances[msg.sender].greenCoin < amount) return;
balances[msg.sender].greenCoin -= amount;
balances[receiver].greenCoin += amount;
}
}

Mappings calculate references for data storage by hashing the keys passed to the mapping. More details on how this works can be found here.

We can also include mappings as datatypes within another mapping:

contract rainbowCoin {
mapping (address => mapping (uint => uint)) balances;
function rainbowCoin() {
balances[msg.sender][0] = 10000; ///red coin
balances[msg.sender][1] = 10000; ///orange coin
balances[msg.sender][2] = 10000; ///yellow coin
balances[msg.sender][3] = 10000; ///green coin
balances[msg.sender][4] = 10000; ///blue coin
balances[msg.sender][5] = 10000; ///indigo coin
balances[msg.sender][6] = 10000; ///violet coin
}
function send(address receiver, uint amount, uint coin) {
if (balances[msg.sender][coin] < amount) return;
balances[msg.sender][coin] -= amount;
balances[receiver][coin] += amount;
}
}

Note how this allows us to access elements in the submapping inside balances using square brackets.

It is also possible to place mappings inside of structs, and place structs inside mappings – in fact the only datatype that you cannot place inside a struct or a mapping is itself.

Try the rainbowCoin contract above by pasting it into the alethzero transact pane. You will find that it behaves just like our coin contract from the first tutorial, the only difference is when sending a transaction you must include a third argument ‘coin’ which should be an integer between 0 and 6.

A typical data array for a transaction should look like this:

$0x67df93f2
0x5487699870...
500
4

Accessor Functions

So far you have viewed the contents of any contract you have added to the network using Alethzero’s GUI, however we have not defined any way to ‘get’ the value associated with a key directly. This is necessary requirement for many contracts because although we as external actors can easily view the whole of the contracts storage – other contracts are not able to look inside another contracts storage without executing a message call to a function specifically defined to return the relevant information.

Fortunately for us, Solidity will automatically create an accessor function to any of the state variables we choose to make public using the public keyword. By amending our Rainbow coin contract we can have solidity create an accessor function automatically:

contract rainbowCoin {
mapping (address => mapping (uint => uint)) public balances;
function rainbowCoin() {
balances[msg.sender][0] = 10000; ///red coin
balances[msg.sender][1] = 10000; ///orange coin
balances[msg.sender][2] = 10000; ///green coin
balances[msg.sender][0] = 10000; ///red coin
balances[msg.sender][1] = 10000; ///orange coin
balances[msg.sender][2] = 10000; ///green coin
}
function send(address receiver, uint amount, uint coin) {
if (balances[msg.sender][coin] < amount) return;
balances[msg.sender][coin] -= amount;
balances[receiver][coin] += amount;
}
}

If you copy the above into Alethzero you will see an additional ABI code has been generated by the compiler called ‘balances’. This function could be executed by a transaction, but in reality it never would be. Instead accessor functions are accessed via message calls from other contracts and calls made from our web front-end. Both of these will be demonstrated in a later tutorial.

Your First Dapp

kennethkappler — Wed, 18 Feb 2015 12:33:22 +0000

Introduction

This tutorial is designed to get you up and running with a very simple contract example – as such we will omit a lot of information for the sake of achieving something tangible quickly. We will also brush on a few topics that will be expanded on in later tutorials – for now if something doesn’t quite make sense it is best to push forward until we cover things in depth later on.

And now, onwards to a decentralized web! Please join us on IRC or our forums if you have questions!

The basics

Ethereum enables the decentralized web, referred to as ‘web 3’. What makes it different from web 2 is that on Ethereum, there are no web servers, and therefore no middlemen to take commissions, steal your data or offer it to the NSA, and of course nothing to DDoS.

A dapp (‘decentralized app’) consists of two parts: a frontend, written in HTML, and a backend (think of it as the ‘database’ for your frontend).

Good news: if you like bootstrap, or any other framework, you can continue using them, as the frontend of dapps have full network access, and CDNs are accessible. In fact, for all intent and purposes, developing a frontend for a dapp written HTML is the exact same as developing a website, and converting from web 2 to web 3 is in many cases trivial.

Even better news: you get reactive programming baked in (which should please angular, meteor and derby fans), by simply using callback functions, and there’s no new framework to learn.

Even even better news: because Ethereum relies on cryptographic principles to function, every dapp knows the pseudonymous identity of each user. That’s right, users won’t need to ‘create accounts’ or ‘log on’ to access your dapps, and you can think of this as openID by default, everywhere.

There is no bad news, except maybe for the bad actors from the web 2 world, such as dishonest exchanges running with the money or gambling sites falsifying random number information to make a quick buck. On Ethereum, the backend operations are validated by all nodes on the network, meaning that a backend will always will do what its code says it does. This is why you might have heard people call Ethereum ‘trustless’ – there’s no need for users to trust into a central authority to ‘do the right thing’.

This tutorial will focus on your first steps using AlethZero (our development client), and the creation of a simple coin contract – the backend of your dapp.

Installing the client

Important Note: The client is currently in a state of flux, and the most stable version is the master build which you will be using. If you are feeling brave feel free to switch to the latest ‘develop’ client but please note that this tutorial has not been tested to work with this version.

We’ll be using AlethZero, the C++ implementation of Ethereum designed for developers. In particular, we’re going to install the ‘development’ version, which contains all the latest goodies.

OS X users: please follow this guide. You can stop following the tutorial after you executed the brew linkapps command, then come back here.

Ubuntu users: please follow this guide. While a bit less user-friendly to install than its OS X counterpart, AlethZero is developed on ubuntu and therefore works very well on this platform.

Windows users: Binaries are available for the master version of the POC8 client – it is not recommended that you attempt to build your own at this stage.

A quick overview of AlethZero:

If all went well, you should see something like this after you start AlethZero, depending on your platform and screen resolution:

If your resolution varies, and not all the interface is visible, manually close all panes in the display by clicking their ‘x’ symbols until they are all gone, resize the screen to fit your resolution and re-add them manually by right clicking just below the titlebar (and just to the right of the ‘refresh’ button).

What’s going on here? At the centre of the screen is a browser window, a Webkit view to be exact. You can browse the existing web from there, just like any other browser, try google for example.

The rest of the panels contain debug and technical information that we’ll make use of a bit later. While useful for developers, this is not a very-user friendly interface, so the final Ethereum browser, tentatively called ‘Mist’ and built on top of the Go Ethereum implementation, will have a completely different look and feel. In fact, it’s likely that once Ethereum is launched, the etherbrowser will look a bit like this:

The above is a concept of a potential look and feel for the etherbrowser “Mist” being developed by our Amsterdam team, accessing a dapp that itself acts as a dapp store.

As far as options are concerned, feel free to reorganise your screen a bit. You can also drag and drop panels on top of each other to ‘stack’ them.

Choices, choices

Ethereum is a generalised programming platform. You can build games, financial applications, gambling apps, insurance companies, social networks, well, anything really! That said, it’s always good to keep in mind your users’ needs first and foremost, so what do you think they are missing from the centralised web? Well, trust of course!

So, for today’s tutorial we will write a simple contract that functions a bit like a bank, but with a transparent ledger that the whole world can audit. We’ll issue 10,000 tokens, and because it wouldn’t be much fun to keep all the tokens for ourselves, we’ll also create a method that allows us to send them to our friends.

This way, we are issuing our own money (in a very basic way, but still). In the web 2 world it would be similarly trivial to build such an app in PHP and MySql, but your users would have to trust you with being an honest accountant, that your ledger stays consistent, that the government wouldn’t ‘help’ itself with some tokens, that hackers wouldn’t break into your server, that your employees would be honest at all times and hadn’t planted a backdoor, or that your programmers wouldn’t have made a single mistake, ever… well, you get the point.

Our Contract

Our backend (referred to as a ‘contract’ in Ethereum) is going to use a language called Solidity. There are several other contract languages you can use when building Ethereum backends, LLL (similar to Lisp) and Serpent (similar to C++). We’ll use Solidity as it is the formally supported language by the ETHDEV team.

As we mentioned above, we’re building a little bank, so we’ll need to do two things:

1) Instantiate at least one account with a balance of tokens, to get things rolling when the contract is first created.

2) Build a ‘send’ function similar to contract.send(account, amount) in order to move tokens around.

Let’s dive in, and feel free to open your favorite text editor to edit your first contract!

contract metaCoin {	
	mapping (address => uint) balances;
	function metaCoin() {
		balances[msg.sender] = 10000;
	}
	function transfer(address receiver, uint amount) {
		if (balances[msg.sender] < amount) return;
		balances[msg.sender] -= amount;
		balances[receiver] += amount;
	}
}

Don’t panic, it’s much simpler than it looks. Contracts are divided into methods. The first method, entitled metaCoin, is a special constructor method that defines the initial state of the contracts data storage. Constructor methods always have the same name of the This initialisation code is run only once when the contract is created, and never again.

The second part of the contract is the contract code itself, the stuff that will live forever on the Ethereum network, immutable, and backed by millions of nodes insuring it returns the expected results every time. In our case, it’s a simple function that checks that the sender has a large enough balance and, if so, transfers the tokens from one account to the other.

Let’s look at this in a bit more detail:

mapping (address => uint) balances;

This line creates a mapping in storage where your code can strictly write information to the contracts storage – here we have defined a mapping for key value pairs of type address and uint called balances. This is where we will store users coin balances.

Note that we have specified two data types, address and uint. Unlike Serpent, Solidity is statically typed and will perform type checking at compile time. Specifying the type before compiling also allows us to reduce the size of the data array passed by transactions, and allows the compiler to create more optimised EVM code.

	function metaCoin() {
		balances[msg.sender] = 10000;
	}

This is the initialisation of our contract: it will only run once (because it’s within the constructor method ‘coin’), and it is doing a couple of things; Firstly, it uses msg.sender to lookup the public address of the transaction sender (you in this case). Secondly, it is accessing our contracts storage by using our mapping balances. Contracts store data as a key value pair both 32 bytes in length.

msg.sender is a 160bit number denoting your public key. This is a unique identifier on the network that cannot be forged, thanks to the cryptographic laws that Ethereum implements ‘under the hood’. There are other things that contracts can ‘trust’ about the transactions they receive and the blocks in the chain – we will explore these in other tutorials.

Now we have assigned ourselves an initial balance, let’s have a look at the ‘send’ function, which will be executed each time we call the contract from now on. This is the only executable function user can call – our initialisation function cannot be called again.

function transfer(address receiver, uint amount) {
		if (balances[msg.sender] < amount) return;
		balances[msg.sender] -= amount;
		balances[receiver] += amount;
	}

This function has two arguments passed to it by the transaction the variable receiver is another 160 bit public address of the recipient. amount is the second argument passed to our function and is the number of tokens you wish to send to the recipient.

On the first line we are going to check the current balance of msg.sender is less than the amount of tokens we wish to send – if it is we return empty and do not execute the next two lines of code. This makes sense as the account calling the contract is the one that is sending tokens, and it must have sufficient tokens to complete the transaction.

So the three arguments passed to our function ‘transfer’ in order to transfer tokens from one storage address to another are: msg.sender, receiver and amount.

If the balance checks out, the conditional will evaluate to false and the next two lines will subtract the amount being sent from the sender balance: balances[msg.sender] -= amount;, then add to the balance of the account receiving the tokens: balances[receiver] += amount;

So now we have a function which will send tokens from the control of one account to another.

Don’t run out of gas!

Before we go further, there is an important concept you need to understand that will help you master ethereum contracts: gas.

Let’s peek under the covers: in order to power the decentralised web, Ethereum cannot possibly rely on any centralised authority (because that authority could manipulate the database). Instead, every node that participates on the network hold a copy of a decentralised database, which they audit.

The network nodes process the code that is being executed in the database and come into agreement as to what the correct state of the database is through a vote. Majority always win the vote, and nodes are incentivised to do this verification work. Voting takes place at regular particular intervals, on average every 12.7 seconds.

The contract we have written earlier will be stored in this database. Contracts are triggered and executed when they are called by users or other contracts.

If you’re thinking that this necessary approach presents limits in terms of processing speed, you’d be correct. The total processing power of the Ethereum network, regardless of the number of nodes that forms it, is equal to a single smartphone from 1999. This means that you’re not going to want to store megabytes of data on the Ethereum network, or render 3d graphics. There are of course workarounds to this, including our upcoming storage solution called Swarm and our secure messaging protocol, Whisper, both companion technologies to Ethereum.

It also means that because computing power is limited, it has to be measured carefully so that no single actor can commit evil deeds such as running infinite loops on all the world’s Ethereum nodes. This unit of measure is called ‘gas’.

Gas comes into play when you try to make a contract do something. You ‘call’ a function of the contract, which then executes that function. It could be validating an escrow, or ‘like’ a friend on a decentralised social app, or transfer an amount of contract-specific token to another user, etc. Anything.

In order to execute this function, the contract will need gas, just like your car does. So, as part of the function call, you specify how much ‘gas’ you want to send to the contract, and how much you’re willing to pay for that gas (priced in ether, Ethereum’s fuel and unit of account).

The different operations a contract can support are priced differently. One execution cycle cost one gas for example. Others, like writing to storage, cost considerably more (because storage is a very scarce resource).

If you send too much gas to the contract, and it doesn’t use all of it, it is refunded to you. If you send too little, the contract stops and rolls back (just like your car when it’s ‘out of gas’).

How gas is priced depends on the global consensus of the community. It’s therefore likely operations that have the best priced gas will be executed first on the network, and the rest a bit later.

Uploading your contract.

Now that you understand Ethereum’s basic principles, and that you have your first contract written up, it’s time to save it on the Ethereum network.

Open up your Alethzero client if you havent already done so, and familiarise yourself with the interface. Make sure you have a notepad open with our contract saved inside. For the purpose of this tutorial you should not connect to the Testnet; Instead, select ‘Use private chain’ from the debug menu and create your very own private chain. This way you are not reliant on the testnet being online while you develop your dapps.

Click on the button marked ‘New Transaction’ in the menu bar to brin up the new transaction dialog. This is where you will input your contract code and send transactions, it consists of an address to send transactions to, options for gas and gasPrice, and a pane for inputing contract code or transaction data. Close this for now.

As mentioned previously, saving this contract or operating it will require ether, which at the moment we have 0 units of. In order to acquire a bit of ether, you need to participate in the voting process which guarantees the integrity of the decentralised database, a process referred to as ‘mining’.

You are not connected to the network in this case as you are running a private chain, so only you can mine for new blocks. Click on ‘Mine’ in the toolbar – then go to Debug and select ‘Force Mining’. You should start seeing various tabs come alive with information. The mining tab has a visual representation of the mining of a block – when a succesful block is found it is marked by a red spike and your balance should increase. An interesting tab to have a look during this process is the ‘Blockchain’ one – each vote is recorded here and tagged with a number. We’ll get back to this shortly.

Once you are the proud holder of say 15000 Finneys, you can stop mining. Click ‘mine’ again to stop the process. Now let’s save our contract.

Reopen the ‘New Transaction’ popup and copy and paste the solidity we wrote earlier within the ‘Data’ textbox. It should look a bit like this:

Since we are trying to create a contract and not send ether to another account, you can safely leave all the fields to their default value. We’ll be sending 10,000 gas to the contract priced at 10 Szabo each. A Szabo is a another unit of value, equivalent to 0.000001 ether. Since our contract creation code is so simple, we’ll be refunded of the majority of this ether as the saving of the contract will not consume all the gas.

If you have any compile errors you may not have copied the contract correctly – the debugger should give you the line and character if it has found an error. If you have pasted the contract correctly, you should two messages in the pane just under your contract code. The first one titled ‘Solidity’ contains what looks like a javascript snippet(which we will not be needing today), a list of all executable functions within the contract, and finally and most importantly for us the ABI (Application Byte Interface) of our function transfer. Take this information and copy it to a notepad as you will be needing it in a moment. The second is a series of assembly-like instructions similar to ‘PUSH2 0x27 0x10 CALLER…’. This is your contract code, in its compiled form.

Now that your contract is compiled, you just have to press the ‘Execute’ to save your contract in the decentralized database.

Since you shouldn’t be mining, it’s likely your contract creation will land ‘pending’. Make sure you have the ‘Pending’ pane open and you will see something like this:

After pressing ‘Execute’ in the transact pane make a quick note of the ‘creates’ field for that particular transaction in the ‘pending’ pane, in this particular case, ‘e1c8eea232d52995bd2202c12d42a28db80b2c44’ (it will be different for you, as each contract created has a unique ID).

Now that you have a pending contract you will need to commit this to the blockchain by mining a block (On a live network anyone else mining will receive this transaction and attempt to include it in the mining of a successful block). Click mine and wait for the transaction to disappear from the pending pane and for a new entry to appear in the ‘contract’ pane. Turn off mining again and click into your new contract in the contract pane. You should see something like the below:

You can see the entry in your contracts data storage from your initial setup showing a key value pair of the SHA3 of your public address and the number ‘10,000’. Everything looks good so we can assume that at the very least our constructor function has been run correctly. Now we wish to test if we can send our tokens to another public key; In order to run our function ‘code’ we need to send a transaction to the contracts address specifying a ‘To’ address, a ‘value’, and importantly: A function ID in the transactions data array. Locate the transact pane and paste the contracts address into the ‘Address’ box:

Now in the area where we previously input our code we are going to put first the function id and a recipient address and a value on separate lines. Use 0xec6d9353ca85eb80076817fa989f8825e136d55d (my public address on the testnet :p) and any value lower than 10,000. The data should look something like this:
$0xd0679d34 0xec6d9353ca85eb80076817fa989f8825e136d55d 500

Click Execute and you should once again see a transaction pending, hit ‘mine’ until you’ve generated a new block and then stop mining. Your contract should now look something like this:

Finally

And that is it – you have created your first contract! If you’re comfortable with what we have covered here – why dont you try and add the contract to the test network. Send me some tokens using ‘0xec6d9353ca85eb80076817fa989f8825e136d55d’ and ping me on twitter @kapplerken to let me know your contract address so I can send some back!

The next lesson will cover the basics of getting started with Ethereum’s Javascript API.

Your development Environment

kennethkappler — Wed, 18 Feb 2015 12:12:09 +0000

Building on Ethereum has been designed to be extremely easy for web designers to learn – with the languages being familiar enough for anyone with a knowledge of javascript to pick up very quickly.

We have three pieces of software that every developer should download – Alethzero, Mist and Mix. Alethzero is a full GUI Client with advanced features like private chains, force mining and full webkit suite. Mist is the Dapp browser and mining client which Dapp users will access your dapps in. Finally, Mix is a fully integrated development environment – purposely designed to build and debug contracts and their corresponding frontends.

Software requirements:

Getting your development environment setup should be fairly simple for anyone who has designed a web page before – just follow the steps below:

Firstly download the latest stable build of Alethzero, our C++ client, and install on your chosen operating system. If you experience problems with the stable build then you may wish to switch to the latest cutting edge version which may ameliorate some of your issues. If you choose instead to build your own then build instructions are here.

Secondly, Install MIX our integrated development environment available for Windows and Mac here. If you are using Linux follow the instructions here to install mix also.

Finally, make sure you install Mist to test your Dapps and fine tune your front-ends as you develop them.

Extra

Unless stated otherwise the tutorials should be run on Alethzero using a private chain – deploying to the test net should be reserved for contracts you want to share with others.

A text editor or Mix can be used for creating the backend contract code which we are going to write, for serpent I suggest you set your editor to treat serpent contracts saved with the ‘.se’ suffix as python syntax and for solidity you should save your files with a ‘.sol’ suffix.

A live refresh solution is *not* recommended when working on your html front-end, as these have not been tested fully.

Introduction to development on Ethereum

kennethkappler — Wed, 18 Feb 2015 11:57:13 +0000

Ethereum – a Decentralised Consensus Network

To most developers, learning to use a new platform, language, or framework will be a familiar task repeated dozens of times during their career. Altogether more novel is learning to develop for a completely different paradigm. The decentralised consensus network, the blockchain, and its most well known implementation ‘bitcoin’ are not well understood even amongst the tech community and the subtleties of how this technology is fundamentally different from what we have used before is certainly lost on most of the general public.

With that in mind before we proceed with building our first decentralised apps I will outline a few of the key technologies that are required to make a decentralised consensus network, and the game theory which makes use of these technologies to create a network.

Core technologies

Public Key Cryptography

Public-private key cryptography is a class of encryption methods which require the creation of two seperate keys; the “private key” known only to the owner, and the “public key” which is known to anyone. It has several useful attributes, the first is the ability of anyone to encrypt data with a public key which can only be decrypted by the private key. The second is the ability of the private key holder to sign a piece of information using their private key in such a way that it can be verified by anyone holding the public key, without giving any information away about the private key. This second attribute is used for the accounts system in a DCN, and forms the basis of sending transactions.

Cryptographic Hash Function

A hash function is a function which takes one piece of information of any size and maps it to another piece of data of a fixed size ie a 1MB file or a 500KB file when run through a hash function would produce two seperate ‘hashes’ 128 bits in length. A Cryptographic Hash Function is one that performs this function but also fulfils three important requirements: it does so in a way that no information is given on what input data produced the hash (non reversible), it does so in a way that a minor change in the input change gives a very different output hash, that the hash cannot be calculated except using the hash function (no shortcuts), that there is an extremely low probability that two different inputs will produce the same hash.

Peer to peer networking

Unlike the Client Server model peer to peer networks consist of networks of computers connected to one another directly without sending requests to any server. All computers taking part in the network are considered to be ‘peers’ and have equal standing within the network as one another. Peer to Peer networks generally rely on the peers being altruistic and sharing at least as many resources as they take from the network

CryptoEconomic Technologies

The Blockchain

A blockchain in all it’s incarnations is a database type designed specifically for use in a DCN. It can hold any information, and can set rules on how information is updated. Its primary feature is that it is updated in discrete chunks called ‘blocks’ which are ‘chained’ together using hashes of the previous blocks content. A blockchain contains not only the information that is currently stored in the database, but also every change made to the database in it’s history.Known as the state and transactions respectively it makes for a database with a complete custodial history that cannot be altered without altering every subsequent block. ‘Transactions’ or requests to change the state of the database are always signed by a private key, and the signature is stored in the blockchain.

Proof of Work

Originaly envisioned as a spam prevention system proof of work is a simple method for proving that you have *probably* performed a large number of mathematical operations. It is implemented in the majority of cases using a cryptographic hash function; given an arbritary piece of data, (like a list of transactions and the header of a block) you must find a second piece of data which, when combined with the first, produces a hash that has certain characteristics (like a number of trailing zeros). Because it is impossible to predict what second piece of data will produce the required hash, you must randomly iterate through possible data until you find one that produces the hash you require.

Ethereum Technologies

Ethereum Virtual Machine

The Ethereum Virtual Machine is the primary innovation of the Ethereum project. This is a virtual machine designed to be run by all participants in a peer to peer network, it can read and write to a blockchain both executable code and data, Verify digital signatures, and is able to run code in a quasi-turing complete manner. It will only execute code when it recieves a message verified by a digital signature, and the information stored on the blockchain tells it is appropriate to do so.

The Decentralized Consensus Network and the Generalised Blockchain

Ethereum is a peer to peer network where every peer stores the same copy of a blockchain database and runs an Ethereum virtual machine to maintain and alter it’s state. Proof of work is integrated into the blockchain technology by making the creation of a new block require the proof of work be undertaken by all members of the network. Consensus is achieved via incentivization for peers to always accept the longest chain of blocks in the blockchain by distribution of a cryptographic token of value: ‘ether’.

This leaves us with a new piece of technology that does not fit within the client-server model nor does it qualify as a traditional peer to peer network as its existence is incentivised meaning it can be relied upon to provide a consistent deterministic service.

Because of its distributed nature and built in cryptographic security it can act as a third party, capable of arbitrating trustlessly, and without interference from outside parties. Through the use of cryptocurrencies decisions made by software can have financial consequences for people, organisations or even other software.

This provides developers with new ways to enable interactions between parties across the internet. While I explain the subtleties of the development of decentralized-apps I will give use cases and try my best to explain the importance of each one.