A next generation blockchain¶

Blockchain technology is the technological basis of Bitcoin, first described by its mysterious author Satoshi Nakamoto in his white paper “Bitcoin: A Peer-to-Peer Electronic Cash System”, published in 2008. While the use of blockchains for more general uses was already discussed in the original paper, it was not until a few years later that blockchain technology emerged as a generic term. A blockchain is a distributed computing architecture where every network node executes and records the same transactions, which are grouped into blocks. Only one block can be added at a time, and every block contains a mathematical proof that verifies that it follows in sequence from the previous block. In this way, the blockchain’s “distributed database” is kept in consensus across the whole network. Individual user interactions with the ledger (transactions) are secured by strong cryptography. Nodes that maintain and verify the network are incentivized by mathematically enforced economic incentives coded into the protocol.

In Bitcoin’s case the distributed database is conceived of as a table of account balances, a ledger, and transactions are transfers of the bitcoin token to facilitate trustless finance between individuals. But as bitcoin began attracting greater attention from developers and technologists, novel projects began to use the bitcoin network for purposes other than transfers of value tokens. Many of these took the form of “alt coins” - separate blockchains with cryptocurrencies of their own which improved on the original bitcoin protocol to add new features or capabilities. In late 2013, Expanse’s inventor Vitalik Buterin proposed that a single blockchain with the capability to be reprogrammed to perform any arbitrarily complex computation could subsume these many other projects.

Expanse Virtual Machine¶

Expanse is a programmable blockchain. Rather than give users a set of pre-defined operations (e.g. bitcoin transactions), Expanse allows users to create their own operations of any complexity they wish. In this way, it serves as a platform for many different types of decentralized blockchain applications, including but not limited to cryptocurrencies.

Expanse in the narrow sense refers to a suite of protocols that define a platform for decentralised applications. At the heart of it is the Expanse Virtual Machine (“EVM”), which can execute code of arbitrary algorithmic complexity. In computer science terms, Expanse is “Turing complete”. Developers can create applications that run on the EVM using friendly programming languages modelled on existing languages like JavaScript and Python.

Like any blockchain, Expanse also includes a peer-to-peer network protocol. The Expanse blockchain database is maintained and updated by many nodes connected to the network. Each and every node of the network runs the EVM and executes the same instructions. For this reason, Expanse is sometimes described evocatively as a “world computer”.

This massive parallelisation of computing across the entire Expanse network is not done to make computation more efficient. In fact, this process makes computation on Expanse far slower and more expensive than on a traditional “computer”. Rather, every Expanse node runs the EVM in order to maintain consensus across the blockchain. Decentralized consensus gives Expanse extreme levels of fault tolerance, ensures zero downtime, and makes data stored on the blockchain forever unchangeable and censorship-resistant.

The Expanse platform itself is featureless or value-agnostic. Similar to programming languages, it is up to entrepreneurs and developers to decide what it should be used for. However, it is clear that certain application types benefit more than others from Expanse’s capabilities. Specifically, expanse is suited for applications that automate direct interaction between peers or facilitate coordinated group action across a network. For instance, applications for coordinating peer-to-peer marketplaces, or the automation of complex financial contracts. Bitcoin allows for individuals to exchange cash without involving any middlemen like financial institutions, banks, or governments. Expanse’s impact may be more far-reaching. In theory, financial interactions or exchanges of any complexity could be carried out automatically and reliably using code running on Expanse. Beyond financial applications, any environments where trust, security, and permanence are important – for instance, asset-registries, voting, governance, and the internet of things – could be massively impacted by the Expanse platform.

How does Expanse work?¶

Expanse incorporates many features and technologies that will be familiar to users of Bitcoin, while also introducing many modifications and innovations of its own.

Whereas the Bitcoin blockchain was purely a list of transactions, Expanse’s basic unit is the account. The Expanse blockchain tracks the state of every account, and all state transitions on the Expanse blockchain are transfers of value and information between accounts. There are two types of accounts:

• Externally Owned Accounts (EOAs), which are controlled by private keys
• Contract Accounts, which are controlled by their contract code and can only be “activated” by an EOA

For most users, the basic difference between these is that human users control EOAs - because they can control the private keys which give control over an EOA. Contract accounts, on the other hand, are governed by their internal code. If they are “controlled” by a human user, it is because they are programmed to be controlled by an EOA with a certain address, which is in turn controlled by whoever holds the private keys that control that EOA. The popular term “smart contracts” refers to code in a Contract Account – programs that execute when a transaction is sent to that account. Users can create new contracts by deploying code to the blockchain.

Contract accounts only perform an operation when instructed to do so by an EOA. So it is not possible for a Contract account to be performing native operations like random number generation or API calls – it can do these things only if prompted by an EOA. This is because Expanse requires nodes to be able to agree on the outcome of computation, which requires a guarantee of strictly deterministic execution.

Like in Bitcoin, users must pay small transaction fees to the network. This protects the Expanse blockchain from frivolous or malicious computational tasks, like DDoS attacks or infinite loops. The sender of a transaction must pay for each step of the “program” they activated, including computation and memory storage. These fees are paid in amounts of Expanse’s native value-token, expanse.

These transaction fees are collected by the nodes that validate the network. These “miners” are nodes in the Expanse network that receive, propogate, verify, and execute transactions. The miners then group the transactions – which include many updates to the “state” of accounts in the Expanse blockchain – into what are called “blocks”, and miners then compete with one another for their block to be the next one to be added to the blockchain. Miners are rewarded with expanse for each successful block they mine. This provides the economic incentive for people to dedicate hardware and electricity to the Expanse network.

Just as in the Bitcoin network, miners are tasked with solving a complex mathematical problem in order to successfully “mine” a block. This is known as a “Proof of Work”. Any computational problem that requires orders of magnitude more resources to solve algorithmically than it takes to verify the solution is a good candidate for proof of work. In order to discourage centralisation due to the use of specialised hardware (e.g. ASICs), as has occurred in the Bitcoin network, Expanse chose a memory-hard computational problem. If the problem requires memory as well as CPU, the ideal hardware is in fact the general computer. This makes Expanse’s Proof of Work ASIC-resistant, allowing a more decentralized distribution of security than blockchains whose mining is dominated by specialized hardware, like Bitcoin.

Using Expanse: The Basics¶

This section captures the basic ways in which a user would want to participate in the Expanse project. First of all becoming a node in the network you need to run an Expanse client. Multiple implementations are listed in the section Choosing a client which also gives you advice what clients to choose in various setups. Connecting to the Network gives you basic information about networks, connectivity troubleshooting and blockchain synchronization. Advanced network topics like setting up private chains is found in Test Networks.

Milestones of the Expanse development roadmap¶

The original development roadmap laid out before Expanse went live specified the following milestones:

• Prerelease Step 0: Olympic testnet - launched May 2015
• Release Step One: Frontier - launched 30 July 2015
• Release Step Two: Homestead - launches 14 March 2016 (Pi Day)
• Release Step Three: Metropolis - TBA
• Release Step Four: Serenity - TBA

While still valid, the substance behind it has changed somewhat. The Olympic testnet phase (before the Frontier release) saw a lot of major improvements, followed by Frontier which was launched immediately after. Homestead marks the exit from a beta product to a stable release. Homestead is introduced automatically at block number 1,150,000 which should occur roughly around March 14th, 2016, Pi Day.

If you are running a node connected to the live network, it is important that you upgrade to a Homestead-compatible client. Such clients with their versions are listed under Expanse Clients. Otherwise you will end up on the wrong fork and will no longer be in sync with the rest of the network.

Once the Expanse blockchain reaches block 1,150,000, the Expanse network will undergo a hardfork enabling a few major changes such as explained in the following section.

Homestead hard fork changes¶

Expanse in the narrow formal sense is a suite of protocols. Homestead comes with a few backward-incompatible protocol changes, and therefore will require a hard fork. These changes that made their way through the process for Expanse Improvement Proposals and included are:

• EIP 2:
  • cost for creating contracts via a transaction is increased from 21000 to 53000. Contract creation from a contract using the CREATE opcode is unaffected.
  • transaction signatures whose s-value is greater than secp256k1n/2 are now considered invalid
  • If contract creation does not have enough gas to pay for the final gas fee for adding the contract code to the state, the contract creation fails (ie. goes out-of-gas) rather than leaving an empty contract.
  • Change the difficulty adjustment algorithm
• EIP 7: DELEGATECALL: Add a new opcode, DELEGATECALL at 0xf4, which is similar in idea to CALLCODE, except that it propagates the sender and value from the parent scope to the child scope, ie. the call created has the same sender and value as the original call. This means contracts can store pass through information while following msg.sender and msg.value from its parent contract. Great for contracts which create contracts but don’t repeat additional information which saves gas. See comments on EIP 7
• EIP 8: devp2p Forward Compatibility compliance with the Robustness Principle Changes to the RLPx Discovery Protocol and RLPx TCP transfer protocol to ensure that all client software in use on the Expanse network can cope with future network protocol upgrades. For older versions of an Expanse client, updates to the network protocol weren’t being accepted by older clients and would refuse communication if the hello packets didn’t meet expectations. This update means all future versions of the client will accept incoming network upgrades and handshakes.

The changes have the following benefits:

• EIP-2/1 eliminates the excess incentive to create contracts via transactions, where the cost is 21000, rather than contracts, where the cost is 32000.
• EIP-2/1 also fixes the protocol “bug” that with the help of suicide refunds, it is currently possible to make a simple expanse value transfer using only 11664 gas.
• EIP-2/2 fixes a transaction malleability concern (not a security flaw, but a UI incovenience).
• EIP-2/3 creates a more intuitive “success or fail” distinction in the result of a contract creation process, rather than the current “success, fail, or empty contract” trichotomy
• EIP-2/4 eliminates the excess incentive to set the timestamp difference to exactly 1 in order to create a block that has slightly higher difficulty and that will thus be guaranteed to beat out any possible forks. This guarantees to keep block time in the 10-20 range and according to simulations restores the target 15 second blocktime (instead of the current effective 17s).
• EIP-7 makes it much easier for a contract to store another address as a mutable source of code and ‘’pass through’’ calls to it, as the child code would execute in essentially the same environment (except for reduced gas and increased callstack depth) as the parent.
• EIP-8 makes sure that all client software in use on the Expanse network can cope with future network protocol upgrades.

Additional resources: - Reddit discussion on Homestead Release - Expanse Improvement Proposals

Smart contracts¶

by Alex:

Would you enter in a contract with someone you’ve never met? Would you agree to lend money to some farmer in Ethiopia? Would you become an investor in a minority-run newspaper in a war zone? Would you go to the hassle of writing up a legal binding contract for a $5 dollar purchase over the internet?

The answer is no for most of these questions, the reason being that a contract requires a large infrastructure: sometimes you need a working trust relationship between the two parties, sometimes you rely on a working legal system, police force and lawyer costs.

In Expanse you don’t need any of that: if all the requisites to the contract can be put in the blockchain then they will, in a trustless environment for almost no cost.

Instead of thinking of moving your current contracts to the blockchain, think of all the thousand little contracts that you would never agree to simply because they weren’t economically feasible or there was not enough legal protection..

DAO¶

Here is just one example: imagine you own a small business with your friends. Lawyers and accountants are expensive, and trusting a single partner to oversee the books can be a source of tension (even an opportunity for fraud). Complying strictly with a system in which more than one partner oversees the books can be trying and is subject to fraud whenever the protocol isn’t followed exactly.

Using a smart contract, ownership in your company and terms for the disbursal of funds can be specified at the outset. The smart contract can be written such that it is only changeable given the approval of a majority of owners. Smart contracts like these will likely be available as open source software, so you won’t even need to hire your own programmer instead of an accountant/lawyer.

A smart contract like this scales instantly. A couple of teenagers can split revenue from a lemonade stand just as transparently as a sovereign wealth fund can disburse funds to the hundred million citizens who are entitled to it. In both cases the price of this transparency is likely to be fractions of a penny per dollar.

Slack¶

• Slack Chatroom - Over 1100+ members

Reddit¶

• /r/ExpanseOfficial - Expanse everything

Meetups¶

• Directory hosted on Meetup
• Meetup channel on Expanse Forum

Expanse Core’s faces to the community¶

• Official website - main entrypoint
• Reddit - see Community
• Blog
• Twitter
• Email - use if you must

For community discussion forums, see Community.

The Expanse network¶

The basis for decentralized consensus is the peer-to-peer network of participating nodes which maintain and secure the blockchain. See Mining.

How to connect¶

Gexp continuously attempts to connect to other nodes on the network until it has peers. If you have UPnP enabled on your router or run Expanse on an Internet-facing server, it will also accept connections from other nodes.

Gexp finds peers through something called the discovery protocol. In the discovery protocol, nodes are gossipping with each other to find out about other nodes on the network. In order to get going initially, gexp uses a set of bootstrap nodes whose endpoints are recorded in the source code.

> net.listening
true

> net.peerCount
4

> admin.peers
[{
      ID: 'a4de274d3a159e10c2c9a68c326511236381b84c9ec52e72ad732eb0b2b1a2277938f78593cdbe734e6002bf23114d434a085d260514ab336d4acdc312db671b',
      Name: 'Gexp/v0.9.14/linux/go1.4.2',
      Caps: 'exp/60',
      RemoteAddress: '5.9.150.40:30301',
      LocalAddress: '192.168.0.28:39219'
 }, {
      ID: 'a979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c',
      Name: 'Gexp/v0.9.15/linux/go1.4.2',
      Caps: 'exp/60',
      RemoteAddress: '52.16.188.185:30303',
      LocalAddress: '192.168.0.28:50995'
 }, {
      ID: 'f6ba1f1d9241d48138136ccf5baa6c2c8b008435a1c2bd009ca52fb8edbbc991eba36376beaee9d45f16d5dcbf2ed0bc23006c505d57ffcf70921bd94aa7a172',
      Name: 'pyethapp_dd52/v0.9.13/linux2/py2.7.9',
      Caps: 'exp/60, p2p/3',
      RemoteAddress: '144.76.62.101:30303',
      LocalAddress: '192.168.0.28:40454'
 }, {
  ID: 'f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0',
  Name: '++exp/Zeppelin/Rascal/v0.9.14/Release/Darwin/clang/int',
  Caps: 'exp/60, shh/2',
  RemoteAddress: '129.16.191.64:30303',
  LocalAddress: '192.168.0.28:39705'
 } ]

> admin.nodeInfo
{
  Name: 'Gexp/v0.9.14/darwin/go1.4.2',
  NodeUrl: 'enode://3414c01c19aa75a34f2dbd2f8d0898dc79d6b219ad77f8155abf1a287ce2ba60f14998a3a98c0cf14915eabfdacf914a92b27a01769de18fa2d049dbf4c17694@[::]:30303',
  NodeID: '3414c01c19aa75a34f2dbd2f8d0898dc79d6b219ad77f8155abf1a287ce2ba60f14998a3a98c0cf14915eabfdacf914a92b27a01769de18fa2d049dbf4c17694',
  IP: '::',
  DiscPort: 30303,
  TCPPort: 30303,
  Td: '2044952618444',
  ListenAddr: '[::]:30303'
}

Download the blockchain faster¶

When you start an Expanse client, the Expanse blockchain is automatically downloaded. The time it takes to download the Expanse blockchain can vary based on client, client settings, connection speed, and number of peers available. Below are some options for more quickly obtaining the Expanse blockchain.

gexp --fast --cache=1024 --jitvm console

Static Nodes, Trusted Nodes, and Boot Nodes¶

Gexp supports a feature called static nodes if you have certain peers you always want to connect to. Static nodes are re-connected on disconnects. You can configure permanent static nodes by putting something like the following into <datadir>/static-nodes.json (this should be the same folder that your chaindata and keystore folders are in)

[
      "enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303",
      "enode://pubkey@ip:port"
]

You can also add static nodes at runtime via the Javascript console using admin.addPeer()

> admin.addPeer("enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303")

Morden testnet¶

Morden is a public Expanse alternative testnet. It is expected to continue throughout the Frontier and Homestead milestones of the software.

exp (C++ client)¶

It is possible to connect to or create a new network by using the –genesis and –config.

It is possible to use both –config and –genesis.

In that case, the genesis block description provided by –config will be overwritten by the –genesis option.

Here is a Config sample (used by the Olympic network):

The content is the same as the genesis field provided by the ‘config’ parameter:

gexp (Go client)¶

You either pre-generate or mine your own Expanse on a private testnet. It is a much more cost effective way of trying out Expanse and you can avoid having to mine or find Morden test expanse.

The things that are required to specify in a private chain are:

• Custom Genesis File
• Custom Data Directory
• Custom NetworkID
• (Recommended) Disable Node Discovery

{
    "nonce": "0x0000000000000042",     "timestamp": "0x0",
    "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "extraData": "0x0",     "gasLimit": "0x8000000",     "difficulty": "0x400",
    "mixhash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "coinbase": "0x3333333333333333333333333333333333333333",     "alloc": {     }
}

gexp --identity "MyNodeName" --genesis /path/to/CustomGenesis.json --rpc --rpcport "8080" --rpccorsdomain "*" --datadir "C:\chains\TestChain1" --port "30303" --nodiscover --rpcapi "db,exp,net,web3" --networkid 1999 console

"alloc":
{
        "<your account address e.g. 0x1fb891f92eb557f4d688463d0d7c560552263b5a>":
        { "balance": "20000000000000000000" }
}

> gexp account list
Account #0: {d1ade25ccd3d550a7eb532ac759cac7be09c2719}
Account #1: {da65665fc30803cb1fb7e6d86691e20b1826dee0}
Account #2: {e470b1a7d2c9c5c6f03bbaa8fa20db6d404a0c32}
Account #3: {f4dd5c3794f1fd0cdc0327a83aa472609c806e99}

> exp.accounts

> primary = exp.accounts[0]

> balance = web3.fromWei(exp.getBalance(primary), "expanse");

EOA vs contract accounts¶

There are two types of accounts in Expanse

• Externally Owned Accounts
• Contracts Accounts

This distinction might be eliminated in Serenity.

What is a transaction?¶

The term “transaction” is used in Expanse to refer to the signed data package that stores a message to be sent from an externally owned account to another account on the blockchain.

Transactions contain:

• the recipient of the message,
• a signature identifying the sender and proving their intention to send the message via the blockchain to the recipient,
• VALUE field - The amount of wei to transfer from the sender to the recipient,
• an optional data field, which can contain the message sent to a contract,
• a STARTGAS value, representing the maximum number of computational steps the transaction execution is allowed to take,
• a GASPRICE value, representing the fee the sender is willing to pay for gas. One unit of gas corresponds to the execution of one atomic instruction, i.e., a computational step.

What is a message?¶

Contracts have the ability to send “messages” to other contracts. Messages are virtual objects that are never serialized and exist only in the Expanse execution environment. They can be conceived of as function calls.

A message contains:

• the sender of the message (implicit).
• the recipient of the message
• VALUE field - The amount of wei to transfer alongside the message to the contract address,
• an optional data field, that is the actual input data to the contract
• a STARTGAS value, which limits the maximum amount of gas the code execution triggered by the message can incur.

Essentially, a message is like a transaction, except it is produced by a contract and not an external actor. A message is produced when a contract currently executing code executes the CALL or DELEGATECALL opcodes, which produces and executes a message. Like a transaction, a message leads to the recipient account running its code. Thus, contracts can have relationships with other contracts in exactly the same way that external actors can.

What is gas?¶

Expanse implements an execution environment on the blockchain called the Expanse Virtual Machine (EVM). Every node participating in the network runs the EVM as part of the block verification protocol. They go through the transactions listed in the block they are verifying and run the code as triggered by the transaction within the EVM. Each and every full node in the network does the same calculations and stores the same values. Clearly Expanse is not about optimising efficiency of computation. Its parallel processing is redundantly parallel. This is to offer an efficient way to reach consensus on the system state without needing trusted third parties, oracles or violence monopolies. But importantly they are not there for optimal computation. The fact that contract executions are redundantly replicated across nodes, naturally makes them expensive, which generally creates an incentive not to use the blockchain for computation that can be done offchain.

When you are running a decentralized application (dapp), it interacts with the blockchain to read and modify its state, but dapps will typically only put the business logic and state that are crucial for consensus on the blockchain.

When a contract is executed as a result of being triggered by a message or transaction, every instruction is executed on every node of the network. This has a cost: for every executed operation there is a specified cost, expressed in a number of gas units.

Gas is the name for the execution fee that senders of transactions need to pay for every operation made on an Expanse blockchain. The name gas is inspired by the view that this fee acts as cryptofuel, driving the motion of smart contracts. Gas is purchased for expanse from the miners that execute the code. Gas and expanse are decoupled deliberately since units of gas align with computation units having a natural cost, while the price of expanse generally fluctuates as a result of market forces. The two are mediated by a free market: the price of gas is actually decided by the miners, who can refuse to process a transaction with a lower gas price than their minimum limit. To get gas you simply need to add expanse to your account. The Expanse clients automatically purchase gas for your Expanse in the amount you specify as your maximum expenditure for the transaction.

The Expanse protocol charges a fee per computational step that is executed in a contract or transaction to prevent deliberate attacks and abuse on the Expanse network. Every transaction is required to include a gas limit and a fee that it is willing to pay per gas. Miners have the choice of including the transaction and collecting the fee or not. If the total amount of gas used by the computational steps spawned by the transaction, including the original message and any sub-messages that may be triggered, is less than or equal to the gas limit, then the transaction is processed. If the total gas exceeds the gas limit, then all changes are reverted, except that the transaction is still valid and the fee can still be collected by the miner. All excess gas not used by the transaction execution is reimbursed to the sender as Expanse. You do not need to worry about overspending, since you are only charged for the gas you consume. This means that it is useful as well as safe to send transactions with a gas limit well above the estimates.

Estimating transaction costs¶

The total expanse cost of a transaction is based on 2 factors:

gasUsed is the total gas that is consumed by the transaction

gasPrice price (in expanse) of one unit of gas specified in the transaction

Total cost = gasUsed * gasPrice

Account interactions example - betting contract¶

As previously mentioned, there are two types of accounts:

• Externally owned account (EOAs): an account controlled by a private key, and if you own the private key associated with the EOA you have the ability to send expanse and messages from it.
• Contract: an account that has its own code, and is controlled by code.

By default, the Expanse execution environment is lifeless; nothing happens and the state of every account remains the same. However, any user can trigger an action by sending a transaction from an externally owned account, setting Expanse’s wheels in motion. If the destination of the transaction is another EOA, then the transaction may transfer some expanse but otherwise does nothing. However, if the destination is a contract, then the contract in turn activates, and automatically runs its code.

The code has the ability to read/write to its own internal storage (a database mapping 32-byte keys to 32-byte values), read the storage of the received message, and send messages to other contracts, triggering their execution in turn. Once execution stops, and all sub-executions triggered by a message sent by a contract stop (this all happens in a deterministic and synchronous order, ie. a sub-call completes fully before the parent call goes any further), the execution environment halts once again, until woken by the next transaction.

Contracts generally serve four purposes:

• Maintain a data store representing something which is useful to either other contracts or to the outside world; one example of this is a contract that simulates a currency, and another is a contract that records membership in a particular organization.
• Serve as a sort of externally-owned account with a more complicated access policy; this is called a “forwarding contract” and typically involves simply resending incoming messages to some desired destination only if certain conditions are met; for example, one can have a forwarding contract that waits until two out of a given three private keys have confirmed a particular message before resending it (ie. multisig). More complex forwarding contracts have different conditions based on the nature of the message sent. The simplest use case for this functionality is a withdrawal limit that is overrideable via some more complicated access procedure. A wallet contract is a good example of this.
• Manage an ongoing contract or relationship between multiple users. Examples of this include a financial contract, an escrow with some particular set of mediators, or some kind of insurance. One can also have an open contract that one party leaves open for any other party to engage with at any time; one example of this is a contract that automatically pays a bounty to whoever submits a valid solution to some mathematical problem, or proves that it is providing some computational resource.
• Provide functions to other contracts, essentially serving as a software library.

Contracts interact with each other through an activity that is alternately called either “calling” or “sending messages”. A “message” is an object containing some quantity of expanse, a byte-array of data of any size, the addresses of a sender and a recipient. When a contract receives a message, it has the option of returning some data, which the original sender of the message can then immediately use. In this way, sending a message is exactly like calling a function.

Because contracts can play such different roles, we expect that contracts will be interacting with each other. As an example, consider a situation where Alice and Bob are betting 100 GavCoin that the temperature in San Francisco will not exceed 35ºC at any point in the next year. However, Alice is very security-conscious, and as her primary account uses a forwarding contract which only sends messages with the approval of two out of three private keys. Bob is paranoid about quantum cryptography, so he uses a forwarding contract which passes along only messages that have been signed with Lamport signatures alongside traditional ECDSA (but because he’s old fashioned, he prefers to use a version of Lamport sigs based on SHA256, which is not supported in Expanse directly).

The betting contract itself needs to fetch data about the San Francisco weather from some contract, and it also needs to talk to the GavCoin contract when it wants to actually send the GavCoin to either Alice or Bob (or, more precisely, Alice or Bob’s forwarding contract). We can show the relationships between the accounts thus:

When Bob wants to finalize the bet, the following steps happen:

1. A transaction is sent, triggering a message from Bob’s EOA to his forwarding contract.
2. Bob’s forwarding contract sends the hash of the message and the Lamport signature to a contract which functions as a Lamport signature verification library.
3. The Lamport signature verification library sees that Bob wants a SHA256-based Lamport sig, so it calls the SHA256 library many times as needed to verify the signature.
4. Once the Lamport signature verification library returns 1, signifying that the signature has been verified, it sends a message to the contract representing the bet.
5. The bet contract checks the contract providing the San Francisco temperature to see what the temperature is.
6. The bet contract sees that the response to the messages shows that the temperature is above 35ºC, so it sends a message to the GavCoin contract to move the GavCoin from its account to Bob’s forwarding contract.

Note that the GavCoin is all “stored” as entries in the GavCoin contract’s database; the word “account” in the context of step 6 simply means that there is a data entry in the GavCoin contract storage with a key for the bet contract’s address and a value for its balance. After receiving this message, the GavCoin contract decreases this value by some amount and increases the value in the entry corresponding to Bob’s forwarding contract’s address. We can see these steps in the following diagram:

Signing transactions offline¶

[ Maybe add this to the FAQ and point to the ethkey section of turboethereum guide? ]

• Resilience Raw Transaction Broadcaster

What is a contract?¶

A contract is a collection of code (its functions) and data (its state) that resides at a specific address on the Expanse blockchain. Contract accounts are able to pass messages between themselves as well as doing practically Turing complete computation. Contracts live on the blockchain in a Expanse-specific binary format called Expanse Virtual Machine (EVM) bytecode.

Contracts are typically written in some high level language such as Solidity and then compiled into bytecode to be uploaded on the blockchain.

Dapp development resources lists the integrated development environments, developer tools that help you develop in these languages, offering testing, and deployment support among other features.

Expanse high level languages¶

Contracts live on the blockchain in an Expanse-specific binary format (EVM bytecode) that is executed by the Expanse Virtual Machine (EVM). However, contracts are typically written in a higher level language and then compiled using the EVM compiler into byte code to be deployed to the blockchain.

Below are the different high level languages developers can use to write smart contracts for Expanse.

Writing a contract¶

No language would be complete without a Hello World program. Operating within the Expanse environment, Solidity has no obvious way of “outputting” a string. The closest we can do is to use a log event to place a string into the blockchain:

contract HelloWorld {
        event Print(string out);
        function() { Print("Hello, World!"); }
}

This contract will create a log entry on the blockchain of type Print with a parameter “Hello, World!” each time it is executed.

Compiling a contract¶

Compilation of solidity contracts can be accomplished via a number of mechanisms.

• Using the solc compiler via the command line.
• Using web3.exp.compile.solidity in the javascript console provided by gexp or exp (This still requires the solc compiler to be installed).
• The online Solidity realtime compiler.
• The Meteor dapp Cosmo for building solidity contracts.
• The Mix IDE.
• The Expanse Wallet.

> web3.exp.getCompilers();
["lll", "solidity", "serpent"]

$ gexp --solc /usr/local/bin/solc

> admin.setSolc("/usr/local/bin/solc")
solc, the solidity compiler commandline interface
Version: 0.2.2-02bb315d/.-Darwin/appleclang/JIT linked to libethereum-1.2.0-8007cef0/.-Darwin/appleclang/JIT
path: /usr/local/bin/solc

> source = "contract test { function multiply(uint a) returns(uint d) { return a * 7; } }"

> contract = exp.compile.solidity(source).test
{
  code: '605280600c6000396000f3006000357c010000000000000000000000000000000000000000000000000000000090048063c6888fa114602e57005b60376004356041565b8060005260206000f35b6000600782029050604d565b91905056',
  info: {
    language: 'Solidity',
    languageVersion: '0',
    compilerVersion: '0.9.13',
    abiDefinition: [{
      constant: false,
      inputs: [{
        name: 'a',
        type: 'uint256'
      } ],
      name: 'multiply',
      outputs: [{
        name: 'd',
        type: 'uint256'
      } ],
      type: 'function'
    } ],
    userDoc: {
      methods: {
      }
    },
    developerDoc: {
      methods: {
      }
    },
    source: 'contract test { function multiply(uint a) returns(uint d) { return a * 7; } }'
  }
}

$ gexp --datadir ~/exp/ --loglevel 6 --logtostderr=true --rpc --rpcport 8100 --rpccorsdomain '*' --mine console  2>> ~/exp/exp.log
$ curl -X POST --data '{"jsonrpc":"2.0","method":"exp_compileSolidity","params":["contract test { function multiply(uint a) returns(uint d) { return a * 7; } }"],"id":1}' http://127.0.0.1:8100

contracts = exp.compile.solidity(globalRegistrarSrc)

Create and deploy a contract¶

Before you begin this section, make sure you have both an unlocked account as well as some funds.

You will now create a contract on the blockchain by sending a transaction to the empty address with the EVM code from the previous section as data.

var primaryAddress = exp.accounts[0]
var abi = [{ constant: false, inputs: [{ name: 'a', type: 'uint256' } ]
var MyContract = exp.contract(abi)
var contract = MyContract.new(arg1, arg2, ..., {from: primaryAddress, data: evmByteCodeFromPreviousSection})

All binary data is serialised in hexadecimal form. Hex strings always have a hex prefix 0x.

It is worth pointing out that this step requires you to pay for execution. Your balance on the account (that you put as sender in the from field) will be reduced according to the gas rules of the EVM once your transaction makes it into a block. After some time, your transaction should appear included in a block confirming that the state it brought about is a consensus. Your contract now lives on the blockchain.

The asynchronous way of doing the same looks like this:

MyContract.new([arg1, arg2, ...,]{from: primaryAccount, data: evmCode}, function(err, contract) {
  if (!err && contract.address)
    console.log(contract.address);
});

Interacting with a contract¶

Interaction with a contract is typically done using an abstraction layer such as the exp.contract() function which returns a javascript object with all of the contract functions available as callable functions in javascript.

The standard way to describe the available functions of a contract is the ABI definition. This object is an array which describles the call signature and return values for each available contract function.

var Multiply7 = exp.contract(contract.info.abiDefinition);
var myMultiply7 = Multiply7.at(address);

Now all the function calls specified in the ABI are made available on the contract instance. You can just call those methods on the contract instance in one of two ways.

> myMultiply7.multiply.sendTransaction(3, {from: address})
"0x12345"
> myMultiply7.multiply.call(3)
21

When called using sendTransaction the function call is executed via sending a transaction. This will cost expanse to send and the call will be recorded forever on the blockchain. The return value of calls made in this manner is the hash of the stransaction.

When called using call the function is executed locally in the EVM and the return value of the function is returned with the function. Calls made in this manner are not recorded on the blockchain and thus, cannot modify the internal state of the contract. This manner of call is referred to as a constant function call. Calls made in this manner do not cost any expanse.

You should use call if you are interested only in the return value and use sendTransaction if you only care about side effects on the state of the contract.

In the example above, there are no side effects, therefore sendTransaction only burns gas and increases the entropy of the universe.

Contract metadata¶

In the previous sections we explained how you create a contract on the blockchain. Now we will deal with the rest of the compiler output, the contract metadata or contract info.

When interacting with a contract you did not create you might want documentation or to look at the source code. Contract authors are encouraged to make such information available by registering it on the blockchain or through a third party service, such as EtherChain. The admin API provides convenience methods to fetch this bundle for any contract that chose to register.

// get the contract info for contract address to do manual verification
var info = admin.getContractInfo(address) // lookup, fetch, decode
var source = info.source;
var abiDef = info.abiDefinition

The underlying mechanism that makes this work is is that:

• contract info is uploaded somewhere identifiable by a URI which is publicly accessible
• anyone can find out what the URI is only knowing the contracts address

These requirements are achieved using a 2 step blockchain registry. The first step registers the contract code (hash) with a content hash in a contract called HashReg. The second step registers a url with the content hash in the UrlHint contract. These registry contracts were part of the Frontier release and have carried on into Homestead.

By using this scheme, it is sufficient to know a contract’s address to look up the url and fetch the actual contract metadata info bundle.

So if you are a conscientious contract creator, the steps are the following:

1. Deploy the contract itself to the blockchain
2. Get the contract info json file.
3. Deploy contract info json file to any url of your choice
4. Register codehash ->content hash -> url

The JS API makes this process very easy by providing helpers. Call admin.register to extract info from the contract, write out its json serialisation in the given file, calculates the content hash of the file and finally registers this content hash to the contract’s code hash. Once you deployed that file to any url, you can use admin.registerUrl to register the url with your content hash on the blockchain as well. (Note that in case a fixed content addressed model is used as document store, the url-hint is no longer necessary.)

source = "contract test { function multiply(uint a) returns(uint d) { return a * 7; } }"
// compile with solc
contract = exp.compile.solidity(source).test
// create contract object
var MyContract = exp.contract(contract.info.abiDefinition)
// extracts info from contract, save the json serialisation in the given file,
contenthash = admin.saveInfo(contract.info, "~/dapps/shared/contracts/test/info.json")
// send off the contract to the blockchain
MyContract.new({from: primaryAccount, data: contract.code}, function(error, contract){
  if(!error && contract.address) {
    // calculates the content hash and registers it with the code hash in `HashReg`
    // it uses address to send the transaction.
    // returns the content hash that we use to register a url
    admin.register(primaryAccount, contract.address, contenthash)
    // here you deploy ~/dapps/shared/contracts/test/info.json to a url
    admin.registerUrl(primaryAccount, hash, url)
  }
});

Testing contracts and transactions¶

Often you need to resort to a low level strategy of testing and debugging contracts and transactions. This section introduces some debug tools and practices you can use. In order to test contracts and transactions without real-word consequences, you best test it on a private blockchain. This can be achieved with configuring an alternative network id (select a unique integer) and/or disable peers. It is recommended practice that for testing you use an alternative data directory and ports so that you never even accidentally clash with your live running node (assuming that runs using the defaults. Starting your gexp with in VM debug mode with profiling and highest logging verbosity level is recommended:

gexp --datadir ~/dapps/testing/00/ --port 30310 --rpcport 8110 --networkid 4567890 --nodiscover --maxpeers 0 --vmdebug --verbosity 6 --pprof --pprofport 6110 console 2>> ~/dapp/testint/00/00.log

Before you can submit any transactions, you need set up your private test chain. See Test Networks.

// create account. will prompt for password
personal.newAccount();
// name your primary account, will often use it
primary = exp.accounts[0];
// check your balance (denominated in expanse)
balance = web3.fromWei(exp.getBalance(primary), "expanse");

// assume an existing unlocked primary account
primary = exp.accounts[0];

// mine 10 blocks to generate expanse

// starting miner
miner.start(4);
// sleep for 10 blocks (this can take quite some time).
admin.sleepBlocks(10);
// then stop mining (just not to burn heat in vain)
miner.stop();
balance = web3.fromWei(exp.getBalance(primary), "expanse");

After you create transactions, you can force process them with the following lines:

miner.start(1);
admin.sleepBlocks(1);
miner.stop();

You can check your pending transactions with:

// shows transaction pool
txpool.status
// number of pending txs
exp.getBlockTransactionCount("pending");
// print all pending txs
exp.getBlock("pending", true).transactions

If you submitted contract creation transaction, you can check if the desired code actually got inserted in the current blockchain:

txhash = exp.sendTansaction({from:primary, data: code})
//... mining
contractaddress = exp.getTransactionReceipt(txhash);
exp.getCode(contractaddress)

RPC¶

In previous sections we have seen how contracts can be written, deployed and interacted with. Now it’s time to dive in the details of communicating with the Expanse network and smart contracts.

An Expanse node offers a RPC interface. This interface gives Ðapp’s access to the Expanse blockchain and functionality that the node provides, such as compiling smart contract code. It uses a subset of the JSON-RPC 2.0 specification (no support for notifications or named parameters) as serialisation protocol and is available over HTTP and IPC (unix domain sockets on linux/OSX and named pipe’s on Windows).

If you are not interested in the details but are looking for an easy to use javascript library you can skip the following sections and continue with Using Web3.

Conventions¶

The RPC interface uses a couple of conventions that are not part of the JSON-RPC 2.0 specification:

• Numbers are hex encoded. This decision was made because some languages have no or limited support for working with extremly large numbers. To prevent these type of errors numbers are hex encoded and it is up to the deverloper to parse these numbers and handle them appropriately. See the hex encoding section on the wiki for examples.
• Default block number, several RPC methods accept a block number. In some cases it’s not possible to give a block number or not very convenient. For these cases the default block number can be one of these strings [“earliest”, “latest”, “pending”]. See the wiki page for a list of RPC methods that use the default block parameters.

Deploy contract¶

We will go through the different steps to deploy the following contract using only the RPC interface.

contract Multiply7 {
   event Print(uint);
   function multiply(uint input) returns (uint) {
      Print(input * 7);
      return input * 7;
   }
}

The first thing to do is make sure the HTTP RPC interface is enabled. This means for gexp we supply the --rpc flag on startup and for exp the -j flag. In this example we use the gexp node on a private development chain. Using this approach we don’t need expanse on the real network.

> gexp --rpc --dev --mine --minerthreads 1 --unlock 0 console 2>>gexp.log

This will start the HTTP RPC interface on http://localhost:8545.

We can verify that the interface is running by retrieving the coinbase address and balance using curl. Please note that data in these examples will differ on your local node. If you want to try these command replace the request params accordingly.

> curl --data '{"jsonrpc":"2.0","method":"exp_coinbase", "id":1}' localhost:8545
{"id":1,"jsonrpc":"2.0","result":["0xeb85a5557e5bdc18ee1934a89d8bb402398ee26a"]}

> curl --data '{"jsonrpc":"2.0","method":"exp_getBalance", "params": ["0xeb85a5557e5bdc18ee1934a89d8bb402398ee26a"], "id":2}' localhost:8545
{"id":2,"jsonrpc":"2.0","result":"0x1639e49bba16280000"}

Remember when we said that numbers are hex encoded? In this case the balance is returned in Wei as a hex string. If we want to have the balance in Expanse as a number we can use web3 from the gexp console.

> web3.fromWei("0x1639e49bba16280000", "expanse")
"410"

Now that we have some expanse on our private development chain we can deploy the contract. The first step is to verify that the solidity compiler is available. We can retrieve available compilers using the exp_getCompilers RPC method.

> curl --data '{"jsonrpc":"2.0","method": "exp_getCompilers", "id": 3}' localhost:8545
{"id":3,"jsonrpc":"2.0","result":["Solidity"]}

We can see that the solidity compiler is available. If it’s not available follow these instructions.

The next step is to compile the Multiply7 contract to byte code that can be send to the EVM.

> curl --data '{"jsonrpc":"2.0","method": "exp_compileSolidity", "params": ["contract Multiply7 { event Print(uint); function multiply(uint input) returns (uint) { Print(input * 7); return input * 7; } }"], "id": 4}' localhost:8545
{"id":4,"jsonrpc":"2.0","result":{"Multiply7":{"code":"0x6060604052605f8060106000396000f3606060405260e060020a6000350463c6888fa18114601a575b005b60586004356007810260609081526000907f24abdb5865df5079dcc5ac590ff6f01d5c16edbc5fab4e195d9febd1114503da90602090a15060070290565b5060206060f3","info":{"source":"contract Multiply7 { event Print(uint); function multiply(uint input) returns (uint) { Print(input * 7); return input * 7; } }","language":"Solidity","languageVersion":"0.2.2","compilerVersion":"0.2.2","compilerOptions":"--bin --abi --userdoc --devdoc --add-std --optimize -o /tmp/solc205309041","abiDefinition":[{"constant":false,"inputs":[{"name":"input","type":"uint256"}],"name":"multiply","outputs":[{"name":"","type":"uint256"}],"type":"function"},{"anonymous":false,"inputs":[{"indexed":false,"name":"","type":"uint256"}],"name":"Print","type":"event"}],"userDoc":{"methods":{}},"developerDoc":{"methods":{}}}}}}

Now that we have the compiled code we need to determine how much gas it costs to deploy it. The RPC interface has an exp_estimateGas method that will give us an estimate.

> curl --data '{"jsonrpc":"2.0","method": "exp_estimateGas", "params": [{"from": "0xeb85a5557e5bdc18ee1934a89d8bb402398ee26a", "data": "0x6060604052605f8060106000396000f3606060405260e060020a6000350463c6888fa18114601a575b005b60586004356007810260609081526000907f24abdb5865df5079dcc5ac590ff6f01d5c16edbc5fab4e195d9febd1114503da90602090a15060070290565b5060206060f3"}], "id": 5}' localhost:8545
{"id":5,"jsonrpc":"2.0","result":"0xb8a9"}

And finally deploy the contract.

> curl --data '{"jsonrpc":"2.0","method": "exp_sendTransaction", "params": [{"from": "0xeb85a5557e5bdc18ee1934a89d8bb402398ee26a", "gas": "0xb8a9", "data": "0x6060604052605f8060106000396000f3606060405260e060020a6000350463c6888fa18114601a575b005b60586004356007810260609081526000907f24abdb5865df5079dcc5ac590ff6f01d5c16edbc5fab4e195d9febd1114503da90602090a15060070290565b5060206060f3"}], "id": 6}' localhost:8545
{"id":6,"jsonrpc":"2.0","result":"0x3a90b5face52c4c5f30d507ccf51b0209ca628c6824d0532bcd6283df7c08a7c"}

The transaction is accepted by the node and a transaction hash is returned. We can use this hash to track the transaction.

The next step is to determine the address where our contract is deployed. Each executed transaction will create a receipt. This receipt contains various information about the transaction such as in which block the transaction was included and how much gas was used by the EVM. If a transaction creates a contract it will also contain the contract address. We can retrieve the receipt with the exp_getTransactionReceipt RPC method.

> curl --data '{"jsonrpc":"2.0","method": "exp_getTransactionReceipt", "params": ["0x3a90b5face52c4c5f30d507ccf51b0209ca628c6824d0532bcd6283df7c08a7c"], "id": 7}' localhost:8545
{"id":7,"jsonrpc":"2.0","result":{"transactionHash":"0x3a90b5face52c4c5f30d507ccf51b0209ca628c6824d0532bcd6283df7c08a7c","transactionIndex":"0x0","blockNumber":"0x4c","blockHash":"0xe286656e478a1b99030e318d0f5c3a61a644f25e63deaa8be52e80da1e7b0c47","cumulativeGasUsed":"0xb8a9","gasUsed":"0xb8a9","contractAddress":"0x6ff93b4b46b41c0c3c9baee01c255d3b4675963d","logs":[]}}

We can see that our contract was created on 0x6ff93b4b46b41c0c3c9baee01c255d3b4675963d. If you got null instead of a receipt the transaction has not been included in a block yet. Wait for a moment and check if your miner is running and retry it.

Interacting with smart contracts¶

Now that our contract is deployed we can interact with it. There are 2 methods for this, sending a transaction or using call as previously explained. In this example we will be sending a transaction to the multiply method of the contract.

If we look at the documentation for the exp_sendTransaction we can see that we need to supply several arguments. In our case we need to specify the from, to and data arguments. From is the public address of our account and to the contract address. The data argument is a bit harder. It contains a payload that defines which method must be called and with which arguments. This is were the ABI comes into play. The ABI defines how to define and encode data for the EVM. You can read all the details about the ABI here.

The bytes of the payload is the function selector and defines which method is called. This is done by taking the first 4 bytes from the Keccak hash over the function name and its argument types and hex encode it. The multiply function accepts an uint which is an alias for uint256. This leaves us with:

> web3.sha3("multiply(uint256)").substring(0, 8)
"c6888fa1"

See for details this page.

The next step is to encode the arguments. We only have one uint256, lets assume we supply the value 6. The ABI has a section which specifies how to encode uint256 types.

int<M>: enc(X) is the big-endian two’s complement encoding of X, padded on the higher-oder (left) side with 0xff for negative X and with zero bytes for positive X such that the length is a multiple of 32 bytes.

This encodes to 0000000000000000000000000000000000000000000000000000000000000006.

Combining the function selector and the encoded argument our data will be 0xc6888fa10000000000000000000000000000000000000000000000000000000000000006.

Lets try it:

> curl --data '{"jsonrpc":"2.0","method": "exp_sendTransaction", "params": [{"from": "0xeb85a5557e5bdc18ee1934a89d8bb402398ee26a", "to": "0x6ff93b4b46b41c0c3c9baee01c255d3b4675963d", "data": "0xc6888fa10000000000000000000000000000000000000000000000000000000000000006"}], "id": 8}' localhost:8545
{"id":8,"jsonrpc":"2.0","result":"0x759cf065cbc22e9d779748dc53763854e5376eea07409e590c990eafc0869d74"}

Since we sent a transaction we got the transaction hash returned. If we retrieve the receipt we can see something new:

{
   blockHash: "0xbf0a347307b8c63dd8c1d3d7cbdc0b463e6e7c9bf0a35be40393588242f01d55",
   blockNumber: 268,
   contractAddress: null,
   cumulativeGasUsed: 22631,
   gasUsed: 22631,
   logs: [{
      address: "0x6ff93b4b46b41c0c3c9baee01c255d3b4675963d",
      blockHash: "0xbf0a347307b8c63dd8c1d3d7cbdc0b463e6e7c9bf0a35be40393588242f01d55",
      blockNumber: 268,
      data: "0x000000000000000000000000000000000000000000000000000000000000002a",
      logIndex: 0,
      topics: ["0x24abdb5865df5079dcc5ac590ff6f01d5c16edbc5fab4e195d9febd1114503da"],
      transactionHash: "0x759cf065cbc22e9d779748dc53763854e5376eea07409e590c990eafc0869d74",
      transactionIndex: 0
  }],
  transactionHash: "0x759cf065cbc22e9d779748dc53763854e5376eea07409e590c990eafc0869d74",
  transactionIndex: 0
}

The receipt contains a log. This log was generated by the EVM on transaction execution and included in the receipt. If we look at the multipy function we can see that the Print event was raised with the input times 7. Since the argument for the Print event was a uint256 we can decode it according to the ABI rules which will leave us with the expected decimal 42. Apart from the data it is worth noting that topics can be used to determine which event created the log:

> web3.sha3("Print(uint256)")
"24abdb5865df5079dcc5ac590ff6f01d5c16edbc5fab4e195d9febd1114503da"

You can read more about events, topics and indexing in the Solidity tutorial.

This was just a brief introduction into some of the most common tasks. See for a full list of available RPC methods the RPC wiki page.

Web3.js¶

As we have seen in the previous example using the JSON-RPC interface can be quite tedious and error-prone, especially when we have to deal with the ABI. Web3.js is a javascript library that works on top of the Expanse RPC interface. Its goal is to provide a more user friendly interface and reducing the chance for errors.

Deploying the Multiply7 contract using web3 would look like:

var source = 'contract Multiply7 { event Print(uint); function multiply(uint input) returns (uint) { Print(input * 7); return input * 7; } }';
var compiled = web3.exp.compile.solidity(source);
var code = compiled.Multiply7.code;
var abi = compiled.Multiply7.info.abiDefinition;

web3.exp.contract(abi).new({from: "0xeb85a5557e5bdc18ee1934a89d8bb402398ee26a", data: code}, function (err, contract) {
   if (!err && contract.address)
      console.log("deployed on:", contract.address);
   }
);

deployed on: 0x0ab60714033847ad7f0677cc7514db48313976e2

Load a deployed contract and send a transaction:

var source = 'contract Multiply7 { event Print(uint); function multiply(uint input) returns (uint) { Print(input * 7); return input * 7; } }';
var compiled = web3.exp.compile.solidity(source);
var Multiply7 = web3.exp.contract(compiled.Multiply7.info.abiDefinition);
var multi = Multiply7.at("0x0ab60714033847ad7f0677cc7514db48313976e2")
multi.multiply.sendTransaction(6, {from: "0xeb85a5557e5bdc18ee1934a89d8bb402398ee26a"})

Register a callback which is called when the Print event created a log.

multi.Print(function(err, data) { console.log(JSON.stringify(data)) })
{"address":"0x0ab60714033847ad7f0677cc7514db48313976e2","args": {"":"21"},"blockHash":"0x259c7dc07c99eed9dd884dcaf3e00a81b2a1c83df2d9855ce14c464b59f0c8b3","blockNumber":539,"event":"Print","logIndex":0, "transactionHash":"0x5c115aaa5418118457e96d3c44a3b66fe9f2bead630d79455d0ecd832dc88d48","transactionIndex":0}

See for more information the web3.js wiki page.

Console¶

The gexp console offers a command line interface with a javascript runtime. It can connect to a local or remote gexp or exp node. It will load the web3.js library that users can use. This allows users to deploy and interact with smart contract from the console using web3.js. In fact the examples in the Web3.js section can by copied into the console.

Viewing Contracts and Transactions¶

There are several online blockchain explorers available that will allow you to inspect the Expanse blockchain. See for a list: Blockchain explorers.

Dapp directories¶

Dapps that use Expanse are compiled to the following lists. They are listed in various stages of development (concept, working prototype, live/deployed). If you are developing a dapp, consider adding an entry to these listings:

• Ethercasts State of the Ðapps
• Dappslist
• Dappcentral - Sortable pages for Dapps with instructions, code validation, and network stats.
• Dapps Mailing List - Mailing list for developers on Expanse (discontinued).

The offered decentralised services listed cover a wide range of areas including finance, insurance, prediction markets, social networks, distributed computation and storage, gambling, marketplace, internet of things, governance, collaboration, development and games.

• What apps can we eventually expect? https://www.reddit.com/r/expanse/comments/2mnl7f/the_top_10_ether_dapps_of_2015/cm63nsf

In the future, dapps are likely to be listed and distributed in dappstores integrated in dapp browsers.

Dapp browsers¶

• Mist - official GUI dapp browser developed by the foundation, alpha stage. Mist as Wallet dapp is in beta.
• Syng - Mobile Expanse browser (alpha) by Jarrad Hope - supported by DEVgrants
• MetaMask - Aaron Kumavis Davis’s in-browser GUI. Epicenter Bitcoin interview on github - supported by DEVgrants
• AlethZero - C++ exp client GUI, (discontinued).
• Supernova - (discontinued).

Dapp development resources¶

• Smart contracts ELI5
• https://blog.slock.it/a-primer-to-the-decentralized-autonomous-organization-dao-69fb125bd3cd
• A 101 noob’s intro to programming smart contracts
• Standardised contract APIs listing

Mix-IDE¶

Mix is the official Expanse IDE that allows developers to build and deploy contracts and decentralized applications on top of the Expanse blockchain. It includes a Solidity source code debugger. Mix

IDEs/Frameworks¶

Below are developer frameworks and IDEs used for writing Expanse dapps.

• Truffle - Truffle is a development environment, testing framework and asset pipeline for Expanse.
• Dapple - Dapple is a tool for Solidity developers to help build and manage complex contract systems on Expanse-like blockchains.
• Populus - Populus is a Smart Contract development framework written in python.
• Eris-PM - The Eris Package Manager deploys and tests smart contract systems on private and public chains.
• Embark - Embark is a Ðapp development framework written in JavaScript.
• EtherScripter (obsolete, discontinued)
• Resilience Raw Transaction Broadcaster

Expanse-console¶

Commandline console for Expanse nodes.

Ethconsole connects to an Expanse node running in the background (tested with exp and gexp) via IPC and provides an interactive javascript console containing the web3 object with admin additions.

Here you could find a list of available commands expanse node control commands

To use this console you would need to start a local expanse node with ipc communication socket enabled (file gexp.ipc in data directory). By default ipc socket should be located at you local home directory in .expanse after you started a node. You could also set --test option to use specific node test commands.

In the console you could then type

Here the defenition of --test mode node commands:

More information about node configuration file.

Base layer services¶

The EVM¶

The Expanse Virtual Machine (EVM) is the runtime environment for smart contracts in Expanse. It is not only sandboxed, but actually completely isolated, which means that code running inside the EVM has no access to network, filesystem, or other processes. Smart contracts even have limited access to other smart contracts.

Contracts live on the blockchain in an Expanse-specific binary format (EVM bytecode). However, contracts are typically written in an Expanse high level language, compiled into byte code using an EVM compiler, and finally uploaded on the blockchain using an Expanse client.

Swarm - Decentralised data storage and distribution¶

Swarm is a peer to peer data sharing network in which files are addressed by the hash of their content. Similar to Bittorrent, it is possible to fetch the data from many nodes at once and as long as a single node hosts a piece of data, it will remain accessible everywhere. This approach makes it possible to distribute data without having to host any kind of server - data accessibility is location independent.

Other nodes in the network can be incentivised to replicate and store the data themselves, obviating the need for hosting services when the original nodes are not connected to the network.

Whisper - Decentralised messaging¶

A protocol for private, secure communication directly between nodes.

Furthermore, standard contracts are being created to make the development and usage of distributed applications easier:

Name registry¶

Because dapps can be stored anywhere, including the Swarm network, the name registry maps names to their content or location. This is a decentralised alternative to the Domain Name System (DNS).

See https://github.com/expanse-org/EIPs/issues/26

Contract registry¶

To publish the source code of a specific contract, its address has to be mapped to it. The contract registry stores this mapping. Users can then look up this mapping and verify the contract byte code.

See * global registrar code * namereg API