docs(guides): Add draft guide for contract interaction using Contract…

… ACI

docs/guides/contract-usage.md

@@ -0,0 +1,102 @@
+## Contract Usage
+
+To have ability to interact with Aeternity Smart Contracts you need two things:
+ - Compiler
+ - Node
+ - SDK
+
+Let's look how to use SDK for that
+
+```js
+const { Universal: Ae, MemoryAccount, Node } = require('@aeternity/aepp-sdk')
+
+const NODE_URL;
+const NODE_INTERNAL_URL;
+const KEYPAIR;
+const CONTRACT_SOURCE;
+
+// same with async
+const main = async () => {
+  const node1 = await Node({ url: NODE_URL, internalUrl: NODE_INTERNAL_URL })
+  const acc = MemoryAccount({ keypair: KEYPAIR })
+
+  const sdkInstance = await Ae({
+      nodes: [
+        { name: 'testNet', instance: node },
+      ],
+      compilerUrl: 'COMPILER_URL',
+      accounts: [acc],
+      address: KEYPAIR.publicKey
+  })
+  const height = await client.height()
+  console.log('Current Block Height', height)
+
+  // Contract ACI. First of all we need to create a contract object
+  // contractAddress is optional
+  const contractObject = await sdkInstance.getContractInstance(CONTRACT_SOURCE, { contractAddress })
+  // 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
+  // which you will find in `contractObject.methods` object
+
+
+  // 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
+
+ // 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)
+
+ // 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})
+
+ // 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)
+}
+
+// call main
+main()
+```