update smart contract design patterns & smart contract security vulnerabilities (#1689)

* smart contract security documentation with new sections

* design patterns

* consistent cardano-cli commands era flags

* remove duplicate link

* cardano-cli era flags update

* refactor testnet docs and add redirects

* infrastructure docs refactor

* refactor core concepts & get started

* fix broken testnet links

* revert secure-workflow.md to staging to avoid merge conflict with #1690

* update redirects for additional path to running cardano node docs

Author: 0xBora

docs/build/integrate/overview.md

@@ -10,20 +10,23 @@ image: /img/og/og-developer-portal.png
 ![Integrate Cardano](/img/card-integrate-cardano-title.svg)
 
 ## Introduction
-Here we show you how to integrate Cardano into existing websites and services. 
+
+Here we show you how to integrate Cardano into existing websites and services.
 
 ## Integration Components
+
 - [Overview](/docs/get-started/infrastructure/node/cardano-components) of the different Cardano components.
 - [cardano-node](https://github.com/IntersectMBO/cardano-node) is the top level for the node and aggregates the other components from other packages: consensus, ledger and networking, with configuration, CLI, logging and monitoring.
 - [cardano-wallet](https://github.com/cardano-foundation/cardano-wallet) helps you manage ada. You can use it to send and receive payments on the Cardano blockchain via a http and cli interface.
-- [cardano-db-sync](https://github.com/IntersectMBO/cardano-db-sync) follows the Cardano chain and takes information from the chain and an internally maintained copy of ledger state. Data is then extracted from the chain and inserted into a PostgreSQL database. 
+- [cardano-db-sync](https://github.com/IntersectMBO/cardano-db-sync) follows the Cardano chain and takes information from the chain and an internally maintained copy of ledger state. Data is then extracted from the chain and inserted into a PostgreSQL database.
 - [cardano-graphql](https://github.com/cardano-foundation/cardano-graphql) a cross-platform, typed, and queryable API for Cardano.
-- [cardano-rosetta](https://github.com/cardano-foundation/cardano-rosetta-java) a multi-platform implementation of [Rosetta](https://www.rosetta-api.org) for Cardano, targeting the version defined in the [API docs](https://cardano-foundation.github.io/cardano-rosetta-java/api). 
+- [cardano-rosetta](https://github.com/cardano-foundation/cardano-rosetta-java) a multi-platform implementation of [Rosetta](https://www.rosetta-api.org) for Cardano, targeting the version defined in the [API docs](https://cardano-foundation.github.io/cardano-rosetta-java/api).
 - [cardano-addresses](https://github.com/IntersectMBO/cardano-addresses) provides mnemonic (backup phrase) creation, and conversion of a mnemonic to seed for wallet restoration, and address derivation functionalities.
 
 ## Tutorials
+
 - [Listening for ada payments](payments/listening-for-payments/overview) - learn different approaches to detect and confirm ada payments in your applications.
-- [Testnet Faucet](/docs/get-started/networks/testnets/testnet-faucet) - a service that provides test ada (tAda) to users of the Cardano testnets. 
+- [Testnet Faucet](/docs/get-started/networks/testnets) - a service that provides test ada (tAda) to users of the Cardano testnets.
 - [Sample queries](https://iohk.zendesk.com/hc/en-us/articles/4402395914009-Sample-cardano-rosetta-queries) for cardano-rosetta.
 - [Sample queries](https://iohk.zendesk.com/hc/en-us/articles/900000906566-Sample-cardano-graphql-queries) for cardano-graphql.
 

docs/build/integrate/payments/listening-for-payments/cardano-cli.md

@@ -19,7 +19,7 @@ For a higher-level approach with less infrastructure, check out the [Point of Sa
 :::note
 This guide assumes that you have basic understanding of `cardano-cli`, how to use it and that you have installed it into your system. Otherwise we recommend reading [Installing cardano-node](/docs/get-started/infrastructure/node/installing-cardano-node), [Running cardano-node](/docs/get-started/infrastructure/node/running-cardano.md) and [Get started with Cardano CLI](/docs/get-started/infrastructure/cardano-cli/basic-operations/get-started) guides first.
 
-This guide also assumes that you have `cardano-node` running in the background and connected to a [testnet network](/docs/get-started/networks/testnets/overview).
+This guide also assumes that you have `cardano-node` running in the background and connected to a [testnet network](/docs/get-started/networks/testnets).
 :::
 
 ## Use case

docs/build/integrate/payments/listening-for-payments/cardano-wallet.md

@@ -20,7 +20,7 @@ For a simpler approach without running any blockchain infrastructure, check out
 
 This guide assumes that you have basic understanding of `cardano-wallet`, how to use it and that you have installed it into your system. Otherwise we recommend reading [Installing cardano-node](/docs/get-started/infrastructure/node/installing-cardano-node), [Running cardano-node](/docs/get-started/infrastructure/node/running-cardano.md), [Installing cardano-wallet](/docs/get-started/infrastructure/cardano-wallet/cardano-wallet) and [Using cardano-wallet](/docs/get-started/infrastructure/cardano-wallet/using-cardano-wallet) guides first.
 
-This guide also assumes that you have `cardano-node` and `cardano-wallet` running in the background and connected to a [testnet network](/docs/get-started/networks/testnets/overview).
+This guide also assumes that you have `cardano-node` and `cardano-wallet` running in the background and connected to a [testnet network](/docs/get-started/networks/testnets).
 
 :::
 
@@ -203,7 +203,7 @@ var resp = await http.PostAsJsonAsync("wallets", new {
 
 #### Get unused wallet address to receive some payments
 
-We will get a **wallet address** to show to the customers and for them to send payments to the wallet. In this case we can use the address to request some `tAda` from the [Cardano Testnet Faucet](/docs/get-started/networks/testnets/testnet-faucet) and simulate a payment:
+We will get a **wallet address** to show to the customers and for them to send payments to the wallet. In this case we can use the address to request some `tAda` from the [Cardano Testnet Faucet](/docs/get-started/networks/testnets) and simulate a payment:
 
 <Tabs
   defaultValue="js"
@@ -592,7 +592,7 @@ The code is telling us that our current wallet has received a total of `0 lovela
 
 What we can do to simulate a successful payment is to send at least `1,000,000 lovelace` into the **wallet address** that we have just generated for this project. We show how you can get the **wallet address** via code in the examples above.
 
-Now simply send at least `1,000,000 lovelace` to this **wallet address** or request some `test ada` funds from the [Cardano Testnet Faucet](/docs/get-started/networks/testnets/testnet-faucet). Once complete, we can now run the code again and we should see a successful result this time.
+Now simply send at least `1,000,000 lovelace` to this **wallet address** or request some `test ada` funds from the [Cardano Testnet Faucet](/docs/get-started/networks/testnets). Once complete, we can now run the code again and we should see a successful result this time.
 
 <Tabs
   defaultValue="js"

docs/build/native-tokens/minting.md

@@ -98,7 +98,7 @@ export CARDANO_NODE_SOCKET_PATH="$HOME/TESTNET_NODE/socket/node.socket"
 You need to adjust the path on your setup and your socket path accordingly.
 
 ### Improve readability
-Since we've already answered all of the questions above, we will set variables on our terminal/bash to make readability a bit easier. First, we will specify a [testnet](/docs/get-started/networks/testnets/overview), either Pre-production:
+Since we've already answered all of the questions above, we will set variables on our terminal/bash to make readability a bit easier. First, we will specify a [testnet](/docs/get-started/networks/testnets), either Pre-production:
 ```bash
 testnet="--testnet-magic 1"
 ```
@@ -185,7 +185,7 @@ address=$(cat payment.addr)
 Submitting transactions always require you to pay a fee. Sending native assets also requires sending at least 1 ada.  
 So make sure the address you are going to use as the input for the minting transaction has sufficient funds. 
 
-For **testnets**, you can request funds through the [Testnet Faucet](/docs/get-started/networks/testnets/testnet-faucet).
+For **testnets**, you can request funds through the [Testnet Faucet](/docs/get-started/networks/testnets).
 
 ### Export protocol parameters
 

docs/build/smart-contracts/advanced/design-patterns/enum-redeemers.md

@@ -1,8 +1,8 @@
 ---
-id: merkelized-validators
-title: Merkelized Validators
-sidebar_label: Merkelized Validators
-description: Circumvent validator script size limitations.
+id: merkelized-validator
+title: Merkelized Validator
+sidebar_label: Merkelized Validator
+description: Delegate logic to external withdrawal scripts to stay within size limits
 ---
 
 There are very tight execution budget constraints imposed on Plutus script evaluation; this, in combination with the fact that a higher execution budget
@@ -98,6 +98,42 @@ This is useful because with reference scripts this essentially gives us the abil
 
 Consider a batching architecture, with a very large `processOrders` function. Normally it would not be feasible to perform recursion unrolling / inlining optimizations with such a function since it would quickly exceed the max script size limit; however, with this design pattern we simply move `processOrders` into its own validator script which we can fill with 16kb of loop unrolling and other powerful optimizations which increase script size in order to reduce ExUnits. We provide this new script as a reference script when executing our main validator. Then in our main validator we verify that the `processOrders` validator was executed with the expected redeemer (`inputState` must match the arguments we want to pass to `processOrders`) after which have access to the result of the optimized `processOrders` function applied to our inputs.
 
+## Aiken Implementation
+
+Since transaction size is limited in Cardano, some validators benefit from a solution which allows them to delegate parts of their logics. This becomes more prominent in cases where such logics can greatly benefit from optimization solutions that trade computation resources for script sizes (e.g. table lookups can take up more space so that costly computations can be averted).
+
+This design pattern offers an interface for off-loading such logics into an external withdrawal script, so that the size of the validator itself can stay within the limits of Cardano.
+
 :::note
-You can find a sample implementation of a merkelized validator written in Aiken in this[repository](https://github.com/keyan-m/aiken-delegation-sample/blob/main/validators/main-contract.ak).
+Be aware that total size of reference scripts is currently limited to 200KiB (204800 bytes), and they also impose additional fees in an exponential manner. See [here](https://github.com/IntersectMBO/cardano-ledger/issues/3952) and [here](https://github.com/CardanoSolutions/ogmios/releases/tag/v6.5.0) for more info.
 :::
+
+### Using the Library
+
+The exposed `delegated_compute` function from `merkelized_validator` expects 4 arguments:
+
+1. The arbitrary input value for the underlying computation logic
+2. The hash of the withdrawal validator that performs the computation
+3. Validation function for coercing a `Data` to the format of the input expected by the staking script's computation
+4. The `Pairs` of all redeemers within the current script context
+
+This function expects to find the given stake validator in the `redeemers` list, such that its redeemer is of type `WithdrawRedeemerIO` (which carries the generic input argument(s) and the expected output(s)), makes sure provided input(s) match the ones given to the validator through its redeemer, and returns the output(s) (which are carried inside the withdrawal redeemer) so that you can safely use them.
+
+### Withdrawal Script (Computation Logic)
+
+For defining a withdrawal logic that carries out the computation, use the exposed `withdraw_io` function. It expects 2 arguments:
+
+1. The computation itself. It has to take an argument of type `a`, and return a value of type `b`
+2. A redeemer of type `WithdrawRedeemerIO<a, b>`. Note that `a` is the type of input argument(s), and `b` is the type of output argument(s)
+
+It validates that the given input(s) and output(s) match correctly with the provided computation logic.
+
+There are also `WithdrawRedeemer<a>`, `withdraw` and `delegated_validation` variants which can be used for validations that don't return any outputs.
+
+## Example Code
+
+Full working example: [merkelized-validator.ak](https://github.com/Anastasia-Labs/aiken-design-patterns/blob/main/validators/examples/merkelized-validator.ak)
+
+Library implementation: [merkelized_validator module](https://github.com/Anastasia-Labs/aiken-design-patterns/blob/main/lib/aiken-design-patterns/merkelized-validator.ak)
+
+Additional sample: [aiken-delegation-sample](https://github.com/keyan-m/aiken-delegation-sample/blob/main/validators/main-contract.ak)