API to approve ERC20 on a different contract

docs/API.md

@@ -35,6 +35,37 @@ Every method in this class sends an RPC message to the wrapper.
 
 The app communicates with the wrapper using a messaging provider. The default provider uses the [MessageChannel PostMessage API](https://developer.mozilla.org/en-US/docs/Web/API/MessagePort/postMessage), but you may specify another provider to use (see the exported [providers](/docs/PROVIDERS.md) to learn more about them). You will most likely want to use the [`WindowMessage` provider](/docs/PROVIDERS.md#windowmessage) in your frontend.
 
+### Parameters
+
+- `provider` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** (optional, default `MessagePortMessage`): A provider used to send and receive messages to and from the wrapper. See [providers](/docs/PROVIDERS.md).
+
+### Examples
+
+```javascript
+import AragonApp, { providers } from '@aragon/api'
+
+// The default provider should be used in background scripts
+const backgroundScriptOfApp = new AragonApp()
+
+// The WindowMessage provider should be used for front-ends
+const frontendOfApp = new AragonApp(new providers.WindowMessage(window.parent))
+```
+
+> **Note**<br>
+> Most of the returned observables will propagate errors from `@aragon/wrapper` (e.g. the Aragon client) if an RPC request failed. An example would be trying to use `api.call('nonexistentFunction')`. Multi-emission observables (e.g. `api.accounts()`) will forward the error without stopping the stream, leaving the subscriber to handle the error case.
+
+> **Note**<br>
+> Although many of the API methods return observables, many of them are single-emission observables that you can turn directly into a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). While this is seen as an "antipattern" by experienced RxJS users, it is highly convenient when you're not working fully in the context of streams and just need a particular async value (e.g. `api.call('getVoteDetails', voteId)`). The Aragon One team recommends this approach when first developing your apps if you are not already experienced with RxJS.
+>
+> You can use the [`.toPromise()`](https://rxjs-dev.firebaseapp.com/api/index/class/Observable#toPromise) method on all single-emission observables safely (e.g. `await api.call('getVoteDetails', voteId).toPromise()`). If you receive a multi-emission observable (e.g. `api.accounts()`) but only care about its current value, you can use the [`first()`](https://rxjs-dev.firebaseapp.com/api/operators/first) operator, e.g. `api.accounts().pipe(first()).toPromise()`.
+
+> **Note**<br>
+> All methods returning observables will only send their RPC requests upon the returned observable being subscribed. For example, calling `api.increment()` will **NOT** send an intent until you have subscribed to the returned observable. This is to ensure that responses cannot be accidentally skipped.
+>
+> If you're not interested in the response, you can either make an "empty" subscription (i.e. `api.increment().subscribe()`), or turn it into a promise and await it (i.e. `await api.increment().toPromise()`).
+
+### intents
+
 To send an intent to the wrapper (i.e. invoke a method on your smart contract), simply call it on the instance of this class as if it was a JavaScript function.
 
 For example, to execute the `increment` function in your app's smart contract:
@@ -51,15 +82,28 @@ api
   )
 ```
 
-The intent function returns an [RxJS observable](https://rxjs-dev.firebaseapp.com/api/index/class/Observable) that emits the hash of the transaction that was sent or an error if the user choose not to sign the transaction.
+The intent function returns a single-emission [RxJS observable](https://rxjs-dev.firebaseapp.com/api/index/class/Observable) that emits the hash of the transaction that was sent or an error if the user choose not to sign the transaction.
 
-You can also pass an optional object after all the required function arguments to specify some values that will be sent in the transaction. They are the same values that can be passed to `web3.eth.sendTransaction()` and can be checked in this [web3.js document](https://web3js.readthedocs.io/en/1.0/web3-eth.html#id62).
+You can also pass an optional object after all the required function arguments to specify some transaction options. They are the same values that can be passed to `web3.eth.sendTransaction()` and the full list can be seen in the [web3.js documentation](https://web3js.readthedocs.io/en/1.0/web3-eth.html#id62).
 
 ```js
 api.increment(1, { gas: 200000, gasPrice: 80000000 })
 ```
 
-You can include a `token` parameter in this optional object if you need to do a token approval before a transaction. A slightly modified [example](https://github.com/aragon/aragon-apps/blob/master/apps/finance/app/src/App.js#L79) from the Finance app:
+Some caveats to customizing transaction parameters:
+
+- `from`, `to`, `data`: will be ignored as aragonAPI will calculate those.
+- `gas`: If the intent cannot be performed directly (needs to be forwarded), the gas amount will be interpreted as the minimum amount of gas to send in the transaction. Because forwarding performs a heavier transaction gas-wise, if the gas estimation done by aragonAPI results in more gas than provided in the parameter, the estimated gas will prevail.
+
+#### Pretransactions
+
+> **Note**<br>
+> Some intents may require additional transactions ahead of the actual intent, such as a token approval if the intent is to transfer tokens on the user's behalf.
+> We use the concept of "pretransactions" to allow apps to easily declare that they require these actions.
+
+**Token Approvals**
+
+You can include a `token` parameter in the final options object if you need to grant the app an token allowance before a transaction. A slightly modified [example](https://github.com/aragon/aragon-apps/blob/7d61235044509095db09cf354f38422f0778d4bb/apps/finance/app/src/App.js#L58) from the Finance app:
 
 ```js
 intentParams = {
@@ -70,40 +114,17 @@ intentParams = {
 api.deposit(tokenAddress, amount, reference, intentParams)
 ```
 
-Some caveats to customizing transaction parameters:
-
-- `from`, `to`, `data`: will be ignored as aragon.js will calculate those.
-- `gas`: If the intent cannot be performed directly (needs to be forwarded), the gas amount will be interpreted as the minimum amount of gas to send in the transaction. Because forwarding performs a heavier transaction gas-wise, if the gas estimation done by aragon.js results in more gas than provided in the parameter, the estimated gas will prevail.
-
-### Parameters
-
-- `provider` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** (optional, default `MessagePortMessage`): A provider used to send and receive messages to and from the wrapper. See [providers](/docs/PROVIDERS.md).
-
-### Examples
+If you want to grant the token allowance to a different contract from the current app, you can pass along a `spender` paramater in the `token` object as follows:
 
-```javascript
-import AragonApp, { providers } from '@aragon/api'
-
-// The default provider should be used in background scripts
-const backgroundScriptOfApp = new AragonApp()
+```js
+intentParams = {
+  token: { address: tokenAddress, value: amount, spender: otherContractAddress }
+  gas: 500000
+}
 
-// The WindowMessage provider should be used for front-ends
-const frontendOfApp = new AragonApp(new providers.WindowMessage(window.parent))
+api.deposit(tokenAddress, amount, reference, intentParams)
 ```
 
-> **Note**<br>
-> Most of the returned observables will propagate errors from `@aragon/wrapper` (e.g. the Aragon client) if an RPC request failed. An example would be trying to use `api.call('nonexistentFunction')`. Multi-emission observables (e.g. `api.accounts()`) will forward the error without stopping the stream, leaving the subscriber to handle the error case.
-
-> **Note**<br>
-> Although many of the API methods return observables, many of them are single-emission observables that you can turn directly into a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). While this is seen as an "antipattern" by experienced RxJS users, it is highly convenient when you're not working fully in the context of streams and just need a particular async value (e.g. `api.call('getVoteDetails', voteId)`). The Aragon One team recommends this approach when first developing your apps if you are not already experienced with RxJS.
->
-> You can use the [`.toPromise()`](https://rxjs-dev.firebaseapp.com/api/index/class/Observable#toPromise) method on all single-emission observables safely (e.g. `await api.call('getVoteDetails', voteId).toPromise()`). If you receive a multi-emission observable (e.g. `api.accounts()`) but only care about its current value, you can use the [`first()`](https://rxjs-dev.firebaseapp.com/api/operators/first) operator, e.g. `api.accounts().pipe(first()).toPromise()`.
-
-> **Note**<br>
-> All methods returning observables will only send their RPC requests upon the returned observable being subscribed. For example, calling `api.increment()` will **NOT** send an intent until you have subscribed to the returned observable. This is to ensure that responses cannot be accidentally skipped.
->
-> If you're not interested in the response, you can either make an "empty" subscription (i.e. `api.increment().subscribe()`), or turn it into a promise and await it (i.e. `await api.increment().toPromise()`).
-
 ### accounts
 
 Get an array of the accounts the user currently controls over time.

packages/aragon-wrapper/src/rpc/handlers/intent.js

@@ -1,8 +1,8 @@
 export default async function (request, proxy, wrapper) {
   const transactionPath = await wrapper.getTransactionPath(
     proxy.address,
-    request.params[0],
-    request.params.slice(1)
+    request.params[0], // contract method
+    request.params.slice(1) // params
   )
 
   return wrapper.performTransactionPath(transactionPath)

packages/aragon-wrapper/src/utils/transactions.js

@@ -40,7 +40,7 @@ export async function createDirectTransaction (sender, app, methodName, params,
   }
 
   if (transactionOptions.token) {
-    const { address: tokenAddress, value: tokenValue } = transactionOptions.token
+    const { address: tokenAddress, value: tokenValue, spender } = transactionOptions.token
 
     const erc20ABI = getAbi('standard/ERC20')
     const tokenContract = new web3.eth.Contract(erc20ABI, tokenAddress)
@@ -62,11 +62,13 @@ export async function createDirectTransaction (sender, app, methodName, params,
         console.warn(`${sender} already approved ${destination}. In some tokens, approval will fail unless the allowance is reset to 0 before re-approving again.`)
       }
 
+      // Approve the app (destination) unless an spender is passed to approve a different contract
+      const approveSpender = spender || destination
       const tokenApproveTransaction = {
         // TODO: should we include transaction options?
         from: sender,
         to: tokenAddress,
-        data: tokenContract.methods.approve(destination, tokenValue).encodeABI()
+        data: tokenContract.methods.approve(approveSpender, tokenValue).encodeABI()
       }
 
       directTransaction.pretransaction = tokenApproveTransaction