Merge pull request #69 from ten-protocol/tudor/update_dev_qs

tudor-malene · web-flow · commit 1c35120c702f · 2024-12-13T08:08:37.000Z
improve dev quick start
diff --git a/docs/introduction/developer-quickstart.md b/docs/introduction/developer-quickstart.md
@@ -2,38 +2,39 @@
 sidebar_position: 4
 ---
 
-# Migrate your dApp to Ten
-Migrating to Ten is a straightforward process that immediately unlocks "Programmable Encryption".
+# Migrate your dApp to TEN
 
-There are a couple of changes you need to make:
+Migrating to TEN enables your dApp to leverage "Programmable Encryption". Below are steps to help you transition smoothly.
 
-1. Change your hardhat deployment script so that you can use `--network ten`.
-2. Add logic to your view functions to protect data (if needed).
-3. Configure event log visibility (if needed).
-4. Add a widget to your javascript UI to onboard Ten users.
+### Key Migration Steps
+
+1. Update your Hardhat deployment to support the `--network ten` option.
+2. Add data protection logic to your view functions (if applicable).
+3. Configure visibility rules for event logs and internal storage.
+4. Add the TEN onboarding widget to your JavaScript UI.
 
 ## 1. Configuring Hardhat
 
-To begin building on Ten, you can start by setting up a Hardhat project as usual.
+First, set up a Hardhat project if you haven't already.
 
-### 1.1 Installing the Ten Hardhat Plugin
+### 1.1 Installing the TEN Hardhat Plugin
 
-To integrate the Ten Network into your Hardhat project, install the ten-hardhat-plugin:
+To add TEN Network compatibility, install the `ten-hardhat-plugin`:
 
 ```bash
 npm install ten-hardhat-plugin
 ```
 
-Note: Plugins can be installed using `npm` or `yarn`.
+_You can use `npm` or `yarn` to install plugins._
 
-### 1.2 Configuring `hardhat.config.js` for the Ten Testnet
+### 1.2 Configuring `hardhat.config.js`
 
-Open `hardhat.config.js` in your project's root directory and configure it in the following way:
+Modify `hardhat.config.js` in your project’s root directory as follows:
 
 ```javascript
-import {HardhatUserConfig} from "hardhat/config";
+import { HardhatUserConfig } from "hardhat/config";
 import "@nomiclabs/hardhat-waffle";
-import 'ten-hardhat-plugin'
+import "ten-hardhat-plugin";
 
 module.exports = {
   solidity: "0.8.10",
@@ -42,35 +43,37 @@ module.exports = {
         // Configuration for the Hardhat Network
     },
     ten: {
-        url: "https://testnet.ten.xyz/v1/", 
-        chainId: 443, 
+        url: "https://testnet.ten.xyz/v1/",
+        chainId: 443,
         accounts: ["your-private-key"],
     },
   },
 };
 
 export default config;
 ```
-Now, you can start writing or migrating the smart contracts.
 
-# 2. Writing Smart Contracts
+Once configured, you can start writing or migrating your smart contracts.
 
-Ten performs bytecode execution in the EVM identically to Ethereum, allowing developers to leverage their existing codebase and tools.
+## 2. Writing Smart Contracts for TEN
 
-The main difference is that, during execution, private variables and the internal state of the contract are hidden from everyone, including node operators and the sequencer.
-This is a major advantage that represents "Programmable Privacy".
+TEN executes smart contracts within the EVM similarly to Ethereum, so you can reuse your existing code. 
+However, the execution and the internal state are hidden from everyone, including node operators and the sequencer.
 
 :::info
-In Ten, the internal node database is encrypted, and the execution itself is also encrypted inside the TEE.
+TEN encrypts both the execution and its internal database using Trusted Execution Environments (TEEs).
 :::
 
-The calls to [getStorageAt](https://docs.alchemy.com/reference/eth-getstorageat) are disabled by default, so all data access will be performed through view functions which are under the control of the smart contract developer. Note that public variables are accessible to everyone because Solidity automatically generates a getter function for them.
+The [getStorageAt](https://docs.alchemy.com/reference/eth-getstorageat) method is disabled by default on TEN, so data access relies on view functions that you define. 
+Public variables remain accessible as Solidity automatically creates getters for them.
+
+Let's illustrate with a basic storage dApp example where users can store and retrieve a number.
 
-We'll illustrate how this works by creating a simple data storage example. In this dApp, users can store a number and retrieve it later.
+At every step, we'll add a new feature and explain the difference between `TEN` and `Ethereum`.
 
-## Step 1: Declaring a Public Variable
+## Step 1: Basic contract with a Public Variable
 
-### Code:
+### Code
 
 ```solidity
 // SPDX-License-Identifier: MIT
@@ -85,13 +88,17 @@ contract StorageExample {
 }
 ```
 
-### Explanation:
+### Explanation
+
+In this step, we created a public variable `storedValues` that maps the provided value to the address of the user who called the `storeValue` function. 
 
-In this step, we've declared a public variable `storedValues`. Solidity automatically generates a public getter view function for it, so on both Ethereum and Ten, you can call this view function without any restrictions. We also created a function that allows users to store a value against their address.
+Because the variable is public, Solidity will provide a default public getter for it. 
 
-## Step 2: Transitioning to a Private Variable with a Getter Function
+Since there are no data access restrictions, on both Ethereum and TEN, everyone will be able to read the values of all users.
 
-### Code:
+## Step 2: Converting to a Private Variable with an explicit Getter Function
+
+### Code
 
 ```solidity
 contract StorageExample {
@@ -107,19 +114,18 @@ contract StorageExample {
 }
 ```
 
-### Explanation:
+### Explanation
 
-We've now made our data variable private, meaning it can't be accessed directly from outside the contract. To fetch its value, we've provided a custom public view function `getValue` where the user provides the address. On both Ethereum and Ten, if you call this function you will retrieve the number stored by that address.
+The `storedValues` variable is now private, and we added a basic `getValue` function for users to retrieve their value. 
 
-:::caution
-In Ethereum, the `_storedValues` variable can also be accessed directly using the `getStorageAt` method, but not in Ten.
-:::
+On both Ethereum and TEN, anyone can call `getValue` to retrieve any value.   
+On Ethereum, `_storedValues` can also be accessed directly with `getStorageAt`
 
-## Step 3: Implementing Data Access Control 
+## Step 3:  Data Access Control
 
-In this step, we aim to restrict users to only access their own value. This feature can only be implemented in Ten because as mentioned above, `_storedValues` is not hidden in Ethereum.
+In this step, we'll add restrictions so users can only access their own data. 
 
-### Code:
+### Code
 
 ```solidity
 contract StorageExample {
@@ -136,21 +142,23 @@ contract StorageExample {
 }
 ```
 
-### Explanation:
+### Explanation
 
-Since `getValue` is the only function which exposes the values, we can add a check like this: `require(tx.origin == account, "Not authorized!");` If anyone, other than the original account, asks for the value, they will get an error.
+The key line is: ``require(tx.origin == account, "Not authorized!");``, which ensures that the caller of the view function is the owner of the data.
 
 :::info
-In Ethereum, since all data is accessible anyway, there is no need to sign calls to view functions, so `tx.origin` can be spoofed.
+TEN uses  "Viewing Keys" to authenticate view function calls.
 :::
 
-In Ten, the platform ensures that calls to view functions are authenticated, which means that behind the scenes, there is a "Viewing Key" signature of the `tx.origin` address.
+**When deployed on TEN, this code guarantees that all users can only access their own values, and nobody can read the `_storedValues`.**
+
+## Step 4: Emitting Events - Default Visibility
 
-## Step 4: Emitting Events - Default visibility
+Event logs notify UIs about state changes in smart contracts. 
 
-Events in Ethereum are crucial for UIs to react to smart contract state changes. In this step, we'll emit an event when a user stores a value. We'll also gauge the popularity of our contract by emitting an event when certain milestones are reached.
+To improve our smart contract, we’ll emit an event when a user stores a value and milestone events when a specific size threshold is met.
 
-### Code:
+### Code
 
 ```solidity
 contract StorageExample {
@@ -176,50 +184,38 @@ contract StorageExample {
 }
 ```
 
-### Explanation:
+### Explanation
 
-On Ethereum, events are visible to anyone. For example, you can subscribe to the `DataChanged` event and receive notifications in real time about the data of everyone else. 
+Notice how we defined the two events: `DataChanged` and `MilestoneReached`, and are emitting them in the `storeValue` function.
 
-The programmable encryption of Ten allows you full control over visibility but also has sensible defaults. 
-Event logs can be queried using `eth_getLogs` or subscribed to using the `logs` endpoint. Both these calls are authenticated, and the platform makes sure to return only visible logs.
+In Ethereum, everyone can query and subscribe to these events. This obviously can't be the case for TEN because it would completely break the functionality.
 
-In our case, the requirements are very simple and common sense:
+Notice how in this version, we have no configuration for event log visibility, so we are relying on the default rules.
 
-- The `DataChanged` event is specific to an account, so it should only be received by that user.
-- `MilestoneReached`, on the other hand, is intended for everyone, as we want to show how popular our contract is.
+Rule 1: Event logs that contain EOAs as indexed fields (topics) are only visible to those EOAs.
+Rule 2: Event logs that don't contain any EOA are visible to everyone.
 
-The behaviour you desire is to restrict the visibility of `DataChanged`, but not that of `MilestoneReached`. **Which is exactly how it works by default!**
+In our case, the default rules ensure that:
+- `DataChanged` is visible only to the address that is storing the value.
+- `MilestoneReached` is publicly visible.
 
-Default behaviour:
 
-- `DataChanged` - has an address as a topic (an indexed field), which instructs the platform that the event log is only visible to that address.
-- `MilestoneReached` - has no address topic which by default means it is visible to everyone.
+## Step 5: Customizing Event Visibility
 
-All you have to do is emit events as usual, and the platform applies common-sense visibility rules.
+The default visibility rules are a good starting point, but complex dApps require greater flexibility. 
 
+TEN give you explicit control over event visibility. 
 
-## Step 5: Emitting Events - Configuring visibility
-
-Once you prepare your application for production, you will want explicit control over the event visibility.
-
-### Code:
+### Code
 
 ```solidity
 interface ContractTransparencyConfig {
-    enum Field {
-        TOPIC1, TOPIC2, TOPIC3,
-        SENDER,  // tx.origin - msg.sender
-        EVERYONE // the event is public - visible to everyone
-    }
-
-    enum ContractCfg {
-        TRANSPARENT, // internal state via getStorageAt is accessible to everyone, all events are public
-        PRIVATE      // internal state is hidden, and events can be configured individually
-    }
+    enum Field { TOPIC1, TOPIC2, TOPIC3, SENDER, EVERYONE }
+    enum ContractCfg { TRANSPARENT, PRIVATE }
 
     struct EventLogConfig {
-        bytes32 eventSignature; // the event signature hash
-        Field[] visibleTo;      // list of fields denoting who can see the event when private
+        bytes32 eventSignature;
+        Field[] visibleTo;
     }
 
     struct VisibilityConfig {
@@ -230,7 +226,7 @@ interface ContractTransparencyConfig {
     function visibilityRules() external pure returns (VisibilityConfig memory);
 }
 
-contract StorageExample is ContractTransparencyConfig{
+contract StorageExample is ContractTransparencyConfig {
     mapping(address => uint256) private _storedValues;
     uint256 private totalCalls = 0;
 
@@ -254,14 +250,14 @@ contract StorageExample is ContractTransparencyConfig{
     function visibilityRules() external pure override returns (VisibilityConfig memory) {
         EventLogConfig[]  memory eventLogConfigs = new EventLogConfig[](2);
 
-        // the signagure of "event DataChanged(address indexed account, uint256 newValue);"
+        // the signature of "event DataChanged(address indexed account, uint256 newValue);"
         bytes32 dataChangedEventSig = hex"0xec851d5c322f7f1dd5581f7432e9f6683a8709a4b1ca754ccb164742b82a7d2f";
         Field[]  memory relevantTo = new Field[](2);
         relevantTo[0] = Field.TOPIC1;
         relevantTo[1] = Field.SENDER;
         eventLogConfigs[0] = EventLogConfig(dataChangedEventSig, relevantTo);
 
-        // the signagure of "event MilestoneReached(uint256 noStoredValues);"
+        // the signature of "event MilestoneReached(uint256 noStoredValues);"
         bytes32 milestoneReachedEventSig = hex"0xd41033274424d56dd572e7196fb4230cf4141d546b91fc00555cab8403965924";
         Field[]  memory relevantTo = new Field[](1);
         relevantTo[0] = Field.EVERYONE;
@@ -272,11 +268,16 @@ contract StorageExample is ContractTransparencyConfig{
 }
 ```
 
-### Explanation:
+### Explanation
+
+The `ContractTransparencyConfig` interface is known by the TEN platform. 
+When a contract is deployed, the platform will call the `visibilityRules` function, and store the `VisibilityConfig`.
 
-By implementing the `ContractTransparencyConfig.visibilityRules` method you can configure the visibility concerns of the current contract.
+For each event type, you can configure which fields can access it. 
+This allows the developer to configure an event to be public even if it has EOAs or to allow the sender of the transaction to access events emitted even if the address is not in the event.  
 
-A `ContractCfg.PUBLIC` contract behaves exactly like a contract deployed on Ethereum. The storage slots are exposed, and all contracts are public.
+Notice how in the `visibilityRules` above, we configure the `DataChanged` event to be visible to the first field and the sender, and the `MilestoneReached` to be visible to everyone. 
 
-For private contracts, you can configure the visibility of each individual event type you're emitting by specifying the "fields" that can receive it. 
-`Field.EVERYONE` means that this is a public event.
+The other configuration: `VisibilityConfig.contractCfg` applies to the entire contract:
+- `ContractCfg.TRANSPARENT`: The contracts will have public storage and events, behaving exactly like Ethereum.
+- `ContractCfg.PRIVATE`: The default TEN behaviour, where the storage is not accessible and the events are individually configurable.
