Merge pull request #147 from tqtezos/pasqu4le/suggestions

Small documentation and performance suggestions

ChangeLog.md

@@ -9,10 +9,12 @@ SPDX-License-Identifier: MIT
 <!-- Don't forget to update the gas/transaction costs tables in the
 README when a new version is released. -->
 
+## 1.5.0
+
 * [#144](https://github.com/tqtezos/stablecoin/pull/144)
   * Add `total_supply` field to the contract.
 
-* [142](https://github.com/tqtezos/stablecoin/pull/142)
+* [#142](https://github.com/tqtezos/stablecoin/pull/142)
   * Deploy TZIP-16 metadata to an external contract by default.
   * Provide deploy options `--contract-metadata-in-place` and
     `--contract-metadata-off-chain` to let user to embed the metadata

Makefile

@@ -3,7 +3,7 @@
 
 .PHONY: all build-ligo build-haskell optimize-ligo test test-dumb-term test-hide-successes nettest clean
 
-# Morley executable, it is used for optimizing Michelsion version
+# Morley executable, it is used for optimizing Michelson version
 # of stablecoin.tz
 MORLEY ?= morley
 

README.md

@@ -25,8 +25,8 @@ The project also includes an alternative FA1.2-compatible smart contract, availa
 ## How to get
 
 You can download Michelson source code of all provided smart contracts in [release assets](https://github.com/tqtezos/stablecoin/releases/latest).
-We also provide static `stablecoin-client` executable that should work on any x86_64 Linux system.
-If you are using a different operating OS or just want to build from sources, see [instructions below](#build-instructions).
+We also provide a static `stablecoin-client` executable that should work on any x86_64 Linux system.
+If you are using a different OS or just want to build from sources, see [instructions below](#build-instructions).
 
 ## Usage
 
@@ -50,17 +50,17 @@ Please refer to the [`haskell/`](/haskell/) directory for details.
 ## Gas / Transaction costs
 
 The tables below show the gas and transaction costs of both versions (FA1.2 and FA2) of
-the stablecoin contract [v1.4.0](https://github.com/tqtezos/stablecoin/releases/tag/v1.4.0) in Delphinet.
+the stablecoin contract [v1.5.0](https://github.com/tqtezos/stablecoin/releases/tag/v1.5.0) in Delphinet.
 
 ### Delphinet
 
-* [FA1.2 operations](https://better-call.dev/delphinet/KT1AMAqrzMQqB6QK724Bagp8LL2JrdXEF3By/operations)
-* [FA2 operations](https://better-call.dev/delphinet/KT1G3n8sDudm1FzCn9JYa5BM2QRaxgKry8My/operations)
+* [FA1.2 operations](https://better-call.dev/delphinet/KT1P4wqBia7AmRFQqrzfPcjdFYiiCMffE9xD/operations)
+* [FA2 operations](https://better-call.dev/delphinet/KT1VVJ8oEGaMX93PqcuFDVojHncySDEfxnrF/operations)
 
 |             | FA1.2 Gas cost | FA2 Gas cost | FA1.2 Tx cost | FA2 Tx cost |
 | ----------- | -------------- | ------------ | ------------- | ----------- |
-| origination | 75928          | 72689        | 3.942008 ꜩ    | 3.87493 ꜩ   |
-| transfer    | 79196          | 73293        | 0.007978 ꜩ    | 0.007702 ꜩ  |
+| origination | 65562          | 63843        | 2.867507 ꜩ    | 2.868852 ꜩ  |
+| transfer    | 67566          | 66254        | 0.007115 ꜩ    | 0.006998 ꜩ  |
 
 ### Measuring
 

docs/specification.md

@@ -51,7 +51,7 @@ CENTRE Fiat Token specification. These roles apply to the whole contract
 (hence "global"):
 
 * **contract owner**
-  - Can assign and re-assign any role of the token.
+  - Can assign and re-assign any role of the token, except `minter`s.
   - There always must be exactly one contract owner.
 
 * **master minter**
@@ -67,7 +67,7 @@ CENTRE Fiat Token specification. These roles apply to the whole contract
   - There can be any number of minters.
 
 * **pauser**
-  - Can pause transferring, burning and minting operations.
+  - Can pause transferring, burning, minting and allowance operations.
     During the pause, these operations cannot be performed
     and fail with an error if the user decides to try them.
   - There always must be exactly one pauser.
@@ -435,14 +435,14 @@ configure_minter =
 
 Parameter (in Michelson)
 ```
-(pair
+(pair %configure_minter
   (address %minter)
-  (pair ((option nat) %current_minting_allowance) (nat %new_minting_allowance))
+  (pair (option %current_minting_allowance nat) (nat %new_minting_allowance))
 )
 ```
 
 - Adds `minter` to the minter list to allow him to mint tokens (if `minter` is not in the list already).
-  Currently we allow upto 12 minters.
+  Currently we allow up to 12 minters.
 
 - Sets the specified minting allowance (`new_minting_allowance`) for this minter.
 
@@ -483,7 +483,7 @@ Types
 ```
 mint_param
   ( address :to_
-  , nat     :value
+  , nat     :amount
   )
 
 mint = list mint_param
@@ -494,7 +494,7 @@ Parameter (in Michelson):
 (list
   (pair
     (address %to_)
-    (nat %value)
+    (nat %amount)
   )
 )
 ```
@@ -608,13 +608,24 @@ Parameter (in Michelson): `option address`.
 
 ### **permit**
 
+Types
+```
+permit_signature
+  ( signature
+  , blake2b_hash :permit_hash
+  )
+
+permit = (key, permit_signature)
+```
+
 Parameter (in Michelson):
 ```
-pair %permit
+(pair %permit
   key
   (pair
     signature
     (bytes %permit_hash))
+)
 ```
 
 - Creates a permit, allowing any user to call this contract with a pre-signed parameter on the signer's behalf.
@@ -638,14 +649,23 @@ pair %permit
 
 ### **set_expiry**
 
-Parameter (in Michelson):
+Types
+```
+set_expiry
+  ( address :issuer
+  , seconds :expiry
+  , (option blake2b_hash) :permit_hash
+  )
 ```
 
-pair
+Parameter (in Michelson):
+```
+(pair %set_expiry
   (address %issuer)
   (pair
     (nat %expiry)
     (option %permit_hash bytes))
+)
 ```
 
 - Only the issuer of permit can set expiry.

haskell/README.md

@@ -22,9 +22,9 @@ The help message should be sufficiently descriptive, however, there are some cav
 1. Node data (address, port and whether to use TLS) is taken from `tezos-client` config by default.
 Make sure it points to an active node in the network where you want to submit your operations.
 You can override this data using the respective options of `stablecoin-client`.
-1. There is a global option `--user` that specifies which user will make operations, it defaults to `stablecoin-user`.
+1. There is a global option `--user` that specifies which user will make the operations, it defaults to `stablecoin-user`.
 You should ensure that:
-  * An address with provided alias is known to `tezos-client`.
+  * An address with the provided alias is known to `tezos-client`.
   * Its secret key is known.
   * It has sufficient balance to make operations (pay for storage and fee).
 
@@ -35,7 +35,7 @@ Note: if you are on Linux and just want to get `stablecoin-client`, we recommend
 You need [Stack](http://haskellstack.org/) to build this package.
 
 To build the library and the executable:
-1. Copy or symlink  stablecoin and metadata smart contracts (their Michelson versions) to `test/resources/` and then run `stack build`.
+1. Copy or symlink the stablecoin and metadata smart contracts (their Michelson versions) to `test/resources/` and then run `stack build`.
 The contracts are parsed and typechecked at compile-time.
 2. Or, alternatively, run `make build` (from this folder) provided that you have `ligo` and [`morley`](https://gitlab.com/morley-framework/morley) in your `$PATH`.
 

haskell/package.yaml

@@ -4,7 +4,7 @@
 <<: !include "./hpack/module.yaml"
 
 name:                stablecoin
-version:             1.4.0
+version:             1.5.0
 
 extra-source-files:
 - README.md

haskell/src/Lorentz/Contracts/Stablecoin.hs

@@ -327,7 +327,7 @@ type StorageView = Storage' BigMapId
 deriving stock instance Show StorageView
 deriving anyclass instance IsoValue StorageView
 
--- Currently the contract allows to add upto 12 minters.
+-- Currently the contract allows to add up to 12 minters.
 minterLimit :: Int
 minterLimit = 12
 

ligo/README.md

@@ -8,15 +8,15 @@ Implementation of a token smart contract in LIGO according to the [specification
 
 ## Usage
 
-We recommend using [`stablecoin-client`](/haskell/README.md#client) to interact with smart contracts.
-If you don't want to do that for some reason, you can use `ligo` tool to compile smart contracts and construct their initial storage values for origination.
-You also need [`tezos-client`](http://tezos.gitlab.io/introduction/howtoget.html) or similar software to create and submit operations to Tezos network.
+We recommend using [`stablecoin-client`](/haskell/README.md#client) to interact with the smart contracts.
+If you don't want to do that for some reason, you can use the `ligo` tool to compile the smart contracts and construct their initial storage values for origination.
+You also need [`tezos-client`](http://tezos.gitlab.io/introduction/howtoget.html) or similar software to create and submit operations to the Tezos network.
 
 ## Build Instructions
 
-In order to build LIGO smart contracts you need to have [`ligo`](https://ligolang.org/) in your `$PATH`.
-You can provide a different name/command to launch `ligo` using `$LIGO` environment variable.
+In order to build the LIGO smart contracts you need to have [`ligo`](https://ligolang.org/) in your `$PATH`.
+You can provide a different name/command to launch `ligo` using the `$LIGO` environment variable.
 Since LIGO is an actively developed project, some versions of it may be incompatible with Stablecoin.
-Revision specified in the [sources.json](/nix/sources.json) file is guaranteed to be compatible.
-Use [`Makefile`](/ligo/Makefile) to compile smart contracts.
+The revision specified in the [sources.json](/nix/sources.json) file is guaranteed to be compatible.
+Use [`Makefile`](/ligo/Makefile) to compile the smart contracts.
 For example, running `make` without arguments in this folder should produce `stablecoin.tz`.