Skip to content

Commit

Permalink
First fixing round
Browse files Browse the repository at this point in the history
  • Loading branch information
@anegg0
anegg0 committed Dec 18, 2019
1 parent f15a64e commit 036e3ec
Show file tree
Hide file tree
Showing 8 changed files with 95 additions and 102 deletions.
26 changes: 2 additions & 24 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,33 +2,11 @@
Nethereum documentation

## Contributing guidelines
1. One pull request per document at a time, this way they can be reviewed and edited for corrections.
2. Any code sample, interaction, should be created as a workbook.
3. Any general introduction and when workbooks do not make any sense obviously NOT, for example Azure BaaS interaction, Code generation, Service structure, Getting started with Unity3d, BUT ideally the aim is to have everything in Worbooks and unit tested.

## Workbooks contribution
1. Any modificactions should be pushed on the Nethereum.Workbooks repository
2. Any new workbooks need to have a unit test associated with it, or changes unit tested before hand.
For an introduction on unit testing workbooks [Check this blog post](https://medium.com/@juanfranblanco/unit-or-integration-tests-of-xamarin-workbooks-6f206b8483d6)
3. All the workbooks need to be in the same folder and indexed in the index.md file. See previous entry on how to format links.

## Workbooks submodule update
1. To update the workbooks submodule run ```git submodule update --rebase --remote```
One pull request per document at a time, this way they can be reviewed and edited for corrections.

## Setting up a local environment
To visualise the docs in context and to see how they'll look when published, you'll need a local environment. This will involve a process to build (aka serve) the documents locally and view them via a browser. These are rough and ready instructions to set up a local mkdocs environment. The instructions were tested against a Windows 10 PC. Previous versions of mkdocs and related extensions were removed first.

**These steps are ONLY intended to allow you to view the documents - it excludes setup necessary to build and run workbooks. The install commands may require administrative priveleges.**

Tested against:
* Windows 10
* Python 3.7.4 (``` python --version ```)
* mkdocs-material 4.4.2 (``` pip show mkdocs-material ```)
* mkdocs 1.0.4 (``` pip show mkdocs ```)
* markdown 3.1.1 (``` pip show markdown ```)
* markdown-include 0.5.1 (``` pip show markdown-include ```)
* Firefox 69.0

### Prerequisites
**Python must be installed first**. Preferably 3.7.4, other version may work but are untested.

Expand All @@ -42,4 +20,4 @@ Mkdocs and theme setup (installs markdown and mkdocs)
Running Mkdocs
1. in a console, navigate to the Nethereum.Docs directory
2. ``` mkdocs serve ```
4. open http://127.0.0.1:8000 in your browser
4. open http://127.0.0.1:8000 in your browser
29 changes: 15 additions & 14 deletions docs/contracts/calling-transactions-events.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,12 @@ The previous guide covered how to deploy and call a contract, this guide will de

## Videos

This hands on demo covers the steps provided in this guide for calls, transactions, events, filters and topics
This hands-on demo covers the steps provided in this guide for calls, transactions, events, filters and topics

[![Introduction to Calls, Transactions, Events, Filters and Topics](http://img.youtube.com/vi/Yir_nu5mmw8/0.jpg)](https://www.youtube.com/watch?v=Yir_nu5mmw8 "Introduction to Calls, Transactions, Events, Filters and Topics")

## The test contract

The following smart contract is an updated version of the "multiply" contract from the previous guide:

```javascript
Expand All @@ -28,11 +29,11 @@ contract test {
}
}
```
The smart contract now includes an Event
"Multiplied". The event will store on the log the original parameter for multiplication "a", the address of the "sender" and the "result" of the multiplication.
The smart contract now includes an Event called "Multiplied". The event will store on the log the original parameter for multiplication "a", the address of the "sender" and the "result" of the multiplication.
The parameter "a" and the "sender" address are both indexed so we can create specific filters for those two values using topics.

## Deploying the contract

As per the previous guide, we can deploy the contract as follows:

```csharp
Expand All @@ -57,7 +58,7 @@ As per the previous guide, we can deploy the contract as follows:

## The multiply transaction

When performing a call we are either retrieving data which is stored in the smart contract state or we are performing an action (i.e multiplication), calls are not transactions which are verified through the blockchain consensus.
When performing a call, we are either retrieving data which is stored in the smart contract state or we are performing an action (i.e multiplication), calls are not transactions which are verified through the blockchain consensus.

Submitting a transaction to perform a function operation in a smart contract does not return the result of the operation, events can be used to retrieve information or we can inspect the state of the smart contract by using function calls.

Expand All @@ -80,7 +81,7 @@ The function object simplifies submitting transactions in the same way as calls.

There is also the option to specify the gas or include an Ether value as part of the transaction.

On the example we have submitted 2 transactions to perform a multiplication for 7 and 8 respectively, and wait for the transaction to be mined on our private test chain.
On the example, we have submitted 2 transactions to perform a multiplication for 7 and 8 respectively, and are waiting for the transaction to be mined on our private test chain.

## Events, filters and topics

Expand All @@ -92,7 +93,7 @@ Events are defined as part of the abi, and similarly to the functions we can get
var multiplyEvent = contract.GetEvent("Multiplied");
```

The event object allows to create filters to retrieve the information stored on the log.
The event object allows to create filters in order to retrieve the information stored on the log.

We can create filters that retrieve all the event logs

Expand All @@ -106,9 +107,9 @@ Or for an specific topic
var filter7 = await multiplyEvent.CreateFilterAsync(7);
```

In the example above we are retrieving the logs which multiply parameter is 7, because the input parameter for the multiplication is marked as indexed, we can filter for that topic.
In the example above we are retrieving the logs in which the multiply parameter is 7, because the input parameter for the multiplication is marked as indexed, we can filter for that topic.

In a similar way we can filter for the sender address as it is also marked as indexed, but if we wanted to filter for that specific topic we will use the the second parameter when creating the filter.
In a similar way, we can filter the sender address as it is also marked as indexed, but if we wanted to filter for that specific topic we will use the second parameter when creating the filter.

```csharp
var filterSender = await multiplyEvent.CreateFilterAsync(null, senderAddress);
Expand All @@ -132,12 +133,12 @@ Event data transfer objects allows to simply decode all the event parameters int
}

```
In the example above the MultipliedEvent properties have been "mapped" with custom parameter attributes to the event parameters. Each parameter specifies the original type, name, order and if is indexed or not.
As we can see types like address are decoded into strings and in our scenario we are safe to decode int256 to int32 but if not known the final type BigInteger would have been a better option.
In the example above, the MultipliedEvent properties have been "mapped" with custom parameter attributes to the event parameters. Each parameter specifies the original type, name, order and if is indexed or not.
As we can see, types like address are decoded into strings and in our scenario we are safe to decode `int256` to `int32` but if not known, the final type `BigInteger` would have been a better option.

### Retrieving the events and logs

Using the filters we have already created we can retrieve the logs and events.
Using the filters we have already created, we can retrieve the logs and events.

```csharp

Expand All @@ -146,12 +147,12 @@ Using the filters we have already created we can retrieve the logs and events.

```

Above we are using GetFilterChanges, this can be used to retrieve any logs that match our criteria since the filter was created or since the last time we tried to get the changes.
Other option would have been to use GetAllChanges using the FilterInput.
Above we are using `GetFilterChanges`, which can be used to retrieve any logs that matches our criteria since the filter was created or since the last time we tried to retrieve the changes.
Other option would have been to use `GetAllChanges` using the `FilterInput`.

### The final code

All the source code can be found under CallTransactionEvents in the [Tutorials solution](https://github.com/Nethereum/Nethereum/tree/master/src/Nethereum.Tutorials)
All the source code can be found under `CallTransactionEvents` in the [Tutorials solution](https://github.com/Nethereum/Nethereum/tree/master/src/Nethereum.Tutorials)

```csharp
public async Task ShouldBeAbleCallAndReadEventLogs()
Expand Down
46 changes: 25 additions & 21 deletions docs/contracts/deploying.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,20 +5,21 @@ The first step to be able to interact with any contract is to deploy it to the E

## Videos

These are two videos that can take you through all the steps, one in the classic windows, visual studio environment and another in a cross platform Mac and Visual Studio code.
These are two videos taking you through all the steps, one in the classic windows: visual studio environment and another in a cross platform Mac and Visual Studio code.

### Windows, Visual Studio, .Net 451 Video
This video takes you through the steps of creating a smart contract, compile it, start a private chain and deploy it using Nethereum.
This video takes you through the steps of creating a smart contract, compiling it, starting a private chain and deploying it using Nethereum.

[![Smart contracts, private test chain and deployment to Ethereum with Nethereum](http://img.youtube.com/vi/4t5Z3eX59k4/0.jpg)](http://www.youtube.com/watch?v=4t5Z3eX59k4 "Smart contracts, private test chain and deployment to Ethereum with Nethereum")

### Cross platform, Visual Studio Code, .Net core Video

If you want to develop in a cross platform environment this video takes you through same steps but in a Mac using Visual Studio Code and .Net Core.
If you want to develop in a cross platform environment, this video takes you through same steps but in a Mac using Visual Studio Code and .Net Core.

[![Cross platform development in Ethereum using .Net Core and VsCode and Nethereum](http://img.youtube.com/vi/M1qKcJyQcMY/0.jpg)](http://www.youtube.com/watch?v=M1qKcJyQcMY "Cross platform development in Ethereum using .Net Core and VsCode and Nethereum")

## The test contract

This is a very simple example of a solidity contract:

```javascript
Expand All @@ -36,19 +37,19 @@ This is a very simple example of a solidity contract:
}
```

The contract named "test" has a constructor named after the contract (class) and a function multiply.
The function multiply returns the result of the multiplication of a parameter "a" by the value of the "multiplier" provider at time of deployment to the constructor.
The contract has been named "test", it has a constructor named after the contract (class) and a function "multiply".
The function "multiply" returns the result of the multiplication of a parameter "a" by the value of the "multiplier" provider at time of deployment to the constructor.

## Contract compilation, the Bytecode and the ABI
Before a contract can be deployed it needs to be compiled. Let's quickly see how to do this with Visual Studio Code
Before a contract can be deployed, it needs to be compiled. Let's quickly see how to do this with Visual Studio Code

### Visual Studio Code

1. Open Visual Studio Code
2. Copy the contract test into a new file and save it as "test.sol", you will need to have opened a folder as your workspace.
3. If you don't have the Solidity extension press F1 or Shift+Command+P on a mac and type "ext", then search for "solidity" and install it.
4. Now that is installed you can press F1 again type "compile" and select the option to "Compile current contract"
5. Your abi and bytecode files can be found now in your bin folder.
5. Your ABI and bytecode files can be found now in your bin folder.

![VsCode solidity compilation](https://raw.githubusercontent.com/Nethereum/Nethereum/master/docs/screenshots/vscode.png)

Expand All @@ -70,33 +71,35 @@ To unlock an account you will need to pass the address, password and the duratio
```

### The deployment transaction

After unlocking your account you are ready to create the transaction to deploy it.

To create a deployment transaction you will use web3.Eth.DeployContract, using the abi (as we are having a constructor), the byte code, and any parameters to the constructor
To create a deployment transaction, you will use `web3.Eth.DeployContract`, using the ABI (as we are having a constructor), the byte code, and any parameters to the constructor

```csharp
var transactionHash =
await web3.Eth.DeployContract.SendRequestAsync(abi, byteCode, senderAddress, multiplier);
await web3.Eth.DeployContract.SendRequestAsync(ABI, byteCode, senderAddress, multiplier);
```

Deploying a transaction will return a transactionHash which will be using later on to retrieve the transaction receipt.
Deploying a transaction will return a transactionHash which will be used later on to retrieve the transaction receipt.

### Start mining

The transaction that has deployed the contract needs to be verified by the network, if we are running a private chain with a single node we will need to mine the transaction.
The transaction that has deployed the contract needs to be verified by the network. If we are running a private chain with a single node, we will need to mine the transaction.

PS: Nethereum offers a quick and easy way to start your local test , just execute startgeth.bat (for Windows) or startgeth.sh (for Mac and Linux) at: https://github.com/Nethereum/Nethereum.Workbooks/tree/master/testchain/clique
PS: Nethereum offers a quick and easy way to start your local test , just execute startgeth.bat (for Windows) or startgeth.sh (for Mac and Linux) at: https://github.com/Nethereum/TestChains

Start the chain using startgeth.bat (Windows) or startgeth.sh (Mac/Linux). The chain is setup with the Proof of Authority consensus and will start the mining process inmediatly.
Start the chain using startgeth.bat (Windows) or startgeth.sh (Mac/Linux). The chain is setup with the Proof of Authority consensus and will start the mining process immediately.

```csharp
var mineResult = await web3.Miner.Start.SendRequestAsync(6);
```

### The transaction receipt

Once we have started mining (or we know that are miners in the network) we can can attempt to retrieve the transaction receipt, we will need this as it contains our contract address.

The transaction might have not be mined yet, so when attempting to get the receipt it might return a null value, in this scenario we will continue trying until we get a not null result.
The transaction might have not be mined yet, so when attempting to get the receipt, it might return a null value. In this scenario we will continue trying until we get a not null result.

```csharp
var receipt = await web3.Eth.Transactions.GetTransactionReceipt.SendRequestAsync(transactionHash);
Expand All @@ -115,18 +118,19 @@ The transaction might have not be mined yet, so when attempting to get the recei
```

### Calling the contract function and return a value
Once we have the receipt, we can retrieve the contract address of our newly deployed contract. Using the contract address and the abi we can create an instance of the Contract object.

Using the contract we can get a Function object using the name of function.
Once we've obtained the receipt, we can retrieve the contract address of our newly deployed contract. Using the contract address and the ABI we can create an instance of the Contract object.

Using the contract we can get a `Function` object using the name of the function.

Now with the function we will be able to do a Call to our multiply function by passing a parameter to do the multiplication.
Now with the function we will be able to do a `Call` to our multiply function by passing a parameter to do the multiplication.

Note: Calls are not the same as transactions so are not submitted to the network for consensus. Calls are a simple way to retrieve data or do an operation from a contract as our multiplication.

```csharp
var contractAddress = receipt.ContractAddress;

var contract = web3.Eth.GetContract(abi, contractAddress);
var contract = web3.Eth.GetContract(ABI, contractAddress);

var multiplyFunction = contract.GetFunction("multiply");

Expand All @@ -142,7 +146,7 @@ All the source code can be found under deployment in the [Tutorials solution](ht
```csharp
var senderAddress = "0x12890d2cce102216644c59daE5baed380d84830c";
var password = "password";
var abi = @"[{""constant"":false,""inputs"":[{""name"":""val"",""type"":""int256""}],""name"":""multiply"",""outputs"":[{""name"":""d"",""type"":""int256""}],""type"":""function""},{""inputs"":[{""name"":""multiplier"",""type"":""int256""}],""type"":""constructor""}]";
var ABI = @"[{""constant"":false,""inputs"":[{""name"":""val"",""type"":""int256""}],""name"":""multiply"",""outputs"":[{""name"":""d"",""type"":""int256""}],""type"":""function""},{""inputs"":[{""name"":""multiplier"",""type"":""int256""}],""type"":""constructor""}]";
var byteCode =
"0x60606040526040516020806052833950608060405251600081905550602b8060276000396000f3606060405260e060020a60003504631df4f1448114601a575b005b600054600435026060908152602090f3";

Expand All @@ -154,7 +158,7 @@ All the source code can be found under deployment in the [Tutorials solution](ht
Assert.True(unlockAccountResult);

var transactionHash =
await web3.Eth.DeployContract.SendRequestAsync(abi, byteCode, senderAddress, multiplier);
await web3.Eth.DeployContract.SendRequestAsync(ABI, byteCode, senderAddress, multiplier);

var mineResult = await web3.Miner.Start.SendRequestAsync(6);

Expand All @@ -173,7 +177,7 @@ All the source code can be found under deployment in the [Tutorials solution](ht

var contractAddress = receipt.ContractAddress;

var contract = web3.Eth.GetContract(abi, contractAddress);
var contract = web3.Eth.GetContract(ABI, contractAddress);

var multiplyFunction = contract.GetFunction("multiply");

Expand Down
Loading

0 comments on commit 036e3ec

Please sign in to comment.