docs(guide): Adjust contract aci guide

aeternity · Jan 10, 2020 · 5220a74 · 5220a74
1 parent a9c101b
commit 5220a74
Showing 1 changed file with 64 additions and 57 deletions.
diff --git a/docs/guides/contract-usage.md b/docs/guides/contract-usage.md
@@ -1,11 +1,11 @@
 ## Contract Usage
 
-To have ability to interact with Aeternity Smart Contracts you need two things:
+To have ability to interact with Aeternity Smart Contracts you need:
  - Compiler
  - Node
  - SDK
 
-Let's look how to use SDK for that
+## Creating Contract Instance
 
 ```js
 const { Universal: Ae, MemoryAccount, Node } = require('@aeternity/aepp-sdk')
@@ -37,66 +37,73 @@ const main = async () => {
   // Create contract object for contract which have external dependencies
   const contractObject = await sdkInstance.getContractInstance(CONTRACT_SOURCE, { contractAddress, filesystem })
   // In this step sdk will call the compiler and get the ACI for provided source code
-  // base on ACI sdk will generate the `js functions` for each of you SC method
+  // base on ACI sdk will generate the `js functions` for each of your SC method
   // which you will find in `contractObject.methods` object
+```
+## Deploying Smart Contract
+Now we want to deploy our SC with init function like:
+  `stateful function init(n: int) : state => { count: n }`
+  ```js
+const count = 1
+await contractObject.deploy([count])
+// or
+await contractObject.methods.init(count)
 
+// Now our SC is deployed and we can find a deploy information
+console.log(contractObject.deployInfo) // { owner, transaction, address, createdAt, result, rawTx }
+ ```
 
-  // Then we want to deploy our SC with init function like:
-  // stateful function init(n: int) : state => { count: n }
-  const count = 1
-  await contractObject.deploy([count])
-  // or
-  await contractObject.methods.init(count)
-
- // Now our SC is deployed and we can find a deploy information
- console.log(contractObject.deployInfo) // { owner, transaction, address, createdAt, result, rawTx }
-
- // Now we can make call to one of our SC function
- // Lets assume that we has a function like:
- // function sum (a: int, b: int) : int = a + b
- const callResult = await contractObject.methods.sum(1 , 2)
- // or
- const callResult = await contractObject.call('sum', [1, 2])
- // callResult will contain all info related to contract call transaction
- console.log(callResult.decodedRes) // 3
+## Call Smart Contract methods
+### Simple call
+Now we can make call to one of our SC function.
+Let's assume that we have a function like:
+`function sum (a: int, b: int) : int = a + b`
+```js
+const callResult = await contractObject.methods.sum(1 , 2)
+// or
+const callResult = await contractObject.call('sum', [1, 2])
 
- // Let's talk more about autogenerated function of `contractObject`
- // `await contractObject.methods.sum(1 , 2)` here the sdk will decide:
- // 1) If the function is stateful(chgange SC state)
- // OnChain call: the sdk will prepare and broadcast a contract call transaction
- // 2) if function is not stateful(state is not chanched)
- // OffChain/Static call: the sdk will prepare contract call transaction and dry-run it
-
- // Also you can manually control this behaviour
- // Using the `send` and `get` methods
- // Exm:
- // Broadcast transaction to the chanin
- const callResult = await contractObject.methods.sum.send(1 , 2)
- // Dry-run transaction
- // Make sure that you provide the node `internalUrl` which is used for `dry-run` node API endpoint
- const callResult = await contractObject.methods.sum.get(1 , 2)
+// callResult will contain all info related to contract call transaction
+console.log(callResult.decodedRes) // 3
+```
+### How it's works inside
 
- // Make contract call and overwrite transaction props passing it's as option: fee, amount, ttl, ...
- // Under `methods` object function 
- // will have the same arguments length and order as we had in our SC source
- // The last arguments is always options object
- // if `options` is not provide sdk will use the default options 
- // which you can find under the `contractObject.options` 
- const callResult = await contractObject.methods.sum.get(1 , 2, { amount: 1000, fee: 3232, gas: 123})
- // or
- const callResult = await contractObject.call('sum', [1 , 2], { amount: 1000, fee: 3232, gas: 123})
+Let's talk more about autogenerated function of `contractObject` 
+ >`await contractObject.methods.sum(1 , 2)`
+>
+Here the sdk will decide:
+ - If the function is `stateful`(change SC state) -> `SDK` will prepare and broadcast a `contract call` transaction
+ - If function is `not stateful`(state is not changed) -> `sdk` will prepare contract call transaction and `dry-run` it
 
- // Call contract using specific account
- // You can use `onAccount` option for that whcih can bew one of:
- // 1) keypair object({ secretKey, publicKey })
- // 2) MemoryAccount instance
- // 3) account public key
- // account must be included in sdk or you can alway add it using account management API of SDK
- // await sdkInstance.addAccount(MemoryAccount({ keypair }))
- const options = { onAccount: keypair || MemoryAccount || publicKey } 
- const callResult = await contractObject.methods.sum.get(1 , 2, options)
-}
+### Manual control
+Also you can manually control this behaviour using the `send` and `get` methods:
+```js
+// Sign and Broadcast transaction to the chain
+const callResult = await contractObject.methods.sum.send(1 , 2)
 
-// call main
-main()
+// Dry-run transaction
+// Make sure that you provide the node `internalUrl` which is used for `dry-run` node API endpoint
+const callResult = await contractObject.methods.sum.get(1 , 2)
+``` 
+### Overriding default transaction params
+Make contract call and overwrite transaction props passing it's as option: `fee, amount, ttl, ...`
+ Auto-generate functions(under `methods`) will have the same arguments length and order as we had in our SC source,
+ the last arguments is always options object
+ if `options` is not provide sdk will use the default options 
+ which you can find under the `contractObject.options` 
+ ```js
+const callResult = await contractObject.methods.sum.get(1 , 2, { amount: 1000, fee: 3232, gas: 123})
+// or
+const callResult = await contractObject.call('sum', [1 , 2], { amount: 1000, fee: 3232, gas: 123})
+```
+### Call contract using specific account
+You can use `onAccount` option for that which can bew one of:
+ - `keypair` object({ secretKey, publicKey })
+ - `MemoryAccount` instance
+ - account `public key`
+ ```js
+// account must be included in sdk or you can always add it using account management API of SDK
+// await sdkInstance.addAccount(MemoryAccount({ keypair }))
+const options = { onAccount: keypair || MemoryAccount || publicKey } 
+const callResult = await contractObject.methods.sum.get(1 , 2, options)
 ```