DEV Community: Oleksandr

Building dApp with Near Protocol and React

Oleksandr — Fri, 03 Dec 2021 11:00:44 +0000

Introduction

In this tutorial you can learn how to build web application using React.js, build and deploy a smart contract on the Near Blockchain and connect web app with the smart contract to have a working web application which will interact with the smart contract.

Prerequisites

To prepare the development environment, make sure you have installed nodejs 12+, yarn and the latest near-cli

You also need to create a testnet account, go to the testnet wallet and create one, it's easy and free:

Getting Started with the project

The easiest way to get started is using npx - Node Package Execute

Install `npx` as a global dependency

npm install -g npx

Generate starter project

Let's generate the new project. Go to a directory where you want to have your project in the terminal. In our case we will be using home directory.

For near dapps there is a npx binary create-near-app. It has some options to choose what type of frontend you are going to use and also what type of smart contract you are going to use. Here are the option you can use:

➜  ~ npx create-near-app -h
create-near-app <projectDir>

Create a new NEAR project

Options:
  --version   Show version number                                      [boolean]
  --frontend  template to use
            [choices: "vanilla", "react", "vue", "angular"] [default: "vanilla"]
  --contract  language for smart contract
                 [choices: "assemblyscript", "rust"] [default: "assemblyscript"]
  --help      Show help                                                [boolean]

Examples:
  create-near-app new-app  Create a project called "new-app"

For this tutorial we are going to use react as a frontend and assemblyscript as a smart contract.

Open terminal and execute the command:

npx create-near-app near-tutorial --frontend=react --contract=assemblyscript

Wait a bit to download everything and when it finish you will see something like this:

In general our new project is ready to be started, the only thing you still need is to login in your near testnet account you should have create before. To do this open the terminal and call:

near login

It should open the browser where you approve login, after that you are ready to interact with the near blockchain using `near cli.

That's it we have created our project, now we can get hands dirty in the code. Open the project in you favourite IDE, the recommended option is using free VS Code:

bash cd near-tutorial code .

Project structure

Our newly created project has several main places:

src - React source code
contract - Smart contract source code
package.json - Project dependencies and running scripts
Readme.md - Project documentation and development tips
neardev - Configuration for smart contract development

Running the project

First of all we need to install dependencies using yarn command:

bash yarn

It can take some minutes depending on your network, be patient :)

After that we can already run the project in the dev environment. You can use one simple command:

bash yarn dev

After a couple of seconds you should see something similar in your terminal and it should also open the app in your default browser:

The app url http://localhost:1234/ opened in browser should look like this:

In the dev console you can also see that you dev smart contract was deployed to the blockchain, it starts with dev- and have some random numbers, in our case its dev-1638480997606-36755974489881. You can also see the link to the smart contract transaction deployment: https://explorer.testnet.near.org/transactions/7N4BWLVyuo9gXp9sGe8WKXBZEX7iJUq5AvZXAGqoRij1
Opening the link in your terminal will show you similar:

Now let's jump in the browser and test how it works.
Generated project has predefined greeting smart contract, you can enter the custom greeting message and it will save it in the smart contract storage, change it to something custom and press save. It should redirect you to the wallet where you can sign the smart contract with your near testnet account.

Press allow to approve transaction:

After successful approval you will be redirected back to the ui and will see the new greeting which is loaded from the smart contract:

It works, let's see how its done

Smart contract implementation and cli interaction:

Smart contract is located in contract/assembly/index.ts:

It has the default message which we saw in the browser right after the opening:

javascript const DEFAULT_MESSAGE = "Hello";

And it has two methods getGreeting(accountId: string) and setGreeting(message: string)

Mutating method `setGreeting`

javascript export function setGreeting(message: string): void { const accountId = Context.sender; // Use logging.log to record logs permanently to the blockchain! logging.log(Saving greeting "${message}" for account "${accountId}"); storage.set(accountId, message); }

As you can see this method contains one argument message which was send when we approved the transaction. Inside the method we are extracting a the sender accountId from the Context class:

javascript const accountId = Context.sender;

Context is a class provided from the near-sdk-as and it has some useful data you may need in your during the development:

You may find the whole class clicking on it in IDE or you can also check it out on near-sdk-as docs

After extracting the accountId we are using another class storage and its method storage.set:

javascript storage.set(accountId, message);

Storage is a key-value store that is persisted on the NEAR blockchain. Read the docs to check all the available methods.

Lets test the method using the near cli.

To make is easy we will set the CONTRACT_NAME env variable, and to do so we can call neardev/dev-account.env which has our contract name inside:

Call this in the terminal and check if you have exported the variable:

bash source neardev/dev-account.env echo $CONTRACT_NAME

Call result:

One more thing to do is to set our testnet account as ID env variable:

bash export ID=your-account.testnet echo $ID

Call result:

If you want to pass a method argument using near-cli you can pass a json string afther the contract name.
Now we can set the greeting using near-cli:

bash near call $CONTRACT_NAME setGreeting '{"message": "Near CLI Greeting"}' --accountId $ID

It will call the smart contract and print you the transaction id:

Readonly method `getGreeting`

getGreeting method is a readonly method, which mean we cannot use the context.sender to get the account id, its only accessible in mutating state calls:

javascript export function getGreeting(accountId: string): string | null { // This uses rawstorage.get, a low-level way to interact with on-chain // storage for simple contracts. // If you have something more complex, check out persistent collections: // https://docs.near.org/docs/concepts/data-storage#assemblyscript-collection-types return storage.get < string > (accountId, DEFAULT_MESSAGE); }

It is doing one call to storage to get the greeting from the smart contract storage or the default method, if there is no message in the storage for the account we use. Readonly methods are using view instead of call we used for setGreeting:

bash near view $CONTRACT_NAME getGreeting "{\"accountId\": \"$ID\"}"

Boom, we can see the greeting we set in the previous step:

Let go to the browser and refresh the page to verify that our message is also there. If everything goes well you will see this after refresh:

How React connects with Near

Now lets check how we interact with the Near Blockchain in frontend

In our react application we have two configuration files where we connect to the blockchain: config.js and utils.js:

Inside config.js we define our contract name, which is also taken from environment variable :

javascript const CONTRACT_NAME = process.env.CONTRACT_NAME || "near-tutorial";

And we also have getConfig function with the blockchain configuration for testnet, mainnet and some other environments:

`javascript
function getConfig(env) {
switch (env) {

case 'production':
case 'mainnet':
return {
networkId: 'mainnet',
nodeUrl: 'https://rpc.mainnet.near.org',
contractName: CONTRACT_NAME,
walletUrl: 'https://wallet.near.org',
helperUrl: 'https://helper.mainnet.near.org',
explorerUrl: 'https://explorer.mainnet.near.org',
}
case 'development':
case 'testnet':
return {
networkId: 'testnet',
nodeUrl: 'https://rpc.testnet.near.org',
contractName: CONTRACT_NAME,
walletUrl: 'https://wallet.testnet.near.org',
helperUrl: 'https://helper.testnet.near.org',
explorerUrl: 'https://explorer.testnet.near.org',
}
...
}
`

The next file is utils.js where we use the config from config.js, wand the main is initContract() method, where we connect to the blockchain rpc and list all the available methods in our contract:

`javascript
import { connect, Contract, keyStores, WalletConnection } from "near-api-js";
import getConfig from "./config";

const nearConfig = getConfig(process.env.NODE_ENV || "development");

// Initialize contract & set global variables
export async function initContract() {
// Initialize connection to the NEAR testnet
const near = await connect(
Object.assign(
{ deps: { keyStore: new keyStores.BrowserLocalStorageKeyStore() } },
nearConfig
)
);

// Initializing Wallet based Account. It can work with NEAR testnet wallet that
// is hosted at https://wallet.testnet.near.org
window.walletConnection = new WalletConnection(near);

// Getting the Account ID. If still unauthorized, it's just empty string
window.accountId = window.walletConnection.getAccountId();

// Initializing our contract APIs by contract name and configuration
window.contract = await new Contract(
window.walletConnection.account(),
nearConfig.contractName,
{
// View methods are read only. They don't modify the state, but usually return some value.
viewMethods: ["getGreeting"],
// Change methods can modify the state. But you don't receive the returned value when called.
changeMethods: ["setGreeting"],
}
);
}
`

We expand the global window object with the methods we will be using to interact with the blockchain and our smart contract. And here we also list viewMethods which we were calling with near view and changeMethods which we were calling with near call. So whenever you add new methods to your contract you have to update this file and list all the methods in the appropriate section, so that you can also use them later in your React Components.

In src/App.js you can see how the contract is used:

`javascript
// The useEffect hook can be used to fire side-effects during render
// Learn more: https://reactjs.org/docs/hooks-intro.html
React.useEffect(
() => {
// in this case, we only care to query the contract when signed in
if (window.walletConnection.isSignedIn()) {
// window.contract is set by initContract in index.js
window.contract
.getGreeting({ accountId: window.accountId })
.then((greetingFromContract) => {
setGreeting(greetingFromContract);
});
}
},

// The second argument to useEffect tells React when to re-run the effect
// Use an empty array to specify "only run on first render"
// This works because signing into NEAR Wallet reloads the page
[]
);
`

Making Changes

So now when we know how everything is connected to each other let's make it ours by making some changes.

Updating Smart Contract

Let's expand our smart contract with some properties, like date when the most recent greeting has been set.

In VSCode open contract/assemble/index.ts and add replace setGreeting method with the following:

javascript export function setGreeting(message: string): void { const accountId = Context.sender; const timestamp = Context.blockTimestamp; // Use logging.log to record logs permanently to the blockchain! logging.log(Saving greeting "${message}" with timestamp: ${timestamp} for account "${accountId}"); storage.set(accountId, message); storage.set(${accountId}_last_updated,${new Date(timestamp / 1000000).toDateString()} ${new Date(
timestamp / 1000000
).toTimeString()}); }

We have added two lines, first one is getting the block timestamp, which is provided in nanoseconds:

javascript const timestamp = Context.blockTimestamp;

Second one - convert set the storage to contains last update date of the greeting:

javascript storage.set(${accountId}_last_updated,${new Date(timestamp / 1000000).toDateString()} ${new Date(
timestamp / 1000000
).toTimeString()});

Then let's add the method to get last update value from the smart contract using the ${accountId}_last_updated key:

javascript export function getUpdateDate(accountId: string): string | null { return ( storage.get < string > (${accountId}_last_updated, "No custom greeting.") ); }

Updating React

Now let's use our new method in the React Code.

First of all we need to add them to the contract definition inside src/utils.js. Go and add new method getUpdateDate to viewMethods and save file so it will look like this:

Then open src/App.js and add a new state variable to store our update date:

javascript const [updateDate, setUpdateDate] = React.useState();

After that inside useEffect hook where we are getting the greeting add one more call to get the getLastUpdate and when we fetch the value we can update our updateDate state hook by calling setUpdateDate. The code we add should look as following:

javascript window.contract .getUpdateDate({ accountId: window.accountId }) .then((greetingUpdateDate) => { setUpdateDate(greetingUpdateDate); });

And here how the file should look after we added those changes:

And the last part is to show the updateDate in the UI. Find the h1 tag where you show current greeting and add some other tag for example h3 after to show the last update date.

`javascript

Last Update: {updateDate}

Then if you open the browser you will see the default response because we have to call setGreeting again to save the timestamp in the smart contract storage.
So let's update the greeting and press save again, approve the transaction and when getting back we will see the date (refresh the page to see the latest changes):

Great we did it, it looks awesome, isn't it?

When you save any file in your project it is automatically rebuild and redeployed to the dev in terminal, so you should be ready to use it. If it didn't happen or you have stopped your app, just use yarn dev again and it will start up.

Deploying to the GitHub Pages

The project is already set to be deployed to the Github Pages, check package.json for all the commands available, but to simply deploy it as is you can use yarn deploy:pages or to deploy everything including your smart contract you can use command yarn deploy which will build and deploy both the contract, and also the ui app.

But make sure to first commit and push your app to Github and also add the homepage property to the package.json. More details can be found here

Conclusion

That's it for now, we learned how to generate a new react app connect it with the near smart contract, how to add new methods to the smart contract, and how to use them in the UI.

You can add some more methods by your own, for example add some change methods to have some custom logic for your greeting, for example return it as a reversed string, or maybe store some custom colours or font settings for the greeting in the smart contract.

The tutorial source code is accessible here and demo app is deployed to GithubPages.

To learn more check https://near.org/learn/ or https://near.academy/

Happy coding!

Building a Voting Smart Contract with Near Protocol and Typescript

Oleksandr — Thu, 25 Nov 2021 21:28:36 +0000

Voting App Smart Contract Tutorial

Welcome to the Voting App Near Smart Contract Tutorial!
Here you can find the detailed steps of what we are going to implement, how to build, run, and deploy it to the testnet.
This tutorial is based on near-sdk-as Starter Kit which contains AssemblyScript written in Typescript
and allows everyone to write and deploy smart contracts using TypeScript instead of Rust.
You are using yarn tasks to build the smart contract.

Prerequisites

Make sure you have installed nodejs 12+, yarn and the latest near-cli.

Voting App Smart Contract Description

The Voting App Contract we are going to build is designed to support multiple ongoing elections. Here are the supported features:

Any election can have unlimited amount of candidates.
Every near user can vote, but only once for one of the candidates.
Every election has startDate and endDate properties which are used to control the election process.
Any candidate can add his candidacy before the election startDate.
A user can only add his vote for the specific election, if the election has already started, meaning currentTime > election.startDate.

Tutorial

To start building the new smart contract using AssemblyScript you can close use this repository and apply the steps one by one to build and deploy the contract.

Step 1 - Prepate structure and create a contract

By default starter kit contains two examples: simple and singleton, lets define a new workspace item "src/voting" in asconfig.json so it will look like this:

{
  "workspaces": [
    "src/simple",
    "src/singleton",
    "src/voting"
  ]
}

Then lets add a new component into the source folder called voting and another two folders assembly and __tests__ inside it:

mkdir src/voting
mkdir src/voting/assembly
mkdir src/voting/__tests__

Folder __tests__ will contain some unit tests, so we also need to have a file to support the testing library used, we can just copy it from another folder:

cp -r src/simple/__tests__/as-pect.d.ts src/voting/__tests__/.

Then we can add an empty test file which we will later use to write tests:

touch src/voting/__tests__/index.unit.spec.ts

Next for now we can put some empty spec inside the test, you copy and paste it inside the index.unit.spec.ts file:

import { Contract } from "../assembly";

let contract: Contract

beforeEach(() => {
  contract = new Contract()
})

describe("Voting Contract", () => {
  // VIEW method tests

  it("view method 1", () => {
    // expect(contract.method_name()).toStrictEqual("expected_result")
  })

  // CHANGE method tests

  it("change method 1", () => {
    // expect(contract.methodName("some-key", "some value")).toStrictEqual("Data processed.")
  })
})

And the last step is to create actual contract file src/voting/index.ts:

touch src/voting/assembly/index.ts

And to make it compilable we add some definition in the new index.ts file:

@nearBindgen
export class Contract {
  get_info(): string {
    return "This is the near protocol voting app smart contract tutorial.";
  }
}

To make sure everything is done properly in this step we can build the project with yarn build:release and
check build/release/ folder, to verify it contains our new contract:

yarn
yarn build:release
ls build/release

If everything goes well you should see three files in build/release folder including new voting.wasm:

➜  near-voting-app-smart-contract-tut git:(main) ✗ ls build/release/

simple.wasm     singleton.wasm  voting.wasm

Step 2 - Define Data Model

Lets create a new file called model.ts so it will hold all our models:

touch src/voting/assembly/model.ts

So because we are going to support multiple elections in parallel, every election will have a list of candidates and also a votes for every candidate lets add models in the model.ts, copy and paste this code:

import { PersistentMap, PersistentSet, u128 } from "near-sdk-as";
import { AccountId, Timestamp } from "../../utils";

@nearBindgen
export class Candidate {
  constructor(
    public accountId: AccountId,
    public registrationDate: Timestamp,
    public name: string,
    public slogan: string,
    public goals: string
  ) {}
}

@nearBindgen
export class Vote {
  constructor(
    public accountId: AccountId,
    public date: Timestamp,
    public candidateId: AccountId,
    public comment: string,
    public donation: u128
  ) {}
}

@nearBindgen
export class ElectionInfo {
  constructor(
    public id: u32,
    public initiator: AccountId,
    public creationDate: Timestamp,
    public startDate: Timestamp,
    public endDate: Timestamp,
    public title: string,
    public description: string
  ) {}
}

@nearBindgen
export class CandidateVotes {
  constructor(public candidate: Candidate, public votes: Vote[]) {}
}

@nearBindgen
export class ElectionVotes {
  constructor(public election: ElectionInfo, public votes: CandidateVotes[]) {}
}

@nearBindgen
export class Election {
  public candidates: PersistentSet<Candidate>;
  public candidateIds: PersistentSet<string>;
  public votes: PersistentMap<AccountId, PersistentSet<Vote>>;
  public voters: PersistentSet<AccountId>;
  public electionInfo: ElectionInfo;
}

These are all the models simple models, we will be using.

Now lets add constructor to the Election class so it will look like:

@nearBindgen
export class Election {
  public candidates: PersistentSet<Candidate>;
  public candidateIds: PersistentSet<AccountId>;
  public votes: PersistentMap<AccountId, PersistentSet<Vote>>;
  public voters: PersistentSet<AccountId>;
  public electionInfo: ElectionInfo;

  constructor(
    id: u8,
    initiator: AccountId,
    creationDate: Timestamp,
    startDate: Timestamp,
    endDate: Timestamp,
    title: string,
    description: string
  ) {
    this.electionInfo = new ElectionInfo(
      id,
      initiator,
      creationDate,
      startDate,
      endDate,
      title,
      description
    );
    this.candidates = new PersistentSet<Candidate>(`e${id}_c`);
    this.votes = new PersistentMap<AccountId, PersistentSet<Vote>>(`e${id}_v`);
    this.candidateIds = new PersistentSet<string>(`e${id}_ci`);
    this.voters = new PersistentSet<AccountId>(`e${id}_vt`);
  }
}

It is the main wrapper object for the elections, so it will contain all the candidates, votes and election metadata.

We are using PersistentSet to store candidates and candidateIds.

Why do we need to store candidateIds additionally? This is to be able to check if we have such candidate registered faster without the need of iterating over the objects.

To store the votes we are using PersistenceMap where the key is the candidate's account_id it will help us to get votes for a specific candidate.

We also store some metadata in ElectionInfo class, it will be used to return the general election information later in the smart contract.

Step 3 - Contract Initialisation

So After we defined the data model we can jump into the business logic implementation.
Let us add the constructor and some properties to the contract. Replace the voting/assembly/index.ts so it will look like this:

import { PersistentSet, PersistentMap } from "near-sdk-core";
import { Election } from "./model";
@nearBindgen
export class Contract {
  private elections: PersistentMap<u32, Election>;
  private electionIds: PersistentSet<u32>;

  constructor() {
    this.elections = new PersistentMap<u32, Election>("e");
    this.electionIds = new PersistentSet<u32>("ei");
  }
}

Default constructor is needed to initialise our contract when it's deployed.
We are initialising empty PersistentMap<u32, Election> which will store all future elections,
and also PersistentSet<u32> of the electionId's so we can quickly check if the election with provided id exists.

Step 4 - Define Readonly methods

Our voting contract will have some readonly methods, which do not mutate state, so they can be called with near view. Let's add several handy methods. Copy those three code snippets in the contract:

get_elections() - get all existing elections:

  get_elections(): ElectionInfo[] {
    const electionIds = this.electionIds.values();
    let elections: ElectionInfo[] = [];
    for (let i: i32 = 0; i < electionIds.length; i++) {
      elections.push(this.elections.getSome(electionIds[i]).electionInfo);
    }
    return elections;
  }

get_candidates(electionId: u32) - get all candidates for the specified electionId:

  get_candidates(electionId: u32): Candidate[] {
    assert(
      this.elections.contains(electionId),
      `No election with id [${electionId}] found. Did you mistype?`
    );
    return this.elections.getSome(electionId).candidates.values();
  }

get_votes(electionId: u32) - get current voting results for the specified electionId:

  get_votes(electionId: u32): ElectionVotes {
    assert(
      this.elections.contains(electionId),
      `No election with id [${electionId}] found. Did you mistype?`
    );
    const election = this.elections.getSome(electionId);
    const allCandidates = election.candidates.values();
    const candidatesVotes: CandidateVotes[] = [];
    for (let i: i32 = 0; i < allCandidates.length; i++) {
      const candidate = allCandidates[i];
      let votes: Vote[];
      if (election.votes.contains(candidate.accountId)) {
        votes = election.votes.getSome(candidate.accountId).values();
      } else {
        votes = [];
      }
      const candidateVote = new CandidateVotes(candidate, votes);
      candidatesVotes.push(candidateVote);
    }
    return new ElectionVotes(election.electionInfo, candidatesVotes);
  }

Also you would need to update imports so you can do it manually in the IDE or just replace the imports with this:

  import { PersistentSet, PersistentMap } from "near-sdk-core";
  import {
    Candidate,
    CandidateVotes,
    Election,
    ElectionInfo,
    ElectionVotes,
    Vote,
  } from "./model";

As you can see we are using assert() method in get_candidates and get_votes. This is very useful to add such assertions in your contracts, so you always know everything is going as expected:

assert(this.elections.contains(electionId),`No election with id [${electionId}] found.`);

Step 5 - Add Change State Methods

The next part of the implementation is the methods which will be modifying the contract state.
Those methods are marked with @mutateState() annotation in the contract. Lets add 3 methods to the code:
add_election, add_candidacy, and add_vote.

Step 5.1 - Method `add_election` implementation

Now we can add the new method to register new election.
Lets take a look on the method signature:

add_election(
  title: string,
  description: string,
  startDate: Timestamp,
  endDate: Timestamp
): void

It accept Election Metadata Parameters: title, description, startDate and endDate
To generate unique election id we will be using random number generator RNG provided by near sdk.
In this method we don't need any assertions, so any near user can register new election.
Properties startDate and endDate will be used to set the start and end of election as a timestamp in milliseconds. You can pass 0 for both properties, then the default values will be used:

default for start date is 1 day since election creation, so candidates will have 24 hours to submit their candidacy.
default for end date is 7 days after the election start date, so contract will be accepting votes for the period of one week.

You can copy-paste the whole method in the contract:

@mutateState()
add_election(
  title: string,
  description: string,
  startDate: Timestamp,
  endDate: Timestamp
): void {
  const rng = new RNG<u16>(1, u16.MAX_VALUE);
  const electionId = rng.next();
  const start = startDate > 0
      ? startDate * 1000000
      : context.blockTimestamp + 86400000000000
  const election = new Election(
    electionId,
    context.sender,
    context.blockTimestamp,
    startDate > 0
      ? startDate * 1000000
      : context.blockTimestamp + 86400000000000,
    endDate > 0
      ? endDate * 1000000
      : start + 86400000000000 * 7,
    title,
    description
  );
  this.electionIds.add(electionId);
  this.elections.set(electionId, election);
}

Step 5.2 - Method `add_candidacy` implementation

This method is used to submit the candidacy in the election by electionId.
Lets define the method definition:

@mutateState()
add_candidacy(
  electionId: u32,
  name: string,
  slogan: string,
  goals: string
): void {}

To verify that election exists we are using assert() method to check if we have election with the specified id in the contract storage:

assert(
    this.elections.contains(electionId),
    `No election with id [${electionId}] found. Did you mistype?`
  );

We can also use assert() to check if there is no such candidate in the current election:

const election = this.elections.getSome(electionId);
  assert(
    election.electionInfo.startDate > context.blockTimestamp,
    "Could not add candidacy to the ongoing elections."
  );

And also we check if the candidates name, slogan and goals are defined. Because empty candidacy is no very informative:

assert(
    name.length > 0,
    "Name is required, put your account ID as name if you was us to put it on the election billboard!"
  );
  assert(
    slogan.length > 0,
    "Slogan is required, what are you going to print on the snapbacks and t-shirts?"
  );
  assert(
    goals.length > 0,
    "Goals is required, who will vote to you without the goals?"
  );

After we verified all the properties we can add the candidate in the election candidates list:

const date = context.blockTimestamp;
  const candidate = new Candidate(candidateId, date, name, slogan, goals);
  election.candidates.add(candidate);
  election.candidateIds.add(candidateId);
  this.elections.set(electionId, election);

Here is the full method definition which you can copy-paste to the contract.

@mutateState()
add_candidacy(
  electionId: u32,
  name: string,
  slogan: string,
  goals: string
): void {
  const candidateId = context.sender;
  assert(
    this.elections.contains(electionId),
    `No election with id [${electionId}] found. Did you mistype?`
  );
  const election = this.elections.getSome(electionId);
  assert(
    election.electionInfo.startDate > context.blockTimestamp,
    "Could not add candidacy to the ongoing elections."
  );
  assert(
    !election.candidateIds.has(candidateId),
    "Candidate is already registered in this election, don't cheat! Your votes will not sum up in case you register yourself twice :)"
  );
  assert(
    name.length > 0,
    "Name is required, put your account ID as name if you was us to put it on the election billboard!"
  );
  assert(
    slogan.length > 0,
    "Slogan is required, what are you going to print on the snapbacks and t-shirts?"
  );
  assert(
    goals.length > 0,
    "Goals is required, who will vote to you without the goals?"
  );

  const date = context.blockTimestamp;
  const candidate = new Candidate(candidateId, date, name, slogan, goals);
  election.candidates.add(candidate);
  election.candidateIds.add(candidateId);
  this.elections.set(electionId, election);
}

Step 5.3 - Method `add_vote` implementation

The last method is add_vote which allows users to submit their vote for a specific candidate in the election.
Here we also use assertions to validate that election by id exists, whether the candidate exists, and also if the user didn't vote yet, because you can only vote once in the whole election.
Here is the full method implementation, add this to the contract:

@mutateState()
add_vote(electionId: u32, candidateId: string, comment: string): void {
  assert(
    this.elections.contains(electionId),
    `No election with id [${electionId}] found. Did you mistype?`
  );
  const election = this.elections.getSome(electionId);
  assert(
    election.electionInfo.startDate > context.blockTimestamp,
    "Could not add vote to the election which is not yet started."
  );
  assert(
    election.electionInfo.endDate < context.blockTimestamp,
    "Could not add vote to the election which is already finished."
  );
  const voterId = context.sender;
  const date = context.blockTimestamp;
  const donation = context.attachedDeposit;
  assert(
    election.candidateIds.has(candidateId),
    "Candidate is not registered in the election. Maybe you mistyped his account id?"
  );

  assert(!election.voters.has(voterId), "Sorry, you can only vote once!");
  election.voters.add(voterId);
  const vote = new Vote(
    voterId,
    date,
    candidateId,
    comment ? comment : "",
    donation
  );

  let votes = election.votes.get(candidateId);
  if (votes == null) {
    votes = new PersistentSet<Vote>("vt");
  }
  votes.add(vote);
  election.votes.set(candidateId, votes);
  this.elections.set(electionId, election);
}

Step 6 - Deploy the dev contract

We have build our contract with all the methods so we can already test it out, let's run this commands to build and deploy dev-contract. Make you are are logged in in the near cli using near login command prior to this step:

yarn build:release && near dev-deploy --wasmFile build/release/voting.wasm

If everything goes well, you should see something like this in your terminal:

➜  near-voting-app-smart-contract-tut git:(main) ✗ yarn build:release && near dev-deploy --wasmFile build/release/voting.wasm
yarn run v1.22.17
warning ../../package.json: No license field
$ asb
✨  Done in 16.10s.
Starting deployment. Account id: dev-1637852337467-70985280826279, node: https://rpc.testnet.near.org, helper: https://helper.testnet.near.org, file: build/release/voting.wasm
Transaction Id 641CmZv5cZHcWe773C8g5uaBDpqoTt8zp4CfBxjytEWR
To see the transaction in the transaction explorer, please open this url in your browser
https://explorer.testnet.near.org/transactions/641CmZv5cZHcWe773C8g5uaBDpqoTt8zp4CfBxjytEWR
Done deploying to dev-1637852337467-70985280826279

Congratulations, you contract is deployed now. So let's test it works. The last line in the terminal show you the dev contract name which looks like dev-1234567890-123456789 this is the contract name you will be using. It is also added to the file neardev/dev-account.env and we will use is to set up ENV variables before we call the contract.

Step 7 - Initialise dev contract

To initialise contract we can use the new method which will call the Contract class constructor. To init the contract use this command:

source neardev/dev-account.env
near call $CONTRACT_NAME new --accountId $CONTRACT_NAME

Step 8 - Use dev contract

Let's use our contract, by calling the methods we added to verify the process of election is working as expected.

Step 8.1 - Add new election

Let's add new election using near cli using add_election and then call get_elections to check our new election. You can pass startDate to the current time stamp + 5 minutes, so you will have 5 minutes to submit the candidates before the voting start, you can use some service like currentmillis.com

source neardev/dev-account.env
near call $CONTRACT_NAME add_election '{"title": "First election!", "description": "Testing the election model.", "startDate": "1637874480000", "endDate": "0"}' --accountId $CONTRACT_NAME
near view $CONTRACT_NAME get_elections

The result of get_election will look like this:

➜  near-voting-app-smart-contract-tutorial git:(main) ✗ near view $CONTRACT_NAME get_elections
View call: dev-1637871596730-46015068107726.get_elections()
[
  {
    id: 43094,
    initiator: 'dev-1637871596730-46015068107726',
    creationDate: '1637874334500905663',
    startDate: '1637874360000000000',
    endDate: '1638479160000000000',
    title: 'First election!',
    description: 'Testing the election model.'
  }
]

Now you have the election id 38749 which you can use to submit candidacy, for you it will be different id, so you can use the once you received from the contract.

Step 8.2 - Add new candidacy

To add new candidacy we are going to use add_candidacy method and then you call get_candidates to verify that your candidacy has been added:

source neardev/dev-account.env
near call $CONTRACT_NAME add_candidacy '{"electionId": 38749, "name": "Donald Duck", "slogan": "Make river great again!", "goals": "Do good, do not do bad!"}' --accountId $CONTRACT_NAME
near view $CONTRACT_NAME get_candidates '{"electionId": 38749}'

You should get back the list of candidates, containing only one:

➜  near-voting-app-smart-contract-tutorial git:(main) ✗ near view $CONTRACT_NAME get_candidates '{"electionId": 42719}'
View call: dev-1637871596730-46015068107726.get_candidates({"electionId": 38749})
[
  {
    accountId: 'dev-1637871596730-46015068107726',
    registrationDate: '1637873336622836513',
    name: 'Donald Duck',
    slogan: 'Make river great again!',
    goals: 'Do good, do not do bad!'
  }
]

Step 8.3 - Add new vote

To add new vote you should use the third method we have added: add_vote.
It will only accept candidates if the start date is < current timestamp, meaning that the election is already in progress. The candidate id you can get from the list of candidates you got in the previous step:

#!/bin/bash
source neardev/dev-account.env
near call $CONTRACT_NAME add_vote '{"electionId": 38749, "candidateId": "dev-1637871596730-46015068107726", "comment": "I believe that guy!"}' --accountId $CONTRACT_NAME

When your vote has been added you can use the read method get_votes to check the current votes of the election:

#!/bin/bash
source neardev/dev-account.env
near view $CONTRACT_NAME get_votes '{"electionId": 38749}'

You will get the response with the list of election

➜  near-voting-app-smart-contract-tutorial git:(main) ✗ near view $CONTRACT_NAME get_votes '{"electionId": 38749}'
View call: dev-1637871596730-46015068107726.get_votes({"electionId": 38749})
{
  election: {
    id: 38749,
    initiator: 'dev-1637871596730-46015068107726',
    creationDate: '1637874426134027892',
    startDate: '1637874480000000000',
    endDate: '1638479280000000000',
    title: 'First election!',
    description: 'Testing the election model.'
  },
  votes: [
    {
      candidate: {
        accountId: 'dev-1637871596730-46015068107726',
        registrationDate: '1637874452572363281',
        name: 'Donald Duck',
        slogan: 'Make river great again!',
        goals: 'Do good, do not do bad!'
      },
      votes: [
        {
          accountId: 'dev-1637871596730-46015068107726',
          date: '1637874808410611274',
          candidateId: 'dev-1637871596730-46015068107726',
          comment: 'I believe that guy!',
          donation: '0'
        }
      ]
    }
  ]
}

When the election endDate will be less than the current date it will mean that election process is finished and you will not be able submit votes, so get_votes will be giving the final results of voting.

Production deployment

When you have tested the whole flow with the dev contract you can deploy the contract to the actual account or sub-account. To deploy the contract you can use this command passing the contract account you want:

near deploy --wasmFile build/release/voting.wasm --accountId voting.your_account.testnet

You should get the transaction id after succesfull deployment:

➜  near-voting-app-smart-contract-tutorial git:(main) ✗ near create-account voting.your_account.testnet --masterAccount lkskrnk.testnet
Saving key to '/Users/oleksandrkorniienko/.near-credentials/testnet/voting.your_account.testnet.json'
Account voting.your_account.testnet for network "testnet" was created.

Final

That's it, now you can try to build some nice web app to have a frontend application which can use your smart contract.
Useful library to get started with the js api for building near web apps is near-api-js or if you're familiar with react you can use create-near-app library. Good luck!

Full implementation of the contract can be found here

Deploy Oracle Cloud Compute Instance, configure Nginx with TLS on GitHub Actions using Terraform and Ansible for free

Oleksandr — Fri, 27 Nov 2020 11:00:58 +0000

Intro

This is an article which describes how to provision a free Oracle Cloud Compute Instance from GitHub Actions using terraform, configure Nginx and generate LetsEncrypt SSL certificates for a free dynamic domain from DuckDNS and deploy a simple NodeJS app on that instance.

DEV Community: Oleksandr

Building dApp with Near Protocol and React

Introduction

Prerequisites

Getting Started with the project

Install npx as a global dependency

Generate starter project

Project structure

Running the project

It works, let's see how its done

Smart contract implementation and cli interaction:

Mutating method setGreeting

Readonly method getGreeting

How React connects with Near

Making Changes

Updating Smart Contract

Updating React

Last Update: {updateDate}

Deploying to the GitHub Pages

Conclusion

Building a Voting Smart Contract with Near Protocol and Typescript

Voting App Smart Contract Tutorial

Prerequisites

Voting App Smart Contract Description

Tutorial

Step 1 - Prepate structure and create a contract

Step 2 - Define Data Model

Now lets add constructor to the Election class so it will look like:

Step 3 - Contract Initialisation

Step 4 - Define Readonly methods

Step 5 - Add Change State Methods

Step 5.1 - Method add_election implementation

Step 5.2 - Method add_candidacy implementation

Step 5.3 - Method add_vote implementation

Step 6 - Deploy the dev contract

Step 7 - Initialise dev contract

Step 8 - Use dev contract

Step 8.1 - Add new election

Step 8.2 - Add new candidacy

Step 8.3 - Add new vote

Production deployment

Final

Deploy Oracle Cloud Compute Instance, configure Nginx with TLS on GitHub Actions using Terraform and Ansible for free

Intro

Prerequisites

Install `npx` as a global dependency

Mutating method `setGreeting`

Readonly method `getGreeting`

Step 5.1 - Method `add_election` implementation

Step 5.2 - Method `add_candidacy` implementation

Step 5.3 - Method `add_vote` implementation