aeternity/aepp-sophia-examples

Sophia Smart Contract examples using AEproject.

aepp-sophia-examples

AEproject

AEproject is the testing framework for Sophia Smart Contract development and allows developers to easily run a local dev environment & test their Smart Contracts.

The structure of this repository follows the default structure that AEproject provides if you initialize a new project.

Note

• This repository doesn't provide any deployment scripts as it is only intended to showcase Sophia Smart Contracts & how to test those.
• All Sophia examples are provided with corresponding tests written in JavaScript which can be found under ./test.

Standards (Aeternity Expansions) & Implementations

The Aeternity Expansions (AEX) are standards on aeternity proposed by the community. If you have a good idea or face common requirements you can also submit a new AEX proposal for which a reference implementation can be developed.

• AEX-9: Fungible Token
  • Reference Implementation
• AEX-141: Non Fungible Token
  • NFT Collection Example Implementation
  • Simple Marketplace Example Implementation

Smart Contract Examples

Disclaimer

The provided Sophia examples are only tested to the extend represented. None of the code was security audited by aeternity or is provided to be used in production, without thorough checks.

Library Usage

The LibraryUsage.aes contract shows how to include default and custom libraries in a Smart Contract. The example currently includes following custom libraries:

• BaseConverter.aes
• DateTime.aes

Delegation signatures

It is possible to delegate the right to perform certain AENS or Oracle related actions to a contract. Check out the following examples and corresponding tests to see how you can use it:

• AensDelegation.aes
  • Delegation signatures for AENS functions can e.g. be used to create an AENS marketplace
• OracleDelegation.aes

Oracles

ExchangeOracles

• ExchangeOracle.aes registers an oracle and allows to respond to oracle queries.
• ExchangeMarket.aes showcases how to query prices from an oracle and how to get the answers of an oracle.

SmartDataProvider

• SmartDataProviderBackendInterface.aes defines entrypoints of the SmartDataProviderBackend
• SmartDataProviderBackend.aes the actual implementation of the interface that registers an oracle and processes responses
• SmartDataProviderClient.aes the client that uses the interfaces to call the entrypoints of the backend implementation

There also exists another repository ae-oracle-pricefeed which includes a complete example that runs a server for the oracle which automatically extends the TTL of the oracle and responds to queries.

An even more complex example which aggregates answers of multiple oracles is included in tipping-oracle-service. The contracts in this repository are being used by https://superhero.com.

Smart Shop

This is a good example to see how to deal with contract interfaces to call remote contracts. All contracts can be found under contracts/SmartShop.

Workflow

1. The Seller deploys the SellerContract by passing the buyer public address and item price as arguments.
2. The Transport Courier deploys the TransportContract passing location as an argument.
3. The Buyer passes SellerContract address and TransportContract address as arguments when deploying BuyerContract.
4. The Buyer deposits the needed amount by calling deposit_to_seller_contract(), which takes the price of the item as Call.value.
5. The Seller now sends the item, which will be redirected to Transport Courier. The function is send_item(). It checks if Buyer has deposited the price of the item to the SellerContract.
6. Buyer can track the status of the item:
   • check_courier_status() - returns current delivery status
   • check_courier_location() - returns current location status
7. Once the item is delivered, the Transport Courier calls delivered_item(city : string) function, with current location.
8. To finalize the order, Buyer calls received_item() function, with SellerContract address.
9. The amount of tokens, payed by Buyer, will be sent to seller's account.

Others (no specific explanation provided/required)

• CryptoHamster.aes
• Ownable.aes
• SmartRealEstate.aes
• SpendToMany.aes
• TicTacToe.aes

Problems / Questions

If you face a problem or have other questions please pick one of the following places:

• https://forum.aeternity.com/c/sophia-smart-contracts/38
• https://stackoverflow.com/questions/tagged/aeternity-blockchain
• æternity Discord / Sophia Channel

We are happy to help!

aepp-sophia-examples's Issues

Create state channels demo

We want to create state channel demo and the use case will be with customers in a bar.
There are some issues there and talk with Dimitar Ivanov will be scheduled.

child of #2

Add Sophia base Converter smart contract example

Bad code style: Map.lookup_default

I've had a look at some of the examples and discovered code that looks inefficient/unnecessarily long/unnecessarily complex:

In many places I see code like:

  switch(Map.lookup(user, state.m_user_todos))
    None => {}
    Some(x) => x

This is better written as Map.lookup_default(user, state.m_user_todos, {}) or the equivalent
state.m_user_todos[user = {}].

Similarily there is the following construction:

  switch(Map.lookup(user, state.m_user_todos))
    None => false
    Some(x) => true

That is more succintly written as Map.member(user, state.m_user_todos).

Bad code style: Functions returning nothing

I've had a look at some of the examples and discovered code that looks inefficient/unnecessarily long/unnecessarily complex:

Sometimes there are functions that only do side effects (either perform a
transaction, like spend, or updates the state) then it is unnecessary to
return anything (in most cases I see a bool being returned)...

  record state = { x : int }

  function add(i : int) : bool =
    put(state{ x = state.x + i })
    true

Is better written like:

  record state = { x : int }

  function add(i : int) : () =
    put(state{ x = state.x + i })

I.e. unit (written as ()) is the preferred return type when there is
nothing to return. And, as an extra benefit this will save a couple of Gas :-)

Missing README.md file for Crypto Hamsters example

Add more comprehensive examples for the standard contracts

Add SmartDataProvider example

Add SmartRealEstate example

Create library for date and time

Library for date and time similar to the solidity one with properties for days, seconds etc

Add library for ecverify

Create library that will make usage of ecrecover more easy.

Smart Contracts Development

Address feedback from Hans

Fix smart contracts examples with the feedback from Hans

Limit line length to 100 or so

To don't enable line wrapping in IDE in vertical screens 😄 and improve readability in github

Create PR for changing smart contracts repo

Currently, the smart contracts are in the limechain repo and we​ should transfer them to the aeternity repo. The repo is already created here is a link:

https://github.com/aeternity/aepp-sophia-examples

child of #2

Add Auction Smart Contract

child of #2

As a user I want to be able to host and participate in Auction, so smart contracts for this can be implemented in Sophia

Add Oracle Smart contracts to examples

Add oracle smart contract that will be used for getting the rate for exchanging ERC20 tokens and AE. The contracts are currently in development, but need to finish.

child of #2

Add Sophia Smart Bank example

Finish Oracle Smart Contracrts

After the recent changes, add missing unit tests for the contracts and push them to the examples repo.

child of #2

Bad code style: Nested maps

I've had a look at some of the examples and discovered code that looks inefficient/unnecessarily long/unnecessarily complex:

In some places there seem to be a struggle to handle nested maps efficiently,
there are helper functions with names like create_nested_map_if_not_exists.

A canonical example could be:

  record state = { x : map(int, map(int, int)) }

  function add(k1 : int, k2 : int, v : int) =
    put(state{ x[k1][k2] = v })

This will fail if there isn't already a map for k1 in x - the reason being
that there will be a lookup of x[k1] that fails - if that is not the behavior
that is intended but instead you'd rather add an empty map and then add k2 to
this map this can be achieved like this:

  record state = { x : map(int, map(int, int)) }

  function add(k1 : int, k2 : int, v : int) =
    put(state{ x[k1 = {}][k2] = v })

Note the k1 = {}, this says that "if k1 is not a member of the map the
default value is {} (the empty map). And we proceed by inserting k2 in this
empty map.

provide example for AENS interface usage

we can now provide examples for the AENS interface usage which can serve as starting point for an AENS marketplace :-)

Add SmartShop example

Add TicTacToe example