refine

Author: polarker

docs/dapps/tutorials/dapp-recipes.md

@@ -258,80 +258,3 @@ const testResult1 = await TokenFaucet.tests.withdraw({
 const contractState1 = testResult1.contracts[0] as TokenFaucetTypes.State
 expect(contractState1.fields.balance).toEqual(8n)
 ```
-
-## Call TxScript
-
-Call `TxScript` is a feature that allows interaction with smart contracts on Alephium without consuming gas and modifying the on-chain state. Instead, it executes scripts and returns updated contract states.
-
-### Call contract functions
-
-```rust
-Contract Foo(mut value: U256) {
-  @using(updateFields = true, checkExternalCaller = false)
-  pub fn foo() -> () {
-    value = value + 1
-  }
-}
-
-@using(preapprovedAssets = false)
-TxScript Main(foo: Foo) {
-  foo.foo()
-}
-```
-
-You can use the generated `TypeScript` code to call `TxScript`:
-
-```typescript
-import { getSigner } from '@alephium/web3-test'
-
-const signer = await getSigner()
-const deployFooResult = await Foo.deploy(signer, { initialFields: { value: 0n } })
-const fooInstance = deployFooResult.contractInstance
-const callResult = await Main.call({
-  initialFields: { foo: fooInstance.contractId },
-  interestedContracts: [fooInstance.address]
-})
-expect(callResult.contracts[0].fields.value).toEqual(1n)
-```
-
-### Query and return contract states
-
-`TxScript` also allows you to query and return the states of multiple contracts in a single request:
-
-```rust
-Contract Foo(value: U256) {
-  pub fn foo() -> U256 {
-    return value
-  }
-}
-
-Contract Bar(value: ByteVec) {
-  pub fn bar() -> ByteVec {
-    return value
-  }
-}
-
-TxScript Main(foo: Foo, bar: Bar) {
-  pub fn main() -> (U256, ByteVec) {
-    return foo.foo(), bar.bar()
-  }
-}
-```
-
-Implicit definition of the `main` function does not allow for return values, so an explicit definition of the `main` function is required here.
-
-You can use the generated `TypeScript` code to call `TxScript`:
-
-```typescript
-import { getSigner } from '@alephium/web3-test'
-
-const signer = await getSigner()
-const deployFooResult = await Foo.deploy(signer, { initialFields: { value: 0n } })
-const deployBarResult = await Bar.deploy(signer, { initialFields: { value: '0011' } })
-const fooInstance = deployFooResult.contractInstance
-const barInstance = deployBarResult.contractInstance
-const callResult = await MainForCall.call({
-  initialFields: { foo: fooInstance.contractId, bar: barInstance.contractId }
-})
-expect(callResult.returns).toEqual([0n, '0011'])
-```

docs/ralph/contracts.md

@@ -337,10 +337,12 @@ TxScript Main(foo: Foo) {
 }
 ```
 
-The `main` function of `TxScript` serves as the entry point for contract code execution. It supports both explicit and implicit definitions of the `main` function:
+### Implicit and Explicit Main Function
 
-1. Implicit definition of the `main` function, in the example above, the compiler automatically generates a `main` function for the `TxScript`.
-2. Explicit definition of the `main` function:
+The `main` function in `TxScript` serves as the entry point for contract code execution. TxScript supports both implicit and explicit definitions of the `main` function:
+
+1. Implicit definition: When Ralph statements are present in the script body,, the compiler automatically generates a `main` function for the `TxScript`.
+2. Explicit definition:
 
 ```rust
 TxScript Main(foo: Foo) {
@@ -352,7 +354,7 @@ TxScript Main(foo: Foo) {
 }
 ```
 
-The explicitly defined `main` function cannot have parameters. If you need to specify parameters, you can pass them as parameters of the `TxScript`.
+In an explicit definition, the `main` function cannot accept parameters directly. If parameters are needed, they should be passed as fields of the `TxScript`.
 
 ## Gasless Transaction
 

docs/sdk/interact-with-contracts.md

@@ -105,6 +105,8 @@ the contract states: `getTotalSupply`, `getSymbol`, `getName`,
 `getDecimals` and `balance`. It also has a function called `withdraw`,
 which not only updates the contract state, but also transfers assets.
 
+## Deploying Contracts
+
 After `TokenFaucet` contract is
 [compiled](/dapps/tutorials/quick-start#compile-your-contract), a
 corresponding Typescript class is generated. We can get an instance of
@@ -142,44 +144,11 @@ You can use `<contractInstance>.fetchState()` to get the current fields of the t
 const state = await tokenFaucet.fetchState()
 ```
 
-## Contract Views
-
-Inside of the `TokenFaucet` typescript class, [Typescript
-SDK](/sdk/getting-started) generates the read-only `view` methods for
-all functions in the `TokenFaucet` contract. `view` methods do not
-update the blockchan state, they can be called just like regular
-typescript functions:
-
-```typescript
-const getNameResult = await tokenFaucet.view.getName()
-console.log(`name: ${hexToString(getNameResult.returns)}`)  // name: TokenFaucet
-
-const getDecimalsResult = await tokenFaucet.view.getDecimals()
-console.log(`decimals: ${getDecimalsResult.returns)}`)      // decimals: 18
-```
-
-Note that results of the `view` methods are returned immediately and
-there is no gas or signatures required.
-
-[Typescript SDK](/sdk/getting-started) also generates code for calling
-multiple functions at the same time, reducing the number of network
-requests:
-
-```typescript
-const result = await tokenFaucet.multicall({
-  getSymbol: {},
-  getName: {},
-  getDecimals: {},
-  getTotalSupply: {}
-})
+## Interact With Contracts
 
-console.log(`name: ${hexToString(result.getName.returns)}`)       // name: TokenFaucet
-console.log(`symbol: ${hexToString(result.getSymbol.returns)}`)   // symbol: TF
-console.log(`decimals: ${result.getDecimals.returns}`)            // decimals: 18
-console.log(`total supply: ${result.getTotalSupply.returns}`)     // total supply: 10
-```
+We can interact with contracts either by sending transactions or by calling contract methods locally without publishing anything onchain.
 
-## TxScript Transactions
+### TxScript Transactions
 
 `TokenFaucet` contract also has a function called `withdraw`, which
 transfers the token from the faucet to the caller and updates the
@@ -226,9 +195,10 @@ non-deterministic depending on the future state of the blockchain when
 the transaction is mined. `Events` are instead often used to gain insights
 into the contract activities.
 
-## Contract Transact Methods
+### Transact Methods
 
-[Typescript SDK](/sdk/getting-started) also generates the `transact`
+Inside of the `TokenFaucet` typescript class, [Typescript
+SDK](/sdk/getting-started) generates the `transact`
 methods for all functions in the `TokenFaucet` contract to simplify
 the scenario where user wants to perform a `TxScript` transaction by
 only calling a function in the contract. For example, the following
@@ -248,6 +218,90 @@ generates bytecode for the corresponding `TxScript` and executes
 it. Note that `TxScript` is still required for more complicated
 scenarios.
 
+### View Methods
+
+[Typescript SDK](/sdk/getting-started) also generates the read-only `view` methods for
+all functions in the `TokenFaucet` contract. `view` methods do not
+update the blockchain state, they can be called just like regular
+typescript functions:
+
+```typescript
+const getNameResult = await tokenFaucet.view.getName()
+console.log(`name: ${hexToString(getNameResult.returns)}`)  // name: TokenFaucet
+
+const getDecimalsResult = await tokenFaucet.view.getDecimals()
+console.log(`decimals: ${getDecimalsResult.returns}`)      // decimals: 18
+```
+
+Note that results of the `view` methods are returned immediately and
+there is no gas or signatures required.
+
+[Typescript SDK](/sdk/getting-started) also generates code for calling
+multiple functions at the same time, reducing the number of network
+requests:
+
+```typescript
+const result = await tokenFaucet.multicall({
+  getSymbol: {},
+  getName: {},
+  getDecimals: {},
+  getTotalSupply: {}
+})
+
+console.log(`name: ${hexToString(result.getName.returns)}`)       // name: TokenFaucet
+console.log(`symbol: ${hexToString(result.getSymbol.returns)}`)   // symbol: TF
+console.log(`decimals: ${result.getDecimals.returns}`)            // decimals: 18
+console.log(`total supply: ${result.getTotalSupply.returns}`)     // total supply: 10
+```
+
+### Call TxScript Locally
+
+The `Call TxScript` feature allows interaction with smart contracts on Alephium without consuming gas and modifying the on-chain state. Instead, it executes scripts and returns updated contract states and the return values of the `TxScript` entry function.
+
+```rust
+Contract Foo(mut value: U256) {
+  pub fn foo() -> U256 {
+    value = value + 1
+    return value
+  }
+}
+
+Contract Bar(value: ByteVec) {
+  pub fn bar() -> ByteVec {
+    return value
+  }
+}
+
+// This TxScript uses explicit main function. In most cases, the main functions are implicit
+TxScript Main(foo: Foo, bar: Bar) {
+  pub fn main() -> (U256, ByteVec) {
+    return foo.foo(), bar.bar()
+  }
+}
+```
+
+Implicit `main` functions do not allow for return values, so an explicit definition of the `main` function is required here.
+More info about `main` function can be found [here](/ralph/contracts#implicit-and-explicit-main-function).
+
+You can use the generated `TypeScript` code to call `TxScript` locally:
+
+```typescript
+import { getSigner } from '@alephium/web3-test'
+
+const signer = await getSigner()
+const deployFooResult = await Foo.deploy(signer, { initialFields: { value: 0n } })
+const deployBarResult = await Bar.deploy(signer, { initialFields: { value: '0011' } })
+const fooInstance = deployFooResult.contractInstance
+const barInstance = deployBarResult.contractInstance
+const callResult = await MainForCall.call({
+  initialFields: { foo: fooInstance.contractId, bar: barInstance.contractId },
+  interestedContracts: [ fooInstance.address, barInstance.address ]
+})
+expect(callResult.contracts[0].fields.value).toEqual(1n)
+expect(callResult.contracts[1].fields.value).toEqual('0011')
+expect(callResult.returns).toEqual([0n, '0011'])
+```
+
 ## Events Subscription
 
 The `withdraw` function for `TokenFaucet` contract emits a `Withdraw`