Pharo Ethereum Driver
# Fog
Pharo Ethereum Driver
Fog is a library that allows the user to connect to an ethereum based blockchain data base.
Is based on the Javascript canonical implementation done by Ethereum community [Ethereum Javascript API](https://github.com/ethereum/wiki/wiki/JavaScript-API).
## Dependencies
Before going further, for avoiding any kind of frustration, let's be clear with the dependencies.
### Geth (or equivalent)
you will have to have an Ethereum node running or at least accessible for being able to use fog. No endpoint, no fun.
Once you installed, as explained in the github site (https://github.com/ethereum/go-ethereum/wiki/Installing-Geth)
Ensure that you run your node exposing the minimal needed services
```
geth --rpcapi eth,web3,net,admin
```
And if you are wondering how to run a node only for testing, maybe you want to execute something like
```
geth --nodiscover --mine --minerthreads 1 --maxpeers 0 --verbosity 3 --unlock "0" --rpcapi eth,web3,net,admin --rpc --testnet
```
Finally if you don't want to deal with the creation of the accounts, passwords, etc. Then you may want to check what is happening in this [folder](./scripts/dev.sh) of this project.
### Solidity
```
npm install solc
```
## Download code
### Iceberg / Baseline
```
Metacello
new
baseline: 'Fog';
repository: 'github://smartanvil/Fog/src';
load.
```
### By hand
You may want to use this version for having access to some scripts and contracts samples.
```
git checkout git@github.com:smartanvil/Fog.git
```
```
Metacello
new
baseline: 'Fog';
repository: 'filetree:///path/to/git-repository/Fog/src';;
load.
```
### Session & Connection
Your best friends as a newcomer in Fog are the connection and the session.
To get new connections with fog is pretty cheap just execute
```
FogConnection on: 'http://localhost:8545'.
```
And you will have a almost free connection. (No services, no major object instantiation, etc).
A FogConnection instance, as we can see in the extended [documentation](./FogComm.md) of the library, allows us already to do many things.
But the main idea of the split in between Connection and Session is to be able to provide different flavours of connections, decoupling the domain objects from the data endpoint.
For using then Fog as we want it, we have to create a session.
To do so, is as easy as:
```
session := FogConnection createDefaultConnection session.
```
or, for non cached session flavour:
```
session := FogConnection createDefaultConnection nonCachedSession.
```
Session are a bit more expensive than connections, specially the default or cached session, which caches any object asked to the connection for faster later access.
The session is always distributed with a side service (provided by TaskIt - https://github.com/sbragagnolo/taskit), with the mission of allowing polling to the connection and permanent syncing.
The session will be then, your favourite entry point in Fog. And you can see the [extended documentation here](./FogLive.md).
### Create an account
For interacting with contracts you will need to have an account. For the database side you may want to check out the documentation [Account management](http://ethdocs.org/en/latest/account-management.html).
By the side of Pharo you will need to create an account object with it related hash ID.
```smalltalk
account := FogExternalAccount new
hash: self ownerAccountAddress ;
name: 'My Account';
yourself
```
After this, you will have to set it up in the session or not, depending the kind of usage you want to do. But we kind of generally recommend to do it
```smalltalk
session applicationAccount: account.
```
In case of testing, the account that you create for mining, is a good account to use. It will always have enough ether for using
### Fetching a block, and inspecting from the block
The block is the time related abstraction in blockchain systems. [Glossary - Block](http://ethdocs.org/en/latest/glossary.html?highlight=block) Inside of it, we can find a father, the included transactions, and the timestamp, inbetween other less remarkable pieces of information.
```
block := session findBlockByTag: #latest full: true.
```
This piece of code gives us the last processed block.
We can use this block as entry point for navigating to the previous blocks by asking for the parent block
```
block := block parent
```
As well in ethereum we have the concept of uncle blocks, for blocks that were processed at the same time as the parent block [Glossary - Uncle](http://ethdocs.org/en/latest/glossary.html?highlight=uncle)
```
uncles := block uncles.
```
Finally, from the block object, we can also navigate to transaction objects [Glossary - Transaction](http://ethdocs.org/en/latest/glossary.html?highlight=transaction).
```
transactions := block transactions.
```
### Fetching a transaction and inspecting from the transaction
A transaction is an change operated into the blockchain distributed ledger. It is included inside a block. It relates accounts with modifications. This modifications may be money transference or code execution.
For accessing a transaction, you can do it from the block, as we saw in the 'From the block' navigation part. But we also can fetch an specific transaction, pointing it by hash
```
transaction := session findTransactionByHash: 'hash'.
```
From a transaction we can access to the owning block
```
ownerBlock := transaction block.
```
And also to the related accounts
```
to := transaction to.
from := transaction from.
```
This accounts may be [external or internal accounts](http://ethdocs.org/en/latest/glossary.html?highlight=account)
### Fetching a deployed contract
Finally, deployed contracts have a particular interest, since is one of the most important functionalities of the Ethereum flavor.
```
instance := session findContractInstanceByHash:'0x2f5d196660eaead329194347e513d486d11984fa' blockNumber: 6814584
```
This code will bring the contract instance binded to the state it had at the given block number. As well you can use tags instead of numbers
```
instance := session findContractInstanceByHash:'0x2f5d196660eaead329194347e513d486d11984fa' blockTag: 'latest'
```
If the contract source code was loaded as a known contract (check in the configuration section), the contract instance will be browsable with GTTools, and it will provide a mirror for interacting with it (check the contract section)
## Navigating the database
The Ethereum database plays with the abstractions of:
* Block
* Transaction
* Accounts
- Real accounts
- Deployed contract instances
The library gives us access to all this information as reifyied objects. Each of these objects has a GTTool inspection extension, focusing on the navigability and in the main data of each object.
So do not hesitate in inspecting the different objects that you may bring from your session.
## Contracts
Finally we have the contracts. Contracts are probably the reason for using Ethereum.
A deployed contract, in the end, is like a deployed object that is interacted by sending messages, that are executed in transactional fashion, or function, depending on if they do or do not state changes.
So far our implementation does not have a real reification of the contract instance, since it should be based on a session concept, that we do not have yet. Then the current proposed usage is based on the generated reflective system.
### Loading a package of contracts
In ethererum there is not notion of package as it is, but there is a notion of files. In a file we can define as much contracts as we want. Then we choose to forget about the files, and talk about this unit of distribution as package.
A session is able to load a package. This package, regardless if it is or not a cached session, will be accessible by name after by querying the session.
A package is able to tell it AST, and it points to a set of contract descriptions that are defined on it.
For loading a package just execute.
```smalltalk
package := session
loadPackageForFileReference: 'provide/here/a/solidity/filename' asFileReference
```
After, for getting a contract description execute
```
contractDescription := package descriptions anyone.
" Or "
contractDescription := session findReference: (FogReference new / #filename / #contractName ).
```
### The contract description
After loading a package, and accessing to a contract description, feel free to inspect it. This object is the Meta type reyfication of a contract. We will use it for mostly every exchange with a deployed contract.
The contract description understands many messages, extensively covered in the [documentation](./FogLive.md). Here we will only remark the most useful, in terms of the cycle of usage.
A contract description understands #mirror and #contract.
The method #mirror will build and return a mirror for the contract type, that will allow us to do metaprogramming.
```
contractMirror := contractDescription mirror.
contractInstanceMirror := contractMirror instanceMirror.
```
The method #contract will generate a proxy, that leveraging the mirror, will encapsulate the metaprogramming capabilities for emulating a regular object.
```
contractProxyGeneratedClass := contractDescription contract.
```
### The contract proxy
The generated contract proxy, by using the Proxybuilder defined in the FogLive project ( not yet documented, since it may change in the near future ), will be a subclass of
#FogContractProxy.
This class will use a Trait also generated by the builder that will implement all the m