Draft of update to taco shop tutorial

Author: timothymcmackin

gitlab-pages/docs/tutorials/getting-started/getting-started.md

@@ -575,4 +575,4 @@ octez-client get contract storage for counter
 Now you have a simple LIGO smart contract and can test it, deploy it, and call it.
 You can use it as a starting point to write your own contracts and experiment with LIGO.
 
-You can also continue with the [Taco shop tutorial](../taco-shop/tezos-taco-shop-smart-contract) to learn more about programming with LIGO.
+You can also continue with the [Taco shop tutorial](../taco-shop/selling-tacos) to learn more about programming with LIGO.

gitlab-pages/docs/tutorials/taco-shop/getting-payouts.md

@@ -0,0 +1,183 @@
+---
+title: "Part 3: Getting the payouts"
+---
+
+Now that the customer-facing entrypoint of the contract is ready, you can set up the administrator-related entrypoint.
+In this case, Pedro needs a way to reset the stock of tacos and send the tez from the contract to his account.
+You could do this in two entrypoints, but for simplicity this tutorial shows how to do both of these things in one entrypoint named `payout`.
+
+## Adding administrator information
+
+Also for the sake of simplicity, the contract will hard-code Pedro's account address.
+In production applications, the address of the administrator should be in the contract storage and an entrypoint should allow the current administrator to change the administrator address.
+As it is, this contract cannot change the administrator address after it is deployed, so use caution.
+
+1. In the contract, after the storage information, add a constant with the address of the owner:
+
+   ```jsligo skip
+   export const owner_address: address = "tz1TGu6TN5GSez2ndXXeDX6LgUDvLzPLqgYV";
+   ```
+
+   This is a made-up address for the purposes of the tutorial.
+   In a production application, you would set the administrator address in storage when you deploy the contract.
+   Note that the code defines the address as a LIGO `address` type; without the `: address` type declaration, LIGO would assume that it was a string.
+
+1. Add a function to get the administrator's account:
+
+   ```jsligo skip
+   const get_receiver_contract = () => match(Tezos.get_contract_opt(owner_address)) {
+     when(Some(contract)): contract;
+     when(None): failwith("Couldn't find account");
+   };
+   ```
+
+   Sending tez to a user account means treating the user account as though it was a smart contract account.
+   This way, sending tez to a user account works in the same way as sending tez to a smart contract.
+
+1. In the `payout` entrypoint, add this code to verify that the administrator is calling the entrypoint:
+
+   ```jsligo skip
+   // Ensure that only the admin can call this entrypoint
+   if (Tezos.get_sender() != owner_address) {
+     failwith("Only the admin can call this entrypoint");
+   }
+   ```
+
+1. Add this code to generate the operation that sends tez to the administrator account:
+
+   ```jsligo skip
+   const payout_operation = Tezos.Operation.transaction(unit, Tezos.get_balance(), get_receiver_contract());
+   ```
+
+   The `Tezos.Operation.transaction` function creates a Tezos transaction.
+   There are many kinds of internal transactions in Tezos, but most smart contracts deal with these transactions:
+
+      - Transferring tez to another account
+      - Calling an entrypoint on a smart contract
+
+   Calling an entrypoint on a smart contract (either the current contract or another contract) is beyond the scope of this tutorial.
+   For information, see [Calling a contract](../../syntax/contracts/operation#calling-a-contract).
+
+   The `Tezos.Operation.transaction` function takes these parameters:
+
+      1. The parameter to pass, in this case `unit`, which means no value
+      1. The amount of tez to include with the transaction, in this case all of the tez the contract has, denoted by the `Tezos.get_balance` function
+      1. The address of the target contract
+
+1. Replace the `payout` entrypoint's `return` statement with this code:
+
+   ```jsligo skip
+   return [[payout_operation], default_storage];
+   ```
+
+   Creating the transaction is not enough to run it; you must return it in the list of operations at the end of the entrypoint.
+
+The complete entrypoint looks like this:
+
+```jsligo skip
+@entry
+const payout = (_u: unit, _taco_data: taco_data): [
+    list<operation>,
+    taco_data
+  ] => {
+
+  // Ensure that only the admin can call this entrypoint
+  if (Tezos.get_sender() != owner_address) {
+    failwith("Only the admin can call this entrypoint");
+  }
+
+  const payout_operation = Tezos.Operation.transaction(unit, Tezos.get_balance(), get_receiver_contract());
+
+  return [[payout_operation], default_storage];
+}
+```
+
+That's all you need to do to reset the storage and send the contract's tez to the administrator.
+If you want to extend this logic, try separating the `payout` entrypoint into separate entrypoints for paying out the tez and resetting the stock of tacos.
+
+## Testing the new entrypoint
+
+Of course, after you implement the `payout` entrypoint, you should add tests for it.
+
+1. At the end of the test function, add this code to get the current balance of Pedro's account and the contract:
+
+   ```jsligo skip
+   // Test the payout entrypoint as the administrator
+   const owner_balance_before = Test.Address.get_balance(TacoShop.owner_address);
+   const contract_balance_before = Test.Typed_address.get_balance(contract.taddr);
+   ```
+
+1. Add this code to call the `payout` entrypoint and verify that the storage was updated, as in previous tests:
+
+   ```jsligo skip
+   const payoutResult =
+     Test.Contract.transfer(
+       Test.Typed_address.get_entrypoint("payout", contract.taddr),
+       unit,
+       0tez
+     );
+   match(payoutResult) {
+     when(Success(_s)):
+       do {
+         const storage = Test.Typed_address.get_storage(contract.taddr);
+         // Check that the stock has been reset
+         Assert.assert(
+           eq_in_map(
+             Map.find(1n, initial_storage),
+             storage,
+             1n
+           ));
+         Assert.assert(
+           eq_in_map(
+             Map.find(2n, initial_storage),
+             storage,
+             2n
+           ));
+         Test.IO.log("Successfully reset taco storage");
+       }
+     when(Fail(_err)): failwith("Failed to collect the payout");
+   };
+   ```
+
+1. Add this code to verify that Pedro's account received the tez from the contract:
+
+   ```jsligo skip
+   // Check that the balance of the contract was sent to the administrator
+   const owner_balance_after = Test.Address.get_balance(TacoShop.owner_address);
+   Assert.assert(owner_balance_before + contract_balance_before == owner_balance_after);
+   ```
+
+1. Add this code to generate a test account and verify that it can not call the `payout` entrypoint because it is not the administrator:
+
+   ```jsligo skip
+   // Verify that the entrypoint fails if called by someone else
+   const other_user_account = Test.Account.address(1n);
+   Test.State.set_source(other_user_account);
+   const failedPayoutResult =
+     Test.Contract.transfer(
+       Test.Typed_address.get_entrypoint("payout", contract.taddr),
+       unit,
+       0tez
+     );
+   match(failedPayoutResult) {
+     when(Success(_s)): failwith("A non-admin user was able to call the payout entrypoint");
+     when(Fail(_err)): Test.IO.log("Successfully prevented a non-admin user from calling the payout entrypoint");
+   };
+   ```
+
+1. Run the test with `ligo run test taco_shop.jsligo` and verify that the test runs successfully.
+
+Now you can allow different users to do different things in the contract.
+
+## Conclusion
+
+Now you have a contract that Pedro can use to sell tacos and manage the profits and the taco stock.
+From here you can expand the contract in many ways, such as:
+
+- Adding more types of tacos
+- Changing how the price of tacos is calculated
+- Expanding the administrator functionality
+- Accepting more than the price of the taco as a tip
+- Adding more tests
+
+You can also try deploying the contract to a test network and trying it in a real Tezos environment.