update soroban doc

Author: christian-rogobete

CHANGELOG.md

@@ -1,3 +1,6 @@
+## [1.6.0] - 19.Jul.2023.
+- add soroban prev. 10 support
+
 ## [1.5.8] - 11.Jul.2023.
 - add SEP-24 support
 - 

README.md

@@ -11,7 +11,7 @@ The Soneso open source Stellar SDK for Flutter is build with Dart and provides A
 1. Add the dependency to your pubspec.yaml file:
 ```
 dependencies:
-  stellar_flutter_sdk: ^1.5.8
+  stellar_flutter_sdk: ^1.6.0
 ```
 2. Install it (command line or IDE):
 ```

documentation/sdk_api_doc.zip

@@ -31,7 +31,7 @@ import 'requests/liquidity_pools_request_builder.dart';
 
 /// Main class of the flutter stellar sdk.
 class StellarSDK {
-  static const versionNumber = "1.5.8";
+  static const versionNumber = "1.6.0";
 
   static final StellarSDK PUBLIC = StellarSDK("https://horizon.stellar.org");
   static final StellarSDK TESTNET = StellarSDK("https://horizon-testnet.stellar.org");

lib/src/stellar_sdk.dart

@@ -1,6 +1,6 @@
 name: stellar_flutter_sdk
 description: A stellar blockchain sdk that query's horizon, build, signs and submits transactions to the stellar network.
-version: 1.5.8
+version: 1.6.0
 homepage: https://github.com/Soneso/stellar_flutter_sdk
 
 environment:

pubspec.yaml

@@ -15,7 +15,7 @@ To deploy and/or invoke smart contracts with the Flutter SDK use the ```SorobanS
 
 Soroban-RPC can be simply described as a “live network gateway for Soroban”. It provides information that the network currently has in its view (i.e. current state). It also has the ability to send a transaction to the network and query the network for the status of previously sent transactions.
 
-You can install your own instance of a Soroban-RPC Server as described [here](https://soroban.stellar.org/docs/tutorials/deploy-to-futurenet). Alternatively, you can use a public remote instance for testing.
+You can install your own instance of a Soroban-RPC Server as described [here](https://soroban.stellar.org/docs/getting-started/deploy-to-futurenet). Alternatively, you can use a public remote instance for testing.
 
 The Soroban-RPC API is described [here](https://soroban.stellar.org/api/).
 
@@ -61,7 +61,7 @@ AccountResponse submitter = await sdk.accounts.account(submitterId);
 
 #### Deploy your contract
 
-If you want to create a smart contract for testing, you can easily build one with our [AssemblyScript Soroban SDK](https://github.com/Soneso/as-soroban-sdk) or with the [official Stellar Rust SDK](https://soroban.stellar.org/docs/examples/hello-world). Here you can find [examples](https://github.com/Soneso/as-soroban-examples) to be build with the AssemblyScript SDK.
+If you want to create a smart contract for testing, you can find the official examples [here](https://github.com/stellar/soroban-examples).
 
 There are two main steps involved in the process of deploying a contract. First you need to **upload** the **contract code** and then to **create** the **contract**.
 
@@ -73,7 +73,7 @@ UploadContractWasmHostFunction uploadFunction =
     UploadContractWasmHostFunction(contractCode);
 
 InvokeHostFunctionOperation operation =
-    (InvokeHostFuncOpBuilder()).addFunction(uploadFunction).build();
+          InvokeHostFuncOpBuilder(uploadFunction).build();
 
 // Build the transaction
 Transaction transaction =
@@ -128,13 +128,16 @@ if (GetTransactionResponse.STATUS_NOT_FOUND == status) {
 }
 ```
 
+Hint: If you experience an error with the transaction result ```txInternalError``` it is most likely that a ledger entry used in the transaction has expired. This is an issue specific to soroban prev. 10 (see [here](https://discord.com/channels/897514728459468821/1130347673627664515)). You can fix it by restoring the footprint (see this [example](https://github.com/Soneso/stellar_flutter_sdk/blob/9a15982ac862bdcab33713184c800065e573f39b/test/soroban_test.dart#L57) in the soroban test of the SDK).
+
 If the transaction was successful, the status response contains the ```wasmId``` of the installed contract code. We need the ```wasmId``` in our next step to **create** the contract:
 
 ```dart
 // Build the operation for creating the contract
-InvokeHostFunctionOperation operation = (InvokeHostFuncOpBuilder())
-    .addFunction(CreateContractHostFunction(wasmId))
-    .build();
+CreateContractHostFunction function = CreateContractHostFunction(
+    Address.forAccountId(accountId), contractWasmId);
+InvokeHostFunctionOperation operation =
+    InvokeHostFuncOpBuilder(function).build();
 
 // Build the transaction for creating the contract
 Transaction transaction = new TransactionBuilder(account)
@@ -144,9 +147,10 @@ Transaction transaction = new TransactionBuilder(account)
 SimulateTransactionResponse simulateResponse =
     await sorobanServer.simulateTransaction(transaction);
 
-// set transaction data, add resource fee and sign transaction
+// set transaction data, add resource fee & auth and sign transaction
 transaction.sorobanTransactionData = simulateResponse.transactionData;
 transaction.addResourceFee(simulateResponse.minResourceFee!);
+transaction.setSorobanAuth(simulateResponse.sorobanAuth);
 transaction.sign(accountKeyPair, Network.FUTURENET);
 
 // Send the transaction to the network.
@@ -159,7 +163,7 @@ if (sendResponse.error == null) {
 }
 ```
 
-As you can see, we use the ```wasmId``` to create the operation and the transaction for creating the contract. After simulating, we obtain the footprint to be set in the transaction. Next, sign the transaction and send it to the Soroban-RPC Server. The transaction status will be "pending", so we need to wait a bit and poll for the current status:
+As you can see, we use the ```wasmId``` to create the operation and the transaction for creating the contract. After simulating, we obtain the transaction data and auth to be set in the transaction. Next, sign the transaction and send it to the Soroban-RPC Server. The transaction status will be "pending", so we need to wait a bit and poll for the current status:
 
 ```dart
 // Fetch transaction 
@@ -193,21 +197,15 @@ GetLedgerEntryResponse contractCodeEntry =
 
 Now, that we successfully deployed our contract, we are going to invoke it using the Flutter SDK.
 
-First let's have a look to a simple (hello word) contract created with the [AssemblyScript Soroban SDK](https://github.com/Soneso/as-soroban-sdk). The code and instructions on how to build it, can be found in this [example](https://github.com/Soneso/as-soroban-examples/tree/main/hello_word).
-
-*Hello Word contract AssemblyScript code:*
+First let's have a look to a simple (hello word) contract created with the Rust Soroban SDK. The code and instructions on how to build it, can be found in the official [soroban docs](https://soroban.stellar.org/docs/getting-started/hello-world).
 
-```typescript
-import {Symbol, VecObject, fromSmallSymbolStr} from 'as-soroban-sdk/lib/value';
-import {Vec} from 'as-soroban-sdk/lib/vec';
+*Hello Word contract code:*
 
-export function hello(to: Symbol): VecObject {
-
-  let vec = new Vec();
-  vec.pushFront(fromSmallSymbolStr("Hello"));
-  vec.pushBack(to);
-  
-  return vec.getHostObject();
+```rust
+impl HelloContract {
+    pub fn hello(env: Env, to: Symbol) -> Vec<Symbol> {
+        vec![&env, symbol_short!("Hello"), to]
+    }
 }
 ```
 
@@ -217,18 +215,18 @@ To invoke the contract with the Flutter SDK, we first need to build the correspo
 
 
 ```dart
-// Name of the method to be invoked
-String method = "hello";
+// Name of the function to be invoked
+String functionName = "hello";
 
 // Prepare the argument (Symbol)
 XdrSCVal arg = XdrSCVal.forSymbol("friend");
 
 // Prepare the "invoke" operation
 InvokeContractHostFunction hostFunction = InvokeContractHostFunction(
-    contractId!, functionName,arguments: [arg]);
+    contractId!, functionName, arguments: [arg]);
 
 InvokeHostFunctionOperation operation =
-    (InvokeHostFuncOpBuilder()).addFunction(hostFunction).build();
+        InvokeHostFuncOpBuilder(hostFunction).build();
 
 // Build the transaction
 Transaction transaction =
@@ -303,74 +301,75 @@ Success!
 
 #### Deploying Stellar Asset Contract (SAC)
 
-The Flutter SDK also provides support for deploying the build-in [Stellar Asset Contract](https://soroban.stellar.org/docs/built-in-contracts/stellar-asset-contract) (SAC). The following operations are available for this purpose:
+The Flutter SDK also provides support for deploying the build-in [Stellar Asset Contract](https://soroban.stellar.org/docs/advanced-tutorials/stellar-asset-contract) (SAC). The following operations are available for this purpose:
 
 1. Deploy SAC with source account:
 
 ```dart
-InvokeHostFunctionOperation operation = (InvokeHostFuncOpBuilder())
-    .addFunction(DeploySACWithSourceAccountHostFunction())
-    .build();
+DeploySACWithSourceAccountHostFunction function =
+    DeploySACWithSourceAccountHostFunction(
+        Address.forAccountId(accountId));
+
+InvokeHostFunctionOperation operation =
+    InvokeHostFuncOpBuilder(function).build();
+
+//...
+// set transaction data, add resource fee & auth and sign transaction
+transaction.sorobanTransactionData = simulateResponse.transactionData;
+transaction.addResourceFee(simulateResponse.minResourceFee!);
+transaction.setSorobanAuth(simulateResponse.sorobanAuth);
+transaction.sign(accountKeyPair, Network.FUTURENET);
 ```
 
 2. Deploy SAC with asset:
 
 ```dart
-InvokeHostFunctionOperation operation = (InvokeHostFuncOpBuilder())
-    .addFunction(DeploySACWithAssetHostFunction(assetFsdk))
-    .build();
+InvokeHostFunctionOperation operation =
+    InvokeHostFuncOpBuilder(DeploySACWithAssetHostFunction(asset))
+        .build();
 ```
 
 #### Soroban Authorization
 
-The Flutter SDK provides support for the [Soroban Authorization Framework](https://soroban.stellar.org/docs/learn/authorization).
+The Flutter SDK provides support for the [Soroban Authorization Framework](https://soroban.stellar.org/docs/fundamentals-and-concepts/authorization).
+The SDK's implementation can be found [here](https://github.com/Soneso/stellar_flutter_sdk/blob/master/lib/src/soroban/soroban_auth.dart).
 
-For this purpose, it offers the `Address`, `AuthorizedInvocation` and `ContractAuth` classes as well as helper functions like `getNonce(...)`.
-
-Here is a code fragment showing how they can be used:
+To provide authorization you can add a list of `SorobanAuthorizationEntry` to the transaction before sending it.
 
 ```dart
-Address invokerAddress = Address.forAccountId(invokerId);
-
-String functionName = "auth";
-List<XdrSCVal> args = [invokerAddress.toXdrSCVal(), XdrSCVal.forU32(3)];
-
-AuthorizedInvocation rootInvocation =
-          AuthorizedInvocation(contractId, functionName, args: args);
-
-int nonce = await sorobanServer.getNonce(invokerId, contractId);
-
-ContractAuth contractAuth =
-          ContractAuth(rootInvocation, address: invokerAddress, nonce: nonce);
-
-// sign
-contractAuth.sign(invokerKeyPair, Network.FUTURENET);
-
-InvokeContractHostFunction hostFunction = InvokeContractHostFunction(
-          contractId, functionName,
-          arguments: args, auth: [contractAuth]);
+transaction.setSorobanAuth(myAuthList);
+```
 
-InvokeHostFunctionOperation operation =
-(InvokeHostFuncOpBuilder()).addFunction(hostFunction).build();
+The easiest way to do this is to use the auth data generated by the simulation.
 
-// simulate first to obtain the transaction data + resource fee
-GetAccountResponse submitter =
-          await sorobanServer.getAccount(submitterId);
+```dart
+transaction.setSorobanAuth(simulateResponse.sorobanAuth);
+```
+But you can also compose the authorization entries by yourself.
 
-Transaction transaction =
-          TransactionBuilder(submitter).addOperation(invokeOp).build();
+If the entries need to be signed you can do it as follows:
+```dart
+// sign auth
+List<SorobanAuthorizationEntry>? auth = simulateResponse.sorobanAuth;
+assert(auth != null);
+
+GetLatestLedgerResponse latestLedgerResponse = await sorobanServer.getLatestLedger();
+
+for (SorobanAuthorizationEntry a in auth!) {
+  // update signature expiration ledger
+  a.credentials.addressCredentials!.signatureExpirationLedger =
+      latestLedgerResponse.sequence! + 10;
+  // sign
+  a.sign(invokerKeypair, Network.FUTURENET);
+}
 
-SimulateTransactionResponse simulateResponse =
-          await sorobanServer.simulateTransaction(transaction);
+transaction.setSorobanAuth(auth);
 ```
 
-The example above invokes this assembly script [auth contract](https://github.com/Soneso/as-soroban-examples/tree/main/auth#code). In this example the submitter of the transaction is not the same as the "invoker" of the contract function.
-
-One can find another example in the [Soroban Auth Test Cases](https://github.com/Soneso/stellar_flutter_sdk/blob/master/test/soroban_test_auth.dart) of the SDK where the submitter and invoker are the same, as well as an example where contract auth from the simulation response is used.
+One can find multiple examples in the [Soroban Auth Test](https://github.com/Soneso/stellar_flutter_sdk/blob/master/test/soroban_test_auth.dart) and [Soroban Atomic Swap Test](https://github.com/Soneso/stellar_flutter_sdk/blob/master/test/soroban_test_atomic_swap.dart) of the SDK.
 
-An advanced auth example can be found in the [flutter atomic swap](https://github.com/Soneso/stellar_flutter_sdk/blob/master/test/soroban_test_atomic_swap.dart) test.
 
-Hint: Resource values and fees have been added in the new soroban preview 9 version. The calculation of the minimum resource values and fee by the simulation (preflight) is not always accurate, because it does not consider signatures. This may result in a failing transaction because of insufficient resources. In this case one can experiment and increase the resources values within the soroban transaction data before signing and submitting the transaction. E.g.:
+Hint: Resource values and fees have been added since soroban preview 9 version. The calculation of the minimum resource values and fee by the simulation (preflight) is not always accurate, because it does not consider signatures. This may result in a failing transaction because of insufficient resources. In this case one can experiment and increase the resources values within the soroban transaction data before signing and submitting the transaction. E.g.:
 
 ```dart
 int instructions = simulateResponse.transactionData!.resources.instructions.uint32;
@@ -392,20 +391,23 @@ The Soroban-RPC server provides the possibility to request contract events.
 You can use the Flutter SDK to request events like this:
 
 ```dart
-EventFilter eventFilter =
-          EventFilter(type: "contract", contractIds: [contractId]);
+TopicFilter topicFilter = TopicFilter(
+    ["*", XdrSCVal.forSymbol('increment').toBase64EncodedXdrString()]);
+
+EventFilter eventFilter = EventFilter(
+    type: "contract", contractIds: [contractId], topics: [topicFilter]);
 
 GetEventsRequest eventsRequest =
-          GetEventsRequest(startLedger, endLedger, filters: [eventFilter]);
+    GetEventsRequest(startLedger, filters: [eventFilter]);
 
 GetEventsResponse eventsResponse =
-          await sorobanServer.getEvents(eventsRequest);
+    await sorobanServer.getEvents(eventsRequest);
 ```
-Find the complete code [here](https://github.com/Soneso/stellar_flutter_sdk/blob/master/test/soroban_test.dart#L488).
+Find the complete code in the [Soroban Test](https://github.com/Soneso/stellar_flutter_sdk/blob/master/test/soroban_test.dart).
 
 #### Hints and Tips
 
-You can find the working code and more in the [Soroban Test Cases](https://github.com/Soneso/stellar_flutter_sdk/blob/master/test/soroban_test.dart) and [Soroban Auth Test Cases](https://github.com/Soneso/stellar_flutter_sdk/blob/master/test/soroban_test_auth.dart) of the Flutter SDK. The used wasm byte-code files can be found in the [test/wasm](https://github.com/Soneso/stellar_flutter_sdk/blob/master/test/wasm/) folder.
+You can find the working code and more in the [Soroban Test](https://github.com/Soneso/stellar_flutter_sdk/blob/master/test/soroban_test.dart), [Soroban Auth Test](https://github.com/Soneso/stellar_flutter_sdk/blob/master/test/soroban_test_auth.dart) and [Soroban Atomic Swap Test](https://github.com/Soneso/stellar_flutter_sdk/blob/master/test/soroban_test_atomic_swap.dart) of the Flutter SDK. The used wasm byte-code files can be found in the [test/wasm](https://github.com/Soneso/stellar_flutter_sdk/blob/master/test/wasm/) folder.
 
 Because Soroban and the Flutter SDK support for Soroban are in development, errors may occur. For a better understanding of an error you can enable the ```SorobanServer``` logging:
 

soroban.md

@@ -332,7 +332,7 @@ void main() {
     response = await sdk.submitTransaction(transaction);
     assert(response.success);
 
-    await Future.delayed(const Duration(seconds: 20), () {});
+    await Future.delayed(const Duration(seconds: 30), () {});
 
     subscription.cancel();
     assert(count == 3);

test/account_test.dart

@@ -1072,8 +1072,8 @@ void main() {
     response = await sdk.submitTransaction(transaction);
     assert(response.success);
 
-    // wait 3 seconds for the payment event.
-    await Future.delayed(const Duration(seconds: 3), () {});
+    // wait 10 seconds for the payment event.
+    await Future.delayed(const Duration(seconds: 10), () {});
     subscription.cancel();
     assert(paymentReceived);
   });