From 22fd98159940daec08be0c1ff71cc74aa53b8d75 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?=
 <andreibancioiu@users.noreply.github.com>
Date: Thu, 29 Jun 2023 11:57:36 +0300
Subject: [PATCH 01/69] Initial commit

---
 network-interaction-sdk/LICENSE | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)
 create mode 100644 network-interaction-sdk/LICENSE

diff --git a/network-interaction-sdk/LICENSE b/network-interaction-sdk/LICENSE
new file mode 100644
index 0000000..24fb407
--- /dev/null
+++ b/network-interaction-sdk/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 MultiversX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

From f44cadd6fe533c59b8b2b43b5f94df82ae3d5261 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Thu, 29 Jun 2023 14:24:35 +0300
Subject: [PATCH 02/69] Initial commit.

---
 network-interaction-sdk/guidelines.md         |  5 ++
 network-interaction-sdk/sdk-core/address.md   | 90 +++++++++++++++++++
 .../sdk-core/transaction.md                   |  0
 .../delegation_transactions_factory.md        |  0
 .../smart_contract_transactions_factory.md    |  0
 .../token_management_transactions_factory.md  |  0
 .../transactions_factory_config.md            |  0
 ..._management_transactions_outcome_parser.md |  0
 .../sdk-core/type_aliases.md                  | 10 +++
 .../sdk-wallet/mnemonic.md                    | 25 ++++++
 network-interaction-sdk/sdk-wallet/pem.md     | 12 +++
 .../sdk-wallet/user_pem.md                    | 13 +++
 .../sdk-wallet/user_public_key.md             | 22 +++++
 .../sdk-wallet/user_secret_key.md             | 26 ++++++
 .../sdk-wallet/user_signer.md                 |  0
 .../sdk-wallet/user_wallet.md                 |  0
 .../sdk-wallet/validator_pem.md               | 13 +++
 .../sdk-wallet/validator_signer.md            |  0
 18 files changed, 216 insertions(+)
 create mode 100644 network-interaction-sdk/guidelines.md
 create mode 100644 network-interaction-sdk/sdk-core/address.md
 create mode 100644 network-interaction-sdk/sdk-core/transaction.md
 create mode 100644 network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
 create mode 100644 network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
 create mode 100644 network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
 create mode 100644 network-interaction-sdk/sdk-core/transactions-factories/transactions_factory_config.md
 create mode 100644 network-interaction-sdk/sdk-core/transactions-outcome-parsers/token_management_transactions_outcome_parser.md
 create mode 100644 network-interaction-sdk/sdk-core/type_aliases.md
 create mode 100644 network-interaction-sdk/sdk-wallet/mnemonic.md
 create mode 100644 network-interaction-sdk/sdk-wallet/pem.md
 create mode 100644 network-interaction-sdk/sdk-wallet/user_pem.md
 create mode 100644 network-interaction-sdk/sdk-wallet/user_public_key.md
 create mode 100644 network-interaction-sdk/sdk-wallet/user_secret_key.md
 create mode 100644 network-interaction-sdk/sdk-wallet/user_signer.md
 create mode 100644 network-interaction-sdk/sdk-wallet/user_wallet.md
 create mode 100644 network-interaction-sdk/sdk-wallet/validator_pem.md
 create mode 100644 network-interaction-sdk/sdk-wallet/validator_signer.md

diff --git a/network-interaction-sdk/guidelines.md b/network-interaction-sdk/guidelines.md
new file mode 100644
index 0000000..7202f79
--- /dev/null
+++ b/network-interaction-sdk/guidelines.md
@@ -0,0 +1,5 @@
+##  **`in-ifaces-out-concrete-types`**
+
+Generally speaking, it's recommended to receive input parameters as abstractions (interfaces) in the public API of the SDKs. This leads to an improved decoupling, and allows for easier type substitution (e.g. easier mocking, testing).
+
+Generally speaking, it's recommended to return concrete types in the public API of the SDKs. The client code is responsible with decoupling from unnecessary data and behaviour of returned objects (e.g. by using interfaces, on their side). 
diff --git a/network-interaction-sdk/sdk-core/address.md b/network-interaction-sdk/sdk-core/address.md
new file mode 100644
index 0000000..3e64daa
--- /dev/null
+++ b/network-interaction-sdk/sdk-core/address.md
@@ -0,0 +1,90 @@
+```
+class Address:
+    // Should also validate the length of the provided input.
+    constructor(pubkey: bytes, hrp: string);
+
+    // Named constructors
+    static fromBech32(value: string): Address;
+    static fromHex(value: string, hrp: string): Address;
+
+    // Returns the address as a string (bech32).
+    bech32(): string;
+
+    // Returns the address as a string (hex).
+    // Name should be adjusted to match the language's convention.
+    hex(): string;
+
+    // Returns the underlying public key.
+    pubkey(): bytes;
+
+    // Returns the shard of the address.
+    getShard(): int;
+
+    // Returns true if the address is a smart contract address.
+    isSmartContract(): bool;
+```
+
+Example of usage:
+
+```
+address = Address.from_bech32("erd1qyu5wthldzr8wx5c9ucg8kjagg0jfs53s8nr3zpz3hypefsdd8ssycr6th")
+
+print("Address (bech32-encoded)", address.bech32())
+print("Public key (hex-encoded):", address.hex())
+```
+
+```
+class AddressFactory:
+    constructor(hrp: string = DEFAULT_HRP);
+
+    // Creates an address with all bytes set to zero.
+    // This is the same as the "contract deployment address".
+    createZero(): Address;
+
+    // Creates an address from a bech32 string.
+    createFromBech32(value: string): Address;
+
+    // Creates an address from a public key.
+    createFromPubkey(pubkey: bytes): Address;
+
+    // Creates an address from a hex string.
+    createFromHex(value: string): Address;
+```
+
+Example of usage:
+
+```
+
+factory = AddressFactory("erd")
+
+address = factory.create_from_bech32("erd1qyu5wthldzr8wx5c9ucg8kjagg0jfs53s8nr3zpz3hypefsdd8ssycr6th")
+address = factory.create_from_hex("0139472eff6886771a982f3083da5d421f24c29181e63888228dc81ca60d69e1")
+address = factory.create_from_pubkey(bytes.fromhex("0139472eff6886771a982f3083da5d421f24c29181e63888228dc81ca60d69e1"))
+```
+
+```
+class AddressConverter:
+    constructor(hrp: string = DEFAULT_HRP);
+
+    // Converts a bech32 string to a public key.
+    bech32ToPubkey(value: string): bytes;
+
+    // Converts a public key to a bech32 string.
+    pubkeyToBech32(pubkey: bytes): string;
+```
+
+Example of usage:
+
+```
+converter = AddressConverter("erd")
+
+pubkey = converter.bech32_to_pubkey("erd1qyu5wthldzr8wx5c9ucg8kjagg0jfs53s8nr3zpz3hypefsdd8ssycr6th")
+bech32 = converter.pubkey_to_bech32(bytes.fromhex("0139472eff6886771a982f3083da5d421f24c29181e63888228dc81ca60d69e1"))
+```
+
+Module-level functions:
+
+```
+// Note that the first input parameter is received as an interface, but the return value is a concrete type [see Guideline **`in-ifaces-out-concrete-types`**].
+compute_contract_address(deployer: IAddress, deployment_nonce: INonce, address_hrp: string): Address:
+```
diff --git a/network-interaction-sdk/sdk-core/transaction.md b/network-interaction-sdk/sdk-core/transaction.md
new file mode 100644
index 0000000..e69de29
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
new file mode 100644
index 0000000..e69de29
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
new file mode 100644
index 0000000..e69de29
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
new file mode 100644
index 0000000..e69de29
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/transactions_factory_config.md b/network-interaction-sdk/sdk-core/transactions-factories/transactions_factory_config.md
new file mode 100644
index 0000000..e69de29
diff --git a/network-interaction-sdk/sdk-core/transactions-outcome-parsers/token_management_transactions_outcome_parser.md b/network-interaction-sdk/sdk-core/transactions-outcome-parsers/token_management_transactions_outcome_parser.md
new file mode 100644
index 0000000..e69de29
diff --git a/network-interaction-sdk/sdk-core/type_aliases.md b/network-interaction-sdk/sdk-core/type_aliases.md
new file mode 100644
index 0000000..4ef6af1
--- /dev/null
+++ b/network-interaction-sdk/sdk-core/type_aliases.md
@@ -0,0 +1,10 @@
+```
+INonce = uint64
+IGasPrice = uint32
+IGasLimit = uint32
+IChainID = str
+ITransactionVersion = int
+ITransactionOptions = int
+ISignature = bytes
+ITokenIdentifier = str
+```
diff --git a/network-interaction-sdk/sdk-wallet/mnemonic.md b/network-interaction-sdk/sdk-wallet/mnemonic.md
new file mode 100644
index 0000000..501cc6e
--- /dev/null
+++ b/network-interaction-sdk/sdk-wallet/mnemonic.md
@@ -0,0 +1,25 @@
+
+```
+class Mnemonic:
+    // At least one of the following constructors should be implemented.
+    // The constructor(s) should also trim whitespace and validate the mnemonic.
+    constructor(text: string);
+    constructor(words: string[]);
+
+    // Alternatively, named constructors can be used:
+    static fromText(text: string): Mnemonic;
+    static fromWords(words: string[]): Mnemonic;
+
+    // Generates a random mnemonic.
+    static generate(): Mnemonic;
+
+    // Derives a secret key from the mnemonic.
+    deriveKey(addressIndex: number = 0, password: string = ""): UserSecretKey;
+
+    // Gets the mnemonic words.
+    getWords(): string[];
+
+    // Returns the mnemonic as a string.
+    toString(): string;
+}
+```
diff --git a/network-interaction-sdk/sdk-wallet/pem.md b/network-interaction-sdk/sdk-wallet/pem.md
new file mode 100644
index 0000000..4571ec5
--- /dev/null
+++ b/network-interaction-sdk/sdk-wallet/pem.md
@@ -0,0 +1,12 @@
+```
+class PemEntry:
+    label: string;
+    data: bytes;
+```
+
+Module-level functions:
+
+```
+parse_text(text: string): PemEntry[];
+parse_file(path: Path): PemEntry[];
+```
diff --git a/network-interaction-sdk/sdk-wallet/user_pem.md b/network-interaction-sdk/sdk-wallet/user_pem.md
new file mode 100644
index 0000000..e58d6d2
--- /dev/null
+++ b/network-interaction-sdk/sdk-wallet/user_pem.md
@@ -0,0 +1,13 @@
+```
+class UserPEM:
+    constructor(label: string, key: UserSecretKey);
+
+    // Named constructors:
+    static from_file(path: Path, index: number = 0): UserPEM;
+    static from_file_all(path: Path): UserPEM[];
+    static from_text(text: string, index: number = 0): UserPEM;
+    static from_text_all(text: string): UserPEM[];
+
+    save(path: Path): void;
+    to_text(): string;
+```
diff --git a/network-interaction-sdk/sdk-wallet/user_public_key.md b/network-interaction-sdk/sdk-wallet/user_public_key.md
new file mode 100644
index 0000000..e9b3056
--- /dev/null
+++ b/network-interaction-sdk/sdk-wallet/user_public_key.md
@@ -0,0 +1,22 @@
+```
+class UserPublicKey:
+    // The constructor(s) should also validate the length of the provided input.
+    constructor(data: bytes);
+
+    verify(data: bytes, signature: bytes): boolean;
+
+    hex(): string {
+        return this.buffer.toString("hex");
+    }
+
+    // Converts the public key to an actual address (bech32).
+    toAddress(): Address;
+
+    // Returns the secret key as a string (hex).
+    // Name should be adjusted to match the language's convention.
+    hex(): string;
+
+    // Implement any of the following to return the secret key as a byte array.
+    valueOf(): bytes;   // specific to JavaScript
+    getData(): bytes;
+```
diff --git a/network-interaction-sdk/sdk-wallet/user_secret_key.md b/network-interaction-sdk/sdk-wallet/user_secret_key.md
new file mode 100644
index 0000000..2dfd2ac
--- /dev/null
+++ b/network-interaction-sdk/sdk-wallet/user_secret_key.md
@@ -0,0 +1,26 @@
+```
+class UserSecretKey:
+    // At least one of the following constructors should be implemented.
+    // The constructor(s) should also validate the length of the provided input.
+    constructor(data: bytes);
+    constructor(hex: string);
+
+    // Alternatively, named constructors can be used:
+    static fromBytes(data: bytes): UserSecretKey;
+    static fromString(value: string): UserSecretKey;
+
+    // Generates the public key corresponding to this secret key.
+    generatePublicKey(): UserPublicKey;
+
+    // Signs an array of bytes.
+    sign(data: bytes): bytes;
+
+    // Returns the secret key as a string (hex).
+    // Name should be adjusted to match the language's convention.
+    hex(): string;
+
+    // Implement any of the following to return the secret key as a byte array.
+    valueOf(): bytes;   // specific to JavaScript
+    getData(): bytes;
+}
+```
diff --git a/network-interaction-sdk/sdk-wallet/user_signer.md b/network-interaction-sdk/sdk-wallet/user_signer.md
new file mode 100644
index 0000000..e69de29
diff --git a/network-interaction-sdk/sdk-wallet/user_wallet.md b/network-interaction-sdk/sdk-wallet/user_wallet.md
new file mode 100644
index 0000000..e69de29
diff --git a/network-interaction-sdk/sdk-wallet/validator_pem.md b/network-interaction-sdk/sdk-wallet/validator_pem.md
new file mode 100644
index 0000000..0f96d0a
--- /dev/null
+++ b/network-interaction-sdk/sdk-wallet/validator_pem.md
@@ -0,0 +1,13 @@
+```
+class ValidatorPEM:
+    constructor(label: string, key: ValidatorSecretKey);
+
+    // Named constructors:
+    static from_file(path: Path, index: number = 0): ValidatorPEM;
+    static from_file_all(path: Path): ValidatorPEM[];
+    static from_text(text: string, index: number = 0): ValidatorPEM;
+    static from_text_all(text: string): ValidatorPEM[];
+
+    save(path: Path): void;
+    to_text(): string;
+```
diff --git a/network-interaction-sdk/sdk-wallet/validator_signer.md b/network-interaction-sdk/sdk-wallet/validator_signer.md
new file mode 100644
index 0000000..e69de29

From 3d131b9b1da430614055b16478fdada6611a94bf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Thu, 29 Jun 2023 14:31:31 +0300
Subject: [PATCH 03/69] Add empty files for network providers.

---
 network-interaction-sdk/sdk-core/address.md                 | 6 ++++++
 .../sdk-network-providers/api_network_provider.md           | 0
 .../sdk-network-providers/proxy_network_provider.md         | 0
 3 files changed, 6 insertions(+)
 create mode 100644 network-interaction-sdk/sdk-network-providers/api_network_provider.md
 create mode 100644 network-interaction-sdk/sdk-network-providers/proxy_network_provider.md

diff --git a/network-interaction-sdk/sdk-core/address.md b/network-interaction-sdk/sdk-core/address.md
index 3e64daa..7e25047 100644
--- a/network-interaction-sdk/sdk-core/address.md
+++ b/network-interaction-sdk/sdk-core/address.md
@@ -1,3 +1,5 @@
+## Address
+
 ```
 class Address:
     // Should also validate the length of the provided input.
@@ -33,6 +35,8 @@ print("Address (bech32-encoded)", address.bech32())
 print("Public key (hex-encoded):", address.hex())
 ```
 
+## AddressFactory
+
 ```
 class AddressFactory:
     constructor(hrp: string = DEFAULT_HRP);
@@ -62,6 +66,8 @@ address = factory.create_from_hex("0139472eff6886771a982f3083da5d421f24c29181e63
 address = factory.create_from_pubkey(bytes.fromhex("0139472eff6886771a982f3083da5d421f24c29181e63888228dc81ca60d69e1"))
 ```
 
+## AddressConverter
+
 ```
 class AddressConverter:
     constructor(hrp: string = DEFAULT_HRP);
diff --git a/network-interaction-sdk/sdk-network-providers/api_network_provider.md b/network-interaction-sdk/sdk-network-providers/api_network_provider.md
new file mode 100644
index 0000000..e69de29
diff --git a/network-interaction-sdk/sdk-network-providers/proxy_network_provider.md b/network-interaction-sdk/sdk-network-providers/proxy_network_provider.md
new file mode 100644
index 0000000..e69de29

From ce3c14f1f41363034ffb0212f02772dd8eb57101 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Thu, 29 Jun 2023 14:41:32 +0300
Subject: [PATCH 04/69] Sketch factory.

---
 .../token_management_transactions_factory.md  | 114 ++++++++++++++++++
 1 file changed, 114 insertions(+)

diff --git a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
index e69de29..d39511b 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
@@ -0,0 +1,114 @@
+## TokenManagementTransactionsFactory
+
+```
+class TokenManagementTransactionsFactory:
+    createIssueFungibleTransaction({
+        sender: IAddress;
+        tokenName: string;
+        tokenTicker: string;
+        canFreeze: boolean;
+        canWipe: boolean;
+        canPause: boolean;
+        canTransferNFTCreateRole: boolean;
+        canChangeOwner: boolean;
+        canUpgrade: boolean;
+        canAddSpecialRoles: boolean;
+
+        // Optionals:
+        transactionNonce?: INonce;
+        value?: ITransactionValue;
+        gasPrice?: IGasPrice;
+        gasLimit?: IGasLimit;
+        guardian? : IAddress;
+    }): Transaction;
+
+    createIssueSemiFungibleTransaction({
+        sender: IAddress;
+        tokenName: string;
+        tokenTicker: string;
+        canFreeze: boolean;
+        canWipe: boolean;
+        canPause: boolean;
+        canTransferNFTCreateRole: boolean;
+        canChangeOwner: boolean;
+        canUpgrade: boolean;
+        canAddSpecialRoles: boolean;
+
+        // Optionals:
+        transactionNonce?: INonce;
+        value?: ITransactionValue;
+        gasPrice?: IGasPrice;
+        gasLimit?: IGasLimit;
+        guardian? : IAddress;
+    })
+
+    createIssueNonFungibleTransaction({
+        sender: IAddress;
+        tokenName: string;
+        tokenTicker: string;
+        canFreeze: boolean;
+        canWipe: boolean;
+        canPause: boolean;
+        canTransferNFTCreateRole: boolean;
+        canChangeOwner: boolean;
+        canUpgrade: boolean;
+        canAddSpecialRoles: boolean;
+
+        // Optionals:
+        transactionNonce?: INonce;
+        value?: ITransactionValue;
+        gasPrice?: IGasPrice;
+        gasLimit?: IGasLimit;
+        guardian? : IAddress;
+    }): Transaction;
+
+    createRegisterMetaESDT({
+        sender: IAddress;
+        tokenName: string;
+        tokenTicker: string;
+        numDecimals: number;
+        canFreeze: boolean;
+        canWipe: boolean;
+        canPause: boolean;
+        canTransferNFTCreateRole: boolean;
+        canChangeOwner: boolean;
+        canUpgrade: boolean;
+        canAddSpecialRoles: boolean;
+
+        // Optionals:
+        transactionNonce?: INonce;
+        value?: ITransactionValue;
+        gasPrice?: IGasPrice;
+        gasLimit?: IGasLimit;
+        guardian? : IAddress;
+    }): Transaction;
+```
+
+If the language supports it, the input arguments objects may be designed using interfaces and inheritance. For example, in TypeScript:
+
+```
+interface IRegisterMetaESDT extends IIssueSemiFungibleArgs {
+    numDecimals: number;
+}
+
+interface IIssueSemiFungibleArgs extends IBaseArgs {
+    issuer: IAddress;
+    tokenName: string;
+    tokenTicker: string;
+    canFreeze: boolean;
+    canWipe: boolean;
+    canPause: boolean;
+    canTransferNFTCreateRole: boolean;
+    canChangeOwner: boolean;
+    canUpgrade: boolean;
+    canAddSpecialRoles: boolean;
+}
+
+interface IBaseArgs {
+    transactionNonce?: INonce;
+    value?: ITransactionValue;
+    gasPrice?: IGasPrice;
+    gasLimit?: IGasLimit;
+    guardian? : IAddress;
+}
+```

From d91c9176bfcc3f2a6d58e084de083ca73f6534ec Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Thu, 29 Jun 2023 15:30:01 +0300
Subject: [PATCH 05/69] Further work.

---
 .../sdk-core/transaction.md                   | 46 ++++++++++++++
 .../token_management_transactions_factory.md  | 62 ++++++++++++++++++-
 .../token_transfers_factory.md                |  0
 3 files changed, 107 insertions(+), 1 deletion(-)
 create mode 100644 network-interaction-sdk/sdk-core/transactions-factories/token_transfers_factory.md

diff --git a/network-interaction-sdk/sdk-core/transaction.md b/network-interaction-sdk/sdk-core/transaction.md
index e69de29..f61caf8 100644
--- a/network-interaction-sdk/sdk-core/transaction.md
+++ b/network-interaction-sdk/sdk-core/transaction.md
@@ -0,0 +1,46 @@
+## Transaction
+
+```
+class Transaction:
+    constructor({
+        sender: IAddress;
+        receiver: IAddress;
+        gasLimit: IGasLimit;
+        chainID: IChainID;
+
+        nonce?: INonce;
+        value?: ITransactionValue;
+        senderUsername?: string;
+        receiverUsername?: string;
+        gasPrice?: IGasPrice;
+
+        data?: ITransactionPayload;
+        version?: ITransactionVersion;
+        options?: ITransactionOptions;
+        guardian?: IAddress;
+    });
+
+    // Getters and setters for all the fields.
+    // ...
+
+    // Optional: alias for setSignature().
+    applySignature(signature: bytes): void;
+    // Optional: alias for setGuardianSignature().
+    applyGuardianSignature(signature: bytes): void;
+
+    serializeForSigning(): bytes;
+
+    // Returns the transaction as a plain object.
+    toPlainObject(withSignatures: bool = true): any;
+
+    // Optional: alias for `toPlainObject()`.
+    toJSON(): any; // JavaScript
+    to_dictionary(): any; // Python
+```
+
+Module-level functions:
+
+```
+computeFee(transaction: ITransaction, networkConfig: INetworkConfig): bigNumber;
+computeTransactionHash(transaction: ITransaction): bytes;
+```
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
index d39511b..f946256 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
@@ -1,5 +1,7 @@
 ## TokenManagementTransactionsFactory
 
+A class that provides methods for creating transactions for token management operations.
+
 ```
 class TokenManagementTransactionsFactory:
     createIssueFungibleTransaction({
@@ -62,7 +64,7 @@ class TokenManagementTransactionsFactory:
         guardian? : IAddress;
     }): Transaction;
 
-    createRegisterMetaESDT({
+    createRegisterMetaESDTTransaction({
         sender: IAddress;
         tokenName: string;
         tokenTicker: string;
@@ -82,6 +84,64 @@ class TokenManagementTransactionsFactory:
         gasLimit?: IGasLimit;
         guardian? : IAddress;
     }): Transaction;
+
+    createRegisterAndSetAllRolesTransaction({
+        sender: IAddress;
+        tokenName: string;
+        tokenTicker: string;
+        tokenType: RegisterAndSetAllRolesTokenType;
+        numDecimals: number;
+
+        // Optionals:
+        transactionNonce?: INonce;
+        value?: ITransactionValue;
+        gasPrice?: IGasPrice;
+        gasLimit?: IGasLimit;
+        guardian? : IAddress;
+    }): Transaction;
+
+    createSetBurnRoleGloballyTransaction({
+        sender: IAddress;
+        tokenIdentifier: string;
+
+        // Optionals:
+        transactionNonce?: INonce;
+        value?: ITransactionValue;
+        gasPrice?: IGasPrice;
+        gasLimit?: IGasLimit;
+        guardian? : IAddress;
+    }): Transaction;
+
+    createUnsetBurnRoleGloballyTransaction({
+        sender: IAddress;
+        tokenIdentifier: string;
+
+        // Optionals:
+        transactionNonce?: INonce;
+        value?: ITransactionValue;
+        gasPrice?: IGasPrice;
+        gasLimit?: IGasLimit;
+        guardian? : IAddress;
+    }): Transaction;
+
+    createSetSpecialRoleOnFungibleTransaction({
+        sender: IAddress;
+        user: IAddress;
+        tokenIdentifier: string;
+        addRoleLocalMint: boolean;
+        addRoleLocalBurn: boolean;
+
+        // Optionals:
+        transactionNonce?: INonce;
+        value?: ITransactionValue;
+        gasPrice?: IGasPrice;
+        gasLimit?: IGasLimit;
+        guardian? : IAddress;
+    }): Transaction;
+
+    createSetSpecialRoleOnSemiFungibleTransaction({
+        
+    })
 ```
 
 If the language supports it, the input arguments objects may be designed using interfaces and inheritance. For example, in TypeScript:
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/token_transfers_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/token_transfers_factory.md
new file mode 100644
index 0000000..e69de29

From 24acf76f0de3ca591b89142aa29d624822550805 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Thu, 29 Jun 2023 16:02:39 +0300
Subject: [PATCH 06/69] Amount and token transfer.

---
 network-interaction-sdk/sdk-core/amount.md    | 21 ++++++++
 .../sdk-core/token_transfer.md                | 53 +++++++++++++++++++
 2 files changed, 74 insertions(+)
 create mode 100644 network-interaction-sdk/sdk-core/amount.md
 create mode 100644 network-interaction-sdk/sdk-core/token_transfer.md

diff --git a/network-interaction-sdk/sdk-core/amount.md b/network-interaction-sdk/sdk-core/amount.md
new file mode 100644
index 0000000..e9b2d0c
--- /dev/null
+++ b/network-interaction-sdk/sdk-core/amount.md
@@ -0,0 +1,21 @@
+## Amount
+
+```
+class Amount:
+    // Private fields (properties):
+    atomic_units: number;
+    num_decimals: number;
+
+    constructor(atomic_units: number, num_decimals?: number = unknown);
+
+    // Named constructors:
+    fromAtomicUnits(atomic_units: number, num_decimals?: number = unknown): Amount;
+    fromUnits(units: number|string, num_decimals: number): Amount;
+    nativeFromUnits(units: number|string): Amount; // num_decimals = 18.
+
+    // Simply returns the value of the private field.
+    toAtomicUnits(): number;
+
+    // Returns the fixed point representation of the amount.
+    toUnits(): string;
+```
diff --git a/network-interaction-sdk/sdk-core/token_transfer.md b/network-interaction-sdk/sdk-core/token_transfer.md
new file mode 100644
index 0000000..286d3b2
--- /dev/null
+++ b/network-interaction-sdk/sdk-core/token_transfer.md
@@ -0,0 +1,53 @@
+## TokenTransfer
+
+```
+class TokenTransfer:
+    // Fields (properties):
+    token_identifier: ITokenIdentifier;
+    token_nonce: INonce;
+    amount_in_atomic_units: number;
+
+    constructor(tokenIdentifier: ITokenIdentifier, tokenNonce: INonce, amountInAtomicUnits: number);
+
+    isEgld(): boolean;
+
+    isFungible(): boolean;
+
+    // Named constructors:
+    static ofEgld(amountInAtomicUnits: number): TokenTransfer;
+    static ofFungible(tokenIdentifier: ITokenIdentifier, amountInAtomicUnits: number): TokenTransfer;
+    static ofNonFungible(tokenIdentifier: ITokenIdentifier, nonce: INonce): TokenTransfer;
+    static ofSemiFungible(tokenIdentifier: ITokenIdentifier, nonce: INonce, quantity: number): TokenTransfer;
+    static ofMetaESDT(tokenIdentifier: ITokenIdentifier, nonce: INonce, amountInAtomicUnits: number): TokenTransfer;
+
+    // Amount in atomic units, as string.
+    toString();
+```
+
+Examples of usage:
+
+```
+amount = Amount.nativeFromUnits("1.50");
+tokenTransfer = TokenTransfer.ofEgld(amount.toUnits());
+
+print(tokenTransfer.isEgld());
+
+transaction = new Transaction({
+    ...
+    value: amount, // compatible with ITransactionValue
+    ...
+});
+```
+
+```
+amount = Amoount.fromUnits("10", 6);
+tokenTransfer = TokenTransfer.ofFungible("TEST-abcdef", amount.toAtomicUnits());
+
+print(tokenTransfer.isFungible());
+
+transaction = tokenTransfersFactory.create_esdt_transfer({ 
+    ...
+    tokenTransfer: tokenTransfer,
+    ...
+ });
+```

From dc061a9d1a8ad000c5069e534fc88084f1a03703 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Thu, 29 Jun 2023 17:29:40 +0300
Subject: [PATCH 07/69] Renaming on transaction factory.

---
 .../token_management_transactions_factory.md  | 53 ++++++++++++-------
 1 file changed, 34 insertions(+), 19 deletions(-)

diff --git a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
index f946256..d50d060 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
@@ -4,7 +4,7 @@ A class that provides methods for creating transactions for token management ope
 
 ```
 class TokenManagementTransactionsFactory:
-    createIssueFungibleTransaction({
+    create_transaction_for_issuing_fungible({
         sender: IAddress;
         tokenName: string;
         tokenTicker: string;
@@ -17,14 +17,14 @@ class TokenManagementTransactionsFactory:
         canAddSpecialRoles: boolean;
 
         // Optionals:
-        transactionNonce?: INonce;
+        nonce?: INonce;
         value?: ITransactionValue;
         gasPrice?: IGasPrice;
         gasLimit?: IGasLimit;
         guardian? : IAddress;
     }): Transaction;
 
-    createIssueSemiFungibleTransaction({
+    create_transaction_for_issuing_semi_fungible({
         sender: IAddress;
         tokenName: string;
         tokenTicker: string;
@@ -37,14 +37,14 @@ class TokenManagementTransactionsFactory:
         canAddSpecialRoles: boolean;
 
         // Optionals:
-        transactionNonce?: INonce;
+        nonce?: INonce;
         value?: ITransactionValue;
         gasPrice?: IGasPrice;
         gasLimit?: IGasLimit;
         guardian? : IAddress;
     })
 
-    createIssueNonFungibleTransaction({
+    create_transaction_for_issuing_non_fungible({
         sender: IAddress;
         tokenName: string;
         tokenTicker: string;
@@ -57,14 +57,14 @@ class TokenManagementTransactionsFactory:
         canAddSpecialRoles: boolean;
 
         // Optionals:
-        transactionNonce?: INonce;
+        nonce?: INonce;
         value?: ITransactionValue;
         gasPrice?: IGasPrice;
         gasLimit?: IGasLimit;
         guardian? : IAddress;
     }): Transaction;
 
-    createRegisterMetaESDTTransaction({
+    create_transaction_for_registering_meta_esdt({
         sender: IAddress;
         tokenName: string;
         tokenTicker: string;
@@ -78,14 +78,14 @@ class TokenManagementTransactionsFactory:
         canAddSpecialRoles: boolean;
 
         // Optionals:
-        transactionNonce?: INonce;
+        nonce?: INonce;
         value?: ITransactionValue;
         gasPrice?: IGasPrice;
         gasLimit?: IGasLimit;
         guardian? : IAddress;
     }): Transaction;
 
-    createRegisterAndSetAllRolesTransaction({
+    create_transaction_for_registering_and_setting_roles({
         sender: IAddress;
         tokenName: string;
         tokenTicker: string;
@@ -93,38 +93,38 @@ class TokenManagementTransactionsFactory:
         numDecimals: number;
 
         // Optionals:
-        transactionNonce?: INonce;
+        nonce?: INonce;
         value?: ITransactionValue;
         gasPrice?: IGasPrice;
         gasLimit?: IGasLimit;
         guardian? : IAddress;
     }): Transaction;
 
-    createSetBurnRoleGloballyTransaction({
+    create_transaction_for_setting_burn_role_globally({
         sender: IAddress;
         tokenIdentifier: string;
 
         // Optionals:
-        transactionNonce?: INonce;
+        nonce?: INonce;
         value?: ITransactionValue;
         gasPrice?: IGasPrice;
         gasLimit?: IGasLimit;
         guardian? : IAddress;
     }): Transaction;
 
-    createUnsetBurnRoleGloballyTransaction({
+    create_transaction_for_unsetting_burn_role_globally({
         sender: IAddress;
         tokenIdentifier: string;
 
         // Optionals:
-        transactionNonce?: INonce;
+        nonce?: INonce;
         value?: ITransactionValue;
         gasPrice?: IGasPrice;
         gasLimit?: IGasLimit;
         guardian? : IAddress;
     }): Transaction;
 
-    createSetSpecialRoleOnFungibleTransaction({
+    create_transaction_for_setting_special_role_on_fungible_token({
         sender: IAddress;
         user: IAddress;
         tokenIdentifier: string;
@@ -132,16 +132,31 @@ class TokenManagementTransactionsFactory:
         addRoleLocalBurn: boolean;
 
         // Optionals:
-        transactionNonce?: INonce;
+        nonce?: INonce;
         value?: ITransactionValue;
         gasPrice?: IGasPrice;
         gasLimit?: IGasLimit;
         guardian? : IAddress;
     }): Transaction;
 
-    createSetSpecialRoleOnSemiFungibleTransaction({
-        
+    create_transaction_for_setting_special_role_on_semi_fungible_token({
+        sender: IAddress;
+        user: IAddress;
+        tokenIdentifier: string;
+        addRoleNFTCreate: boolean;
+        addRoleNFTBurn: boolean;
+        addRoleNFTAddQuantity: boolean;
+        addRoleESDTTransferRole: boolean;
+
+        // Optionals:
+        nonce?: INonce;
+        value?: ITransactionValue;
+        gasPrice?: IGasPrice;
+        gasLimit?: IGasLimit;
+        guardian? : IAddress;
     })
+
+    ...
 ```
 
 If the language supports it, the input arguments objects may be designed using interfaces and inheritance. For example, in TypeScript:
@@ -165,7 +180,7 @@ interface IIssueSemiFungibleArgs extends IBaseArgs {
 }
 
 interface IBaseArgs {
-    transactionNonce?: INonce;
+    nonce?: INonce;
     value?: ITransactionValue;
     gasPrice?: IGasPrice;
     gasLimit?: IGasLimit;

From e80c2b3695932df1eb534a122fc5334021582580 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Fri, 30 Jun 2023 09:29:07 +0300
Subject: [PATCH 08/69] Factories - sketch.

---
 .../delegation_transactions_factory.md        | 35 +++++++++++++++++++
 .../smart_contract_transactions_factory.md    | 14 ++++++++
 .../token_management_transactions_factory.md  | 27 ++++++++++++++
 3 files changed, 76 insertions(+)

diff --git a/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
index e69de29..27f8b99 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
@@ -0,0 +1,35 @@
+## DelegationTransactionsFactory
+
+```
+class DelegationTransactionsFactory:
+    // IConfig should be a private (internal) interface that defines the necessary configuration (e.g. minGasLimit, gasLimitPerByte, issueCost).
+    constructor(config: IConfig);
+
+    create_transaction_for_new_delegation_contract
+
+    create_transaction_for_adding_nodes
+
+    create_transaction_for_removing_nodes
+
+    create_transaction_for_staking_nodes
+
+    create_transaction_for_unbonding_nodes
+
+    create_transaction_for_unstaking_nodes
+
+    create_transaction_for_unjailing_nodes
+
+    create_transaction_for_changing_service_fee
+
+    create_transaction_for_modifying_delegation_cap
+
+    create_transaction_for_setting_automatic_activation
+
+    create_transaction_for_unsetting_automatic_activation
+
+    create_transaction_for_setting_redelegate_cap
+
+    create_transaction_for_unsetting_redelegate_cap
+
+    create_transaction_for_setting_metadata
+```
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
index e69de29..e369692 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
@@ -0,0 +1,14 @@
+## SmartContractTransactionsFactory
+
+```
+class SmartContractTransactionsFactory:
+    // IConfig should be a private (internal) interface that defines the necessary configuration (e.g. minGasLimit, gasLimitPerByte, issueCost).
+    constructor(config: IConfig);
+
+    create_transaction_for_deploy
+
+    create_transaction_for_execute
+
+    create_transaction_for_upgrade
+
+```
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
index d50d060..d9b7999 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
@@ -4,6 +4,9 @@ A class that provides methods for creating transactions for token management ope
 
 ```
 class TokenManagementTransactionsFactory:
+    // IConfig should be a private (internal) interface that defines the necessary configuration (e.g. minGasLimit, gasLimitPerByte, issueCost).
+    constructor(config: IConfig);
+
     create_transaction_for_issuing_fungible({
         sender: IAddress;
         tokenName: string;
@@ -156,6 +159,30 @@ class TokenManagementTransactionsFactory:
         guardian? : IAddress;
     })
 
+    create_transaction_for_setting_special_role_on_non_fungible_token
+
+    create_transaction_for_creating_nft
+
+    create_transaction_for_pausing
+
+    create_transaction_for_unpausing
+
+    create_transaction_for_freezing
+
+    create_transaction_for_unfreezing
+
+    create_transaction_for_wiping
+
+    create_transaction_for_local_minting
+
+    create_transaction_for_local_burning
+
+    create_transaction_for_updating_attributes
+
+    create_transaction_for_adding_quantity
+
+    create_transaction_for_burning_quantity
+
     ...
 ```
 

From 027776b35fb9abd74e0e13ef14ba7d75b3c91782 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Fri, 30 Jun 2023 09:29:33 +0300
Subject: [PATCH 09/69] Signers - sketch.

---
 network-interaction-sdk/sdk-wallet/user_signer.md  | 14 ++++++++++++++
 .../sdk-wallet/validator_signer.md                 | 14 ++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/network-interaction-sdk/sdk-wallet/user_signer.md b/network-interaction-sdk/sdk-wallet/user_signer.md
index e69de29..e1bba47 100644
--- a/network-interaction-sdk/sdk-wallet/user_signer.md
+++ b/network-interaction-sdk/sdk-wallet/user_signer.md
@@ -0,0 +1,14 @@
+## UserSigner
+
+```
+class UserSigner:
+    constructor(secret_key: UserSecretKey);
+
+    // Named constructors
+    static fromPemFile(path: Path, index: number = 0): UserSigner;
+    static fromWallet(path: Path, password: string): UserSigner;
+
+    sign(data: bytes): bytes;
+
+    getAddress(): Address;
+```
diff --git a/network-interaction-sdk/sdk-wallet/validator_signer.md b/network-interaction-sdk/sdk-wallet/validator_signer.md
index e69de29..6981bbc 100644
--- a/network-interaction-sdk/sdk-wallet/validator_signer.md
+++ b/network-interaction-sdk/sdk-wallet/validator_signer.md
@@ -0,0 +1,14 @@
+## ValidatorSigner
+
+```
+class ValidatorSigner:
+    constructor(secret_key: ValidatorSecretKey);
+
+    // Named constructors
+    static fromPemFile(path: Path, index: number = 0): ValidatorSigner;
+
+    sign(data: bytes): bytes;
+
+    getPublicKey(): ValidatorPublicKey;
+```
+

From 98d6fac505ab68713049264b2bc918dc24afda87 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Fri, 30 Jun 2023 10:04:26 +0300
Subject: [PATCH 10/69] Add verifiers.

---
 network-interaction-sdk/sdk-wallet/user_verifier.md | 13 +++++++++++++
 .../sdk-wallet/validator_verifier.md                | 13 +++++++++++++
 2 files changed, 26 insertions(+)
 create mode 100644 network-interaction-sdk/sdk-wallet/user_verifier.md
 create mode 100644 network-interaction-sdk/sdk-wallet/validator_verifier.md

diff --git a/network-interaction-sdk/sdk-wallet/user_verifier.md b/network-interaction-sdk/sdk-wallet/user_verifier.md
new file mode 100644
index 0000000..c8bdbc7
--- /dev/null
+++ b/network-interaction-sdk/sdk-wallet/user_verifier.md
@@ -0,0 +1,13 @@
+## UserVerifier
+
+```
+class UserVerifier:
+    constructor(public_key: UserPublicKey);
+
+    // Named constructor
+    fromAddress(address: IAddress): UserVerifier;
+
+    verify(data: bytes, signature: bytes): boolean;
+
+    getAddress(): Address;
+```
diff --git a/network-interaction-sdk/sdk-wallet/validator_verifier.md b/network-interaction-sdk/sdk-wallet/validator_verifier.md
new file mode 100644
index 0000000..15ef8ba
--- /dev/null
+++ b/network-interaction-sdk/sdk-wallet/validator_verifier.md
@@ -0,0 +1,13 @@
+## ValidatorVerifier
+
+```
+class ValidatorVerifier:
+    constructor(public_key: ValidatorPublicKey);
+
+    // Named constructors
+    static fromPublicKeyString(hex: string): ValidatorVerifier;
+
+    verify(data: bytes, signature: bytes): boolean;
+
+    getPublicKey(): ValidatorPublicKey;
+```

From 4a9c75afec4c7949082a1ce8d8777ad131508c22 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Fri, 30 Jun 2023 10:04:41 +0300
Subject: [PATCH 11/69] Fix after review.

---
 network-interaction-sdk/sdk-core/address.md | 37 ++++-----------------
 1 file changed, 7 insertions(+), 30 deletions(-)

diff --git a/network-interaction-sdk/sdk-core/address.md b/network-interaction-sdk/sdk-core/address.md
index 7e25047..8ca20e5 100644
--- a/network-interaction-sdk/sdk-core/address.md
+++ b/network-interaction-sdk/sdk-core/address.md
@@ -3,7 +3,7 @@
 ```
 class Address:
     // Should also validate the length of the provided input.
-    constructor(pubkey: bytes, hrp: string);
+    constructor(public_key: bytes, hrp: string);
 
     // Named constructors
     static fromBech32(value: string): Address;
@@ -17,10 +17,7 @@ class Address:
     hex(): string;
 
     // Returns the underlying public key.
-    pubkey(): bytes;
-
-    // Returns the shard of the address.
-    getShard(): int;
+    getPublicKey(): bytes;
 
     // Returns true if the address is a smart contract address.
     isSmartContract(): bool;
@@ -49,7 +46,7 @@ class AddressFactory:
     createFromBech32(value: string): Address;
 
     // Creates an address from a public key.
-    createFromPubkey(pubkey: bytes): Address;
+    createFromPublicKey(public_key: bytes): Address;
 
     // Creates an address from a hex string.
     createFromHex(value: string): Address;
@@ -63,34 +60,14 @@ factory = AddressFactory("erd")
 
 address = factory.create_from_bech32("erd1qyu5wthldzr8wx5c9ucg8kjagg0jfs53s8nr3zpz3hypefsdd8ssycr6th")
 address = factory.create_from_hex("0139472eff6886771a982f3083da5d421f24c29181e63888228dc81ca60d69e1")
-address = factory.create_from_pubkey(bytes.fromhex("0139472eff6886771a982f3083da5d421f24c29181e63888228dc81ca60d69e1"))
-```
-
-## AddressConverter
-
-```
-class AddressConverter:
-    constructor(hrp: string = DEFAULT_HRP);
-
-    // Converts a bech32 string to a public key.
-    bech32ToPubkey(value: string): bytes;
-
-    // Converts a public key to a bech32 string.
-    pubkeyToBech32(pubkey: bytes): string;
-```
-
-Example of usage:
-
-```
-converter = AddressConverter("erd")
-
-pubkey = converter.bech32_to_pubkey("erd1qyu5wthldzr8wx5c9ucg8kjagg0jfs53s8nr3zpz3hypefsdd8ssycr6th")
-bech32 = converter.pubkey_to_bech32(bytes.fromhex("0139472eff6886771a982f3083da5d421f24c29181e63888228dc81ca60d69e1"))
+address = factory.create_from_public_key(bytes.fromhex("0139472eff6886771a982f3083da5d421f24c29181e63888228dc81ca60d69e1"))
 ```
 
 Module-level functions:
 
 ```
 // Note that the first input parameter is received as an interface, but the return value is a concrete type [see Guideline **`in-ifaces-out-concrete-types`**].
-compute_contract_address(deployer: IAddress, deployment_nonce: INonce, address_hrp: string): Address:
+compute_contract_address(deployer: IAddress, deployment_nonce: INonce, address_hrp: string): Address;
+
+get_shard_of_address(address: IAddress): number;
 ```

From 0d923b0147d53f126cc3ec3a1d0039c0e7510164 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Fri, 30 Jun 2023 10:13:43 +0300
Subject: [PATCH 12/69] Fix after review.

---
 network-interaction-sdk/sdk-core/address.md            |  2 +-
 .../token_management_transactions_factory.md           | 10 ----------
 2 files changed, 1 insertion(+), 11 deletions(-)

diff --git a/network-interaction-sdk/sdk-core/address.md b/network-interaction-sdk/sdk-core/address.md
index 8ca20e5..fff2c64 100644
--- a/network-interaction-sdk/sdk-core/address.md
+++ b/network-interaction-sdk/sdk-core/address.md
@@ -69,5 +69,5 @@ Module-level functions:
 // Note that the first input parameter is received as an interface, but the return value is a concrete type [see Guideline **`in-ifaces-out-concrete-types`**].
 compute_contract_address(deployer: IAddress, deployment_nonce: INonce, address_hrp: string): Address;
 
-get_shard_of_address(address: IAddress): number;
+get_shard_of_address(address: IAddress, num_shards: number): number;
 ```
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
index d9b7999..71c1ff0 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
@@ -21,7 +21,6 @@ class TokenManagementTransactionsFactory:
 
         // Optionals:
         nonce?: INonce;
-        value?: ITransactionValue;
         gasPrice?: IGasPrice;
         gasLimit?: IGasLimit;
         guardian? : IAddress;
@@ -41,7 +40,6 @@ class TokenManagementTransactionsFactory:
 
         // Optionals:
         nonce?: INonce;
-        value?: ITransactionValue;
         gasPrice?: IGasPrice;
         gasLimit?: IGasLimit;
         guardian? : IAddress;
@@ -61,7 +59,6 @@ class TokenManagementTransactionsFactory:
 
         // Optionals:
         nonce?: INonce;
-        value?: ITransactionValue;
         gasPrice?: IGasPrice;
         gasLimit?: IGasLimit;
         guardian? : IAddress;
@@ -82,7 +79,6 @@ class TokenManagementTransactionsFactory:
 
         // Optionals:
         nonce?: INonce;
-        value?: ITransactionValue;
         gasPrice?: IGasPrice;
         gasLimit?: IGasLimit;
         guardian? : IAddress;
@@ -97,7 +93,6 @@ class TokenManagementTransactionsFactory:
 
         // Optionals:
         nonce?: INonce;
-        value?: ITransactionValue;
         gasPrice?: IGasPrice;
         gasLimit?: IGasLimit;
         guardian? : IAddress;
@@ -109,7 +104,6 @@ class TokenManagementTransactionsFactory:
 
         // Optionals:
         nonce?: INonce;
-        value?: ITransactionValue;
         gasPrice?: IGasPrice;
         gasLimit?: IGasLimit;
         guardian? : IAddress;
@@ -121,7 +115,6 @@ class TokenManagementTransactionsFactory:
 
         // Optionals:
         nonce?: INonce;
-        value?: ITransactionValue;
         gasPrice?: IGasPrice;
         gasLimit?: IGasLimit;
         guardian? : IAddress;
@@ -136,7 +129,6 @@ class TokenManagementTransactionsFactory:
 
         // Optionals:
         nonce?: INonce;
-        value?: ITransactionValue;
         gasPrice?: IGasPrice;
         gasLimit?: IGasLimit;
         guardian? : IAddress;
@@ -153,7 +145,6 @@ class TokenManagementTransactionsFactory:
 
         // Optionals:
         nonce?: INonce;
-        value?: ITransactionValue;
         gasPrice?: IGasPrice;
         gasLimit?: IGasLimit;
         guardian? : IAddress;
@@ -208,7 +199,6 @@ interface IIssueSemiFungibleArgs extends IBaseArgs {
 
 interface IBaseArgs {
     nonce?: INonce;
-    value?: ITransactionValue;
     gasPrice?: IGasPrice;
     gasLimit?: IGasLimit;
     guardian? : IAddress;

From 35e23bb31933af676ca7c1f32c6efeb73f90f1eb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Fri, 30 Jun 2023 10:16:29 +0300
Subject: [PATCH 13/69] Added new named constructor.

---
 network-interaction-sdk/sdk-wallet/validator_pem.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/network-interaction-sdk/sdk-wallet/validator_pem.md b/network-interaction-sdk/sdk-wallet/validator_pem.md
index 0f96d0a..b419fac 100644
--- a/network-interaction-sdk/sdk-wallet/validator_pem.md
+++ b/network-interaction-sdk/sdk-wallet/validator_pem.md
@@ -5,6 +5,7 @@ class ValidatorPEM:
     // Named constructors:
     static from_file(path: Path, index: number = 0): ValidatorPEM;
     static from_file_all(path: Path): ValidatorPEM[];
+    static from_folder_all(path: Path): ValidatorPEM[];
     static from_text(text: string, index: number = 0): ValidatorPEM;
     static from_text_all(text: string): ValidatorPEM[];
 

From 667012858e8532819616d9a67dbe7823bfc26f36 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Mon, 3 Jul 2023 11:13:40 +0300
Subject: [PATCH 14/69] Add some links with implementation examples.

---
 network-interaction-sdk/sdk-wallet/mnemonic.md | 5 +++++
 network-interaction-sdk/sdk-wallet/pem.md      | 6 ++++++
 network-interaction-sdk/sdk-wallet/user_pem.md | 6 ++++++
 3 files changed, 17 insertions(+)

diff --git a/network-interaction-sdk/sdk-wallet/mnemonic.md b/network-interaction-sdk/sdk-wallet/mnemonic.md
index 501cc6e..5d00625 100644
--- a/network-interaction-sdk/sdk-wallet/mnemonic.md
+++ b/network-interaction-sdk/sdk-wallet/mnemonic.md
@@ -1,3 +1,8 @@
+## Mnemonic
+
+Implementation examples:
+ - https://github.com/multiversx/mx-sdk-js-wallet/blob/main/src/mnemonic.ts
+ - https://github.com/multiversx/mx-sdk-py-wallet/blob/main/multiversx_sdk_wallet/mnemonic.py
 
 ```
 class Mnemonic:
diff --git a/network-interaction-sdk/sdk-wallet/pem.md b/network-interaction-sdk/sdk-wallet/pem.md
index 4571ec5..7fb8bd7 100644
--- a/network-interaction-sdk/sdk-wallet/pem.md
+++ b/network-interaction-sdk/sdk-wallet/pem.md
@@ -1,3 +1,9 @@
+## PEM
+
+Implementation examples:
+ - https://github.com/multiversx/mx-sdk-js-wallet/blob/main/src/pem.ts
+ - https://github.com/multiversx/mx-sdk-py-wallet/blob/main/multiversx_sdk_wallet/pem_entry.py
+
 ```
 class PemEntry:
     label: string;
diff --git a/network-interaction-sdk/sdk-wallet/user_pem.md b/network-interaction-sdk/sdk-wallet/user_pem.md
index e58d6d2..be0f0eb 100644
--- a/network-interaction-sdk/sdk-wallet/user_pem.md
+++ b/network-interaction-sdk/sdk-wallet/user_pem.md
@@ -1,3 +1,9 @@
+## UserPEM
+
+Implementation examples:
+ - https://github.com/multiversx/mx-sdk-py-wallet/blob/main/multiversx_sdk_wallet/user_pem.py
+ - https://github.com/multiversx/mx-sdk-js-wallet/blob/main/src/pem.ts
+
 ```
 class UserPEM:
     constructor(label: string, key: UserSecretKey);

From 883c1720fb0bb9465b046ac09e8b2b87b09b7904 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Mon, 3 Jul 2023 14:41:14 +0300
Subject: [PATCH 15/69] Sketch user wallet.

---
 .../sdk-wallet/mnemonic.md                    | 11 ++++++--
 network-interaction-sdk/sdk-wallet/pem.md     | 11 ++++++--
 .../sdk-wallet/user_pem.md                    |  9 ++++--
 .../sdk-wallet/user_public_key.md             |  2 ++
 .../sdk-wallet/user_secret_key.md             |  2 ++
 .../sdk-wallet/user_wallet.md                 | 28 +++++++++++++++++++
 .../sdk-wallet/validator_pem.md               |  7 +++++
 7 files changed, 61 insertions(+), 9 deletions(-)

diff --git a/network-interaction-sdk/sdk-wallet/mnemonic.md b/network-interaction-sdk/sdk-wallet/mnemonic.md
index 5d00625..1a125a9 100644
--- a/network-interaction-sdk/sdk-wallet/mnemonic.md
+++ b/network-interaction-sdk/sdk-wallet/mnemonic.md
@@ -1,8 +1,8 @@
 ## Mnemonic
 
-Implementation examples:
- - https://github.com/multiversx/mx-sdk-js-wallet/blob/main/src/mnemonic.ts
- - https://github.com/multiversx/mx-sdk-py-wallet/blob/main/multiversx_sdk_wallet/mnemonic.py
+This component allows one to generate a new mnemonic, or load / parse / validate an existing one. 
+
+It also allows one to derive a secret key from the mnemonic.
 
 ```
 class Mnemonic:
@@ -28,3 +28,8 @@ class Mnemonic:
     toString(): string;
 }
 ```
+
+### Implementation notes
+
+ - https://github.com/multiversx/mx-sdk-js-wallet/blob/main/src/mnemonic.ts
+ - https://github.com/multiversx/mx-sdk-py-wallet/blob/main/multiversx_sdk_wallet/mnemonic.py
diff --git a/network-interaction-sdk/sdk-wallet/pem.md b/network-interaction-sdk/sdk-wallet/pem.md
index 7fb8bd7..ebb0d3c 100644
--- a/network-interaction-sdk/sdk-wallet/pem.md
+++ b/network-interaction-sdk/sdk-wallet/pem.md
@@ -1,8 +1,8 @@
 ## PEM
 
-Implementation examples:
- - https://github.com/multiversx/mx-sdk-js-wallet/blob/main/src/pem.ts
- - https://github.com/multiversx/mx-sdk-py-wallet/blob/main/multiversx_sdk_wallet/pem_entry.py
+`PemEntry` is a simple tuple of `label` (e.g. bech32 address, BLS key) and `data` (user secret key, validator secret key). It is used handle the hold of PEM files.
+
+Module-level functions are used to parse PEM files into `PemEntry` items.
 
 ```
 class PemEntry:
@@ -16,3 +16,8 @@ Module-level functions:
 parse_text(text: string): PemEntry[];
 parse_file(path: Path): PemEntry[];
 ```
+
+### Implementation notes
+
+ - https://github.com/multiversx/mx-sdk-js-wallet/blob/main/src/pem.ts
+ - https://github.com/multiversx/mx-sdk-py-wallet/blob/main/multiversx_sdk_wallet/pem_entry.py
diff --git a/network-interaction-sdk/sdk-wallet/user_pem.md b/network-interaction-sdk/sdk-wallet/user_pem.md
index be0f0eb..679b668 100644
--- a/network-interaction-sdk/sdk-wallet/user_pem.md
+++ b/network-interaction-sdk/sdk-wallet/user_pem.md
@@ -1,8 +1,6 @@
 ## UserPEM
 
-Implementation examples:
- - https://github.com/multiversx/mx-sdk-py-wallet/blob/main/multiversx_sdk_wallet/user_pem.py
- - https://github.com/multiversx/mx-sdk-js-wallet/blob/main/src/pem.ts
+`UserPEM` is a thin wrapper over the functionality of `pem`.
 
 ```
 class UserPEM:
@@ -17,3 +15,8 @@ class UserPEM:
     save(path: Path): void;
     to_text(): string;
 ```
+
+### Implementation notes
+
+ - https://github.com/multiversx/mx-sdk-py-wallet/blob/main/multiversx_sdk_wallet/user_pem.py
+ - https://github.com/multiversx/mx-sdk-js-wallet/blob/main/src/pem.ts
diff --git a/network-interaction-sdk/sdk-wallet/user_public_key.md b/network-interaction-sdk/sdk-wallet/user_public_key.md
index e9b3056..0a9e9d0 100644
--- a/network-interaction-sdk/sdk-wallet/user_public_key.md
+++ b/network-interaction-sdk/sdk-wallet/user_public_key.md
@@ -1,3 +1,5 @@
+## UserPublicKey
+
 ```
 class UserPublicKey:
     // The constructor(s) should also validate the length of the provided input.
diff --git a/network-interaction-sdk/sdk-wallet/user_secret_key.md b/network-interaction-sdk/sdk-wallet/user_secret_key.md
index 2dfd2ac..e9b5129 100644
--- a/network-interaction-sdk/sdk-wallet/user_secret_key.md
+++ b/network-interaction-sdk/sdk-wallet/user_secret_key.md
@@ -1,3 +1,5 @@
+## UserSecretKey
+
 ```
 class UserSecretKey:
     // At least one of the following constructors should be implemented.
diff --git a/network-interaction-sdk/sdk-wallet/user_wallet.md b/network-interaction-sdk/sdk-wallet/user_wallet.md
index e69de29..7844ab9 100644
--- a/network-interaction-sdk/sdk-wallet/user_wallet.md
+++ b/network-interaction-sdk/sdk-wallet/user_wallet.md
@@ -0,0 +1,28 @@
+## UserWallet
+
+```
+class UserWallet:
+    constructor(kind: str, encrypted_data: EncryptedData, public_key_when_kind_is_secret_key: Optional[UserPublicKey])
+    
+    // Named constructor
+    static from_secret_key(secret_key: UserSecretKey, password: str, randomness: Optional[IRandomness]): UserWallet
+    static from_mnemonic(mnemonic: str, password: str, randomness: Optional[IRandomness]): UserWallet
+
+    // Decryption (static) methods. 'keyfile_object' is the JSON object from the keyfile (wallet JSON).
+    static decrypt_secret_key(keyfile_object: Any, password: str): UserSecretKey;
+    static decrypt_mnemonic(keyfile_object: Any, password: str): Mnemonic;
+
+    // Wrapper over the two methods above. Calls mnemonic.derive_key() under the hood.
+    static load_secret_key(path: Path, password: str, address_index: Optional[int] = 0): UserSecretKey;
+
+    // Saves the wallet to a file.
+    save(path: Path, address_hrp: Optional[str]);
+
+    // Converts the object to a JSON string (ready to be saved to a wallet keyfile).
+    to_json(): str
+```
+
+### Implementation notes
+
+ - https://github.com/multiversx/mx-sdk-py-wallet/blob/main/multiversx_sdk_wallet/user_wallet.py
+ - https://github.com/multiversx/mx-sdk-js-wallet/blob/main/src/userWallet.ts
diff --git a/network-interaction-sdk/sdk-wallet/validator_pem.md b/network-interaction-sdk/sdk-wallet/validator_pem.md
index b419fac..94cac4a 100644
--- a/network-interaction-sdk/sdk-wallet/validator_pem.md
+++ b/network-interaction-sdk/sdk-wallet/validator_pem.md
@@ -1,3 +1,7 @@
+## ValidatorPEM
+
+`ValidatorPEM` is a thin wrapper over the functionality of `pem`.
+
 ```
 class ValidatorPEM:
     constructor(label: string, key: ValidatorSecretKey);
@@ -12,3 +16,6 @@ class ValidatorPEM:
     save(path: Path): void;
     to_text(): string;
 ```
+
+### Implementation notes
+

From e29ebe6da0865c849295d4e9ca649750a05013d6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Tue, 4 Jul 2023 11:34:29 +0300
Subject: [PATCH 16/69] Update guidelines.

---
 network-interaction-sdk/guidelines.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/network-interaction-sdk/guidelines.md b/network-interaction-sdk/guidelines.md
index 7202f79..b680c61 100644
--- a/network-interaction-sdk/guidelines.md
+++ b/network-interaction-sdk/guidelines.md
@@ -3,3 +3,12 @@
 Generally speaking, it's recommended to receive input parameters as abstractions (interfaces) in the public API of the SDKs. This leads to an improved decoupling, and allows for easier type substitution (e.g. easier mocking, testing).
 
 Generally speaking, it's recommended to return concrete types in the public API of the SDKs. The client code is responsible with decoupling from unnecessary data and behaviour of returned objects (e.g. by using interfaces, on their side). 
+
+## **`pay-attention-to-types`**
+
+ - For JavaScript / TypeScript, `bytes` should be `Uint8Array`.
+
+## **`follow-language-conventions`**
+ 
+ - Make sure to follow the naming conventions of the language you're using, e.g. `snake_case` vs. `camelCase`.
+ - In the specs, interfaces are prefixed with `I`, simply to make them stand out. However, in the implementing libraries, this convention does not have to be applied. 

From eb273f262658c1a58f6ddde88e799649b6ade976 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Tue, 4 Jul 2023 11:36:18 +0300
Subject: [PATCH 17/69] Init sdk-wallet.

---
 network-interaction-sdk/guidelines.md         | 14 ++++++++
 .../sdk-wallet/public_key.md                  |  8 +++++
 .../sdk-wallet/secret_key.md                  |  8 +++++
 .../sdk-wallet/user_crypto_provider.md        | 33 +++++++++++++++++++
 .../sdk-wallet/validator_crypto_provider.md   | 24 ++++++++++++++
 5 files changed, 87 insertions(+)
 create mode 100644 network-interaction-sdk/guidelines.md
 create mode 100644 network-interaction-sdk/sdk-wallet/public_key.md
 create mode 100644 network-interaction-sdk/sdk-wallet/secret_key.md
 create mode 100644 network-interaction-sdk/sdk-wallet/user_crypto_provider.md
 create mode 100644 network-interaction-sdk/sdk-wallet/validator_crypto_provider.md

diff --git a/network-interaction-sdk/guidelines.md b/network-interaction-sdk/guidelines.md
new file mode 100644
index 0000000..b680c61
--- /dev/null
+++ b/network-interaction-sdk/guidelines.md
@@ -0,0 +1,14 @@
+##  **`in-ifaces-out-concrete-types`**
+
+Generally speaking, it's recommended to receive input parameters as abstractions (interfaces) in the public API of the SDKs. This leads to an improved decoupling, and allows for easier type substitution (e.g. easier mocking, testing).
+
+Generally speaking, it's recommended to return concrete types in the public API of the SDKs. The client code is responsible with decoupling from unnecessary data and behaviour of returned objects (e.g. by using interfaces, on their side). 
+
+## **`pay-attention-to-types`**
+
+ - For JavaScript / TypeScript, `bytes` should be `Uint8Array`.
+
+## **`follow-language-conventions`**
+ 
+ - Make sure to follow the naming conventions of the language you're using, e.g. `snake_case` vs. `camelCase`.
+ - In the specs, interfaces are prefixed with `I`, simply to make them stand out. However, in the implementing libraries, this convention does not have to be applied. 
diff --git a/network-interaction-sdk/sdk-wallet/public_key.md b/network-interaction-sdk/sdk-wallet/public_key.md
new file mode 100644
index 0000000..e56fb9f
--- /dev/null
+++ b/network-interaction-sdk/sdk-wallet/public_key.md
@@ -0,0 +1,8 @@
+## PublicKey
+
+```
+interface IPublicKey:
+    get_bytes(): bytes
+```
+
+In order to create and handle public keys, use the methods of the `(User|Validator)CryptoProvider`.
diff --git a/network-interaction-sdk/sdk-wallet/secret_key.md b/network-interaction-sdk/sdk-wallet/secret_key.md
new file mode 100644
index 0000000..09633c1
--- /dev/null
+++ b/network-interaction-sdk/sdk-wallet/secret_key.md
@@ -0,0 +1,8 @@
+## SecretKey
+
+```
+interface ISecretKey:
+    get_bytes(): bytes
+```
+
+In order to create and handle secret keys, use the methods of the `(User|Validator)CryptoProvider`.
diff --git a/network-interaction-sdk/sdk-wallet/user_crypto_provider.md b/network-interaction-sdk/sdk-wallet/user_crypto_provider.md
new file mode 100644
index 0000000..8fbecff
--- /dev/null
+++ b/network-interaction-sdk/sdk-wallet/user_crypto_provider.md
@@ -0,0 +1,33 @@
+## UserCryptoProvider
+
+```
+class UserCryptoProvider:
+    // Should not throw.
+    generate_pair(): (ISecretKey, IPublicKey)
+
+    // Can throw:
+    // - ErrInvalidSecretKey
+    sign(data: bytes, secret_key: ISecretKey): bytes
+
+    // Can throw:
+    // - ErrInvalidPublicKey
+    // - ErrInvalidSignature
+    verify(data: bytes, signature: bytes, public_key: IPublicKey): bool
+
+    // Can throw:
+    // - ErrInvalidSecretKey
+    create_secret_key_from_bytes(data: bytes): ISecretKey
+
+    // Can throw:
+    // - ErrInvalidPublicKey
+    create_public_key_from_bytes(data: bytes): IPublicKey
+
+    // Should not throw.
+    generate_mnemonic(): Mnemonic
+
+    // Can throw:
+    // - ErrInvalidMnemonic
+    derive_secret_key_from_mnemonic(mnemonic: Mnemonic, address_index: number = 0, password: string = ""): ISecretKey
+```
+
+Generally speaking, `generate_mnemonic` and `derive_secret_key_from_mnemonic` are only available in the `UserCryptoProvider` (that is, they are not available in `ValidatorCryptoProvider`).
diff --git a/network-interaction-sdk/sdk-wallet/validator_crypto_provider.md b/network-interaction-sdk/sdk-wallet/validator_crypto_provider.md
new file mode 100644
index 0000000..ec4a263
--- /dev/null
+++ b/network-interaction-sdk/sdk-wallet/validator_crypto_provider.md
@@ -0,0 +1,24 @@
+## ValidatorCryptoProvider
+
+```
+class ValidatorCryptoProvider:
+    // Should not throw.
+    generate_pair(): (ISecretKey, IPublicKey)
+
+    // Can throw:
+    // - ErrInvalidSecretKey
+    sign(data: bytes, secret_key: ISecretKey): bytes
+
+    // Can throw:
+    // - ErrInvalidPublicKey
+    // - ErrInvalidSignature
+    verify(data: bytes, signature: bytes, public_key: IPublicKey): bool
+
+    // Can throw:
+    // - ErrInvalidSecretKey
+    create_secret_key_from_bytes(data: bytes): ISecretKey
+
+    // Can throw:
+    // - ErrInvalidPublicKey
+    create_public_key_from_bytes(data: bytes): IPublicKey
+```

From 5099607665bd8f73b41e7f033751bb84119d9ac6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Tue, 4 Jul 2023 18:09:25 +0300
Subject: [PATCH 18/69] Further work ("crypto" etc.).

---
 network-interaction-sdk/guidelines.md         |  3 +-
 .../keypair_based_encryptor_decryptor.md      |  8 +++++
 .../password_based_encryptor_decryptor.md     |  8 +++++
 .../crypto/password_encrypted_data.md         | 30 +++++++++++++++++
 .../crypto/public_key_encrypted_data.md       | 16 ++++++++++
 .../keystores/encrypted_keystore.md           | 32 +++++++++++++++++++
 .../sdk-wallet/keystores/pem_keystore.md      | 23 +++++++++++++
 network-interaction-sdk/sdk-wallet/notes.md   |  0
 ...to_provider.md => user_wallet_provider.md} |  6 ++--
 ...ovider.md => validator_wallet_provider.md} |  4 +--
 10 files changed, 124 insertions(+), 6 deletions(-)
 create mode 100644 network-interaction-sdk/sdk-wallet/crypto/keypair_based_encryptor_decryptor.md
 create mode 100644 network-interaction-sdk/sdk-wallet/crypto/password_based_encryptor_decryptor.md
 create mode 100644 network-interaction-sdk/sdk-wallet/crypto/password_encrypted_data.md
 create mode 100644 network-interaction-sdk/sdk-wallet/crypto/public_key_encrypted_data.md
 create mode 100644 network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
 create mode 100644 network-interaction-sdk/sdk-wallet/keystores/pem_keystore.md
 create mode 100644 network-interaction-sdk/sdk-wallet/notes.md
 rename network-interaction-sdk/sdk-wallet/{user_crypto_provider.md => user_wallet_provider.md} (82%)
 rename network-interaction-sdk/sdk-wallet/{validator_crypto_provider.md => validator_wallet_provider.md} (90%)

diff --git a/network-interaction-sdk/guidelines.md b/network-interaction-sdk/guidelines.md
index b680c61..addc9a3 100644
--- a/network-interaction-sdk/guidelines.md
+++ b/network-interaction-sdk/guidelines.md
@@ -11,4 +11,5 @@ Generally speaking, it's recommended to return concrete types in the public API
 ## **`follow-language-conventions`**
  
  - Make sure to follow the naming conventions of the language you're using, e.g. `snake_case` vs. `camelCase`.
- - In the specs, interfaces are prefixed with `I`, simply to make them stand out. However, in the implementing libraries, this convention does not have to be applied. 
+ - In the specs, interfaces are prefixed with `I`, simply to make them stand out. However, in the implementing libraries, this convention does not have to be applied.
+ - In `go`, the term `serialize` (whether it's part of a class name or a function name) can be replaced by `marshal`, since that is the convention.
diff --git a/network-interaction-sdk/sdk-wallet/crypto/keypair_based_encryptor_decryptor.md b/network-interaction-sdk/sdk-wallet/crypto/keypair_based_encryptor_decryptor.md
new file mode 100644
index 0000000..c7df225
--- /dev/null
+++ b/network-interaction-sdk/sdk-wallet/crypto/keypair_based_encryptor_decryptor.md
@@ -0,0 +1,8 @@
+## KeyPairBasedEncryptorDecryptor
+
+```
+class KeyPairBasedEncryptorDecryptor:
+    encrypt(data: bytes, recipient_public_key: IPublicKey, auth_secret_key: ISecretKey): PublicKeyEncryptedData;
+
+    decrypt(data: PublicKeyEncryptedData, decryptor_secret_key: SecretKey): data;
+```
diff --git a/network-interaction-sdk/sdk-wallet/crypto/password_based_encryptor_decryptor.md b/network-interaction-sdk/sdk-wallet/crypto/password_based_encryptor_decryptor.md
new file mode 100644
index 0000000..eb2989f
--- /dev/null
+++ b/network-interaction-sdk/sdk-wallet/crypto/password_based_encryptor_decryptor.md
@@ -0,0 +1,8 @@
+## PasswordBasedEncryptorDecryptor
+
+```
+class PasswordBasedEncryptorDecryptor:
+    encrypt(data: bytes, password: string): PasswordEncryptedData;
+
+    decrypt(data: PasswordEncryptedData, password: string): bytes;
+```
diff --git a/network-interaction-sdk/sdk-wallet/crypto/password_encrypted_data.md b/network-interaction-sdk/sdk-wallet/crypto/password_encrypted_data.md
new file mode 100644
index 0000000..f184b14
--- /dev/null
+++ b/network-interaction-sdk/sdk-wallet/crypto/password_encrypted_data.md
@@ -0,0 +1,30 @@
+## PasswordEncryptedData
+
+```
+dto PasswordEncryptedData:
+    id: string;
+    version: number;
+    cipher: string;
+    ciphertext: string;
+    iv: string;
+    kdf: string;
+    kdfparams: object;
+    salt: string;
+    mac: string;
+
+// Example of class compatible with "PasswordEncryptedData.kdfparams".
+// Can be anything, and it's specific to a "PasswordEncryptedData.kdf" (e.g. "scrypt").
+// EncryptorDecryptor.encrypt() puts this into "PasswordEncryptedData.kdfparams".
+// EncryptorDecryptor.decrypt() interprets (possibly validates) it.
+dto ScryptKeyDerivationParams:
+    // numIterations
+    n = 4096;
+
+    // memFactor
+    r = 8;
+
+    // pFactor
+    p = 1;
+
+    dklen = 32;
+```
diff --git a/network-interaction-sdk/sdk-wallet/crypto/public_key_encrypted_data.md b/network-interaction-sdk/sdk-wallet/crypto/public_key_encrypted_data.md
new file mode 100644
index 0000000..29495ed
--- /dev/null
+++ b/network-interaction-sdk/sdk-wallet/crypto/public_key_encrypted_data.md
@@ -0,0 +1,16 @@
+## PublicKeyEncryptedData
+
+```
+dto PublicKeyEncryptedData:
+    nonce: string;
+    version: number;
+    cipher: string;
+    ciphertext: string;
+    mac: string;
+    identities: PublicKeyEncryptedDataIdentities;
+
+dto PublicKeyEncryptedDataIdentities:
+    recipient: string;
+    ephemeralPubKey: string;
+    originatorPubKey: string;
+```
diff --git a/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md b/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
new file mode 100644
index 0000000..6f794c4
--- /dev/null
+++ b/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
@@ -0,0 +1,32 @@
+## EncryptedKeystore
+
+```
+class EncryptedKeystore:
+    // The constructor is not captured by the specs; it's up to the implementing library to define it.
+    // Normally, the constructor should receive the following parameters: crypto provider, address HRP.
+
+    // Named constructor
+    static new_from_secret_key(secret_key: ISecretKey, password: string): Keystore
+    
+    // Named constructor
+    // In the future, "Trezor" password can be provided, as well.
+    static new_from_mnemonic(mnemonic: Mnemonic, password: string): Keystore
+    
+    // Named constructor
+    static new_from_file(path: Path, password: string): Keystore
+
+    // When kind == 'secret_key', only index == 0 is supported.
+    // When kind == 'mnemonic', the crypto provider is used under the hood to derive the secret key.
+    get_secret_key(index: int): ISecretKey
+
+    // Returns the JSON representation of the keystore.
+    serialize(): bytes
+
+    save(path: Path)
+```
+
+## Examples of usage
+
+```
+...
+```
diff --git a/network-interaction-sdk/sdk-wallet/keystores/pem_keystore.md b/network-interaction-sdk/sdk-wallet/keystores/pem_keystore.md
new file mode 100644
index 0000000..accd314
--- /dev/null
+++ b/network-interaction-sdk/sdk-wallet/keystores/pem_keystore.md
@@ -0,0 +1,23 @@
+## PEMStore
+
+```
+class PEMKeystore:
+    // The constructor is not captured by the specs; it's up to the implementing library to define it.
+    // Normally, the constructor should receive the following parameters: crypto provider, address HRP.
+
+    // Named constructor
+    static new_from_secret_key(secret_key: ISecretKey): PEMKeystore
+
+    get_secret_key(index: int): ISecretKey
+
+    // Returns the JSON representation of the keystore.
+    serialize(): bytes
+
+    save(path: Path)
+```
+
+## Examples of usage
+
+```
+...
+```
diff --git a/network-interaction-sdk/sdk-wallet/notes.md b/network-interaction-sdk/sdk-wallet/notes.md
new file mode 100644
index 0000000..e69de29
diff --git a/network-interaction-sdk/sdk-wallet/user_crypto_provider.md b/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
similarity index 82%
rename from network-interaction-sdk/sdk-wallet/user_crypto_provider.md
rename to network-interaction-sdk/sdk-wallet/user_wallet_provider.md
index 8fbecff..2ca370e 100644
--- a/network-interaction-sdk/sdk-wallet/user_crypto_provider.md
+++ b/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
@@ -1,7 +1,7 @@
-## UserCryptoProvider
+## UserWalletProvider
 
 ```
-class UserCryptoProvider:
+class UserWalletProvider:
     // Should not throw.
     generate_pair(): (ISecretKey, IPublicKey)
 
@@ -30,4 +30,4 @@ class UserCryptoProvider:
     derive_secret_key_from_mnemonic(mnemonic: Mnemonic, address_index: number = 0, password: string = ""): ISecretKey
 ```
 
-Generally speaking, `generate_mnemonic` and `derive_secret_key_from_mnemonic` are only available in the `UserCryptoProvider` (that is, they are not available in `ValidatorCryptoProvider`).
+Generally speaking, `generate_mnemonic` and `derive_secret_key_from_mnemonic` are only available in the `UserWalletProvider` (that is, they are not available in `ValidatorWalletProvider`).
diff --git a/network-interaction-sdk/sdk-wallet/validator_crypto_provider.md b/network-interaction-sdk/sdk-wallet/validator_wallet_provider.md
similarity index 90%
rename from network-interaction-sdk/sdk-wallet/validator_crypto_provider.md
rename to network-interaction-sdk/sdk-wallet/validator_wallet_provider.md
index ec4a263..72c4b69 100644
--- a/network-interaction-sdk/sdk-wallet/validator_crypto_provider.md
+++ b/network-interaction-sdk/sdk-wallet/validator_wallet_provider.md
@@ -1,7 +1,7 @@
-## ValidatorCryptoProvider
+## ValidatorWalletProvider
 
 ```
-class ValidatorCryptoProvider:
+class ValidatorWalletProvider:
     // Should not throw.
     generate_pair(): (ISecretKey, IPublicKey)
 

From 6d03426200698211a9861ca8736f617d498a8edf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Tue, 4 Jul 2023 21:26:10 +0300
Subject: [PATCH 19/69] Further work.

---
 network-interaction-sdk/guidelines.md         |  4 +
 .../keystores/encrypted_keystore.md           | 86 ++++++++++++++++---
 .../sdk-wallet/keystores/pem_keystore.md      |  7 +-
 network-interaction-sdk/sdk-wallet/notes.md   | 17 ++++
 .../sdk-wallet/user_wallet_provider.md        |  2 +-
 5 files changed, 100 insertions(+), 16 deletions(-)

diff --git a/network-interaction-sdk/guidelines.md b/network-interaction-sdk/guidelines.md
index addc9a3..d07b2ed 100644
--- a/network-interaction-sdk/guidelines.md
+++ b/network-interaction-sdk/guidelines.md
@@ -13,3 +13,7 @@ Generally speaking, it's recommended to return concrete types in the public API
  - Make sure to follow the naming conventions of the language you're using, e.g. `snake_case` vs. `camelCase`.
  - In the specs, interfaces are prefixed with `I`, simply to make them stand out. However, in the implementing libraries, this convention does not have to be applied.
  - In `go`, the term `serialize` (whether it's part of a class name or a function name) can be replaced by `marshal`, since that is the convention.
+
+## **`out-of-specs-arguments-should-be-optional`**
+
+E.g. randomness.
diff --git a/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md b/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
index 6f794c4..58e305c 100644
--- a/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
+++ b/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
@@ -3,28 +3,88 @@
 ```
 class EncryptedKeystore:
     // The constructor is not captured by the specs; it's up to the implementing library to define it.
-    // Normally, the constructor should receive the following parameters: crypto provider, address HRP.
 
     // Named constructor
-    static new_from_secret_key(secret_key: ISecretKey, password: string): Keystore
-    
+    static new_from_secret_key(secret_key: ISecretKey): Keystore
+
     // Named constructor
-    // In the future, "Trezor" password can be provided, as well.
-    static new_from_mnemonic(mnemonic: Mnemonic, password: string): Keystore
+    // Below, "wallet_provider" should implement "derive_secret_key_from_mnemonic()".
+    // Advice: in the implementation all the parameters will be held as instance state (private fields).
+    static new_from_mnemonic(wallet_provider: IWalletProvider, mnemonic: Mnemonic): Keystore
+
+    // Importing "constructor"
+    static import_from_object(wallet_provider: IWalletProvider, object: KeyfileObject, password: string): Keystore
+
+    // Importing "constructor"
+    static import_from_file(wallet_provider: IWalletProvider, path: Path, password: string): Keystore
+
+    // When kind == 'secretKey', only index == 0 is supported.
+    // When kind == 'mnemonic', the wallet provider is used under the hood to derive the secret key.
+    // Below, "passphrase" is the bip39 passphrase required to derive a secret key from a mnemonic (by default, it should be an empty string).
+    get_secret_key(index: int, passphrase: string): ISecretKey
+
+    // Should return true if kind == 'mnemonic' AND passphrases are enabled (left as future work).
+    supports_passphrase(): boolean
+
+    export_to_object(password: string): KeyfileObject
+
+    export_to_file(path: Path, password: string)
+```
+
+```
+dto KeyfileObject:
+    version: number;
+
+    // "secretKey|mnemonic"
+    kind: string;
     
-    // Named constructor
-    static new_from_file(path: Path, password: string): Keystore
+    // a GUID
+    id: string
+
+    // hex representation of the address
+    address: string 
+
+    // bech32 representation of the address
+    bech32: string
+
+    crypto: {
+        // PasswordEncryptedData.ciphertext
+        ciphertext: string;
 
-    // When kind == 'secret_key', only index == 0 is supported.
-    // When kind == 'mnemonic', the crypto provider is used under the hood to derive the secret key.
-    get_secret_key(index: int): ISecretKey
+        cipherparams: {
+            // PasswordEncryptedData.iv
+            iv: string;
+        };
 
-    // Returns the JSON representation of the keystore.
-    serialize(): bytes
+        // PasswordEncryptedData.cipher
+        cipher: string;
 
-    save(path: Path)
+        // PasswordEncryptedData.kdf
+        kdf: string;
+        kdfparams: {
+            // PasswordEncryptedData.kdfparams.n
+            n: number;
+
+            // PasswordEncryptedData.kdfparams.r
+            r: number;
+
+            // PasswordEncryptedData.kdfparams.p
+            p: number;
+
+            // PasswordEncryptedData.kdfparams.dklen
+            dklen: number;
+            
+            // PasswordEncryptedData.salt
+            salt: string; 
+        };
+
+        // PasswordEncryptedData.mac
+        mac: string;
+    };
 ```
 
+TBD: Can we perhaps adjust `EncryptedData` to be more compatible with `KeyfileObject.crypto`?
+
 ## Examples of usage
 
 ```
diff --git a/network-interaction-sdk/sdk-wallet/keystores/pem_keystore.md b/network-interaction-sdk/sdk-wallet/keystores/pem_keystore.md
index accd314..8361f14 100644
--- a/network-interaction-sdk/sdk-wallet/keystores/pem_keystore.md
+++ b/network-interaction-sdk/sdk-wallet/keystores/pem_keystore.md
@@ -3,12 +3,15 @@
 ```
 class PEMKeystore:
     // The constructor is not captured by the specs; it's up to the implementing library to define it.
-    // Normally, the constructor should receive the following parameters: crypto provider, address HRP.
 
     // Named constructor
     static new_from_secret_key(secret_key: ISecretKey): PEMKeystore
 
-    get_secret_key(index: int): ISecretKey
+    // The parameter "passphrase" would normally be ignored.
+    get_secret_key(index: int, passphrase: string): ISecretKey
+
+    // Should return false.
+    supports_passphrase(): boolean
 
     // Returns the JSON representation of the keystore.
     serialize(): bytes
diff --git a/network-interaction-sdk/sdk-wallet/notes.md b/network-interaction-sdk/sdk-wallet/notes.md
index e69de29..ca97ec0 100644
--- a/network-interaction-sdk/sdk-wallet/notes.md
+++ b/network-interaction-sdk/sdk-wallet/notes.md
@@ -0,0 +1,17 @@
+## Keystores
+
+Components in `sdk-wallet/keystore` should implement the interface:
+
+```
+get_secret_key(index: int, passphrase: string): ISecretKey
+```
+
+`PEMKeystore` would simply ignore the parameter `passphrase`. `EncryptedKeystore` created with a secret key (as opposed to a mnemonic) would also ignore the parameter `passphrase`.
+
+**Implementation detail:** given the constraint above, it follows that an instance of `EncryptedKeystore` (which is a wrapper over the well-known JSON wallet) holds decrypted data within its state.
+
+**Design detail:** components in `sdk-wallet/keystore` should not depend on `Address` within their public interface (though they are allowed to depend on it within their implementation). For example, the `export` functionality of `EncryptedKeystore` requires the functionality provided by `Address` (conversion from public key bytes to bech32 representation).
+
+### References:
+ - https://github.com/ethereumjs/keythereum
+ - https://github.com/ethereumjs/ethereumjs-wallet/blob/master/docs/classes/wallet.md
diff --git a/network-interaction-sdk/sdk-wallet/user_wallet_provider.md b/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
index 2ca370e..b2149c6 100644
--- a/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
+++ b/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
@@ -27,7 +27,7 @@ class UserWalletProvider:
 
     // Can throw:
     // - ErrInvalidMnemonic
-    derive_secret_key_from_mnemonic(mnemonic: Mnemonic, address_index: number = 0, password: string = ""): ISecretKey
+    derive_secret_key_from_mnemonic(mnemonic: Mnemonic, address_index: number = 0, passphrase: string = ""): ISecretKey
 ```
 
 Generally speaking, `generate_mnemonic` and `derive_secret_key_from_mnemonic` are only available in the `UserWalletProvider` (that is, they are not available in `ValidatorWalletProvider`).

From cc910f712033906fdda4e8b26a91825aa0233ea3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Wed, 5 Jul 2023 13:52:29 +0300
Subject: [PATCH 20/69] Further work (keystores) etc.

---
 network-interaction-sdk/sdk-core/address.md   | 75 +++++++++++++++++++
 .../keystores/encrypted_keystore.md           |  3 -
 .../sdk-wallet/keystores/pem_keystore.md      | 18 +++--
 .../sdk-wallet/mnemonic.md                    | 24 ++++++
 network-interaction-sdk/sdk-wallet/notes.md   | 12 +--
 5 files changed, 114 insertions(+), 18 deletions(-)
 create mode 100644 network-interaction-sdk/sdk-core/address.md
 create mode 100644 network-interaction-sdk/sdk-wallet/mnemonic.md

diff --git a/network-interaction-sdk/sdk-core/address.md b/network-interaction-sdk/sdk-core/address.md
new file mode 100644
index 0000000..6c16ca9
--- /dev/null
+++ b/network-interaction-sdk/sdk-core/address.md
@@ -0,0 +1,75 @@
+## Address
+
+```
+class Address:
+    // Should also validate the length of the provided input.
+    constructor(public_key: bytes, hrp: string);
+
+    // Named constructor
+    static newfromBech32(value: string): Address;
+
+    // Named constructor
+    static newFromHex(value: string, hrp: string): Address;
+
+    // Returns the address as a string (bech32).
+    bech32(): string;
+
+    // Returns the address as a string (hex).
+    // Name should be adjusted to match the language's convention.
+    hex(): string;
+
+    // Returns the underlying public key.
+    getPublicKey(): bytes;
+
+    // Returns true if the address is a smart contract address.
+    isSmartContract(): bool;
+```
+
+Example of usage:
+
+```
+address = Address.from_bech32("erd1qyu5wthldzr8wx5c9ucg8kjagg0jfs53s8nr3zpz3hypefsdd8ssycr6th")
+
+print("Address (bech32-encoded)", address.bech32())
+print("Public key (hex-encoded):", address.hex())
+```
+
+## AddressFactory
+
+```
+class AddressFactory:
+    constructor(hrp: string = DEFAULT_HRP);
+
+    // Creates an address with all bytes set to zero.
+    // This is the same as the "contract deployment address".
+    createZero(): Address;
+
+    // Creates an address from a bech32 string.
+    createFromBech32(value: string): Address;
+
+    // Creates an address from a public key.
+    createFromPublicKey(public_key: bytes): Address;
+
+    // Creates an address from a hex string.
+    createFromHex(value: string): Address;
+```
+
+Example of usage:
+
+```
+
+factory = AddressFactory("erd")
+
+address = factory.create_from_bech32("erd1qyu5wthldzr8wx5c9ucg8kjagg0jfs53s8nr3zpz3hypefsdd8ssycr6th")
+address = factory.create_from_hex("0139472eff6886771a982f3083da5d421f24c29181e63888228dc81ca60d69e1")
+address = factory.create_from_public_key(bytes.fromhex("0139472eff6886771a982f3083da5d421f24c29181e63888228dc81ca60d69e1"))
+```
+
+Module-level functions:
+
+```
+// Note that the first input parameter is received as an interface, but the return value is a concrete type [see Guideline **`in-ifaces-out-concrete-types`**].
+compute_contract_address(deployer: IAddress, deployment_nonce: INonce, address_hrp: string): Address;
+
+get_shard_of_address(address: IAddress, num_shards: number): number;
+```
diff --git a/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md b/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
index 58e305c..ef41f5f 100644
--- a/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
+++ b/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
@@ -23,9 +23,6 @@ class EncryptedKeystore:
     // Below, "passphrase" is the bip39 passphrase required to derive a secret key from a mnemonic (by default, it should be an empty string).
     get_secret_key(index: int, passphrase: string): ISecretKey
 
-    // Should return true if kind == 'mnemonic' AND passphrases are enabled (left as future work).
-    supports_passphrase(): boolean
-
     export_to_object(password: string): KeyfileObject
 
     export_to_file(path: Path, password: string)
diff --git a/network-interaction-sdk/sdk-wallet/keystores/pem_keystore.md b/network-interaction-sdk/sdk-wallet/keystores/pem_keystore.md
index 8361f14..b0d9e15 100644
--- a/network-interaction-sdk/sdk-wallet/keystores/pem_keystore.md
+++ b/network-interaction-sdk/sdk-wallet/keystores/pem_keystore.md
@@ -7,16 +7,20 @@ class PEMKeystore:
     // Named constructor
     static new_from_secret_key(secret_key: ISecretKey): PEMKeystore
 
-    // The parameter "passphrase" would normally be ignored.
-    get_secret_key(index: int, passphrase: string): ISecretKey
+    // Named constructor
+    static new_from_secret_keys(secret_keys: ISecretKey[]): PEMKeystore
+
+    // Importing "constructor"
+    static import_from_text(text: string): PEMKeystore
+
+    // Importing "constructor"
+    static import_from_file(path: Path): PEMKeystore
 
-    // Should return false.
-    supports_passphrase(): boolean
+    get_secret_key(index: int): ISecretKey
 
-    // Returns the JSON representation of the keystore.
-    serialize(): bytes
+    export_to_text(): string
 
-    save(path: Path)
+    export_to_file(path: Path)
 ```
 
 ## Examples of usage
diff --git a/network-interaction-sdk/sdk-wallet/mnemonic.md b/network-interaction-sdk/sdk-wallet/mnemonic.md
new file mode 100644
index 0000000..fa58a8c
--- /dev/null
+++ b/network-interaction-sdk/sdk-wallet/mnemonic.md
@@ -0,0 +1,24 @@
+## Mnemonic
+
+This component allows one to load / parse / validate an existing one. 
+
+It also allows one to derive a secret key from the mnemonic.
+
+```
+class Mnemonic:
+    // At least one of the following constructors should be implemented.
+    // The constructor(s) should also trim whitespace and validate the mnemonic.
+    constructor(text: string);
+    constructor(words: string[]);
+
+    // Alternatively, named constructors can be used:
+    static newfromText(text: string): Mnemonic;
+    static newfromWords(words: string[]): Mnemonic;
+
+    // Gets the mnemonic words.
+    getWords(): string[];
+
+    // Returns the mnemonic as a string.
+    toString(): string;
+}
+```
diff --git a/network-interaction-sdk/sdk-wallet/notes.md b/network-interaction-sdk/sdk-wallet/notes.md
index ca97ec0..9ad0a31 100644
--- a/network-interaction-sdk/sdk-wallet/notes.md
+++ b/network-interaction-sdk/sdk-wallet/notes.md
@@ -1,17 +1,13 @@
 ## Keystores
 
-Components in `sdk-wallet/keystore` should implement the interface:
+Components in `sdk-wallet/keystore`, even they do share a common purpose - storing secret keys - are not meant to be used interchangeably. Generally speaking, they do not (are not required to) share a common interface. If needed, client code can design adapters over these components in order to unify their interfaces. This is outside of the specs.
 
-```
-get_secret_key(index: int, passphrase: string): ISecretKey
-```
-
-`PEMKeystore` would simply ignore the parameter `passphrase`. `EncryptedKeystore` created with a secret key (as opposed to a mnemonic) would also ignore the parameter `passphrase`.
-
-**Implementation detail:** given the constraint above, it follows that an instance of `EncryptedKeystore` (which is a wrapper over the well-known JSON wallet) holds decrypted data within its state.
+**Implementation detail:** an instance of `EncryptedKeystore` (which is a wrapper over the well-known JSON wallet) holds decrypted data within its state.
 
 **Design detail:** components in `sdk-wallet/keystore` should not depend on `Address` within their public interface (though they are allowed to depend on it within their implementation). For example, the `export` functionality of `EncryptedKeystore` requires the functionality provided by `Address` (conversion from public key bytes to bech32 representation).
 
 ### References:
  - https://github.com/ethereumjs/keythereum
  - https://github.com/ethereumjs/ethereumjs-wallet/blob/master/docs/classes/wallet.md
+ - https://github.com/multiversx/mx-sdk-js-wallet/blob/main/src/userWallet.ts
+ - https://github.com/multiversx/mx-sdk-py-wallet/blob/main/multiversx_sdk_wallet/user_wallet.py

From 9df1a84b56c39afca1d0e61f9270dad38b413436 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Wed, 5 Jul 2023 14:38:50 +0300
Subject: [PATCH 21/69] Add examples of usage etc.

---
 .../keystores/encrypted_keystore.md           | 32 +++++++++++++++++--
 .../sdk-wallet/keystores/pem_keystore.md      |  4 +--
 .../sdk-wallet/user_wallet_provider.md        |  4 +++
 3 files changed, 35 insertions(+), 5 deletions(-)

diff --git a/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md b/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
index ef41f5f..fd522c4 100644
--- a/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
+++ b/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
@@ -23,9 +23,9 @@ class EncryptedKeystore:
     // Below, "passphrase" is the bip39 passphrase required to derive a secret key from a mnemonic (by default, it should be an empty string).
     get_secret_key(index: int, passphrase: string): ISecretKey
 
-    export_to_object(password: string): KeyfileObject
+    export_to_object(password: string, address_hrp: string): KeyfileObject
 
-    export_to_file(path: Path, password: string)
+    export_to_file(path: Path, password: string, address_hrp: string)
 ```
 
 ```
@@ -84,6 +84,32 @@ TBD: Can we perhaps adjust `EncryptedData` to be more compatible with `KeyfileOb
 
 ## Examples of usage
 
+Create a new JSON keystore using a new mnemonic:
+
+```
+provider = new UserWalletProvider()
+mnemonic = provider.generate_mnemonic()
+keystore = EncryptedKeystore.new_from_mnemonic(provider, mnemonic)
+keystore.export_to_file("path/to/file.json", "password", "erd")
+```
+
+Iterating over the first 3 accounts:
+
+```
+provider = new UserWalletProvider()
+keystore = EncryptedKeystore.import_from_file(provider, "path/to/file.json", "password")
+
+for i in [0, 1, 2]:
+    secret_key = keystore.get_secret_key(i, "")
+    public_key = provider.compute_public_key_from_secret_key(secret_key)
+    address = new Address(public_key, "erd")
+    print("Address", i, address.bech32())
+```
+
+Changing the password of an exisint keystore:
+
 ```
-...
+provider = new UserWalletProvider()
+keystore = EncryptedKeystore.import_from_file(provider, "path/to/file.json", "password")
+keystore.export_to_file("path/to/file.json", "new_password", "erd")
 ```
diff --git a/network-interaction-sdk/sdk-wallet/keystores/pem_keystore.md b/network-interaction-sdk/sdk-wallet/keystores/pem_keystore.md
index b0d9e15..4202b65 100644
--- a/network-interaction-sdk/sdk-wallet/keystores/pem_keystore.md
+++ b/network-interaction-sdk/sdk-wallet/keystores/pem_keystore.md
@@ -18,9 +18,9 @@ class PEMKeystore:
 
     get_secret_key(index: int): ISecretKey
 
-    export_to_text(): string
+    export_to_text(address_hrp: string): string
 
-    export_to_file(path: Path)
+    export_to_file(path: Path, address_hrp: string)
 ```
 
 ## Examples of usage
diff --git a/network-interaction-sdk/sdk-wallet/user_wallet_provider.md b/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
index b2149c6..37546f6 100644
--- a/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
+++ b/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
@@ -22,6 +22,10 @@ class UserWalletProvider:
     // - ErrInvalidPublicKey
     create_public_key_from_bytes(data: bytes): IPublicKey
 
+    // Can throw:
+    // - ErrInvalidSecretKey
+    compute_public_key_from_secret_key(secret_key: ISecretKey): IPublicKey
+
     // Should not throw.
     generate_mnemonic(): Mnemonic
 

From 1012030614927e27ce33fdfe3ce1ef15265132b3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Wed, 5 Jul 2023 14:58:46 +0300
Subject: [PATCH 22/69] Extra examples, renamings etc.

---
 .../keystores/encrypted_keystore.md           | 10 +++---
 .../sdk-wallet/keystores/pem_keystore.md      | 33 ++++++++++++++++---
 network-interaction-sdk/sdk-wallet/notes.md   |  2 +-
 .../sdk-wallet/user_wallet_provider.md        |  2 +-
 .../sdk-wallet/validator_wallet_provider.md   |  2 +-
 5 files changed, 36 insertions(+), 13 deletions(-)

diff --git a/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md b/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
index fd522c4..1f01575 100644
--- a/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
+++ b/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
@@ -90,14 +90,14 @@ Create a new JSON keystore using a new mnemonic:
 provider = new UserWalletProvider()
 mnemonic = provider.generate_mnemonic()
 keystore = EncryptedKeystore.new_from_mnemonic(provider, mnemonic)
-keystore.export_to_file("path/to/file.json", "password", "erd")
+keystore.export_to_file("file.json", "password", "erd")
 ```
 
 Iterating over the first 3 accounts:
 
 ```
 provider = new UserWalletProvider()
-keystore = EncryptedKeystore.import_from_file(provider, "path/to/file.json", "password")
+keystore = EncryptedKeystore.import_from_file(provider, "file.json", "password")
 
 for i in [0, 1, 2]:
     secret_key = keystore.get_secret_key(i, "")
@@ -106,10 +106,10 @@ for i in [0, 1, 2]:
     print("Address", i, address.bech32())
 ```
 
-Changing the password of an exisint keystore:
+Changing the password of an existing keystore:
 
 ```
 provider = new UserWalletProvider()
-keystore = EncryptedKeystore.import_from_file(provider, "path/to/file.json", "password")
-keystore.export_to_file("path/to/file.json", "new_password", "erd")
+keystore = EncryptedKeystore.import_from_file(provider, "file.json", "password")
+keystore.export_to_file("file.json", "new_password", "erd")
 ```
diff --git a/network-interaction-sdk/sdk-wallet/keystores/pem_keystore.md b/network-interaction-sdk/sdk-wallet/keystores/pem_keystore.md
index 4202b65..71a1c3b 100644
--- a/network-interaction-sdk/sdk-wallet/keystores/pem_keystore.md
+++ b/network-interaction-sdk/sdk-wallet/keystores/pem_keystore.md
@@ -5,19 +5,21 @@ class PEMKeystore:
     // The constructor is not captured by the specs; it's up to the implementing library to define it.
 
     // Named constructor
-    static new_from_secret_key(secret_key: ISecretKey): PEMKeystore
+    static new_from_secret_key(wallet_provider: IWalletProvider, secret_key: ISecretKey): PEMKeystore
 
     // Named constructor
-    static new_from_secret_keys(secret_keys: ISecretKey[]): PEMKeystore
+    static new_from_secret_keys(wallet_provider: IWalletProvider, secret_keys: ISecretKey[]): PEMKeystore
 
     // Importing "constructor"
-    static import_from_text(text: string): PEMKeystore
+    static import_from_text(wallet_provider: IWalletProvider, text: string): PEMKeystore
 
     // Importing "constructor"
-    static import_from_file(path: Path): PEMKeystore
+    static import_from_file(wallet_provider: IWalletProvider, path: Path): PEMKeystore
 
     get_secret_key(index: int): ISecretKey
 
+    get_number_of_secret_keys(): number
+
     export_to_text(address_hrp: string): string
 
     export_to_file(path: Path, address_hrp: string)
@@ -25,6 +27,27 @@ class PEMKeystore:
 
 ## Examples of usage
 
+Creating a PEM file to hold three newly created secret keys.
+
+```
+provider = new UserWalletProvider()
+sk1, _ = provider.generate_keypair()
+sk2, _ = provider.generate_keypair()
+sk3, _ = provider.generate_keypair()
+
+keystore = PEMKeystore.new_from_secret_keys(provider, [sk1, sk2, sk3])
+keystore.export_to_file(Path("file.pem"), "erd")
+```
+
+Iterating over the accounts in a PEM file.
+
 ```
-...
+provider = new UserWalletProvider()
+keystore = PEMKeystore.import_from_file(provider, Path("file.pem"))
+
+for i in range(keystore.get_number_of_secret_keys()):
+    sk = keystore.get_secret_key(i)
+    pk = provider.compute_public_key_from_secret_key(sk)
+    address = new Address(public_key, "erd")
+    print("Address", i, address.bech32())
 ```
diff --git a/network-interaction-sdk/sdk-wallet/notes.md b/network-interaction-sdk/sdk-wallet/notes.md
index 9ad0a31..ae5d91e 100644
--- a/network-interaction-sdk/sdk-wallet/notes.md
+++ b/network-interaction-sdk/sdk-wallet/notes.md
@@ -1,6 +1,6 @@
 ## Keystores
 
-Components in `sdk-wallet/keystore`, even they do share a common purpose - storing secret keys - are not meant to be used interchangeably. Generally speaking, they do not (are not required to) share a common interface. If needed, client code can design adapters over these components in order to unify their interfaces. This is outside of the specs.
+Components in `sdk-wallet/keystore`, even they do share a common purpose - storing secret keys - are not meant to be used interchangeably. Generally speaking, they do not (are not required to) share a common interface. If needed (for exotic use-cases), client code can design customized adapters over these components in order to unify their interfaces (this is not covered by specs).
 
 **Implementation detail:** an instance of `EncryptedKeystore` (which is a wrapper over the well-known JSON wallet) holds decrypted data within its state.
 
diff --git a/network-interaction-sdk/sdk-wallet/user_wallet_provider.md b/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
index 37546f6..ed164f4 100644
--- a/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
+++ b/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
@@ -3,7 +3,7 @@
 ```
 class UserWalletProvider:
     // Should not throw.
-    generate_pair(): (ISecretKey, IPublicKey)
+    generate_keypair(): (ISecretKey, IPublicKey)
 
     // Can throw:
     // - ErrInvalidSecretKey
diff --git a/network-interaction-sdk/sdk-wallet/validator_wallet_provider.md b/network-interaction-sdk/sdk-wallet/validator_wallet_provider.md
index 72c4b69..08b1531 100644
--- a/network-interaction-sdk/sdk-wallet/validator_wallet_provider.md
+++ b/network-interaction-sdk/sdk-wallet/validator_wallet_provider.md
@@ -3,7 +3,7 @@
 ```
 class ValidatorWalletProvider:
     // Should not throw.
-    generate_pair(): (ISecretKey, IPublicKey)
+    generate_keypair(): (ISecretKey, IPublicKey)
 
     // Can throw:
     // - ErrInvalidSecretKey

From e273fda355331591d5637196c0aad2783883cafa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Wed, 5 Jul 2023 15:03:14 +0300
Subject: [PATCH 23/69] Add usage example.

---
 network-interaction-sdk/sdk-wallet/mnemonic.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/network-interaction-sdk/sdk-wallet/mnemonic.md b/network-interaction-sdk/sdk-wallet/mnemonic.md
index fa58a8c..4df2ee4 100644
--- a/network-interaction-sdk/sdk-wallet/mnemonic.md
+++ b/network-interaction-sdk/sdk-wallet/mnemonic.md
@@ -22,3 +22,19 @@ class Mnemonic:
     toString(): string;
 }
 ```
+
+## Examples of usage
+
+Creating a new mnemonic and deriving the first secret key.
+
+```
+provider = new UserWalletProvider()
+mnemonic = provider.generate_mnemonic()
+print(mnemonic.toString())
+
+mnemonic = Mnemonic.newfromText("...")
+sk = provider.derive_secret_key_from_mnemonic(mnemonic, address_index=0 , passphrase="")
+pk = provider.compute_public_key_from_secret_key(sk)
+address = new Address(public_key, "erd")
+print(address.bech32())
+```

From e306cb003fe09e49448c187ff4919db219232473 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Wed, 5 Jul 2023 15:11:38 +0300
Subject: [PATCH 24/69] Fix after self review.

---
 network-interaction-sdk/sdk-core/address.md | 48 +++++++++++++++------
 1 file changed, 36 insertions(+), 12 deletions(-)

diff --git a/network-interaction-sdk/sdk-core/address.md b/network-interaction-sdk/sdk-core/address.md
index 6c16ca9..74685d6 100644
--- a/network-interaction-sdk/sdk-core/address.md
+++ b/network-interaction-sdk/sdk-core/address.md
@@ -3,32 +3,42 @@
 ```
 class Address:
     // Should also validate the length of the provided input.
+    // Can throw:
+    // - ErrInvalidPublicKey
     constructor(public_key: bytes, hrp: string);
 
     // Named constructor
-    static newfromBech32(value: string): Address;
+    // Can throw:
+    // - ErrInvalidBech32Address
+    static new_from_bech32(value: string): Address;
 
     // Named constructor
-    static newFromHex(value: string, hrp: string): Address;
+    // Can throw:
+    // - ErrInvalidHexString
+    static new_from_hex(value: string, hrp: string): Address;
 
     // Returns the address as a string (bech32).
-    bech32(): string;
+    // Name should be adjusted to match the language's convention.
+    to_bech32(): string;
 
     // Returns the address as a string (hex).
     // Name should be adjusted to match the language's convention.
-    hex(): string;
+    to_hex(): string;
 
     // Returns the underlying public key.
-    getPublicKey(): bytes;
+    get_public_key(): bytes;
+
+    // Returns the human-readable part of the address.
+    get_hrp(): string;
 
     // Returns true if the address is a smart contract address.
-    isSmartContract(): bool;
+    is_smart_contract(): bool;
 ```
 
 Example of usage:
 
 ```
-address = Address.from_bech32("erd1qyu5wthldzr8wx5c9ucg8kjagg0jfs53s8nr3zpz3hypefsdd8ssycr6th")
+address = Address.new_from_bech32("erd1qyu5wthldzr8wx5c9ucg8kjagg0jfs53s8nr3zpz3hypefsdd8ssycr6th")
 
 print("Address (bech32-encoded)", address.bech32())
 print("Public key (hex-encoded):", address.hex())
@@ -42,16 +52,16 @@ class AddressFactory:
 
     // Creates an address with all bytes set to zero.
     // This is the same as the "contract deployment address".
-    createZero(): Address;
+    create_zero(): Address;
 
     // Creates an address from a bech32 string.
-    createFromBech32(value: string): Address;
+    create_from_bech32(value: string): Address;
 
     // Creates an address from a public key.
-    createFromPublicKey(public_key: bytes): Address;
+    create_from_public_key(public_key: bytes): Address;
 
     // Creates an address from a hex string.
-    createFromHex(value: string): Address;
+    create_from_hex(value: string): Address;
 ```
 
 Example of usage:
@@ -69,7 +79,21 @@ Module-level functions:
 
 ```
 // Note that the first input parameter is received as an interface, but the return value is a concrete type [see Guideline **`in-ifaces-out-concrete-types`**].
-compute_contract_address(deployer: IAddress, deployment_nonce: INonce, address_hrp: string): Address;
+compute_contract_address(deployer: IAddress, deployment_nonce: INonce): Address;
 
 get_shard_of_address(address: IAddress, num_shards: number): number;
 ```
+
+Above, `IAddress` should satisfy:
+
+```
+get_public_key(): bytes;
+get_hrp(): string;
+```
+
+OR, perhaps, it should simply satisfy:
+
+```
+// Name should be adjusted to match the language's convention.
+to_bech32(): string;
+```

From 2d861bb4a485731fd90f11ea489abb1a5827da45 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Wed, 5 Jul 2023 15:23:59 +0300
Subject: [PATCH 25/69] Adjust readme.

---
 .../{guidelines.md => README.md}              | 21 +++++++++++++------
 .../sdk-wallet/{notes.md => README.md}        |  0
 2 files changed, 15 insertions(+), 6 deletions(-)
 rename network-interaction-sdk/{guidelines.md => README.md} (61%)
 rename network-interaction-sdk/sdk-wallet/{notes.md => README.md} (100%)

diff --git a/network-interaction-sdk/guidelines.md b/network-interaction-sdk/README.md
similarity index 61%
rename from network-interaction-sdk/guidelines.md
rename to network-interaction-sdk/README.md
index d07b2ed..42af870 100644
--- a/network-interaction-sdk/guidelines.md
+++ b/network-interaction-sdk/README.md
@@ -1,19 +1,28 @@
-##  **`in-ifaces-out-concrete-types`**
+# Specifications for mx-sdk-* libraries
+
+This repository contains specifications for the `mx-sdk-*` libraries. The specifications are written in a language-agnostic manner, and are meant to be implemented in multiple languages (e.g. Go, TypeScript, Python, Rust, etc.).
+
+## Structure
+
+- `sdk-core`: core components (address, transaction, etc.).
+- `sdk-wallet`: core wallet components (generation, signing).
+- `sdk-network-providers`: Network Provider (API, Gateway) components.
+
+## Guidelines
+
+###  **`in-ifaces-out-concrete-types`**
 
 Generally speaking, it's recommended to receive input parameters as abstractions (interfaces) in the public API of the SDKs. This leads to an improved decoupling, and allows for easier type substitution (e.g. easier mocking, testing).
 
 Generally speaking, it's recommended to return concrete types in the public API of the SDKs. The client code is responsible with decoupling from unnecessary data and behaviour of returned objects (e.g. by using interfaces, on their side). 
 
-## **`pay-attention-to-types`**
+### **`pay-attention-to-types`**
 
  - For JavaScript / TypeScript, `bytes` should be `Uint8Array`.
 
-## **`follow-language-conventions`**
+### **`follow-language-conventions`**
  
  - Make sure to follow the naming conventions of the language you're using, e.g. `snake_case` vs. `camelCase`.
  - In the specs, interfaces are prefixed with `I`, simply to make them stand out. However, in the implementing libraries, this convention does not have to be applied.
  - In `go`, the term `serialize` (whether it's part of a class name or a function name) can be replaced by `marshal`, since that is the convention.
 
-## **`out-of-specs-arguments-should-be-optional`**
-
-E.g. randomness.
diff --git a/network-interaction-sdk/sdk-wallet/notes.md b/network-interaction-sdk/sdk-wallet/README.md
similarity index 100%
rename from network-interaction-sdk/sdk-wallet/notes.md
rename to network-interaction-sdk/sdk-wallet/README.md

From 3cda74dc40ab047f8080da3c9969dffd00e4c628 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Thu, 6 Jul 2023 11:40:41 +0300
Subject: [PATCH 26/69] Fix after review (part 1).

---
 network-interaction-sdk/README.md                             | 3 ++-
 network-interaction-sdk/sdk-wallet/README.md                  | 2 +-
 .../sdk-wallet/crypto/keypair_based_encryptor_decryptor.md    | 2 +-
 .../sdk-wallet/keystores/encrypted_keystore.md                | 2 +-
 network-interaction-sdk/sdk-wallet/mnemonic.md                | 4 ++++
 network-interaction-sdk/sdk-wallet/public_key.md              | 2 +-
 network-interaction-sdk/sdk-wallet/secret_key.md              | 2 +-
 network-interaction-sdk/sdk-wallet/user_wallet_provider.md    | 4 ----
 8 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/network-interaction-sdk/README.md b/network-interaction-sdk/README.md
index 42af870..a8dac8f 100644
--- a/network-interaction-sdk/README.md
+++ b/network-interaction-sdk/README.md
@@ -14,7 +14,7 @@ This repository contains specifications for the `mx-sdk-*` libraries. The specif
 
 Generally speaking, it's recommended to receive input parameters as abstractions (interfaces) in the public API of the SDKs. This leads to an improved decoupling, and allows for easier type substitution (e.g. easier mocking, testing).
 
-Generally speaking, it's recommended to return concrete types in the public API of the SDKs. The client code is responsible with decoupling from unnecessary data and behaviour of returned objects (e.g. by using interfaces, on their side). 
+Generally speaking, it's recommended to return concrete types in the public API of the SDKs. The client code is responsible with decoupling from unnecessary data and behaviour of returned objects (e.g. by using interfaces, on their side). The only notable exception to this is when working with factories (abstract or method factories) that should have the function output an interface type. For example, have a look over `(User|Validator)WalletProvider.generate_keypair()` - this method returns abstract types (interfaces).
 
 ### **`pay-attention-to-types`**
 
@@ -25,4 +25,5 @@ Generally speaking, it's recommended to return concrete types in the public API
  - Make sure to follow the naming conventions of the language you're using, e.g. `snake_case` vs. `camelCase`.
  - In the specs, interfaces are prefixed with `I`, simply to make them stand out. However, in the implementing libraries, this convention does not have to be applied.
  - In `go`, the term `serialize` (whether it's part of a class name or a function name) can be replaced by `marshal`, since that is the convention.
+ - Errors should also follow the language convention - e.g. `ErrInvalidPublicKey` vs `InvalidPublicKeyError`. Should have the same error message in all implementing libraries, though.
 
diff --git a/network-interaction-sdk/sdk-wallet/README.md b/network-interaction-sdk/sdk-wallet/README.md
index ae5d91e..63c05a2 100644
--- a/network-interaction-sdk/sdk-wallet/README.md
+++ b/network-interaction-sdk/sdk-wallet/README.md
@@ -1,6 +1,6 @@
 ## Keystores
 
-Components in `sdk-wallet/keystore`, even they do share a common purpose - storing secret keys - are not meant to be used interchangeably. Generally speaking, they do not (are not required to) share a common interface. If needed (for exotic use-cases), client code can design customized adapters over these components in order to unify their interfaces (this is not covered by specs).
+Components in `sdk-wallet/keystore`, even if they do share a common purpose - storing secret keys - are not meant to be used interchangeably. Generally speaking, they do not (are not required to) share a common interface. If needed (for exotic use-cases), client code can design customized adapters over these components in order to unify their interfaces (this is not covered by specs).
 
 **Implementation detail:** an instance of `EncryptedKeystore` (which is a wrapper over the well-known JSON wallet) holds decrypted data within its state.
 
diff --git a/network-interaction-sdk/sdk-wallet/crypto/keypair_based_encryptor_decryptor.md b/network-interaction-sdk/sdk-wallet/crypto/keypair_based_encryptor_decryptor.md
index c7df225..7652cc9 100644
--- a/network-interaction-sdk/sdk-wallet/crypto/keypair_based_encryptor_decryptor.md
+++ b/network-interaction-sdk/sdk-wallet/crypto/keypair_based_encryptor_decryptor.md
@@ -4,5 +4,5 @@
 class KeyPairBasedEncryptorDecryptor:
     encrypt(data: bytes, recipient_public_key: IPublicKey, auth_secret_key: ISecretKey): PublicKeyEncryptedData;
 
-    decrypt(data: PublicKeyEncryptedData, decryptor_secret_key: SecretKey): data;
+    decrypt(data: PublicKeyEncryptedData, decryptor_secret_key: SecretKey): bytes;
 ```
diff --git a/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md b/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
index 1f01575..5d275e2 100644
--- a/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
+++ b/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
@@ -19,7 +19,7 @@ class EncryptedKeystore:
     static import_from_file(wallet_provider: IWalletProvider, path: Path, password: string): Keystore
 
     // When kind == 'secretKey', only index == 0 is supported.
-    // When kind == 'mnemonic', the wallet provider is used under the hood to derive the secret key.
+    // When kind == 'mnemonic', secret key derivation happens under the hood.
     // Below, "passphrase" is the bip39 passphrase required to derive a secret key from a mnemonic (by default, it should be an empty string).
     get_secret_key(index: int, passphrase: string): ISecretKey
 
diff --git a/network-interaction-sdk/sdk-wallet/mnemonic.md b/network-interaction-sdk/sdk-wallet/mnemonic.md
index 4df2ee4..84db91c 100644
--- a/network-interaction-sdk/sdk-wallet/mnemonic.md
+++ b/network-interaction-sdk/sdk-wallet/mnemonic.md
@@ -15,6 +15,10 @@ class Mnemonic:
     static newfromText(text: string): Mnemonic;
     static newfromWords(words: string[]): Mnemonic;
 
+    // Can throw:
+    // - ErrInvalidMnemonic
+    derive_secret_key(address_index: number = 0, passphrase: string = ""): ISecretKey
+
     // Gets the mnemonic words.
     getWords(): string[];
 
diff --git a/network-interaction-sdk/sdk-wallet/public_key.md b/network-interaction-sdk/sdk-wallet/public_key.md
index e56fb9f..54d9298 100644
--- a/network-interaction-sdk/sdk-wallet/public_key.md
+++ b/network-interaction-sdk/sdk-wallet/public_key.md
@@ -5,4 +5,4 @@ interface IPublicKey:
     get_bytes(): bytes
 ```
 
-In order to create and handle public keys, use the methods of the `(User|Validator)CryptoProvider`.
+In order to create and handle public keys, use the methods of the `(User|Validator)WalletProvider`.
diff --git a/network-interaction-sdk/sdk-wallet/secret_key.md b/network-interaction-sdk/sdk-wallet/secret_key.md
index 09633c1..4c2a7ad 100644
--- a/network-interaction-sdk/sdk-wallet/secret_key.md
+++ b/network-interaction-sdk/sdk-wallet/secret_key.md
@@ -5,4 +5,4 @@ interface ISecretKey:
     get_bytes(): bytes
 ```
 
-In order to create and handle secret keys, use the methods of the `(User|Validator)CryptoProvider`.
+In order to create and handle secret keys, use the methods of the `(User|Validator)WalletProvider`.
diff --git a/network-interaction-sdk/sdk-wallet/user_wallet_provider.md b/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
index ed164f4..209cb30 100644
--- a/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
+++ b/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
@@ -28,10 +28,6 @@ class UserWalletProvider:
 
     // Should not throw.
     generate_mnemonic(): Mnemonic
-
-    // Can throw:
-    // - ErrInvalidMnemonic
-    derive_secret_key_from_mnemonic(mnemonic: Mnemonic, address_index: number = 0, passphrase: string = ""): ISecretKey
 ```
 
 Generally speaking, `generate_mnemonic` and `derive_secret_key_from_mnemonic` are only available in the `UserWalletProvider` (that is, they are not available in `ValidatorWalletProvider`).

From 1ce8a143d50d42d40f8022effaac5e2d88168f93 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Thu, 6 Jul 2023 15:14:41 +0300
Subject: [PATCH 27/69] Fix after review (part 2).

---
 network-interaction-sdk/sdk-core/address.md          | 12 ++++++++----
 .../sdk-wallet/keystores/encrypted_keystore.md       |  7 +++++++
 .../sdk-wallet/user_wallet_provider.md               |  8 ++++++++
 3 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/network-interaction-sdk/sdk-core/address.md b/network-interaction-sdk/sdk-core/address.md
index 74685d6..67935c9 100644
--- a/network-interaction-sdk/sdk-core/address.md
+++ b/network-interaction-sdk/sdk-core/address.md
@@ -75,13 +75,17 @@ address = factory.create_from_hex("0139472eff6886771a982f3083da5d421f24c29181e63
 address = factory.create_from_public_key(bytes.fromhex("0139472eff6886771a982f3083da5d421f24c29181e63888228dc81ca60d69e1"))
 ```
 
-Module-level functions:
+## AddressComputer
 
 ```
-// Note that the first input parameter is received as an interface, but the return value is a concrete type [see Guideline **`in-ifaces-out-concrete-types`**].
-compute_contract_address(deployer: IAddress, deployment_nonce: INonce): Address;
+class AddressComputer:
+    // The constructor is not captured by the specs; it's up to the implementing library to define it.
 
-get_shard_of_address(address: IAddress, num_shards: number): number;
+    // Note that the first input parameter is received as an interface, but the return value is a concrete type (see guidelines).
+    compute_contract_address(deployer: IAddress, deployment_nonce: INonce): Address;
+
+    // The number of shards (necessary for computing the shard ID) would be received as a constructor parameter - constructor is not captured by specs.
+    get_shard_of_address(address: IAddress): number;
 ```
 
 Above, `IAddress` should satisfy:
diff --git a/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md b/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
index 5d275e2..65de186 100644
--- a/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
+++ b/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
@@ -23,6 +23,13 @@ class EncryptedKeystore:
     // Below, "passphrase" is the bip39 passphrase required to derive a secret key from a mnemonic (by default, it should be an empty string).
     get_secret_key(index: int, passphrase: string): ISecretKey
 
+    // Can throw:
+    // - ErrMnemonicNotAvailable
+    // 
+    // Returns the mnemonic used to create the keystore (if available, i.e. if kind == 'mnemonic').
+    // This function is useful for UX flows where the application has to display the mnemonic etc.
+    get_mnemonic(): Mnemonic
+
     export_to_object(password: string, address_hrp: string): KeyfileObject
 
     export_to_file(path: Path, password: string, address_hrp: string)
diff --git a/network-interaction-sdk/sdk-wallet/user_wallet_provider.md b/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
index 209cb30..2b25faa 100644
--- a/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
+++ b/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
@@ -5,6 +5,14 @@ class UserWalletProvider:
     // Should not throw.
     generate_keypair(): (ISecretKey, IPublicKey)
 
+    // Should not throw (generally speaking).
+    //
+    // Generates a keypair that satisfies the given constraints.
+    // 
+    // Generally speaking, the input paramters would be a predicate (function that returns a boolean) 
+    // or something similar (depending on the programming language).
+    generate_keypair_with_constraint(isConstraintSatisfied: Predicate[input = (ISecretKey, IPublicKey), output = boolean]): (ISecretKey, IPublicKey)
+
     // Can throw:
     // - ErrInvalidSecretKey
     sign(data: bytes, secret_key: ISecretKey): bytes

From 6fa37c0c2ee3ef48715fa3e3ebf90224872b568e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Fri, 7 Jul 2023 13:45:32 +0300
Subject: [PATCH 28/69] Fix after review, remove
 "generate_keypair_with_constraint".

---
 .../sdk-wallet/user_wallet_provider.md                    | 8 --------
 1 file changed, 8 deletions(-)

diff --git a/network-interaction-sdk/sdk-wallet/user_wallet_provider.md b/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
index 2b25faa..209cb30 100644
--- a/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
+++ b/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
@@ -5,14 +5,6 @@ class UserWalletProvider:
     // Should not throw.
     generate_keypair(): (ISecretKey, IPublicKey)
 
-    // Should not throw (generally speaking).
-    //
-    // Generates a keypair that satisfies the given constraints.
-    // 
-    // Generally speaking, the input paramters would be a predicate (function that returns a boolean) 
-    // or something similar (depending on the programming language).
-    generate_keypair_with_constraint(isConstraintSatisfied: Predicate[input = (ISecretKey, IPublicKey), output = boolean]): (ISecretKey, IPublicKey)
-
     // Can throw:
     // - ErrInvalidSecretKey
     sign(data: bytes, secret_key: ISecretKey): bytes

From 30a1934b7701c9b5fbeeada54895ee9f2463b91f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Mon, 10 Jul 2023 11:37:35 +0300
Subject: [PATCH 29/69] Fix after review, added string literal instead of
 constant.

---
 network-interaction-sdk/sdk-core/address.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/network-interaction-sdk/sdk-core/address.md b/network-interaction-sdk/sdk-core/address.md
index 67935c9..c951018 100644
--- a/network-interaction-sdk/sdk-core/address.md
+++ b/network-interaction-sdk/sdk-core/address.md
@@ -48,7 +48,7 @@ print("Public key (hex-encoded):", address.hex())
 
 ```
 class AddressFactory:
-    constructor(hrp: string = DEFAULT_HRP);
+    constructor(hrp: string = "erd");
 
     // Creates an address with all bytes set to zero.
     // This is the same as the "contract deployment address".

From 127415d91b170353feeb6d13845c9b93aaca8749 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Tue, 11 Jul 2023 13:08:10 +0300
Subject: [PATCH 30/69] Removed sdk-wallet - to be taken from "main" branch.

---
 .../sdk-wallet/mnemonic.md                    | 35 -------------------
 network-interaction-sdk/sdk-wallet/pem.md     | 23 ------------
 .../sdk-wallet/user_pem.md                    | 22 ------------
 .../sdk-wallet/user_public_key.md             | 24 -------------
 .../sdk-wallet/user_secret_key.md             | 28 ---------------
 .../sdk-wallet/user_signer.md                 | 14 --------
 .../sdk-wallet/user_verifier.md               | 13 -------
 .../sdk-wallet/user_wallet.md                 | 28 ---------------
 .../sdk-wallet/validator_pem.md               | 21 -----------
 .../sdk-wallet/validator_signer.md            | 14 --------
 .../sdk-wallet/validator_verifier.md          | 13 -------
 11 files changed, 235 deletions(-)
 delete mode 100644 network-interaction-sdk/sdk-wallet/mnemonic.md
 delete mode 100644 network-interaction-sdk/sdk-wallet/pem.md
 delete mode 100644 network-interaction-sdk/sdk-wallet/user_pem.md
 delete mode 100644 network-interaction-sdk/sdk-wallet/user_public_key.md
 delete mode 100644 network-interaction-sdk/sdk-wallet/user_secret_key.md
 delete mode 100644 network-interaction-sdk/sdk-wallet/user_signer.md
 delete mode 100644 network-interaction-sdk/sdk-wallet/user_verifier.md
 delete mode 100644 network-interaction-sdk/sdk-wallet/user_wallet.md
 delete mode 100644 network-interaction-sdk/sdk-wallet/validator_pem.md
 delete mode 100644 network-interaction-sdk/sdk-wallet/validator_signer.md
 delete mode 100644 network-interaction-sdk/sdk-wallet/validator_verifier.md

diff --git a/network-interaction-sdk/sdk-wallet/mnemonic.md b/network-interaction-sdk/sdk-wallet/mnemonic.md
deleted file mode 100644
index 1a125a9..0000000
--- a/network-interaction-sdk/sdk-wallet/mnemonic.md
+++ /dev/null
@@ -1,35 +0,0 @@
-## Mnemonic
-
-This component allows one to generate a new mnemonic, or load / parse / validate an existing one. 
-
-It also allows one to derive a secret key from the mnemonic.
-
-```
-class Mnemonic:
-    // At least one of the following constructors should be implemented.
-    // The constructor(s) should also trim whitespace and validate the mnemonic.
-    constructor(text: string);
-    constructor(words: string[]);
-
-    // Alternatively, named constructors can be used:
-    static fromText(text: string): Mnemonic;
-    static fromWords(words: string[]): Mnemonic;
-
-    // Generates a random mnemonic.
-    static generate(): Mnemonic;
-
-    // Derives a secret key from the mnemonic.
-    deriveKey(addressIndex: number = 0, password: string = ""): UserSecretKey;
-
-    // Gets the mnemonic words.
-    getWords(): string[];
-
-    // Returns the mnemonic as a string.
-    toString(): string;
-}
-```
-
-### Implementation notes
-
- - https://github.com/multiversx/mx-sdk-js-wallet/blob/main/src/mnemonic.ts
- - https://github.com/multiversx/mx-sdk-py-wallet/blob/main/multiversx_sdk_wallet/mnemonic.py
diff --git a/network-interaction-sdk/sdk-wallet/pem.md b/network-interaction-sdk/sdk-wallet/pem.md
deleted file mode 100644
index ebb0d3c..0000000
--- a/network-interaction-sdk/sdk-wallet/pem.md
+++ /dev/null
@@ -1,23 +0,0 @@
-## PEM
-
-`PemEntry` is a simple tuple of `label` (e.g. bech32 address, BLS key) and `data` (user secret key, validator secret key). It is used handle the hold of PEM files.
-
-Module-level functions are used to parse PEM files into `PemEntry` items.
-
-```
-class PemEntry:
-    label: string;
-    data: bytes;
-```
-
-Module-level functions:
-
-```
-parse_text(text: string): PemEntry[];
-parse_file(path: Path): PemEntry[];
-```
-
-### Implementation notes
-
- - https://github.com/multiversx/mx-sdk-js-wallet/blob/main/src/pem.ts
- - https://github.com/multiversx/mx-sdk-py-wallet/blob/main/multiversx_sdk_wallet/pem_entry.py
diff --git a/network-interaction-sdk/sdk-wallet/user_pem.md b/network-interaction-sdk/sdk-wallet/user_pem.md
deleted file mode 100644
index 679b668..0000000
--- a/network-interaction-sdk/sdk-wallet/user_pem.md
+++ /dev/null
@@ -1,22 +0,0 @@
-## UserPEM
-
-`UserPEM` is a thin wrapper over the functionality of `pem`.
-
-```
-class UserPEM:
-    constructor(label: string, key: UserSecretKey);
-
-    // Named constructors:
-    static from_file(path: Path, index: number = 0): UserPEM;
-    static from_file_all(path: Path): UserPEM[];
-    static from_text(text: string, index: number = 0): UserPEM;
-    static from_text_all(text: string): UserPEM[];
-
-    save(path: Path): void;
-    to_text(): string;
-```
-
-### Implementation notes
-
- - https://github.com/multiversx/mx-sdk-py-wallet/blob/main/multiversx_sdk_wallet/user_pem.py
- - https://github.com/multiversx/mx-sdk-js-wallet/blob/main/src/pem.ts
diff --git a/network-interaction-sdk/sdk-wallet/user_public_key.md b/network-interaction-sdk/sdk-wallet/user_public_key.md
deleted file mode 100644
index 0a9e9d0..0000000
--- a/network-interaction-sdk/sdk-wallet/user_public_key.md
+++ /dev/null
@@ -1,24 +0,0 @@
-## UserPublicKey
-
-```
-class UserPublicKey:
-    // The constructor(s) should also validate the length of the provided input.
-    constructor(data: bytes);
-
-    verify(data: bytes, signature: bytes): boolean;
-
-    hex(): string {
-        return this.buffer.toString("hex");
-    }
-
-    // Converts the public key to an actual address (bech32).
-    toAddress(): Address;
-
-    // Returns the secret key as a string (hex).
-    // Name should be adjusted to match the language's convention.
-    hex(): string;
-
-    // Implement any of the following to return the secret key as a byte array.
-    valueOf(): bytes;   // specific to JavaScript
-    getData(): bytes;
-```
diff --git a/network-interaction-sdk/sdk-wallet/user_secret_key.md b/network-interaction-sdk/sdk-wallet/user_secret_key.md
deleted file mode 100644
index e9b5129..0000000
--- a/network-interaction-sdk/sdk-wallet/user_secret_key.md
+++ /dev/null
@@ -1,28 +0,0 @@
-## UserSecretKey
-
-```
-class UserSecretKey:
-    // At least one of the following constructors should be implemented.
-    // The constructor(s) should also validate the length of the provided input.
-    constructor(data: bytes);
-    constructor(hex: string);
-
-    // Alternatively, named constructors can be used:
-    static fromBytes(data: bytes): UserSecretKey;
-    static fromString(value: string): UserSecretKey;
-
-    // Generates the public key corresponding to this secret key.
-    generatePublicKey(): UserPublicKey;
-
-    // Signs an array of bytes.
-    sign(data: bytes): bytes;
-
-    // Returns the secret key as a string (hex).
-    // Name should be adjusted to match the language's convention.
-    hex(): string;
-
-    // Implement any of the following to return the secret key as a byte array.
-    valueOf(): bytes;   // specific to JavaScript
-    getData(): bytes;
-}
-```
diff --git a/network-interaction-sdk/sdk-wallet/user_signer.md b/network-interaction-sdk/sdk-wallet/user_signer.md
deleted file mode 100644
index e1bba47..0000000
--- a/network-interaction-sdk/sdk-wallet/user_signer.md
+++ /dev/null
@@ -1,14 +0,0 @@
-## UserSigner
-
-```
-class UserSigner:
-    constructor(secret_key: UserSecretKey);
-
-    // Named constructors
-    static fromPemFile(path: Path, index: number = 0): UserSigner;
-    static fromWallet(path: Path, password: string): UserSigner;
-
-    sign(data: bytes): bytes;
-
-    getAddress(): Address;
-```
diff --git a/network-interaction-sdk/sdk-wallet/user_verifier.md b/network-interaction-sdk/sdk-wallet/user_verifier.md
deleted file mode 100644
index c8bdbc7..0000000
--- a/network-interaction-sdk/sdk-wallet/user_verifier.md
+++ /dev/null
@@ -1,13 +0,0 @@
-## UserVerifier
-
-```
-class UserVerifier:
-    constructor(public_key: UserPublicKey);
-
-    // Named constructor
-    fromAddress(address: IAddress): UserVerifier;
-
-    verify(data: bytes, signature: bytes): boolean;
-
-    getAddress(): Address;
-```
diff --git a/network-interaction-sdk/sdk-wallet/user_wallet.md b/network-interaction-sdk/sdk-wallet/user_wallet.md
deleted file mode 100644
index 7844ab9..0000000
--- a/network-interaction-sdk/sdk-wallet/user_wallet.md
+++ /dev/null
@@ -1,28 +0,0 @@
-## UserWallet
-
-```
-class UserWallet:
-    constructor(kind: str, encrypted_data: EncryptedData, public_key_when_kind_is_secret_key: Optional[UserPublicKey])
-    
-    // Named constructor
-    static from_secret_key(secret_key: UserSecretKey, password: str, randomness: Optional[IRandomness]): UserWallet
-    static from_mnemonic(mnemonic: str, password: str, randomness: Optional[IRandomness]): UserWallet
-
-    // Decryption (static) methods. 'keyfile_object' is the JSON object from the keyfile (wallet JSON).
-    static decrypt_secret_key(keyfile_object: Any, password: str): UserSecretKey;
-    static decrypt_mnemonic(keyfile_object: Any, password: str): Mnemonic;
-
-    // Wrapper over the two methods above. Calls mnemonic.derive_key() under the hood.
-    static load_secret_key(path: Path, password: str, address_index: Optional[int] = 0): UserSecretKey;
-
-    // Saves the wallet to a file.
-    save(path: Path, address_hrp: Optional[str]);
-
-    // Converts the object to a JSON string (ready to be saved to a wallet keyfile).
-    to_json(): str
-```
-
-### Implementation notes
-
- - https://github.com/multiversx/mx-sdk-py-wallet/blob/main/multiversx_sdk_wallet/user_wallet.py
- - https://github.com/multiversx/mx-sdk-js-wallet/blob/main/src/userWallet.ts
diff --git a/network-interaction-sdk/sdk-wallet/validator_pem.md b/network-interaction-sdk/sdk-wallet/validator_pem.md
deleted file mode 100644
index 94cac4a..0000000
--- a/network-interaction-sdk/sdk-wallet/validator_pem.md
+++ /dev/null
@@ -1,21 +0,0 @@
-## ValidatorPEM
-
-`ValidatorPEM` is a thin wrapper over the functionality of `pem`.
-
-```
-class ValidatorPEM:
-    constructor(label: string, key: ValidatorSecretKey);
-
-    // Named constructors:
-    static from_file(path: Path, index: number = 0): ValidatorPEM;
-    static from_file_all(path: Path): ValidatorPEM[];
-    static from_folder_all(path: Path): ValidatorPEM[];
-    static from_text(text: string, index: number = 0): ValidatorPEM;
-    static from_text_all(text: string): ValidatorPEM[];
-
-    save(path: Path): void;
-    to_text(): string;
-```
-
-### Implementation notes
-
diff --git a/network-interaction-sdk/sdk-wallet/validator_signer.md b/network-interaction-sdk/sdk-wallet/validator_signer.md
deleted file mode 100644
index 6981bbc..0000000
--- a/network-interaction-sdk/sdk-wallet/validator_signer.md
+++ /dev/null
@@ -1,14 +0,0 @@
-## ValidatorSigner
-
-```
-class ValidatorSigner:
-    constructor(secret_key: ValidatorSecretKey);
-
-    // Named constructors
-    static fromPemFile(path: Path, index: number = 0): ValidatorSigner;
-
-    sign(data: bytes): bytes;
-
-    getPublicKey(): ValidatorPublicKey;
-```
-
diff --git a/network-interaction-sdk/sdk-wallet/validator_verifier.md b/network-interaction-sdk/sdk-wallet/validator_verifier.md
deleted file mode 100644
index 15ef8ba..0000000
--- a/network-interaction-sdk/sdk-wallet/validator_verifier.md
+++ /dev/null
@@ -1,13 +0,0 @@
-## ValidatorVerifier
-
-```
-class ValidatorVerifier:
-    constructor(public_key: ValidatorPublicKey);
-
-    // Named constructors
-    static fromPublicKeyString(hex: string): ValidatorVerifier;
-
-    verify(data: bytes, signature: bytes): boolean;
-
-    getPublicKey(): ValidatorPublicKey;
-```

From a5eba98fa56c77b41a4d8c392409fd7b64435a7d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Tue, 11 Jul 2023 17:21:35 +0300
Subject: [PATCH 31/69] Fix after review (partial).

---
 network-interaction-sdk/sdk-core/address.md   |   2 +-
 .../sdk-core/token_transfer.md                |  10 +-
 .../sdk-core/transaction.md                   |  62 +++-----
 .../sdk-core/transaction_intent.md            |  10 ++
 .../token_management_transactions_factory.md  | 142 ++++--------------
 .../sdk-core/type_aliases.md                  |  10 --
 6 files changed, 70 insertions(+), 166 deletions(-)
 create mode 100644 network-interaction-sdk/sdk-core/transaction_intent.md
 delete mode 100644 network-interaction-sdk/sdk-core/type_aliases.md

diff --git a/network-interaction-sdk/sdk-core/address.md b/network-interaction-sdk/sdk-core/address.md
index c951018..2e07f34 100644
--- a/network-interaction-sdk/sdk-core/address.md
+++ b/network-interaction-sdk/sdk-core/address.md
@@ -82,7 +82,7 @@ class AddressComputer:
     // The constructor is not captured by the specs; it's up to the implementing library to define it.
 
     // Note that the first input parameter is received as an interface, but the return value is a concrete type (see guidelines).
-    compute_contract_address(deployer: IAddress, deployment_nonce: INonce): Address;
+    compute_contract_address(deployer: IAddress, deployment_nonce: number): Address;
 
     // The number of shards (necessary for computing the shard ID) would be received as a constructor parameter - constructor is not captured by specs.
     get_shard_of_address(address: IAddress): number;
diff --git a/network-interaction-sdk/sdk-core/token_transfer.md b/network-interaction-sdk/sdk-core/token_transfer.md
index 286d3b2..a6cf5ee 100644
--- a/network-interaction-sdk/sdk-core/token_transfer.md
+++ b/network-interaction-sdk/sdk-core/token_transfer.md
@@ -4,10 +4,10 @@
 class TokenTransfer:
     // Fields (properties):
     token_identifier: ITokenIdentifier;
-    token_nonce: INonce;
+    token_nonce: number;
     amount_in_atomic_units: number;
 
-    constructor(tokenIdentifier: ITokenIdentifier, tokenNonce: INonce, amountInAtomicUnits: number);
+    constructor(tokenIdentifier: ITokenIdentifier, tokenNonce: number, amountInAtomicUnits: number);
 
     isEgld(): boolean;
 
@@ -16,9 +16,9 @@ class TokenTransfer:
     // Named constructors:
     static ofEgld(amountInAtomicUnits: number): TokenTransfer;
     static ofFungible(tokenIdentifier: ITokenIdentifier, amountInAtomicUnits: number): TokenTransfer;
-    static ofNonFungible(tokenIdentifier: ITokenIdentifier, nonce: INonce): TokenTransfer;
-    static ofSemiFungible(tokenIdentifier: ITokenIdentifier, nonce: INonce, quantity: number): TokenTransfer;
-    static ofMetaESDT(tokenIdentifier: ITokenIdentifier, nonce: INonce, amountInAtomicUnits: number): TokenTransfer;
+    static ofNonFungible(tokenIdentifier: ITokenIdentifier, nonce: number): TokenTransfer;
+    static ofSemiFungible(tokenIdentifier: ITokenIdentifier, nonce: number, quantity: number): TokenTransfer;
+    static ofMetaESDT(tokenIdentifier: ITokenIdentifier, nonce: number, amountInAtomicUnits: number): TokenTransfer;
 
     // Amount in atomic units, as string.
     toString();
diff --git a/network-interaction-sdk/sdk-core/transaction.md b/network-interaction-sdk/sdk-core/transaction.md
index f61caf8..ed94214 100644
--- a/network-interaction-sdk/sdk-core/transaction.md
+++ b/network-interaction-sdk/sdk-core/transaction.md
@@ -1,46 +1,32 @@
 ## Transaction
 
 ```
-class Transaction:
-    constructor({
-        sender: IAddress;
-        receiver: IAddress;
-        gasLimit: IGasLimit;
-        chainID: IChainID;
-
-        nonce?: INonce;
-        value?: ITransactionValue;
-        senderUsername?: string;
-        receiverUsername?: string;
-        gasPrice?: IGasPrice;
-
-        data?: ITransactionPayload;
-        version?: ITransactionVersion;
-        options?: ITransactionOptions;
-        guardian?: IAddress;
-    });
-
-    // Getters and setters for all the fields.
-    // ...
-
-    // Optional: alias for setSignature().
-    applySignature(signature: bytes): void;
-    // Optional: alias for setGuardianSignature().
-    applyGuardianSignature(signature: bytes): void;
-
-    serializeForSigning(): bytes;
-
-    // Returns the transaction as a plain object.
-    toPlainObject(withSignatures: bool = true): any;
-
-    // Optional: alias for `toPlainObject()`.
-    toJSON(): any; // JavaScript
-    to_dictionary(): any; // Python
+dto Transaction:
+    sender: string;
+    receiver: string;
+    gasLimit: uint32;
+    chainID: string;
+
+    nonce?: uint64;
+    value?: string;
+    senderUsername?: string;
+    receiverUsername?: string;
+    gasPrice?: uint32;
+
+    data?: bytes;
+    version?: uint32;
+    options?: uint32;
+    guardian?: string;
+
+    signature: bytes;
+    guardianSignature: bytes;
 ```
 
-Module-level functions:
+## TransactionComputer
 
 ```
-computeFee(transaction: ITransaction, networkConfig: INetworkConfig): bigNumber;
-computeTransactionHash(transaction: ITransaction): bytes;
+class TransactionComputer:
+    compute_transaction_fee(transaction: Transaction, network_config: INetworkConfig): bigNumber;
+    compute_bytes_for_signing(transaction: Transaction): bytes;
+    compute_transaction_hash(transaction: Transaction): bytes;
 ```
diff --git a/network-interaction-sdk/sdk-core/transaction_intent.md b/network-interaction-sdk/sdk-core/transaction_intent.md
new file mode 100644
index 0000000..a5445c3
--- /dev/null
+++ b/network-interaction-sdk/sdk-core/transaction_intent.md
@@ -0,0 +1,10 @@
+## TransactionIntent
+
+```
+dto TransactionIntent:
+    sender: string;
+    receiver: string;
+    value?: string;
+    data?: bytes;
+    gasLimit: uint32;
+```
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
index 71c1ff0..50ac6d0 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
@@ -7,7 +7,7 @@ class TokenManagementTransactionsFactory:
     // IConfig should be a private (internal) interface that defines the necessary configuration (e.g. minGasLimit, gasLimitPerByte, issueCost).
     constructor(config: IConfig);
 
-    create_transaction_for_issuing_fungible({
+    create_transaction_intent_for_issuing_fungible({
         sender: IAddress;
         tokenName: string;
         tokenTicker: string;
@@ -18,15 +18,9 @@ class TokenManagementTransactionsFactory:
         canChangeOwner: boolean;
         canUpgrade: boolean;
         canAddSpecialRoles: boolean;
+    }): TransactionIntent;
 
-        // Optionals:
-        nonce?: INonce;
-        gasPrice?: IGasPrice;
-        gasLimit?: IGasLimit;
-        guardian? : IAddress;
-    }): Transaction;
-
-    create_transaction_for_issuing_semi_fungible({
+    create_transaction_intent_for_issuing_semi_fungible({
         sender: IAddress;
         tokenName: string;
         tokenTicker: string;
@@ -37,15 +31,9 @@ class TokenManagementTransactionsFactory:
         canChangeOwner: boolean;
         canUpgrade: boolean;
         canAddSpecialRoles: boolean;
+    }): TransactionIntent;
 
-        // Optionals:
-        nonce?: INonce;
-        gasPrice?: IGasPrice;
-        gasLimit?: IGasLimit;
-        guardian? : IAddress;
-    })
-
-    create_transaction_for_issuing_non_fungible({
+    create_transaction_intent_for_issuing_non_fungible({
         sender: IAddress;
         tokenName: string;
         tokenTicker: string;
@@ -56,15 +44,9 @@ class TokenManagementTransactionsFactory:
         canChangeOwner: boolean;
         canUpgrade: boolean;
         canAddSpecialRoles: boolean;
+    }): TransactionIntent;
 
-        // Optionals:
-        nonce?: INonce;
-        gasPrice?: IGasPrice;
-        gasLimit?: IGasLimit;
-        guardian? : IAddress;
-    }): Transaction;
-
-    create_transaction_for_registering_meta_esdt({
+    create_transaction_intent_for_registering_meta_esdt({
         sender: IAddress;
         tokenName: string;
         tokenTicker: string;
@@ -76,65 +58,35 @@ class TokenManagementTransactionsFactory:
         canChangeOwner: boolean;
         canUpgrade: boolean;
         canAddSpecialRoles: boolean;
+    }): TransactionIntent;
 
-        // Optionals:
-        nonce?: INonce;
-        gasPrice?: IGasPrice;
-        gasLimit?: IGasLimit;
-        guardian? : IAddress;
-    }): Transaction;
-
-    create_transaction_for_registering_and_setting_roles({
+    create_transaction_intent_for_registering_and_setting_roles({
         sender: IAddress;
         tokenName: string;
         tokenTicker: string;
         tokenType: RegisterAndSetAllRolesTokenType;
         numDecimals: number;
+    }): TransactionIntent;
 
-        // Optionals:
-        nonce?: INonce;
-        gasPrice?: IGasPrice;
-        gasLimit?: IGasLimit;
-        guardian? : IAddress;
-    }): Transaction;
-
-    create_transaction_for_setting_burn_role_globally({
+    create_transaction_intent_for_setting_burn_role_globally({
         sender: IAddress;
         tokenIdentifier: string;
+    }): TransactionIntent;
 
-        // Optionals:
-        nonce?: INonce;
-        gasPrice?: IGasPrice;
-        gasLimit?: IGasLimit;
-        guardian? : IAddress;
-    }): Transaction;
-
-    create_transaction_for_unsetting_burn_role_globally({
+    create_transaction_intent_for_unsetting_burn_role_globally({
         sender: IAddress;
         tokenIdentifier: string;
+    }): TransactionIntent;
 
-        // Optionals:
-        nonce?: INonce;
-        gasPrice?: IGasPrice;
-        gasLimit?: IGasLimit;
-        guardian? : IAddress;
-    }): Transaction;
-
-    create_transaction_for_setting_special_role_on_fungible_token({
+    create_transaction_intent_for_setting_special_role_on_fungible_token({
         sender: IAddress;
         user: IAddress;
         tokenIdentifier: string;
         addRoleLocalMint: boolean;
         addRoleLocalBurn: boolean;
+    }): TransactionIntent;
 
-        // Optionals:
-        nonce?: INonce;
-        gasPrice?: IGasPrice;
-        gasLimit?: IGasLimit;
-        guardian? : IAddress;
-    }): Transaction;
-
-    create_transaction_for_setting_special_role_on_semi_fungible_token({
+    create_transaction_intent_for_setting_special_role_on_semi_fungible_token({
         sender: IAddress;
         user: IAddress;
         tokenIdentifier: string;
@@ -142,65 +94,31 @@ class TokenManagementTransactionsFactory:
         addRoleNFTBurn: boolean;
         addRoleNFTAddQuantity: boolean;
         addRoleESDTTransferRole: boolean;
+    }): TransactionIntent;
 
-        // Optionals:
-        nonce?: INonce;
-        gasPrice?: IGasPrice;
-        gasLimit?: IGasLimit;
-        guardian? : IAddress;
-    })
-
-    create_transaction_for_setting_special_role_on_non_fungible_token
+    create_transaction_intent_for_setting_special_role_on_non_fungible_token
 
-    create_transaction_for_creating_nft
+    create_transaction_intent_for_creating_nft
 
-    create_transaction_for_pausing
+    create_transaction_intent_for_pausing
 
-    create_transaction_for_unpausing
+    create_transaction_intent_for_unpausing
 
-    create_transaction_for_freezing
+    create_transaction_intent_for_freezing
 
-    create_transaction_for_unfreezing
+    create_transaction_intent_for_unfreezing
 
-    create_transaction_for_wiping
+    create_transaction_intent_for_wiping
 
-    create_transaction_for_local_minting
+    create_transaction_intent_for_local_minting
 
-    create_transaction_for_local_burning
+    create_transaction_intent_for_local_burning
 
-    create_transaction_for_updating_attributes
+    create_transaction_intent_for_updating_attributes
 
-    create_transaction_for_adding_quantity
+    create_transaction_intent_for_adding_quantity
 
-    create_transaction_for_burning_quantity
+    create_transaction_intent_for_burning_quantity
 
     ...
 ```
-
-If the language supports it, the input arguments objects may be designed using interfaces and inheritance. For example, in TypeScript:
-
-```
-interface IRegisterMetaESDT extends IIssueSemiFungibleArgs {
-    numDecimals: number;
-}
-
-interface IIssueSemiFungibleArgs extends IBaseArgs {
-    issuer: IAddress;
-    tokenName: string;
-    tokenTicker: string;
-    canFreeze: boolean;
-    canWipe: boolean;
-    canPause: boolean;
-    canTransferNFTCreateRole: boolean;
-    canChangeOwner: boolean;
-    canUpgrade: boolean;
-    canAddSpecialRoles: boolean;
-}
-
-interface IBaseArgs {
-    nonce?: INonce;
-    gasPrice?: IGasPrice;
-    gasLimit?: IGasLimit;
-    guardian? : IAddress;
-}
-```
diff --git a/network-interaction-sdk/sdk-core/type_aliases.md b/network-interaction-sdk/sdk-core/type_aliases.md
deleted file mode 100644
index 4ef6af1..0000000
--- a/network-interaction-sdk/sdk-core/type_aliases.md
+++ /dev/null
@@ -1,10 +0,0 @@
-```
-INonce = uint64
-IGasPrice = uint32
-IGasLimit = uint32
-IChainID = str
-ITransactionVersion = int
-ITransactionOptions = int
-ISignature = bytes
-ITokenIdentifier = str
-```

From b271131889dc3941095c1104ead64f3153679c3d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Tue, 11 Jul 2023 17:38:26 +0300
Subject: [PATCH 32/69] Sketch message.

---
 network-interaction-sdk/sdk-core/message.md | 26 +++++++++++++++++++++
 1 file changed, 26 insertions(+)
 create mode 100644 network-interaction-sdk/sdk-core/message.md

diff --git a/network-interaction-sdk/sdk-core/message.md b/network-interaction-sdk/sdk-core/message.md
new file mode 100644
index 0000000..1464f17
--- /dev/null
+++ b/network-interaction-sdk/sdk-core/message.md
@@ -0,0 +1,26 @@
+## Message
+
+```
+dto Message:
+    data: bytes;
+    signature: bytes;
+```
+
+## MessageComputer
+
+```
+class MessageComputer:
+    compute_bytes_for_signing(message: Message): bytes;
+```
+
+Reference implementation of `compute_bytes_for_signing`:
+
+```
+compute_bytes_for_signing(message: Message):
+    PREFIX = bytes.fromhex("17456c726f6e64205369676e6564204d6573736167653a0a")
+    size = length of message.data, encoded as a string
+    content = concat(PREFIX, size, message.data)
+    content_hash = keccak(digest_bits=256)
+    
+    return content_hash
+```

From b14c7921ec24f67f910fd8e15a701c547368e4ba Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Fri, 14 Jul 2023 12:27:15 +0300
Subject: [PATCH 33/69] TokenManagementTransactionsFactory - more operations.

---
 .../token_management_transactions_factory.md  | 83 ++++++++++++++++---
 1 file changed, 71 insertions(+), 12 deletions(-)

diff --git a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
index 50ac6d0..472ec48 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
@@ -96,29 +96,88 @@ class TokenManagementTransactionsFactory:
         addRoleESDTTransferRole: boolean;
     }): TransactionIntent;
 
-    create_transaction_intent_for_setting_special_role_on_non_fungible_token
+    create_transaction_intent_for_setting_special_role_on_non_fungible_token({
+        sender: IAddress;
+        user: IAddress;
+        tokenIdentifier: str;
+        addRoleNftCreate: bool;
+        addRoleNftBurn: bool;
+        addRoleNftUpdate_attributes: bool;
+        addRoleNftAddUri: bool;
+        addRoleESDTTransferRole: bool;
+    }): TransactionIntent;
 
-    create_transaction_intent_for_creating_nft
+    create_transaction_intent_for_creating_nft({
+        sender: IAddress;
+        tokenIdentifier: str;
+        initialQuantity: int;
+        name: str;
+        royalties: int;
+        hash: str;
+        attributes: bytes;
+        uris: List[str];
+    }): TransactionIntent;
 
-    create_transaction_intent_for_pausing
+    create_transaction_intent_for_pausing({
+        sender: IAddress;
+        tokenIdentifier: str;
+    }): TransactionIntent;
 
-    create_transaction_intent_for_unpausing
+    create_transaction_intent_for_unpausing({
+        sender: IAddress;
+        tokenIdentifier: str;
+    }): TransactionIntent;
 
-    create_transaction_intent_for_freezing
+    create_transaction_intent_for_freezing({
+        sender: IAddress;
+        user: IAddress;
+        tokenIdentifier: str;
+    }): TransactionIntent;
 
-    create_transaction_intent_for_unfreezing
+    create_transaction_intent_for_unfreezing({
+        sender: IAddress;
+        user: IAddress;
+        tokenIdentifier: str;
+    }): TransactionIntent;
 
-    create_transaction_intent_for_wiping
+    create_transaction_intent_for_wiping({
+        sender: IAddress;
+        user: IAddress;
+        tokenIdentifier: str;
+    }): TransactionIntent;
 
-    create_transaction_intent_for_local_minting
+    create_transaction_intent_for_local_minting({
+        sender: IAddress;
+        tokenIdentifier: str;
+        supplyToMint: int;
+    }): TransactionIntent;
 
-    create_transaction_intent_for_local_burning
+    create_transaction_intent_for_local_burning({
+        sender: IAddress;
+        tokenIdentifier: str;
+        supplyToBurn: int;
+    }): TransactionIntent;
 
-    create_transaction_intent_for_updating_attributes
+    create_transaction_intent_for_updating_attributes({
+        sender: IAddress;
+        tokenIdentifier: str;
+        tokenNonce: int;
+        attributes: bytes;
+    }): TransactionIntent;
 
-    create_transaction_intent_for_adding_quantity
+    create_transaction_intent_for_adding_quantity({
+        sender: IAddress;
+        tokenIdentifier: str;
+        tokenNonce: int;
+        quantityToAdd: int;
+    }): TransactionIntent;
 
-    create_transaction_intent_for_burning_quantity
+    create_transaction_intent_for_burning_quantity({
+        sender: IAddress;
+        tokenIdentifier: str;
+        tokenNonce: int;
+        quantityToBurn: int;
+    }): TransactionIntent;
 
     ...
 ```

From 3f6169abed64e0f1e6166b72083a7185d9b24948 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Fri, 14 Jul 2023 13:41:48 +0300
Subject: [PATCH 34/69] Fix after review (add params on delegation txs
 factory).

---
 .../sdk-core/transaction.md                   |  2 +-
 .../delegation_transactions_factory.md        | 91 +++++++++++++++----
 .../token_management_transactions_factory.md  |  5 +-
 3 files changed, 79 insertions(+), 19 deletions(-)

diff --git a/network-interaction-sdk/sdk-core/transaction.md b/network-interaction-sdk/sdk-core/transaction.md
index ed94214..ae5d534 100644
--- a/network-interaction-sdk/sdk-core/transaction.md
+++ b/network-interaction-sdk/sdk-core/transaction.md
@@ -8,7 +8,7 @@ dto Transaction:
     chainID: string;
 
     nonce?: uint64;
-    value?: string;
+    value?: (string|bigNumber);
     senderUsername?: string;
     receiverUsername?: string;
     gasPrice?: uint32;
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
index 27f8b99..f3a1f4b 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
@@ -2,34 +2,93 @@
 
 ```
 class DelegationTransactionsFactory:
-    // IConfig should be a private (internal) interface that defines the necessary configuration (e.g. minGasLimit, gasLimitPerByte, issueCost).
-    constructor(config: IConfig);
+    // The constructor is not captured by the specs; it's up to the implementing library to define it.
+    // Generally speaking, the constructor should be parametrized with a configuration object which defines entries such as:
+    // "minGasLimit", "gasLimitPerByte", gas limit for specific operations etc. (e.g. "gasLimitForStaking").
 
-    create_transaction_for_new_delegation_contract
+    create_transaction_intent_for_new_delegation_contract({
+        sender: IAddress;
+        totalDelegationCap: (string|bigNumber);
+        service_fee: number;
+        value: (string|bigNumber);
+    }): TransactionIntent;
 
-    create_transaction_for_adding_nodes
+    create_transaction_intent_for_adding_nodes({
+        sender: IAddress;
+        delegationContract: IAddress;
+        publicKeys: List[IPublicKey];
+        signedMessages: List[bytes];
+    }): TransactionIntent;
 
-    create_transaction_for_removing_nodes
+    create_transaction_intent_for_removing_nodes({
+        sender: IAddress,
+        delegationContract: IAddress;
+        publicKeys: List[IPublicKey];
+    }): TransactionIntent;
 
-    create_transaction_for_staking_nodes
+    create_transaction_intent_for_staking_nodes({
+        sender: IAddress,
+        delegationContract: IAddress;
+        publicKeys: List[IPublicKey];
+    }): TransactionIntent;
 
-    create_transaction_for_unbonding_nodes
+    create_transaction_intent_for_unbonding_nodes({
+        sender: IAddress,
+        delegationContract: IAddress;
+        publicKeys: List[IPublicKey];
+    }): TransactionIntent;
 
-    create_transaction_for_unstaking_nodes
+    create_transaction_intent_for_unstaking_nodes({
+        sender: IAddress,
+        delegationContract: IAddress;
+        publicKeys: List[IPublicKey];
+    }): TransactionIntent;
 
-    create_transaction_for_unjailing_nodes
+    create_transaction_intent_for_unjailing_nodes({
+        sender: IAddress,
+        delegationContract: IAddress;
+        publicKeys: List[IPublicKey];
+    }): TransactionIntent;
 
-    create_transaction_for_changing_service_fee
+    create_transaction_intent_for_changing_service_fee({
+        sender: IAddress;
+        delegationContract: IAddress;
+        serviceFee: int;
+    }): TransactionIntent;
 
-    create_transaction_for_modifying_delegation_cap
+    create_transaction_intent_for_modifying_delegation_cap({
+        sender: IAddress;
+        delegationContract: IAddress;
+        delegationCap: int;
+    }): TransactionIntent;
 
-    create_transaction_for_setting_automatic_activation
+    create_transaction_intent_for_setting_automatic_activation({
+        sender: IAddress;
+        delegationContract: IAddress;
+    }): TransactionIntent;
 
-    create_transaction_for_unsetting_automatic_activation
+    create_transaction_intent_for_unsetting_automatic_activation({
+        sender: IAddress;
+        delegationContract: IAddress;
+    }): TransactionIntent;
 
-    create_transaction_for_setting_redelegate_cap
+    create_transaction_intent_for_setting_cap_check_on_redelegate_rewards({
+        sender: IAddress;
+        delegationContract: IAddress;
+    }): TransactionIntent;
 
-    create_transaction_for_unsetting_redelegate_cap
+    create_transaction_intent_for_unsetting_cap_check_on_redelegate_rewards({
+        sender: IAddress;
+        delegationContract: IAddress;
+    }): TransactionIntent;
 
-    create_transaction_for_setting_metadata
+    create_transaction_intent_for_setting_metadata({
+        sender: IAddress;
+        delegationContract: IAddress;
+        name: str;
+        website: str;
+        identifier: str;
+    }): TransactionIntent;
+
+    ...
 ```
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
index 472ec48..640582e 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
@@ -4,8 +4,9 @@ A class that provides methods for creating transactions for token management ope
 
 ```
 class TokenManagementTransactionsFactory:
-    // IConfig should be a private (internal) interface that defines the necessary configuration (e.g. minGasLimit, gasLimitPerByte, issueCost).
-    constructor(config: IConfig);
+    // The constructor is not captured by the specs; it's up to the implementing library to define it.
+    // Generally speaking, the constructor should be parametrized with a configuration object which defines entries such as:
+    // "minGasLimit", "gasLimitPerByte", "issueCost", gas limit for specific operations etc. (e.g. "gasLimitForSettingSpecialRole").
 
     create_transaction_intent_for_issuing_fungible({
         sender: IAddress;

From 7fd089de448b4c32c608cd83f43515f964a1c5d3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Fri, 14 Jul 2023 15:37:10 +0300
Subject: [PATCH 35/69] Define SC txs factory.

---
 network-interaction-sdk/guidelines.md         |  9 +++++
 network-interaction-sdk/sdk-core/abi.md       | 27 +++++++++++++
 .../smart_contract_transactions_factory.md    | 40 ++++++++++++++++---
 .../token_transfers_factory.md                |  1 +
 .../transactions_factory_config.md            |  0
 ..._management_transactions_outcome_parser.md |  1 +
 6 files changed, 73 insertions(+), 5 deletions(-)
 create mode 100644 network-interaction-sdk/sdk-core/abi.md
 delete mode 100644 network-interaction-sdk/sdk-core/transactions-factories/transactions_factory_config.md

diff --git a/network-interaction-sdk/guidelines.md b/network-interaction-sdk/guidelines.md
index b680c61..c3c0164 100644
--- a/network-interaction-sdk/guidelines.md
+++ b/network-interaction-sdk/guidelines.md
@@ -12,3 +12,12 @@ Generally speaking, it's recommended to return concrete types in the public API
  
  - Make sure to follow the naming conventions of the language you're using, e.g. `snake_case` vs. `camelCase`.
  - In the specs, interfaces are prefixed with `I`, simply to make them stand out. However, in the implementing libraries, this convention does not have to be applied. 
+
+## **`any-object`**
+
+In the specs, `object` is used as a placeholder for any type of object. In the implementing libraries, this would be replaced with the most appropriate type. For example:
+
+- in Go: `map[string]interface{}` or directly `interface{}` (depending on the context)
+- in Python: `dict` or `Any`
+- in JavaScript / TypeScript: `object` or `any`
+
diff --git a/network-interaction-sdk/sdk-core/abi.md b/network-interaction-sdk/sdk-core/abi.md
new file mode 100644
index 0000000..4470aab
--- /dev/null
+++ b/network-interaction-sdk/sdk-core/abi.md
@@ -0,0 +1,27 @@
+## ABI
+
+TBD: Definitions will be continued in a future PR.
+
+### AbiRegistry
+
+`AbiRegistry` is an abstraction over the content of a `*.abi.json` file.
+
+```
+class AbiRegistry:
+    // Will be defined in a future PR.
+```
+
+### Codec
+
+```
+class Codec {
+    // The constructor is not captured by the specs; it's up to the implementing library to define it.
+    // Generally speaking, the constructor should be parametrized with an AbiRegistry, when this is available for a given contract.
+    // It follows that a Codec instance would be bound to a specific contract.
+
+    encode_top_level(value: object): bytes;
+    encode_nested(value: object): bytes;
+    decode_top_level(data: bytes): object;
+    decode_nested(data: bytes): object;
+}
+```
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
index e369692..d00a992 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
@@ -2,13 +2,43 @@
 
 ```
 class SmartContractTransactionsFactory:
-    // IConfig should be a private (internal) interface that defines the necessary configuration (e.g. minGasLimit, gasLimitPerByte, issueCost).
-    constructor(config: IConfig);
+    // The constructor is not captured by the specs; it's up to the implementing library to define it.
+    // Generally speaking, the constructor should be parametrized with a configuration object which defines entries such as:
+    // "minGasLimit", "gasLimitPerByte" etc.
+    // The constructor should also be parametrized with a Codec instance, necessary to encode contract call arguments.
 
-    create_transaction_for_deploy
+    create_transaction_intent_for_deploy({
+        sender: IAddress;
+        bytecode: bytes OR bytecodePath: Path;
+        arguments: List[object] = [];
+        isUpgradeable: bool = True;
+        isReadable: bool = True;
+        isPayable: bool = False;
+        isPayableBySC: bool = True;
+        gasLimit: uint32;
+    }): TransactionIntent;
 
-    create_transaction_for_execute
+    create_transaction_intent_for_execute({
+        sender: IAddress;
+        contract: IAddress;
+        // If "function" is a reserved word in the implementing language, it should be replaced with a different name (e.g. "func" or "functionName").
+        function: string;
+        arguments: List[object] = [];
+        gasLimit: uint32;
+    }): TransactionIntent;
 
-    create_transaction_for_upgrade
+    create_transaction_intent_for_upgrade({
+        sender: IAddress;
+        contract: IAddress;
+        bytecode: bytes OR bytecodePath: Path;
+        arguments: List[object] = [];
+        isUpgradeable: bool = True;
+        isReadable: bool = True;
+        isPayable: bool = False;
+        isPayableBySC: bool = True;
+        gasLimit: uint32;
+    }): TransactionIntent;
+
+    ...
 
 ```
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/token_transfers_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/token_transfers_factory.md
index e69de29..8c7629d 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/token_transfers_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/token_transfers_factory.md
@@ -0,0 +1 @@
+// TBD: will be defined in a future PR.
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/transactions_factory_config.md b/network-interaction-sdk/sdk-core/transactions-factories/transactions_factory_config.md
deleted file mode 100644
index e69de29..0000000
diff --git a/network-interaction-sdk/sdk-core/transactions-outcome-parsers/token_management_transactions_outcome_parser.md b/network-interaction-sdk/sdk-core/transactions-outcome-parsers/token_management_transactions_outcome_parser.md
index e69de29..8c7629d 100644
--- a/network-interaction-sdk/sdk-core/transactions-outcome-parsers/token_management_transactions_outcome_parser.md
+++ b/network-interaction-sdk/sdk-core/transactions-outcome-parsers/token_management_transactions_outcome_parser.md
@@ -0,0 +1 @@
+// TBD: will be defined in a future PR.

From 64226b3a5de18ead53ef2f22fc18ce067345ece9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Fri, 14 Jul 2023 15:42:04 +0300
Subject: [PATCH 36/69] Adjust readme.

---
 network-interaction-sdk/README.md     |  8 ++++++++
 network-interaction-sdk/guidelines.md | 23 -----------------------
 2 files changed, 8 insertions(+), 23 deletions(-)
 delete mode 100644 network-interaction-sdk/guidelines.md

diff --git a/network-interaction-sdk/README.md b/network-interaction-sdk/README.md
index a8dac8f..b9cbcbe 100644
--- a/network-interaction-sdk/README.md
+++ b/network-interaction-sdk/README.md
@@ -27,3 +27,11 @@ Generally speaking, it's recommended to return concrete types in the public API
  - In `go`, the term `serialize` (whether it's part of a class name or a function name) can be replaced by `marshal`, since that is the convention.
  - Errors should also follow the language convention - e.g. `ErrInvalidPublicKey` vs `InvalidPublicKeyError`. Should have the same error message in all implementing libraries, though.
 
+## **`any-object`**
+
+In the specs, `object` is used as a placeholder for any type of object. In the implementing libraries, this would be replaced with the most appropriate type. For example:
+
+- in Go: `map[string]interface{}` or directly `interface{}` (depending on the context)
+- in Python: `dict` or `Any`
+- in JavaScript / TypeScript: `object` or `any`
+
diff --git a/network-interaction-sdk/guidelines.md b/network-interaction-sdk/guidelines.md
deleted file mode 100644
index c3c0164..0000000
--- a/network-interaction-sdk/guidelines.md
+++ /dev/null
@@ -1,23 +0,0 @@
-##  **`in-ifaces-out-concrete-types`**
-
-Generally speaking, it's recommended to receive input parameters as abstractions (interfaces) in the public API of the SDKs. This leads to an improved decoupling, and allows for easier type substitution (e.g. easier mocking, testing).
-
-Generally speaking, it's recommended to return concrete types in the public API of the SDKs. The client code is responsible with decoupling from unnecessary data and behaviour of returned objects (e.g. by using interfaces, on their side). 
-
-## **`pay-attention-to-types`**
-
- - For JavaScript / TypeScript, `bytes` should be `Uint8Array`.
-
-## **`follow-language-conventions`**
- 
- - Make sure to follow the naming conventions of the language you're using, e.g. `snake_case` vs. `camelCase`.
- - In the specs, interfaces are prefixed with `I`, simply to make them stand out. However, in the implementing libraries, this convention does not have to be applied. 
-
-## **`any-object`**
-
-In the specs, `object` is used as a placeholder for any type of object. In the implementing libraries, this would be replaced with the most appropriate type. For example:
-
-- in Go: `map[string]interface{}` or directly `interface{}` (depending on the context)
-- in Python: `dict` or `Any`
-- in JavaScript / TypeScript: `object` or `any`
-

From 6334c427feddc56f645acd83873631aa94e39e3e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Fri, 14 Jul 2023 15:43:41 +0300
Subject: [PATCH 37/69] Removed empty files.

---
 .../sdk-network-providers/api_network_provider.md                 | 0
 .../sdk-network-providers/proxy_network_provider.md               | 0
 2 files changed, 0 insertions(+), 0 deletions(-)
 delete mode 100644 network-interaction-sdk/sdk-network-providers/api_network_provider.md
 delete mode 100644 network-interaction-sdk/sdk-network-providers/proxy_network_provider.md

diff --git a/network-interaction-sdk/sdk-network-providers/api_network_provider.md b/network-interaction-sdk/sdk-network-providers/api_network_provider.md
deleted file mode 100644
index e69de29..0000000
diff --git a/network-interaction-sdk/sdk-network-providers/proxy_network_provider.md b/network-interaction-sdk/sdk-network-providers/proxy_network_provider.md
deleted file mode 100644
index e69de29..0000000

From c6b53967627e6f87547ea7a2ebcbada18a0c4ff8 Mon Sep 17 00:00:00 2001
From: Alexandru Popenta <alexandru.p9913@gmail.com>
Date: Thu, 27 Jul 2023 16:03:04 +0300
Subject: [PATCH 38/69] add missing parmeters

---
 .../token_management_transactions_factory.md                    | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
index 640582e..71a5983 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
@@ -12,6 +12,8 @@ class TokenManagementTransactionsFactory:
         sender: IAddress;
         tokenName: string;
         tokenTicker: string;
+        initialSupply: int;
+        numDecimals: int;
         canFreeze: boolean;
         canWipe: boolean;
         canPause: boolean;

From 55e732d5c2d7a01b5a51dfbfd10d32add167e764 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Camil=20B=C4=83ncioiu?=
 <camilbancioiu@users.noreply.github.com>
Date: Fri, 18 Aug 2023 10:35:09 +0300
Subject: [PATCH 39/69] Mention `any` for golang 1.18

---
 network-interaction-sdk/README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/network-interaction-sdk/README.md b/network-interaction-sdk/README.md
index b9cbcbe..e453ab4 100644
--- a/network-interaction-sdk/README.md
+++ b/network-interaction-sdk/README.md
@@ -31,7 +31,9 @@ Generally speaking, it's recommended to return concrete types in the public API
 
 In the specs, `object` is used as a placeholder for any type of object. In the implementing libraries, this would be replaced with the most appropriate type. For example:
 
-- in Go: `map[string]interface{}` or directly `interface{}` (depending on the context)
+- in Go:
+  - before Go 1.18: `map[string]interface{}` or directly `interface{}` (depending on the context)
+  - after Go 1.18: `map[string]any` or directly `any` (depending on the context)
 - in Python: `dict` or `Any`
 - in JavaScript / TypeScript: `object` or `any`
 

From e506eb63033abe1c310c48b233ad1f979c366e98 Mon Sep 17 00:00:00 2001
From: Alexandru Popenta <alexandru.p9913@gmail.com>
Date: Fri, 25 Aug 2023 11:01:37 +0300
Subject: [PATCH 40/69] rename factory classes

---
 .../transactions-factories/delegation_transactions_factory.md   | 2 +-
 .../smart_contract_transactions_factory.md                      | 2 +-
 .../token_management_transactions_factory.md                    | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
index f3a1f4b..a2202bd 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
@@ -1,7 +1,7 @@
 ## DelegationTransactionsFactory
 
 ```
-class DelegationTransactionsFactory:
+class DelegationTransactionIntentsFactory:
     // The constructor is not captured by the specs; it's up to the implementing library to define it.
     // Generally speaking, the constructor should be parametrized with a configuration object which defines entries such as:
     // "minGasLimit", "gasLimitPerByte", gas limit for specific operations etc. (e.g. "gasLimitForStaking").
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
index d00a992..0c5b2b1 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
@@ -1,7 +1,7 @@
 ## SmartContractTransactionsFactory
 
 ```
-class SmartContractTransactionsFactory:
+class SmartContractTransactionIntentsFactory:
     // The constructor is not captured by the specs; it's up to the implementing library to define it.
     // Generally speaking, the constructor should be parametrized with a configuration object which defines entries such as:
     // "minGasLimit", "gasLimitPerByte" etc.
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
index 71a5983..bf08f7e 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
@@ -3,7 +3,7 @@
 A class that provides methods for creating transactions for token management operations.
 
 ```
-class TokenManagementTransactionsFactory:
+class TokenManagementTransactionIntentsFactory:
     // The constructor is not captured by the specs; it's up to the implementing library to define it.
     // Generally speaking, the constructor should be parametrized with a configuration object which defines entries such as:
     // "minGasLimit", "gasLimitPerByte", "issueCost", gas limit for specific operations etc. (e.g. "gasLimitForSettingSpecialRole").

From 5eeeed395732aad4c22610c677380006a4cb9aec Mon Sep 17 00:00:00 2001
From: Alexandru Popenta <alexandru.p9913@gmail.com>
Date: Fri, 25 Aug 2023 11:06:11 +0300
Subject: [PATCH 41/69] update comments

---
 .../transactions-factories/delegation_transactions_factory.md   | 2 +-
 .../smart_contract_transactions_factory.md                      | 2 +-
 .../token_management_transactions_factory.md                    | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
index a2202bd..84d9f01 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
@@ -1,4 +1,4 @@
-## DelegationTransactionsFactory
+## DelegationTransactionIntentsFactory
 
 ```
 class DelegationTransactionIntentsFactory:
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
index 0c5b2b1..fb84160 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
@@ -1,4 +1,4 @@
-## SmartContractTransactionsFactory
+## SmartContractTransactionIntentsFactory
 
 ```
 class SmartContractTransactionIntentsFactory:
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
index bf08f7e..b083840 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
@@ -1,4 +1,4 @@
-## TokenManagementTransactionsFactory
+## TokenManagementTransactionIntentsFactory
 
 A class that provides methods for creating transactions for token management operations.
 

From 38fc4070afcf3536c20f3ee83b84fdd00db0702e Mon Sep 17 00:00:00 2001
From: Alexandru Popenta <alexandru.p9913@gmail.com>
Date: Fri, 25 Aug 2023 11:13:42 +0300
Subject: [PATCH 42/69] rename factory files

---
 ...tions_factory.md => delegation_transaction_intents_factory.md} | 0
 ...s_factory.md => smart_contract_transaction_intents_factory.md} | 0
 ...factory.md => token_management_transaction_intents_factory.md} | 0
 3 files changed, 0 insertions(+), 0 deletions(-)
 rename network-interaction-sdk/sdk-core/transactions-factories/{delegation_transactions_factory.md => delegation_transaction_intents_factory.md} (100%)
 rename network-interaction-sdk/sdk-core/transactions-factories/{smart_contract_transactions_factory.md => smart_contract_transaction_intents_factory.md} (100%)
 rename network-interaction-sdk/sdk-core/transactions-factories/{token_management_transactions_factory.md => token_management_transaction_intents_factory.md} (100%)

diff --git a/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/delegation_transaction_intents_factory.md
similarity index 100%
rename from network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
rename to network-interaction-sdk/sdk-core/transactions-factories/delegation_transaction_intents_factory.md
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transaction_intents_factory.md
similarity index 100%
rename from network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
rename to network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transaction_intents_factory.md
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transaction_intents_factory.md
similarity index 100%
rename from network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
rename to network-interaction-sdk/sdk-core/transactions-factories/token_management_transaction_intents_factory.md

From db783eface88e4ddbc93052df230770ca8e2298b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Fri, 8 Sep 2023 20:46:28 +0300
Subject: [PATCH 43/69] Rename folder.

---
 .../delegation_transaction_intents_factory.md                     | 0
 .../smart_contract_transaction_intents_factory.md                 | 0
 .../token_management_transaction_intents_factory.md               | 0
 .../token_transfers_factory.md                                    | 0
 4 files changed, 0 insertions(+), 0 deletions(-)
 rename network-interaction-sdk/sdk-core/{transactions-factories => transaction-intents-factories}/delegation_transaction_intents_factory.md (100%)
 rename network-interaction-sdk/sdk-core/{transactions-factories => transaction-intents-factories}/smart_contract_transaction_intents_factory.md (100%)
 rename network-interaction-sdk/sdk-core/{transactions-factories => transaction-intents-factories}/token_management_transaction_intents_factory.md (100%)
 rename network-interaction-sdk/sdk-core/{transactions-factories => transaction-intents-factories}/token_transfers_factory.md (100%)

diff --git a/network-interaction-sdk/sdk-core/transactions-factories/delegation_transaction_intents_factory.md b/network-interaction-sdk/sdk-core/transaction-intents-factories/delegation_transaction_intents_factory.md
similarity index 100%
rename from network-interaction-sdk/sdk-core/transactions-factories/delegation_transaction_intents_factory.md
rename to network-interaction-sdk/sdk-core/transaction-intents-factories/delegation_transaction_intents_factory.md
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transaction_intents_factory.md b/network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md
similarity index 100%
rename from network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transaction_intents_factory.md
rename to network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transaction_intents_factory.md b/network-interaction-sdk/sdk-core/transaction-intents-factories/token_management_transaction_intents_factory.md
similarity index 100%
rename from network-interaction-sdk/sdk-core/transactions-factories/token_management_transaction_intents_factory.md
rename to network-interaction-sdk/sdk-core/transaction-intents-factories/token_management_transaction_intents_factory.md
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/token_transfers_factory.md b/network-interaction-sdk/sdk-core/transaction-intents-factories/token_transfers_factory.md
similarity index 100%
rename from network-interaction-sdk/sdk-core/transactions-factories/token_transfers_factory.md
rename to network-interaction-sdk/sdk-core/transaction-intents-factories/token_transfers_factory.md

From 00ebe4415c32ff8974bdeffb55b05ac7261306ad Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?=
 <andreibancioiu@users.noreply.github.com>
Date: Tue, 12 Sep 2023 14:49:30 +0300
Subject: [PATCH 44/69] Rename folder.

---
 .../delegation_transaction_intents_factory.md                     | 0
 .../smart_contract_transaction_intents_factory.md                 | 0
 .../token_management_transaction_intents_factory.md               | 0
 .../token_transfers_factory.md                                    | 0
 4 files changed, 0 insertions(+), 0 deletions(-)
 rename network-interaction-sdk/sdk-core/{transactions-factories => transaction-intents-factories}/delegation_transaction_intents_factory.md (100%)
 rename network-interaction-sdk/sdk-core/{transactions-factories => transaction-intents-factories}/smart_contract_transaction_intents_factory.md (100%)
 rename network-interaction-sdk/sdk-core/{transactions-factories => transaction-intents-factories}/token_management_transaction_intents_factory.md (100%)
 rename network-interaction-sdk/sdk-core/{transactions-factories => transaction-intents-factories}/token_transfers_factory.md (100%)

diff --git a/network-interaction-sdk/sdk-core/transactions-factories/delegation_transaction_intents_factory.md b/network-interaction-sdk/sdk-core/transaction-intents-factories/delegation_transaction_intents_factory.md
similarity index 100%
rename from network-interaction-sdk/sdk-core/transactions-factories/delegation_transaction_intents_factory.md
rename to network-interaction-sdk/sdk-core/transaction-intents-factories/delegation_transaction_intents_factory.md
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transaction_intents_factory.md b/network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md
similarity index 100%
rename from network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transaction_intents_factory.md
rename to network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/token_management_transaction_intents_factory.md b/network-interaction-sdk/sdk-core/transaction-intents-factories/token_management_transaction_intents_factory.md
similarity index 100%
rename from network-interaction-sdk/sdk-core/transactions-factories/token_management_transaction_intents_factory.md
rename to network-interaction-sdk/sdk-core/transaction-intents-factories/token_management_transaction_intents_factory.md
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/token_transfers_factory.md b/network-interaction-sdk/sdk-core/transaction-intents-factories/token_transfers_factory.md
similarity index 100%
rename from network-interaction-sdk/sdk-core/transactions-factories/token_transfers_factory.md
rename to network-interaction-sdk/sdk-core/transaction-intents-factories/token_transfers_factory.md

From 28aaead429de3fa0c88bdeecc85513e7608ae852 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Tue, 12 Sep 2023 18:14:08 +0300
Subject: [PATCH 45/69] Transaction.guardianSignature should be optional.

---
 network-interaction-sdk/sdk-core/transaction.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/network-interaction-sdk/sdk-core/transaction.md b/network-interaction-sdk/sdk-core/transaction.md
index ae5d534..8cd81b5 100644
--- a/network-interaction-sdk/sdk-core/transaction.md
+++ b/network-interaction-sdk/sdk-core/transaction.md
@@ -19,7 +19,7 @@ dto Transaction:
     guardian?: string;
 
     signature: bytes;
-    guardianSignature: bytes;
+    guardianSignature?: bytes;
 ```
 
 ## TransactionComputer

From c2b4b78f8f0f656a166c4a4dec83d72b407eb73e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Tue, 12 Sep 2023 18:37:43 +0300
Subject: [PATCH 46/69] Sketch: CustomToken, CustomTokenTransfer.

---
 .../sdk-core/custom_tokens.md                 | 40 ++++++++++++++
 .../sdk-core/token_transfer.md                | 53 -------------------
 ...rt_contract_transaction_intents_factory.md | 10 +++-
 3 files changed, 49 insertions(+), 54 deletions(-)
 create mode 100644 network-interaction-sdk/sdk-core/custom_tokens.md
 delete mode 100644 network-interaction-sdk/sdk-core/token_transfer.md

diff --git a/network-interaction-sdk/sdk-core/custom_tokens.md b/network-interaction-sdk/sdk-core/custom_tokens.md
new file mode 100644
index 0000000..907eead
--- /dev/null
+++ b/network-interaction-sdk/sdk-core/custom_tokens.md
@@ -0,0 +1,40 @@
+## CustomToken
+
+```
+dto CustomToken:
+    // E.g. "FOO-abcdef", "EGLD".
+    identifier: string;
+    nonce: number;
+```
+
+## TokenComputer
+
+```
+class CustomTokenComputer:
+    // The constructor is not captured by the specs; it's up to the implementing library to define it.
+
+    // Returns token.nonce == 0.
+    is_fungible_token(token: Token): boolean;
+
+    // Given "FOO-abcdef-0a" returns 10.
+    extract_token_nonce_from_extended_identifier(extended_identifier: string): number;
+
+    // Given "FOO-abcdef-0a" returns "FOO-abcdef".
+    extract_token_identifier_from_extended_identifier(extended_identifier: string): string;
+
+    // Given "FOO-abcdef-0a" returns "FOO".
+    extract_token_name_from_extended_identifier(extended_identifier: string): string;
+
+    // Given "FOO-abcdef" returns "FOO".
+    extract_token_name_from_identifier(identifier: string): string;
+```
+
+## CustomTokenTransfer
+
+```
+dto CustomTokenTransfer:
+    token: CustomToken;
+
+    // Always in atomic units, e.g. for transferring 1.000000 "USDC-c76f1f", it must be "1000000".
+    amount: (string|bigNumber);
+```
diff --git a/network-interaction-sdk/sdk-core/token_transfer.md b/network-interaction-sdk/sdk-core/token_transfer.md
deleted file mode 100644
index a6cf5ee..0000000
--- a/network-interaction-sdk/sdk-core/token_transfer.md
+++ /dev/null
@@ -1,53 +0,0 @@
-## TokenTransfer
-
-```
-class TokenTransfer:
-    // Fields (properties):
-    token_identifier: ITokenIdentifier;
-    token_nonce: number;
-    amount_in_atomic_units: number;
-
-    constructor(tokenIdentifier: ITokenIdentifier, tokenNonce: number, amountInAtomicUnits: number);
-
-    isEgld(): boolean;
-
-    isFungible(): boolean;
-
-    // Named constructors:
-    static ofEgld(amountInAtomicUnits: number): TokenTransfer;
-    static ofFungible(tokenIdentifier: ITokenIdentifier, amountInAtomicUnits: number): TokenTransfer;
-    static ofNonFungible(tokenIdentifier: ITokenIdentifier, nonce: number): TokenTransfer;
-    static ofSemiFungible(tokenIdentifier: ITokenIdentifier, nonce: number, quantity: number): TokenTransfer;
-    static ofMetaESDT(tokenIdentifier: ITokenIdentifier, nonce: number, amountInAtomicUnits: number): TokenTransfer;
-
-    // Amount in atomic units, as string.
-    toString();
-```
-
-Examples of usage:
-
-```
-amount = Amount.nativeFromUnits("1.50");
-tokenTransfer = TokenTransfer.ofEgld(amount.toUnits());
-
-print(tokenTransfer.isEgld());
-
-transaction = new Transaction({
-    ...
-    value: amount, // compatible with ITransactionValue
-    ...
-});
-```
-
-```
-amount = Amoount.fromUnits("10", 6);
-tokenTransfer = TokenTransfer.ofFungible("TEST-abcdef", amount.toAtomicUnits());
-
-print(tokenTransfer.isFungible());
-
-transaction = tokenTransfersFactory.create_esdt_transfer({ 
-    ...
-    tokenTransfer: tokenTransfer,
-    ...
- });
-```
diff --git a/network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md b/network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md
index fb84160..4177739 100644
--- a/network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md
+++ b/network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md
@@ -5,12 +5,15 @@ class SmartContractTransactionIntentsFactory:
     // The constructor is not captured by the specs; it's up to the implementing library to define it.
     // Generally speaking, the constructor should be parametrized with a configuration object which defines entries such as:
     // "minGasLimit", "gasLimitPerByte" etc.
-    // The constructor should also be parametrized with a Codec instance, necessary to encode contract call arguments.
+    // The constructor may also be parametrized with a Codec instance, necessary to encode contract call arguments.
 
     create_transaction_intent_for_deploy({
         sender: IAddress;
         bytecode: bytes OR bytecodePath: Path;
         arguments: List[object] = [];
+        // Question for review: is this a valid case?
+        native_transfer_amount: (string|bigNumber) = 0;
+        custom_transfers: List[CustomTokenTransfer] = [];
         isUpgradeable: bool = True;
         isReadable: bool = True;
         isPayable: bool = False;
@@ -24,6 +27,8 @@ class SmartContractTransactionIntentsFactory:
         // If "function" is a reserved word in the implementing language, it should be replaced with a different name (e.g. "func" or "functionName").
         function: string;
         arguments: List[object] = [];
+        native_transfer_amount: (string|bigNumber) = 0;
+        custom_transfers: List[CustomTokenTransfer] = [];
         gasLimit: uint32;
     }): TransactionIntent;
 
@@ -32,6 +37,9 @@ class SmartContractTransactionIntentsFactory:
         contract: IAddress;
         bytecode: bytes OR bytecodePath: Path;
         arguments: List[object] = [];
+        // Question for review: is this a valid case?
+        native_transfer_amount: (string|bigNumber) = 0;
+        custom_transfers: List[CustomTokenTransfer] = [];
         isUpgradeable: bool = True;
         isReadable: bool = True;
         isPayable: bool = False;

From 94fca73694ecf6aa029165f268a81e0c29efc90a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Wed, 13 Sep 2023 16:23:10 +0300
Subject: [PATCH 47/69] Sketch "TransferIntentsFactory".

---
 .../token_transfers_factory.md                | 28 ++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/network-interaction-sdk/sdk-core/transaction-intents-factories/token_transfers_factory.md b/network-interaction-sdk/sdk-core/transaction-intents-factories/token_transfers_factory.md
index 8c7629d..489f122 100644
--- a/network-interaction-sdk/sdk-core/transaction-intents-factories/token_transfers_factory.md
+++ b/network-interaction-sdk/sdk-core/transaction-intents-factories/token_transfers_factory.md
@@ -1 +1,27 @@
-// TBD: will be defined in a future PR.
+## TransferIntentsFactory
+
+A class that provides methods for creating transactions for transfers (native or ESDT).
+
+```
+class TransferIntentsFactory:
+    // The constructor is not captured by the specs; it's up to the implementing library to define it.
+    // Generally speaking, the constructor should be parametrized with a configuration object which defines entries such as:
+    // "minGasLimit", "gasLimitPerByte", "issueCost", gas limit for specific operations etc. (e.g. "gasLimitForESDTTransfer").
+    
+    create_transaction_intent_for_native_transfer({
+        sender: IAddress;
+        receiver: IAddress;
+        native_transfer_amount: (bigNumber|string);
+    }): TransactionIntent;
+
+    // Can throw:
+    // - ErrBadArguments
+    //
+    // All kinds of transfers (native and ESDT) should be handled.
+    // Bad usage should be reported.
+    create_transaction_intent_for_custom_transfers({
+        sender: IAddress;
+        receiver: IAddress;
+        custom_transfers: CustomTokenTransfer[];
+    }): TransactionIntent;
+```

From 7320169bb475f73f128fde549c8fbfc549b654aa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Wed, 13 Sep 2023 16:24:50 +0300
Subject: [PATCH 48/69] Sketch some changes for "amount".

---
 network-interaction-sdk/sdk-core/amount.md | 21 +++++++--------------
 1 file changed, 7 insertions(+), 14 deletions(-)

diff --git a/network-interaction-sdk/sdk-core/amount.md b/network-interaction-sdk/sdk-core/amount.md
index e9b2d0c..dc97e05 100644
--- a/network-interaction-sdk/sdk-core/amount.md
+++ b/network-interaction-sdk/sdk-core/amount.md
@@ -1,21 +1,14 @@
 ## Amount
 
-```
-class Amount:
-    // Private fields (properties):
-    atomic_units: number;
-    num_decimals: number;
+(string, bigNumber, BigInt in go).
 
-    constructor(atomic_units: number, num_decimals?: number = unknown);
 
-    // Named constructors:
-    fromAtomicUnits(atomic_units: number, num_decimals?: number = unknown): Amount;
-    fromUnits(units: number|string, num_decimals: number): Amount;
-    nativeFromUnits(units: number|string): Amount; // num_decimals = 18.
+## AmountComputer
 
-    // Simply returns the value of the private field.
-    toAtomicUnits(): number;
 
-    // Returns the fixed point representation of the amount.
-    toUnits(): string;
+```
+class AmountComputer:
+    // ... atomic_units
+    // ... num_decimals
+    // ... units;
 ```

From 165ea3b4f177a4a2c65f4b2e0d65abde842c032d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Wed, 13 Sep 2023 17:24:20 +0300
Subject: [PATCH 49/69] Redefine amount.

---
 network-interaction-sdk/sdk-core/amount.md    | 50 +++++++++++++++++--
 .../sdk-core/custom_tokens.md                 |  2 +-
 .../delegation_transaction_intents_factory.md |  4 +-
 ...rt_contract_transaction_intents_factory.md |  6 +--
 .../token_transfers_factory.md                |  2 +-
 .../sdk-core/transaction.md                   |  4 +-
 6 files changed, 54 insertions(+), 14 deletions(-)

diff --git a/network-interaction-sdk/sdk-core/amount.md b/network-interaction-sdk/sdk-core/amount.md
index dc97e05..9291a70 100644
--- a/network-interaction-sdk/sdk-core/amount.md
+++ b/network-interaction-sdk/sdk-core/amount.md
@@ -1,14 +1,54 @@
 ## Amount
 
-(string, bigNumber, BigInt in go).
+Generally speaking, the `Amount` type should be:
+ - `int` in Python
+ - `big.Int` or `string` in Go
+ - `BigNumber.Value` (which includes `string`) in JavaScript
 
+The implementing library can define type aliases, if desired, for example:
 
-## AmountComputer
+```Python
+Amount = int
+```
+
+```Go
+type Amount = big.Int
+```
+
+```JavaScript
+type Amount = BigNumber.Value
+```
+
+Furthermore, the implementing library is free to define a wrapper class or structure. This isn't a requirement though. Example:
+
+```
+class Amount:
+    value: (big.Int|bigNumber|string)
+    to_string(): string
+```
+
+Within the specs, we use `Amount` and we mean `(bigNumber|string)`. Or, to put it differently, `(Go[big.Int]|Python[int]|JavaScript[BigNumber.Value|string])`.
+
+**Important:** 
+ - the value of an `Amount` is **always expressed in atomic units**. For example, to represent 1 EGLD, the value of `Amount` should be `1000000000000000000`, whether it's a Go `big.Int`, a Python `int`, a `string` etc.
+ - `Amount` **must not be concerned** with the number of decimals of the token. Just as the Protocol itself isn't concerned with this.
+
+## AmountInUnits
+
+Generally speaking, the `AmountInUnits` type should always be a `string`, so that **computations based on `AmountInUnits` are discouraged**. This type is meant to be used in the higher layers of an application, for example, on display purposes.
 
+The implementing library can define type aliases or wrapper classes (structures), if desired. See above.
+
+## AmountComputer
 
 ```
 class AmountComputer:
-    // ... atomic_units
-    // ... num_decimals
-    // ... units;
+    // The constructor is not captured by the specs; it's up to the implementing library to define it.
+    // For example, the constructor can be parametrized with the decimals separator (e.g. "." or ",") and with the number of decimals of the native token (18).
+
+    amount_to_units(amount: Amount, num_decimals: number): AmountInUnits;
+    units_to_amount(units: AmountInUnits, num_decimals: number): Amount;
+
+    native_amount_to_units(amount: Amount): AmountInUnits;
+    native_units_to_amount(units: AmountInUnits): Amount;
 ```
diff --git a/network-interaction-sdk/sdk-core/custom_tokens.md b/network-interaction-sdk/sdk-core/custom_tokens.md
index 907eead..68cb31b 100644
--- a/network-interaction-sdk/sdk-core/custom_tokens.md
+++ b/network-interaction-sdk/sdk-core/custom_tokens.md
@@ -36,5 +36,5 @@ dto CustomTokenTransfer:
     token: CustomToken;
 
     // Always in atomic units, e.g. for transferring 1.000000 "USDC-c76f1f", it must be "1000000".
-    amount: (string|bigNumber);
+    amount: Amount;
 ```
diff --git a/network-interaction-sdk/sdk-core/transaction-intents-factories/delegation_transaction_intents_factory.md b/network-interaction-sdk/sdk-core/transaction-intents-factories/delegation_transaction_intents_factory.md
index 84d9f01..2b439c1 100644
--- a/network-interaction-sdk/sdk-core/transaction-intents-factories/delegation_transaction_intents_factory.md
+++ b/network-interaction-sdk/sdk-core/transaction-intents-factories/delegation_transaction_intents_factory.md
@@ -8,9 +8,9 @@ class DelegationTransactionIntentsFactory:
 
     create_transaction_intent_for_new_delegation_contract({
         sender: IAddress;
-        totalDelegationCap: (string|bigNumber);
+        totalDelegationCap: Amount;
         service_fee: number;
-        value: (string|bigNumber);
+        value: Amount;
     }): TransactionIntent;
 
     create_transaction_intent_for_adding_nodes({
diff --git a/network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md b/network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md
index 4177739..cca425b 100644
--- a/network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md
+++ b/network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md
@@ -12,7 +12,7 @@ class SmartContractTransactionIntentsFactory:
         bytecode: bytes OR bytecodePath: Path;
         arguments: List[object] = [];
         // Question for review: is this a valid case?
-        native_transfer_amount: (string|bigNumber) = 0;
+        native_transfer_amount: Amount = 0;
         custom_transfers: List[CustomTokenTransfer] = [];
         isUpgradeable: bool = True;
         isReadable: bool = True;
@@ -27,7 +27,7 @@ class SmartContractTransactionIntentsFactory:
         // If "function" is a reserved word in the implementing language, it should be replaced with a different name (e.g. "func" or "functionName").
         function: string;
         arguments: List[object] = [];
-        native_transfer_amount: (string|bigNumber) = 0;
+        native_transfer_amount: Amount = 0;
         custom_transfers: List[CustomTokenTransfer] = [];
         gasLimit: uint32;
     }): TransactionIntent;
@@ -38,7 +38,7 @@ class SmartContractTransactionIntentsFactory:
         bytecode: bytes OR bytecodePath: Path;
         arguments: List[object] = [];
         // Question for review: is this a valid case?
-        native_transfer_amount: (string|bigNumber) = 0;
+        native_transfer_amount: Amount = 0;
         custom_transfers: List[CustomTokenTransfer] = [];
         isUpgradeable: bool = True;
         isReadable: bool = True;
diff --git a/network-interaction-sdk/sdk-core/transaction-intents-factories/token_transfers_factory.md b/network-interaction-sdk/sdk-core/transaction-intents-factories/token_transfers_factory.md
index 489f122..4010d93 100644
--- a/network-interaction-sdk/sdk-core/transaction-intents-factories/token_transfers_factory.md
+++ b/network-interaction-sdk/sdk-core/transaction-intents-factories/token_transfers_factory.md
@@ -11,7 +11,7 @@ class TransferIntentsFactory:
     create_transaction_intent_for_native_transfer({
         sender: IAddress;
         receiver: IAddress;
-        native_transfer_amount: (bigNumber|string);
+        native_transfer_amount: Amount;
     }): TransactionIntent;
 
     // Can throw:
diff --git a/network-interaction-sdk/sdk-core/transaction.md b/network-interaction-sdk/sdk-core/transaction.md
index 8cd81b5..07f706d 100644
--- a/network-interaction-sdk/sdk-core/transaction.md
+++ b/network-interaction-sdk/sdk-core/transaction.md
@@ -8,7 +8,7 @@ dto Transaction:
     chainID: string;
 
     nonce?: uint64;
-    value?: (string|bigNumber);
+    value?: Amount;
     senderUsername?: string;
     receiverUsername?: string;
     gasPrice?: uint32;
@@ -26,7 +26,7 @@ dto Transaction:
 
 ```
 class TransactionComputer:
-    compute_transaction_fee(transaction: Transaction, network_config: INetworkConfig): bigNumber;
+    compute_transaction_fee(transaction: Transaction, network_config: INetworkConfig): Amount;
     compute_bytes_for_signing(transaction: Transaction): bytes;
     compute_transaction_hash(transaction: Transaction): bytes;
 ```

From 041fad72bad6a230c762b9244c44711de6cc707e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Wed, 13 Sep 2023 17:26:56 +0300
Subject: [PATCH 50/69] Remove file.

---
 network-interaction-sdk/sandbox/abi.md | 120 -------------------------
 1 file changed, 120 deletions(-)
 delete mode 100644 network-interaction-sdk/sandbox/abi.md

diff --git a/network-interaction-sdk/sandbox/abi.md b/network-interaction-sdk/sandbox/abi.md
deleted file mode 100644
index 13b423e..0000000
--- a/network-interaction-sdk/sandbox/abi.md
+++ /dev/null
@@ -1,120 +0,0 @@
-## ABI
-
-TBD: Definitions will be continued in a future PR.
-
-### MxValue and implementations
-
-```
-interface MxValue {
-    // Encodes the instance data into a byte array.
-    encode_top_level(): bytes;
-    // Encodes the instance data into a byte array.
-    encode_nested(): bytes;
-    // Populates the instance with the decoded data.
-    decode_top_level(data: bytes);
-    // Populates the instance with the decoded data.
-    decode_nested(data: bytes);
-}
-```
-
-The implementing library should provide a number of `MxValue` implementations, listed below.
-
-Primitive types:
-
-```
-MxBool
-MxInt8, MxInt16, MxInt32, MxInt64, MxUInt8, MxUInt16, MxUInt32, MxUInt64
-MxBigInt, MxBigUInt
-MxBytes
-MxString
-MxH256
-MxAddress
-MxTokenIdentifier
-MxCodeMetadata
-```
-
-Generic types:
-
-```
-MxOption
-MxList
-MxArray
-```
-
-Field-bearing types:
-
-```
-MxStruct (named fields)
-MxTuple (numbered fields)
-MxEnumValue
-```
-
-Additionally, each implementing class should have 
- - a `get_*()` that returns the underlying value(s) as specifically as possible in the implementing language.
- - a `get_length()` method (or something similar, according to language conventions) that returns the number of elements in the value, if applicable.
- - other methods 
-
-For example:
-
-```
-class MxInt32 implements MxValue {
-    get_value(): int32;
-}
-
-class MxList implements MxValue {
-    get_items(): List[MxValue];
-    get_length(): int32;
-}
-```
-
-### MxValuesFactory
-
-```
-interface MxValuesFactory {
-    create_bool(value: boolean): MxBool;
-    create_int8(value: number): MxInt8;
-    create_int16(value: number): MxInt16;
-    create_int32(value: number): MxInt32;
-    create_int64(value: number): MxInt64;
-    create_uint8(value: number): MxUInt8;
-    create_uint16(value: number): MxUInt16;
-    create_uint32(value: number): MxUInt32;
-    create_uint64(value: number): MxUInt64;
-    create_bigint(value: number): MxBigInt;
-    create_biguint(value: number): MxBigUInt;
-    create_bytes(value: bytes): MxBytes;
-    create_string(value: string): MxString;
-    create_h256(value: bytes): MxH256;
-    create_address(value: IAddress|IPublicKey|string): MxAddress;
-    create_token_identifier(value: string): MxTokenIdentifier;
-
-    create_code_metadata(
-        isUpgradeable: bool = True;
-        isReadable: bool = True;
-        isPayable: bool = False;
-        isPayableBySC: bool = True;
-    ): MxCodeMetadata;
-
-    create_option_provided(value: MxValue): MxOption;
-    create_option_missing(): MxOption;
-    create_list(values: List[MxValue]): MxList;
-    create_array(values: List[MxValue]): MxArray;
-
-}
-```
-
-The implementing library should provide the `V1MxValuesFactory` implementation of `MxValuesFactory`.
-
-### AbiRegistry
-
-`AbiRegistry` is an abstraction over the content of a `*.abi.json` file.
-
-```
-class AbiRegistry:
-    // Will be defined in a future PR.
-```
-
-// struct definition
-// enum definition
-
-### TypeInferenceSystem

From c98f97c628032d28d5c7f19440e27015921537dd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Fri, 15 Sep 2023 14:32:30 +0300
Subject: [PATCH 51/69] Fix after review.

---
 network-interaction-sdk/sdk-core/custom_tokens.md | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/network-interaction-sdk/sdk-core/custom_tokens.md b/network-interaction-sdk/sdk-core/custom_tokens.md
index 68cb31b..0aa83bf 100644
--- a/network-interaction-sdk/sdk-core/custom_tokens.md
+++ b/network-interaction-sdk/sdk-core/custom_tokens.md
@@ -23,10 +23,8 @@ class CustomTokenComputer:
     extract_token_identifier_from_extended_identifier(extended_identifier: string): string;
 
     // Given "FOO-abcdef-0a" returns "FOO".
-    extract_token_name_from_extended_identifier(extended_identifier: string): string;
-
     // Given "FOO-abcdef" returns "FOO".
-    extract_token_name_from_identifier(identifier: string): string;
+    extract_token_ticker_from_identifier(identifier: string): string;
 ```
 
 ## CustomTokenTransfer

From 22f61ac465cac9cf4fd37de6848cf0fece38c100 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Fri, 15 Sep 2023 14:45:49 +0300
Subject: [PATCH 52/69] Fix after review.

---
 .../smart_contract_transaction_intents_factory.md               | 2 --
 .../transaction-intents-factories/token_transfers_factory.md    | 1 +
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md b/network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md
index cca425b..f34895a 100644
--- a/network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md
+++ b/network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md
@@ -11,7 +11,6 @@ class SmartContractTransactionIntentsFactory:
         sender: IAddress;
         bytecode: bytes OR bytecodePath: Path;
         arguments: List[object] = [];
-        // Question for review: is this a valid case?
         native_transfer_amount: Amount = 0;
         custom_transfers: List[CustomTokenTransfer] = [];
         isUpgradeable: bool = True;
@@ -37,7 +36,6 @@ class SmartContractTransactionIntentsFactory:
         contract: IAddress;
         bytecode: bytes OR bytecodePath: Path;
         arguments: List[object] = [];
-        // Question for review: is this a valid case?
         native_transfer_amount: Amount = 0;
         custom_transfers: List[CustomTokenTransfer] = [];
         isUpgradeable: bool = True;
diff --git a/network-interaction-sdk/sdk-core/transaction-intents-factories/token_transfers_factory.md b/network-interaction-sdk/sdk-core/transaction-intents-factories/token_transfers_factory.md
index 4010d93..80320af 100644
--- a/network-interaction-sdk/sdk-core/transaction-intents-factories/token_transfers_factory.md
+++ b/network-interaction-sdk/sdk-core/transaction-intents-factories/token_transfers_factory.md
@@ -18,6 +18,7 @@ class TransferIntentsFactory:
     // - ErrBadArguments
     //
     // All kinds of transfers (native and ESDT) should be handled.
+    // If multiple transfers are specified, a multi-ESDT transfer intent should be created.
     // Bad usage should be reported.
     create_transaction_intent_for_custom_transfers({
         sender: IAddress;

From 996d86faf61b262dbd4af670a4bfc445f6001f04 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Fri, 15 Sep 2023 17:41:09 +0300
Subject: [PATCH 53/69] Fix after review.

---
 .../smart_contract_transaction_intents_factory.md               | 2 --
 1 file changed, 2 deletions(-)

diff --git a/network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md b/network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md
index f34895a..aed6f6a 100644
--- a/network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md
+++ b/network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md
@@ -12,7 +12,6 @@ class SmartContractTransactionIntentsFactory:
         bytecode: bytes OR bytecodePath: Path;
         arguments: List[object] = [];
         native_transfer_amount: Amount = 0;
-        custom_transfers: List[CustomTokenTransfer] = [];
         isUpgradeable: bool = True;
         isReadable: bool = True;
         isPayable: bool = False;
@@ -37,7 +36,6 @@ class SmartContractTransactionIntentsFactory:
         bytecode: bytes OR bytecodePath: Path;
         arguments: List[object] = [];
         native_transfer_amount: Amount = 0;
-        custom_transfers: List[CustomTokenTransfer] = [];
         isUpgradeable: bool = True;
         isReadable: bool = True;
         isPayable: bool = False;

From 7f3eb2484d7c7b171ca9a3aa8aaac6af4e5f8b21 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Fri, 15 Sep 2023 19:03:19 +0300
Subject: [PATCH 54/69] Update parameter name.

---
 .../delegation_transaction_intents_factory.md                   | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/network-interaction-sdk/sdk-core/transaction-intents-factories/delegation_transaction_intents_factory.md b/network-interaction-sdk/sdk-core/transaction-intents-factories/delegation_transaction_intents_factory.md
index 2b439c1..4f22b2c 100644
--- a/network-interaction-sdk/sdk-core/transaction-intents-factories/delegation_transaction_intents_factory.md
+++ b/network-interaction-sdk/sdk-core/transaction-intents-factories/delegation_transaction_intents_factory.md
@@ -10,7 +10,7 @@ class DelegationTransactionIntentsFactory:
         sender: IAddress;
         totalDelegationCap: Amount;
         service_fee: number;
-        value: Amount;
+        amount: Amount;
     }): TransactionIntent;
 
     create_transaction_intent_for_adding_nodes({

From 85109f623dd9ee5acabf33a64ca8128b7254c2a5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Wed, 27 Sep 2023 14:03:38 +0300
Subject: [PATCH 55/69] Rename files, methods.

---
 .../sdk-core/transaction.md                   | 11 +++
 .../sdk-core/transaction_intent.md            | 10 ---
 .../delegation_transactions_factory.md}       | 60 ++++++-------
 .../smart_contract_transactions_factory.md}   | 16 ++--
 .../token_management_transactions_factory.md} | 88 +++++++++----------
 .../transfer_transactions_factory.md}         | 14 +--
 6 files changed, 100 insertions(+), 99 deletions(-)
 delete mode 100644 network-interaction-sdk/sdk-core/transaction_intent.md
 rename network-interaction-sdk/sdk-core/{transaction-intents-factories/delegation_transaction_intents_factory.md => transactions-factories/delegation_transactions_factory.md} (56%)
 rename network-interaction-sdk/sdk-core/{transaction-intents-factories/smart_contract_transaction_intents_factory.md => transactions-factories/smart_contract_transactions_factory.md} (83%)
 rename network-interaction-sdk/sdk-core/{transaction-intents-factories/token_management_transaction_intents_factory.md => transactions-factories/token_management_transactions_factory.md} (67%)
 rename network-interaction-sdk/sdk-core/{transaction-intents-factories/token_transfers_factory.md => transactions-factories/transfer_transactions_factory.md} (78%)

diff --git a/network-interaction-sdk/sdk-core/transaction.md b/network-interaction-sdk/sdk-core/transaction.md
index 07f706d..9630879 100644
--- a/network-interaction-sdk/sdk-core/transaction.md
+++ b/network-interaction-sdk/sdk-core/transaction.md
@@ -22,6 +22,17 @@ dto Transaction:
     guardianSignature?: bytes;
 ```
 
+## DraftTransaction
+
+```
+dto DraftTransaction:
+    sender: string;
+    receiver: string;
+    value?: string;
+    data?: bytes;
+    gasLimit: uint32;
+```
+
 ## TransactionComputer
 
 ```
diff --git a/network-interaction-sdk/sdk-core/transaction_intent.md b/network-interaction-sdk/sdk-core/transaction_intent.md
deleted file mode 100644
index a5445c3..0000000
--- a/network-interaction-sdk/sdk-core/transaction_intent.md
+++ /dev/null
@@ -1,10 +0,0 @@
-## TransactionIntent
-
-```
-dto TransactionIntent:
-    sender: string;
-    receiver: string;
-    value?: string;
-    data?: bytes;
-    gasLimit: uint32;
-```
diff --git a/network-interaction-sdk/sdk-core/transaction-intents-factories/delegation_transaction_intents_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
similarity index 56%
rename from network-interaction-sdk/sdk-core/transaction-intents-factories/delegation_transaction_intents_factory.md
rename to network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
index 4f22b2c..8120aff 100644
--- a/network-interaction-sdk/sdk-core/transaction-intents-factories/delegation_transaction_intents_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
@@ -1,94 +1,94 @@
-## DelegationTransactionIntentsFactory
+## DelegationTransactionsFactory
 
 ```
-class DelegationTransactionIntentsFactory:
+class DelegationTransactionsFactory:
     // The constructor is not captured by the specs; it's up to the implementing library to define it.
     // Generally speaking, the constructor should be parametrized with a configuration object which defines entries such as:
     // "minGasLimit", "gasLimitPerByte", gas limit for specific operations etc. (e.g. "gasLimitForStaking").
 
-    create_transaction_intent_for_new_delegation_contract({
+    create_transaction_for_new_delegation_contract({
         sender: IAddress;
         totalDelegationCap: Amount;
         service_fee: number;
         amount: Amount;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_adding_nodes({
+    create_transaction_for_adding_nodes({
         sender: IAddress;
         delegationContract: IAddress;
         publicKeys: List[IPublicKey];
         signedMessages: List[bytes];
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_removing_nodes({
+    create_transaction_for_removing_nodes({
         sender: IAddress,
         delegationContract: IAddress;
         publicKeys: List[IPublicKey];
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_staking_nodes({
+    create_transaction_for_staking_nodes({
         sender: IAddress,
         delegationContract: IAddress;
         publicKeys: List[IPublicKey];
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_unbonding_nodes({
+    create_transaction_for_unbonding_nodes({
         sender: IAddress,
         delegationContract: IAddress;
         publicKeys: List[IPublicKey];
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_unstaking_nodes({
+    create_transaction_for_unstaking_nodes({
         sender: IAddress,
         delegationContract: IAddress;
         publicKeys: List[IPublicKey];
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_unjailing_nodes({
+    create_transaction_for_unjailing_nodes({
         sender: IAddress,
         delegationContract: IAddress;
         publicKeys: List[IPublicKey];
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_changing_service_fee({
+    create_transaction_for_changing_service_fee({
         sender: IAddress;
         delegationContract: IAddress;
         serviceFee: int;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_modifying_delegation_cap({
+    create_transaction_for_modifying_delegation_cap({
         sender: IAddress;
         delegationContract: IAddress;
         delegationCap: int;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_setting_automatic_activation({
+    create_transaction_for_setting_automatic_activation({
         sender: IAddress;
         delegationContract: IAddress;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_unsetting_automatic_activation({
+    create_transaction_for_unsetting_automatic_activation({
         sender: IAddress;
         delegationContract: IAddress;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_setting_cap_check_on_redelegate_rewards({
+    create_transaction_for_setting_cap_check_on_redelegate_rewards({
         sender: IAddress;
         delegationContract: IAddress;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_unsetting_cap_check_on_redelegate_rewards({
+    create_transaction_for_unsetting_cap_check_on_redelegate_rewards({
         sender: IAddress;
         delegationContract: IAddress;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_setting_metadata({
+    create_transaction_for_setting_metadata({
         sender: IAddress;
         delegationContract: IAddress;
         name: str;
         website: str;
         identifier: str;
-    }): TransactionIntent;
+    }): Transaction;
 
     ...
 ```
diff --git a/network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
similarity index 83%
rename from network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md
rename to network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
index aed6f6a..9bd066c 100644
--- a/network-interaction-sdk/sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
@@ -1,13 +1,13 @@
-## SmartContractTransactionIntentsFactory
+## SmartContractTransactionsFactory
 
 ```
-class SmartContractTransactionIntentsFactory:
+class SmartContractTransactionsFactory:
     // The constructor is not captured by the specs; it's up to the implementing library to define it.
     // Generally speaking, the constructor should be parametrized with a configuration object which defines entries such as:
     // "minGasLimit", "gasLimitPerByte" etc.
     // The constructor may also be parametrized with a Codec instance, necessary to encode contract call arguments.
 
-    create_transaction_intent_for_deploy({
+    create_transaction_for_deploy({
         sender: IAddress;
         bytecode: bytes OR bytecodePath: Path;
         arguments: List[object] = [];
@@ -17,9 +17,9 @@ class SmartContractTransactionIntentsFactory:
         isPayable: bool = False;
         isPayableBySC: bool = True;
         gasLimit: uint32;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_execute({
+    create_transaction_for_execute({
         sender: IAddress;
         contract: IAddress;
         // If "function" is a reserved word in the implementing language, it should be replaced with a different name (e.g. "func" or "functionName").
@@ -28,9 +28,9 @@ class SmartContractTransactionIntentsFactory:
         native_transfer_amount: Amount = 0;
         custom_transfers: List[CustomTokenTransfer] = [];
         gasLimit: uint32;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_upgrade({
+    create_transaction_for_upgrade({
         sender: IAddress;
         contract: IAddress;
         bytecode: bytes OR bytecodePath: Path;
@@ -41,7 +41,7 @@ class SmartContractTransactionIntentsFactory:
         isPayable: bool = False;
         isPayableBySC: bool = True;
         gasLimit: uint32;
-    }): TransactionIntent;
+    }): Transaction;
 
     ...
 
diff --git a/network-interaction-sdk/sdk-core/transaction-intents-factories/token_management_transaction_intents_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
similarity index 67%
rename from network-interaction-sdk/sdk-core/transaction-intents-factories/token_management_transaction_intents_factory.md
rename to network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
index b083840..68ad889 100644
--- a/network-interaction-sdk/sdk-core/transaction-intents-factories/token_management_transaction_intents_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/token_management_transactions_factory.md
@@ -1,14 +1,14 @@
-## TokenManagementTransactionIntentsFactory
+## TokenManagementTransactionsFactory
 
 A class that provides methods for creating transactions for token management operations.
 
 ```
-class TokenManagementTransactionIntentsFactory:
+class TokenManagementTransactionsFactory:
     // The constructor is not captured by the specs; it's up to the implementing library to define it.
     // Generally speaking, the constructor should be parametrized with a configuration object which defines entries such as:
     // "minGasLimit", "gasLimitPerByte", "issueCost", gas limit for specific operations etc. (e.g. "gasLimitForSettingSpecialRole").
 
-    create_transaction_intent_for_issuing_fungible({
+    create_transaction_for_issuing_fungible({
         sender: IAddress;
         tokenName: string;
         tokenTicker: string;
@@ -21,9 +21,9 @@ class TokenManagementTransactionIntentsFactory:
         canChangeOwner: boolean;
         canUpgrade: boolean;
         canAddSpecialRoles: boolean;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_issuing_semi_fungible({
+    create_transaction_for_issuing_semi_fungible({
         sender: IAddress;
         tokenName: string;
         tokenTicker: string;
@@ -34,9 +34,9 @@ class TokenManagementTransactionIntentsFactory:
         canChangeOwner: boolean;
         canUpgrade: boolean;
         canAddSpecialRoles: boolean;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_issuing_non_fungible({
+    create_transaction_for_issuing_non_fungible({
         sender: IAddress;
         tokenName: string;
         tokenTicker: string;
@@ -47,9 +47,9 @@ class TokenManagementTransactionIntentsFactory:
         canChangeOwner: boolean;
         canUpgrade: boolean;
         canAddSpecialRoles: boolean;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_registering_meta_esdt({
+    create_transaction_for_registering_meta_esdt({
         sender: IAddress;
         tokenName: string;
         tokenTicker: string;
@@ -61,35 +61,35 @@ class TokenManagementTransactionIntentsFactory:
         canChangeOwner: boolean;
         canUpgrade: boolean;
         canAddSpecialRoles: boolean;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_registering_and_setting_roles({
+    create_transaction_for_registering_and_setting_roles({
         sender: IAddress;
         tokenName: string;
         tokenTicker: string;
         tokenType: RegisterAndSetAllRolesTokenType;
         numDecimals: number;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_setting_burn_role_globally({
+    create_transaction_for_setting_burn_role_globally({
         sender: IAddress;
         tokenIdentifier: string;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_unsetting_burn_role_globally({
+    create_transaction_for_unsetting_burn_role_globally({
         sender: IAddress;
         tokenIdentifier: string;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_setting_special_role_on_fungible_token({
+    create_transaction_for_setting_special_role_on_fungible_token({
         sender: IAddress;
         user: IAddress;
         tokenIdentifier: string;
         addRoleLocalMint: boolean;
         addRoleLocalBurn: boolean;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_setting_special_role_on_semi_fungible_token({
+    create_transaction_for_setting_special_role_on_semi_fungible_token({
         sender: IAddress;
         user: IAddress;
         tokenIdentifier: string;
@@ -97,9 +97,9 @@ class TokenManagementTransactionIntentsFactory:
         addRoleNFTBurn: boolean;
         addRoleNFTAddQuantity: boolean;
         addRoleESDTTransferRole: boolean;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_setting_special_role_on_non_fungible_token({
+    create_transaction_for_setting_special_role_on_non_fungible_token({
         sender: IAddress;
         user: IAddress;
         tokenIdentifier: str;
@@ -108,9 +108,9 @@ class TokenManagementTransactionIntentsFactory:
         addRoleNftUpdate_attributes: bool;
         addRoleNftAddUri: bool;
         addRoleESDTTransferRole: bool;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_creating_nft({
+    create_transaction_for_creating_nft({
         sender: IAddress;
         tokenIdentifier: str;
         initialQuantity: int;
@@ -119,68 +119,68 @@ class TokenManagementTransactionIntentsFactory:
         hash: str;
         attributes: bytes;
         uris: List[str];
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_pausing({
+    create_transaction_for_pausing({
         sender: IAddress;
         tokenIdentifier: str;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_unpausing({
+    create_transaction_for_unpausing({
         sender: IAddress;
         tokenIdentifier: str;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_freezing({
+    create_transaction_for_freezing({
         sender: IAddress;
         user: IAddress;
         tokenIdentifier: str;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_unfreezing({
+    create_transaction_for_unfreezing({
         sender: IAddress;
         user: IAddress;
         tokenIdentifier: str;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_wiping({
+    create_transaction_for_wiping({
         sender: IAddress;
         user: IAddress;
         tokenIdentifier: str;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_local_minting({
+    create_transaction_for_local_minting({
         sender: IAddress;
         tokenIdentifier: str;
         supplyToMint: int;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_local_burning({
+    create_transaction_for_local_burning({
         sender: IAddress;
         tokenIdentifier: str;
         supplyToBurn: int;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_updating_attributes({
+    create_transaction_for_updating_attributes({
         sender: IAddress;
         tokenIdentifier: str;
         tokenNonce: int;
         attributes: bytes;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_adding_quantity({
+    create_transaction_for_adding_quantity({
         sender: IAddress;
         tokenIdentifier: str;
         tokenNonce: int;
         quantityToAdd: int;
-    }): TransactionIntent;
+    }): Transaction;
 
-    create_transaction_intent_for_burning_quantity({
+    create_transaction_for_burning_quantity({
         sender: IAddress;
         tokenIdentifier: str;
         tokenNonce: int;
         quantityToBurn: int;
-    }): TransactionIntent;
+    }): Transaction;
 
     ...
 ```
diff --git a/network-interaction-sdk/sdk-core/transaction-intents-factories/token_transfers_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/transfer_transactions_factory.md
similarity index 78%
rename from network-interaction-sdk/sdk-core/transaction-intents-factories/token_transfers_factory.md
rename to network-interaction-sdk/sdk-core/transactions-factories/transfer_transactions_factory.md
index 80320af..a1a1fc3 100644
--- a/network-interaction-sdk/sdk-core/transaction-intents-factories/token_transfers_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/transfer_transactions_factory.md
@@ -1,28 +1,28 @@
-## TransferIntentsFactory
+## TransferTransactionsFactory
 
 A class that provides methods for creating transactions for transfers (native or ESDT).
 
 ```
-class TransferIntentsFactory:
+class TransferTransactionsFactory:
     // The constructor is not captured by the specs; it's up to the implementing library to define it.
     // Generally speaking, the constructor should be parametrized with a configuration object which defines entries such as:
     // "minGasLimit", "gasLimitPerByte", "issueCost", gas limit for specific operations etc. (e.g. "gasLimitForESDTTransfer").
     
-    create_transaction_intent_for_native_transfer({
+    create_transaction_for_native_transfer({
         sender: IAddress;
         receiver: IAddress;
         native_transfer_amount: Amount;
-    }): TransactionIntent;
+    }): Transaction;
 
     // Can throw:
     // - ErrBadArguments
     //
     // All kinds of transfers (native and ESDT) should be handled.
-    // If multiple transfers are specified, a multi-ESDT transfer intent should be created.
+    // If multiple transfers are specified, a multi-ESDT transfer transaction should be created.
     // Bad usage should be reported.
-    create_transaction_intent_for_custom_transfers({
+    create_transaction_for_custom_transfers({
         sender: IAddress;
         receiver: IAddress;
         custom_transfers: CustomTokenTransfer[];
-    }): TransactionIntent;
+    }): Transaction;
 ```

From 112e71312b4bdd71a49ff48893f8e0abef3da502 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Wed, 27 Sep 2023 15:18:39 +0300
Subject: [PATCH 56/69] More details for transaction, draftTransaction.

---
 network-interaction-sdk/README.md               | 10 ++++++++++
 network-interaction-sdk/sdk-core/transaction.md |  5 +++++
 2 files changed, 15 insertions(+)

diff --git a/network-interaction-sdk/README.md b/network-interaction-sdk/README.md
index e453ab4..055ffd8 100644
--- a/network-interaction-sdk/README.md
+++ b/network-interaction-sdk/README.md
@@ -8,6 +8,16 @@ This repository contains specifications for the `mx-sdk-*` libraries. The specif
 - `sdk-wallet`: core wallet components (generation, signing).
 - `sdk-network-providers`: Network Provider (API, Gateway) components.
 
+Below, we add specific details for some of the most important packages and sub-components.
+
+### Transactions Factories
+
+These components are located in `sdk-core/transactions-factories` and are responsible with creating transactions for specific use cases. They are designed as _multi-factory_ classes, having methods that return a `Transaction` object constructed by following specific recipes (with respect to the Protocol). 
+
+The methods are named in correspondence with the use cases they implement, e.g. `create_transaction_for_native_transfer()` or `create_transaction_for_new_delegation_contract()`. They return a `Transaction` (data transfer object), where `sender`, `receiver`, `value`, `data` and `gasLimit` are properly set (upon eventual computation, where applicable).
+
+Optionally, the implementing library can choose to return an object that isn't a complete representation of the `Transaction`, if desired. In this case, the library must name the incomplete representation `DraftTransaction`, and also must provide a direct conversion facility from `DraftTransaction` to `Transaction` - for example, a named constructor. See [transaction](sdk-core/transaction.md).
+
 ## Guidelines
 
 ###  **`in-ifaces-out-concrete-types`**
diff --git a/network-interaction-sdk/sdk-core/transaction.md b/network-interaction-sdk/sdk-core/transaction.md
index 9630879..5bbcc5f 100644
--- a/network-interaction-sdk/sdk-core/transaction.md
+++ b/network-interaction-sdk/sdk-core/transaction.md
@@ -20,10 +20,15 @@ dto Transaction:
 
     signature: bytes;
     guardianSignature?: bytes;
+
+    // Optional named constructor, if and only if the implementing library defines a `DraftTransaction`.
+    new_from_draft(draft: DraftTransaction): Transaction;
 ```
 
 ## DraftTransaction
 
+Optionally, if desired, the implementing library can also define an incomplete representation of the transaction, to be used as return type for the **transaction factories**. See [README](../README.md), instead of the `Transaction` type.
+
 ```
 dto DraftTransaction:
     sender: string;

From e815a7cc26e371f48b3c07c8754baa8fbde38c89 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Thu, 28 Sep 2023 16:09:12 +0300
Subject: [PATCH 57/69] CustomTokenComputer: define errors. Rename methods, add
 some optional ones.

---
 .../sdk-core/custom_tokens.md                 | 40 +++++++++++++++++--
 1 file changed, 36 insertions(+), 4 deletions(-)

diff --git a/network-interaction-sdk/sdk-core/custom_tokens.md b/network-interaction-sdk/sdk-core/custom_tokens.md
index 0aa83bf..2425f08 100644
--- a/network-interaction-sdk/sdk-core/custom_tokens.md
+++ b/network-interaction-sdk/sdk-core/custom_tokens.md
@@ -14,17 +14,49 @@ class CustomTokenComputer:
     // The constructor is not captured by the specs; it's up to the implementing library to define it.
 
     // Returns token.nonce == 0.
-    is_fungible_token(token: Token): boolean;
+    // Can throw:
+    // - ErrInvalidCustomTokenIdentifier
+    is_fungible(token: CustomToken): boolean;
 
     // Given "FOO-abcdef-0a" returns 10.
-    extract_token_nonce_from_extended_identifier(extended_identifier: string): number;
+    // Can throw:
+    // - ErrInvalidCustomTokenIdentifier
+    extract_nonce_from_extended_identifier(extended_identifier: string): number;
 
     // Given "FOO-abcdef-0a" returns "FOO-abcdef".
-    extract_token_identifier_from_extended_identifier(extended_identifier: string): string;
+    // Can throw:
+    // - ErrInvalidCustomTokenIdentifier
+    extract_identifier_from_extended_identifier(extended_identifier: string): string;
 
     // Given "FOO-abcdef-0a" returns "FOO".
     // Given "FOO-abcdef" returns "FOO".
-    extract_token_ticker_from_identifier(identifier: string): string;
+    // Can throw:
+    // - ErrInvalidCustomTokenIdentifier
+    extract_ticker_from_identifier(identifier: string): string;
+
+    // Optionally, the implementing library can define a method for parsing all token parts at once.
+    // The return type can be a tuple or the struct `CustomTokenIdentifierParts` (see below).
+    // Can throw:
+    // - ErrInvalidCustomTokenIdentifier
+    parse_extended_identifier_parts(identifier: string): CustomTokenIdentifierParts;
+
+    // Given "FOO-abcdef" and 10 returns "FOO-abcdef-0a". If nonce is 0, returns "FOO-abcdef".
+    // For example, useful when preparing the parameters for querying token data from a network provider.
+    compute_extended_identifier_from_identifier_and_nonce(identifier: string, nonce: number): string;
+
+    // Optional, if `parse_extended_identifier_parts()` is also implemented. 
+    // Pick one of the following (if the language does not support overloading):
+    compute_extended_identifier_from_parts(ticker: string, random_sequence: string, nonce: number): string;
+    compute_extended_identifier_from_parts(parts: CustomTokenIdentifierParts): string;
+```
+
+An optional structure, if the implementing library defines a `parse_extended_identifier_parts` method:
+
+```
+dto CustomTokenIdentifierParts:
+    ticker: string;
+    random_sequence: string;
+    nonce: number;
 ```
 
 ## CustomTokenTransfer

From aa752dd882d7fe5492bec96f77ef9c9bf327bf2e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Thu, 28 Sep 2023 16:37:19 +0300
Subject: [PATCH 58/69] Fix after review.

---
 .../sdk-core/custom_tokens.md                 | 32 +++++++++----------
 .../smart_contract_transactions_factory.md    |  2 +-
 .../transfer_transactions_factory.md          |  9 +++---
 3 files changed, 20 insertions(+), 23 deletions(-)

diff --git a/network-interaction-sdk/sdk-core/custom_tokens.md b/network-interaction-sdk/sdk-core/custom_tokens.md
index 2425f08..661cd52 100644
--- a/network-interaction-sdk/sdk-core/custom_tokens.md
+++ b/network-interaction-sdk/sdk-core/custom_tokens.md
@@ -1,7 +1,7 @@
-## CustomToken
+## Token
 
 ```
-dto CustomToken:
+dto Token:
     // E.g. "FOO-abcdef", "EGLD".
     identifier: string;
     nonce: number;
@@ -10,35 +10,33 @@ dto CustomToken:
 ## TokenComputer
 
 ```
-class CustomTokenComputer:
+class TokenComputer:
     // The constructor is not captured by the specs; it's up to the implementing library to define it.
 
     // Returns token.nonce == 0.
-    // Can throw:
-    // - ErrInvalidCustomTokenIdentifier
-    is_fungible(token: CustomToken): boolean;
+    is_fungible(token: Token): boolean;
 
     // Given "FOO-abcdef-0a" returns 10.
     // Can throw:
-    // - ErrInvalidCustomTokenIdentifier
+    // - ErrInvalidTokenIdentifier
     extract_nonce_from_extended_identifier(extended_identifier: string): number;
 
     // Given "FOO-abcdef-0a" returns "FOO-abcdef".
     // Can throw:
-    // - ErrInvalidCustomTokenIdentifier
+    // - ErrInvalidTokenIdentifier
     extract_identifier_from_extended_identifier(extended_identifier: string): string;
 
     // Given "FOO-abcdef-0a" returns "FOO".
     // Given "FOO-abcdef" returns "FOO".
     // Can throw:
-    // - ErrInvalidCustomTokenIdentifier
+    // - ErrInvalidTokenIdentifier
     extract_ticker_from_identifier(identifier: string): string;
 
     // Optionally, the implementing library can define a method for parsing all token parts at once.
-    // The return type can be a tuple or the struct `CustomTokenIdentifierParts` (see below).
+    // The return type can be a tuple or the struct `TokenIdentifierParts` (see below).
     // Can throw:
-    // - ErrInvalidCustomTokenIdentifier
-    parse_extended_identifier_parts(identifier: string): CustomTokenIdentifierParts;
+    // - ErrInvalidTokenIdentifier
+    parse_extended_identifier_parts(identifier: string): TokenIdentifierParts;
 
     // Given "FOO-abcdef" and 10 returns "FOO-abcdef-0a". If nonce is 0, returns "FOO-abcdef".
     // For example, useful when preparing the parameters for querying token data from a network provider.
@@ -47,23 +45,23 @@ class CustomTokenComputer:
     // Optional, if `parse_extended_identifier_parts()` is also implemented. 
     // Pick one of the following (if the language does not support overloading):
     compute_extended_identifier_from_parts(ticker: string, random_sequence: string, nonce: number): string;
-    compute_extended_identifier_from_parts(parts: CustomTokenIdentifierParts): string;
+    compute_extended_identifier_from_parts(parts: TokenIdentifierParts): string;
 ```
 
 An optional structure, if the implementing library defines a `parse_extended_identifier_parts` method:
 
 ```
-dto CustomTokenIdentifierParts:
+dto TokenIdentifierParts:
     ticker: string;
     random_sequence: string;
     nonce: number;
 ```
 
-## CustomTokenTransfer
+## TokenTransfer
 
 ```
-dto CustomTokenTransfer:
-    token: CustomToken;
+dto TokenTransfer:
+    token: Token;
 
     // Always in atomic units, e.g. for transferring 1.000000 "USDC-c76f1f", it must be "1000000".
     amount: Amount;
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
index 9bd066c..0aaf348 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
@@ -26,7 +26,7 @@ class SmartContractTransactionsFactory:
         function: string;
         arguments: List[object] = [];
         native_transfer_amount: Amount = 0;
-        custom_transfers: List[CustomTokenTransfer] = [];
+        token_transfers: List[TokenTransfer] = [];
         gasLimit: uint32;
     }): Transaction;
 
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/transfer_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/transfer_transactions_factory.md
index a1a1fc3..94f37dd 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/transfer_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/transfer_transactions_factory.md
@@ -8,21 +8,20 @@ class TransferTransactionsFactory:
     // Generally speaking, the constructor should be parametrized with a configuration object which defines entries such as:
     // "minGasLimit", "gasLimitPerByte", "issueCost", gas limit for specific operations etc. (e.g. "gasLimitForESDTTransfer").
     
-    create_transaction_for_native_transfer({
+    create_transaction_for_native_token_transfer({
         sender: IAddress;
         receiver: IAddress;
-        native_transfer_amount: Amount;
+        native_amount: Amount;
     }): Transaction;
 
     // Can throw:
     // - ErrBadArguments
     //
-    // All kinds of transfers (native and ESDT) should be handled.
     // If multiple transfers are specified, a multi-ESDT transfer transaction should be created.
     // Bad usage should be reported.
-    create_transaction_for_custom_transfers({
+    create_transaction_for_esdt_token_transfer({
         sender: IAddress;
         receiver: IAddress;
-        custom_transfers: CustomTokenTransfer[];
+        token_transfers: TokenTransfer[];
     }): Transaction;
 ```

From caa7b80da2bb95a2939014fa5986f8319bb25d56 Mon Sep 17 00:00:00 2001
From: Alexandru Popenta <alexandru.p9913@gmail.com>
Date: Fri, 29 Sep 2023 10:01:25 +0300
Subject: [PATCH 59/69] remove create zero address from factory

---
 network-interaction-sdk/sdk-core/address.md | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/network-interaction-sdk/sdk-core/address.md b/network-interaction-sdk/sdk-core/address.md
index 2e07f34..2a6759e 100644
--- a/network-interaction-sdk/sdk-core/address.md
+++ b/network-interaction-sdk/sdk-core/address.md
@@ -50,10 +50,6 @@ print("Public key (hex-encoded):", address.hex())
 class AddressFactory:
     constructor(hrp: string = "erd");
 
-    // Creates an address with all bytes set to zero.
-    // This is the same as the "contract deployment address".
-    create_zero(): Address;
-
     // Creates an address from a bech32 string.
     create_from_bech32(value: string): Address;
 

From 6aec46022286513adf04dad592c5d1eb840ce6de Mon Sep 17 00:00:00 2001
From: Alexandru Popenta <alexandru.p9913@gmail.com>
Date: Fri, 27 Oct 2023 14:40:47 +0300
Subject: [PATCH 60/69] add chain id for DraftTransaction and renamed file

---
 network-interaction-sdk/sdk-core/{custom_tokens.md => tokens.md} | 0
 network-interaction-sdk/sdk-core/transaction.md                  | 1 +
 2 files changed, 1 insertion(+)
 rename network-interaction-sdk/sdk-core/{custom_tokens.md => tokens.md} (100%)

diff --git a/network-interaction-sdk/sdk-core/custom_tokens.md b/network-interaction-sdk/sdk-core/tokens.md
similarity index 100%
rename from network-interaction-sdk/sdk-core/custom_tokens.md
rename to network-interaction-sdk/sdk-core/tokens.md
diff --git a/network-interaction-sdk/sdk-core/transaction.md b/network-interaction-sdk/sdk-core/transaction.md
index 5bbcc5f..e95d17d 100644
--- a/network-interaction-sdk/sdk-core/transaction.md
+++ b/network-interaction-sdk/sdk-core/transaction.md
@@ -36,6 +36,7 @@ dto DraftTransaction:
     value?: string;
     data?: bytes;
     gasLimit: uint32;
+    chainID: string; // The chain ID from the factory's config (received in the constructor) should be used
 ```
 
 ## TransactionComputer

From 4b40d6c96cdcdfe10ceb2e4ee50c93d73c0a5408 Mon Sep 17 00:00:00 2001
From: Alexandru Popenta <alexandru.p9913@gmail.com>
Date: Fri, 17 Nov 2023 10:36:16 +0200
Subject: [PATCH 61/69] add delegation operations

---
 .../delegation_transactions_factory.md        | 27 +++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
index 8120aff..382763e 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
@@ -90,5 +90,32 @@ class DelegationTransactionsFactory:
         identifier: str;
     }): Transaction;
 
+    create_transaction_for_delegating({
+        sender: IAddress;
+        delegationContract: IAddress;
+        value: Amount;
+    }): Transaction;
+
+    create_transaction_for_claiming_rewards({
+        sender: IAddress;
+        delegationContract: IAddress;
+    }): Transaction;
+
+    create_transaction_for_redelegating_rewards({
+        sender: IAddress;
+        delegationContract: IAddress;
+    }): Transaction;
+
+    create_transaction_for_undelegating({
+        sender: IAddress;
+        delegationContract: IAddres;
+        amount_to_undelegate: Amount;
+    }): Transaction;
+
+    create_transaction_for_withdrawing({
+        sender: IAddress;
+        delegationContract: IAddress;
+    })
+
     ...
 ```

From 97e134ddf445d5d365f9c308cba0a72119559465 Mon Sep 17 00:00:00 2001
From: Alexandru Popenta <alexandru.p9913@gmail.com>
Date: Fri, 17 Nov 2023 11:47:07 +0200
Subject: [PATCH 62/69] rename parameter

---
 .../transactions-factories/delegation_transactions_factory.md   | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
index 382763e..cc5bd07 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
@@ -93,7 +93,7 @@ class DelegationTransactionsFactory:
     create_transaction_for_delegating({
         sender: IAddress;
         delegationContract: IAddress;
-        value: Amount;
+        amount: Amount;
     }): Transaction;
 
     create_transaction_for_claiming_rewards({

From c8a956dfcf3205d0d0bd5747196868dd8c81aae7 Mon Sep 17 00:00:00 2001
From: Alexandru Popenta <alexandru.p9913@gmail.com>
Date: Fri, 17 Nov 2023 12:51:43 +0200
Subject: [PATCH 63/69] another renaming

---
 .../transactions-factories/delegation_transactions_factory.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
index cc5bd07..52aa0d7 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/delegation_transactions_factory.md
@@ -109,13 +109,13 @@ class DelegationTransactionsFactory:
     create_transaction_for_undelegating({
         sender: IAddress;
         delegationContract: IAddres;
-        amount_to_undelegate: Amount;
+        amount: Amount;
     }): Transaction;
 
     create_transaction_for_withdrawing({
         sender: IAddress;
         delegationContract: IAddress;
-    })
+    }): Transaction;
 
     ...
 ```

From e06751043bb6304abdfa029443f646b8aca046f7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Fri, 8 Dec 2023 16:35:24 +0200
Subject: [PATCH 64/69] Fix names, move behavior (functions), add extra
 comments.

---
 network-interaction-sdk/sdk-core/abi.md       | 27 -------------------
 .../smart_contract_transactions_factory.md    |  2 +-
 .../keypair_based_encryptor_decryptor.md      |  2 +-
 .../keystores/encrypted_keystore.md           | 12 ++++-----
 .../sdk-wallet/mnemonic.md                    | 12 +++------
 .../sdk-wallet/user_wallet_provider.md        | 13 ++++++++-
 .../sdk-wallet/validator_wallet_provider.md   |  7 +++++
 7 files changed, 29 insertions(+), 46 deletions(-)
 delete mode 100644 network-interaction-sdk/sdk-core/abi.md

diff --git a/network-interaction-sdk/sdk-core/abi.md b/network-interaction-sdk/sdk-core/abi.md
deleted file mode 100644
index 4470aab..0000000
--- a/network-interaction-sdk/sdk-core/abi.md
+++ /dev/null
@@ -1,27 +0,0 @@
-## ABI
-
-TBD: Definitions will be continued in a future PR.
-
-### AbiRegistry
-
-`AbiRegistry` is an abstraction over the content of a `*.abi.json` file.
-
-```
-class AbiRegistry:
-    // Will be defined in a future PR.
-```
-
-### Codec
-
-```
-class Codec {
-    // The constructor is not captured by the specs; it's up to the implementing library to define it.
-    // Generally speaking, the constructor should be parametrized with an AbiRegistry, when this is available for a given contract.
-    // It follows that a Codec instance would be bound to a specific contract.
-
-    encode_top_level(value: object): bytes;
-    encode_nested(value: object): bytes;
-    decode_top_level(data: bytes): object;
-    decode_nested(data: bytes): object;
-}
-```
diff --git a/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
index 0aaf348..66e7abf 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/smart_contract_transactions_factory.md
@@ -5,7 +5,7 @@ class SmartContractTransactionsFactory:
     // The constructor is not captured by the specs; it's up to the implementing library to define it.
     // Generally speaking, the constructor should be parametrized with a configuration object which defines entries such as:
     // "minGasLimit", "gasLimitPerByte" etc.
-    // The constructor may also be parametrized with a Codec instance, necessary to encode contract call arguments.
+    // The constructor may also be parametrized with an `Abi` or `Codec` instance (implementation detail), necessary to encode contract call arguments.
 
     create_transaction_for_deploy({
         sender: IAddress;
diff --git a/network-interaction-sdk/sdk-wallet/crypto/keypair_based_encryptor_decryptor.md b/network-interaction-sdk/sdk-wallet/crypto/keypair_based_encryptor_decryptor.md
index 7652cc9..5766d1a 100644
--- a/network-interaction-sdk/sdk-wallet/crypto/keypair_based_encryptor_decryptor.md
+++ b/network-interaction-sdk/sdk-wallet/crypto/keypair_based_encryptor_decryptor.md
@@ -4,5 +4,5 @@
 class KeyPairBasedEncryptorDecryptor:
     encrypt(data: bytes, recipient_public_key: IPublicKey, auth_secret_key: ISecretKey): PublicKeyEncryptedData;
 
-    decrypt(data: PublicKeyEncryptedData, decryptor_secret_key: SecretKey): bytes;
+    decrypt(data: PublicKeyEncryptedData, decryptor_secret_key: ISecretKey): bytes;
 ```
diff --git a/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md b/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
index 65de186..8238e8e 100644
--- a/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
+++ b/network-interaction-sdk/sdk-wallet/keystores/encrypted_keystore.md
@@ -5,20 +5,20 @@ class EncryptedKeystore:
     // The constructor is not captured by the specs; it's up to the implementing library to define it.
 
     // Named constructor
-    static new_from_secret_key(secret_key: ISecretKey): Keystore
+    static new_from_secret_key(secret_key: ISecretKey): EncryptedKeystore
 
     // Named constructor
     // Below, "wallet_provider" should implement "derive_secret_key_from_mnemonic()".
     // Advice: in the implementation all the parameters will be held as instance state (private fields).
-    static new_from_mnemonic(wallet_provider: IWalletProvider, mnemonic: Mnemonic): Keystore
+    static new_from_mnemonic(wallet_provider: IWalletProvider, mnemonic: Mnemonic): EncryptedKeystore
 
     // Importing "constructor"
-    static import_from_object(wallet_provider: IWalletProvider, object: KeyfileObject, password: string): Keystore
+    static import_from_object(wallet_provider: IWalletProvider, object: KeyfileObject, password: string): EncryptedKeystore
 
     // Importing "constructor"
-    static import_from_file(wallet_provider: IWalletProvider, path: Path, password: string): Keystore
+    static import_from_file(wallet_provider: IWalletProvider, path: Path, password: string): EncryptedKeystore
 
-    // When kind == 'secretKey', only index == 0 is supported.
+    // When kind == 'secretKey', only index == 0 and passphrase == "" is supported.
     // When kind == 'mnemonic', secret key derivation happens under the hood.
     // Below, "passphrase" is the bip39 passphrase required to derive a secret key from a mnemonic (by default, it should be an empty string).
     get_secret_key(index: int, passphrase: string): ISecretKey
@@ -87,8 +87,6 @@ dto KeyfileObject:
     };
 ```
 
-TBD: Can we perhaps adjust `EncryptedData` to be more compatible with `KeyfileObject.crypto`?
-
 ## Examples of usage
 
 Create a new JSON keystore using a new mnemonic:
diff --git a/network-interaction-sdk/sdk-wallet/mnemonic.md b/network-interaction-sdk/sdk-wallet/mnemonic.md
index 84db91c..1d8455a 100644
--- a/network-interaction-sdk/sdk-wallet/mnemonic.md
+++ b/network-interaction-sdk/sdk-wallet/mnemonic.md
@@ -1,24 +1,18 @@
 ## Mnemonic
 
-This component allows one to load / parse / validate an existing one. 
-
-It also allows one to derive a secret key from the mnemonic.
+This component allows one to load / parse an existing mnemonic.
 
 ```
 class Mnemonic:
     // At least one of the following constructors should be implemented.
-    // The constructor(s) should also trim whitespace and validate the mnemonic.
+    // The constructor(s) should also trim whitespace.
     constructor(text: string);
     constructor(words: string[]);
 
     // Alternatively, named constructors can be used:
     static newfromText(text: string): Mnemonic;
     static newfromWords(words: string[]): Mnemonic;
-
-    // Can throw:
-    // - ErrInvalidMnemonic
-    derive_secret_key(address_index: number = 0, passphrase: string = ""): ISecretKey
-
+    
     // Gets the mnemonic words.
     getWords(): string[];
 
diff --git a/network-interaction-sdk/sdk-wallet/user_wallet_provider.md b/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
index 209cb30..43db04d 100644
--- a/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
+++ b/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
@@ -2,6 +2,9 @@
 
 ```
 class UserWalletProvider:
+    // The constructor is not captured by the specs; it's up to the implementing library to define it.
+    // For example, the constructor can be parametrized with underlying, more low-level crypto components, if applicable.
+
     // Should not throw.
     generate_keypair(): (ISecretKey, IPublicKey)
 
@@ -28,6 +31,14 @@ class UserWalletProvider:
 
     // Should not throw.
     generate_mnemonic(): Mnemonic
+
+    // Should not throw.
+    validate_mnemonic(mnemonic: Mnemonic): bool
+
+    derive_secret_key_from_mnemonic(mnemonic: Mnemonic, address_index: int, passphrase: string): ISecretKey
 ```
 
-Generally speaking, `generate_mnemonic` and `derive_secret_key_from_mnemonic` are only available in the `UserWalletProvider` (that is, they are not available in `ValidatorWalletProvider`).
+Generally speaking, the following functions are only available in the `UserWalletProvider` (that is, they are not available in `ValidatorWalletProvider`):
+ - `generate_mnemonic`
+ - `validate_mnemonic`
+ - `derive_secret_key_from_mnemonic`
diff --git a/network-interaction-sdk/sdk-wallet/validator_wallet_provider.md b/network-interaction-sdk/sdk-wallet/validator_wallet_provider.md
index 08b1531..5bfb1eb 100644
--- a/network-interaction-sdk/sdk-wallet/validator_wallet_provider.md
+++ b/network-interaction-sdk/sdk-wallet/validator_wallet_provider.md
@@ -2,6 +2,9 @@
 
 ```
 class ValidatorWalletProvider:
+    // The constructor is not captured by the specs; it's up to the implementing library to define it.
+    // For example, the constructor can be parametrized with underlying, more low-level crypto components, if applicable.
+
     // Should not throw.
     generate_keypair(): (ISecretKey, IPublicKey)
 
@@ -21,4 +24,8 @@ class ValidatorWalletProvider:
     // Can throw:
     // - ErrInvalidPublicKey
     create_public_key_from_bytes(data: bytes): IPublicKey
+
+    // Can throw:
+    // - ErrInvalidSecretKey
+    compute_public_key_from_secret_key(secret_key: ISecretKey): IPublicKey
 ```

From bc6cfc2e68034c5b473816f7273b32bfd23a4310 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Fri, 8 Dec 2023 20:57:24 +0200
Subject: [PATCH 65/69] Fix after review. Also introduced MnemonicComputer.

---
 .../sdk-wallet/interfaces.md                  | 22 +++++++++++++++++
 .../sdk-wallet/mnemonic.md                    | 24 +++++++++++++++++--
 .../sdk-wallet/user_wallet_provider.md        | 19 +++------------
 .../sdk-wallet/validator_wallet_provider.md   |  6 ++---
 4 files changed, 50 insertions(+), 21 deletions(-)
 create mode 100644 network-interaction-sdk/sdk-wallet/interfaces.md

diff --git a/network-interaction-sdk/sdk-wallet/interfaces.md b/network-interaction-sdk/sdk-wallet/interfaces.md
new file mode 100644
index 0000000..38427b4
--- /dev/null
+++ b/network-interaction-sdk/sdk-wallet/interfaces.md
@@ -0,0 +1,22 @@
+## Interfaces
+
+For languages that support **structural typing** (e.g. Go, Python, TypeScript), the following interfaces should not be _exported_, since we'd like to encourage client applications to define their own interfaces, as needed.
+
+For languages that only support **nominal typing** (e.g. C#), these interfaces can be _exported_.
+
+```
+interface IWalletProvider:
+    generate_keypair(): (ISecretKey, IPublicKey)
+    sign(data: bytes, secret_key: ISecretKey): bytes
+    verify(data: bytes, signature: bytes, public_key: IPublicKey): bool
+    create_secret_key_from_bytes(data: bytes): ISecretKey
+    create_public_key_from_bytes(data: bytes): IPublicKey
+    compute_public_key_from_secret_key(secret_key: ISecretKey): IPublicKey
+```
+
+```
+interface IMnemonicComputer:
+    generate_mnemonic(): Mnemonic
+    validate_mnemonic(mnemonic: Mnemonic): bool
+    derive_secret_key_from_mnemonic(mnemonic: Mnemonic, address_index: int, passphrase: string): ISecretKey
+```
diff --git a/network-interaction-sdk/sdk-wallet/mnemonic.md b/network-interaction-sdk/sdk-wallet/mnemonic.md
index 1d8455a..794570b 100644
--- a/network-interaction-sdk/sdk-wallet/mnemonic.md
+++ b/network-interaction-sdk/sdk-wallet/mnemonic.md
@@ -21,17 +21,37 @@ class Mnemonic:
 }
 ```
 
+## MnemonicComputer
+
+Encapsulates logic for generating and validating mnemonics and for deriving secret keys from mnemonics (i.e. BIP39).
+
+```
+class MnemonicComputer implements IMnemonicComputer:
+    // The constructor is not captured by the specs; it's up to the implementing library to define it.
+
+    // Should not throw.
+    generate_mnemonic(): Mnemonic
+
+    // Should not throw.
+    validate_mnemonic(mnemonic: Mnemonic): bool
+
+    // Can throw:
+    // - ErrInvalidMnemonic
+    derive_secret_key_from_mnemonic(mnemonic: Mnemonic, address_index: int, passphrase: string): ISecretKey
+```
+
 ## Examples of usage
 
 Creating a new mnemonic and deriving the first secret key.
 
 ```
+computer = new MnemonicComputer()
 provider = new UserWalletProvider()
-mnemonic = provider.generate_mnemonic()
+mnemonic = computer.generate_mnemonic()
 print(mnemonic.toString())
 
 mnemonic = Mnemonic.newfromText("...")
-sk = provider.derive_secret_key_from_mnemonic(mnemonic, address_index=0 , passphrase="")
+sk = computer.derive_secret_key_from_mnemonic(mnemonic, address_index=0 , passphrase="")
 pk = provider.compute_public_key_from_secret_key(sk)
 address = new Address(public_key, "erd")
 print(address.bech32())
diff --git a/network-interaction-sdk/sdk-wallet/user_wallet_provider.md b/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
index 43db04d..be0cd34 100644
--- a/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
+++ b/network-interaction-sdk/sdk-wallet/user_wallet_provider.md
@@ -1,7 +1,7 @@
 ## UserWalletProvider
 
 ```
-class UserWalletProvider:
+class UserWalletProvider implements IWalletProvider:
     // The constructor is not captured by the specs; it's up to the implementing library to define it.
     // For example, the constructor can be parametrized with underlying, more low-level crypto components, if applicable.
 
@@ -18,27 +18,14 @@ class UserWalletProvider:
     verify(data: bytes, signature: bytes, public_key: IPublicKey): bool
 
     // Can throw:
-    // - ErrInvalidSecretKey
+    // - ErrInvalidSecretKeyBytes
     create_secret_key_from_bytes(data: bytes): ISecretKey
 
     // Can throw:
-    // - ErrInvalidPublicKey
+    // - ErrInvalidPublicKeyBytes
     create_public_key_from_bytes(data: bytes): IPublicKey
 
     // Can throw:
     // - ErrInvalidSecretKey
     compute_public_key_from_secret_key(secret_key: ISecretKey): IPublicKey
-
-    // Should not throw.
-    generate_mnemonic(): Mnemonic
-
-    // Should not throw.
-    validate_mnemonic(mnemonic: Mnemonic): bool
-
-    derive_secret_key_from_mnemonic(mnemonic: Mnemonic, address_index: int, passphrase: string): ISecretKey
 ```
-
-Generally speaking, the following functions are only available in the `UserWalletProvider` (that is, they are not available in `ValidatorWalletProvider`):
- - `generate_mnemonic`
- - `validate_mnemonic`
- - `derive_secret_key_from_mnemonic`
diff --git a/network-interaction-sdk/sdk-wallet/validator_wallet_provider.md b/network-interaction-sdk/sdk-wallet/validator_wallet_provider.md
index 5bfb1eb..9b52937 100644
--- a/network-interaction-sdk/sdk-wallet/validator_wallet_provider.md
+++ b/network-interaction-sdk/sdk-wallet/validator_wallet_provider.md
@@ -1,7 +1,7 @@
 ## ValidatorWalletProvider
 
 ```
-class ValidatorWalletProvider:
+class ValidatorWalletProvider implements IWalletProvider:
     // The constructor is not captured by the specs; it's up to the implementing library to define it.
     // For example, the constructor can be parametrized with underlying, more low-level crypto components, if applicable.
 
@@ -18,11 +18,11 @@ class ValidatorWalletProvider:
     verify(data: bytes, signature: bytes, public_key: IPublicKey): bool
 
     // Can throw:
-    // - ErrInvalidSecretKey
+    // - ErrInvalidSecretKeyBytes
     create_secret_key_from_bytes(data: bytes): ISecretKey
 
     // Can throw:
-    // - ErrInvalidPublicKey
+    // - ErrInvalidPublicKeyBytes
     create_public_key_from_bytes(data: bytes): IPublicKey
 
     // Can throw:

From cf82c9e683de669ea16141725dd51394e300f615 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= <andrei.bancioiu@gmail.com>
Date: Mon, 11 Dec 2023 13:06:44 +0200
Subject: [PATCH 66/69] Fix after review.

---
 network-interaction-sdk/sdk-wallet/mnemonic.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/network-interaction-sdk/sdk-wallet/mnemonic.md b/network-interaction-sdk/sdk-wallet/mnemonic.md
index 794570b..84e55ed 100644
--- a/network-interaction-sdk/sdk-wallet/mnemonic.md
+++ b/network-interaction-sdk/sdk-wallet/mnemonic.md
@@ -37,7 +37,9 @@ class MnemonicComputer implements IMnemonicComputer:
 
     // Can throw:
     // - ErrInvalidMnemonic
-    derive_secret_key_from_mnemonic(mnemonic: Mnemonic, address_index: int, passphrase: string): ISecretKey
+    // Below, "passphrase" is the optional bip39 passphrase used to derive a secret key from a mnemonic.
+    // Reference: https://en.bitcoin.it/wiki/Seed_phrase#Two-factor_seed_phrases
+    derive_secret_key_from_mnemonic(mnemonic: Mnemonic, address_index: int, passphrase: string = ""): ISecretKey
 ```
 
 ## Examples of usage

From 78fdc6e734a13810a178e1454039fc893fe44981 Mon Sep 17 00:00:00 2001
From: Alexandru Popenta <alexandru.p9913@gmail.com>
Date: Mon, 18 Dec 2023 19:08:28 +0200
Subject: [PATCH 67/69] add relayed transaction factory

---
 .../relayed_transactions_factory.md           | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
 create mode 100644 network-interaction-sdk/sdk-core/transactions-factories/relayed_transactions_factory.md

diff --git a/network-interaction-sdk/sdk-core/transactions-factories/relayed_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/relayed_transactions_factory.md
new file mode 100644
index 0000000..fa3f082
--- /dev/null
+++ b/network-interaction-sdk/sdk-core/transactions-factories/relayed_transactions_factory.md
@@ -0,0 +1,19 @@
+## RelayedTransactionsFactory
+
+class RelayedTransactionsFactory:
+    // The constructor is not captured by the specs; it's up to the implementing library to define it.
+    // Generally speaking, the constructor should be parametrized with a configuration object which defines entries such as:
+    // "minGasLimit", "gasLimitPerByte", gas limit for specific operations etc.
+
+    create_relayed_v1_transaction({
+        inner_transaction: ITransaction;
+        relayer_address: IAddress;
+        relayer_nonce: Optional[int];
+    }): Transaction;
+
+    // can throw InvalidGasLimitForInnerTransaction
+    create_relayed_v2_transaction({
+        inner_transaction: ITransaction;
+        relayer_address: IAddress;
+        relayer_nonce: Optional[int];
+    });

From 7e16b0448facaeb2fd32926373c05786cdcfec4f Mon Sep 17 00:00:00 2001
From: Alexandru Popenta <alexandru.p9913@gmail.com>
Date: Tue, 19 Dec 2023 10:25:19 +0200
Subject: [PATCH 68/69] add inner tx gas limit parameter for relayed v2

---
 .../transactions-factories/relayed_transactions_factory.md       | 1 +
 1 file changed, 1 insertion(+)

diff --git a/network-interaction-sdk/sdk-core/transactions-factories/relayed_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/relayed_transactions_factory.md
index fa3f082..abb3417 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/relayed_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/relayed_transactions_factory.md
@@ -14,6 +14,7 @@ class RelayedTransactionsFactory:
     // can throw InvalidGasLimitForInnerTransaction
     create_relayed_v2_transaction({
         inner_transaction: ITransaction;
+        inner_transaction_gas_limit: uint32;
         relayer_address: IAddress;
         relayer_nonce: Optional[int];
     });

From 6207a19be41f507739d500804039599480cddd37 Mon Sep 17 00:00:00 2001
From: Alexandru Popenta <alexandru.p9913@gmail.com>
Date: Tue, 19 Dec 2023 14:21:05 +0200
Subject: [PATCH 69/69] fixes after review

---
 .../transactions-factories/relayed_transactions_factory.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/network-interaction-sdk/sdk-core/transactions-factories/relayed_transactions_factory.md b/network-interaction-sdk/sdk-core/transactions-factories/relayed_transactions_factory.md
index abb3417..0ba2f14 100644
--- a/network-interaction-sdk/sdk-core/transactions-factories/relayed_transactions_factory.md
+++ b/network-interaction-sdk/sdk-core/transactions-factories/relayed_transactions_factory.md
@@ -5,16 +5,17 @@ class RelayedTransactionsFactory:
     // Generally speaking, the constructor should be parametrized with a configuration object which defines entries such as:
     // "minGasLimit", "gasLimitPerByte", gas limit for specific operations etc.
 
+    // Each implementation is responsible to check that each inner transaction is signed.
+    // Can throw InvalidInnerTransactionError
+
     create_relayed_v1_transaction({
         inner_transaction: ITransaction;
         relayer_address: IAddress;
-        relayer_nonce: Optional[int];
     }): Transaction;
 
-    // can throw InvalidGasLimitForInnerTransaction
+    // can throw InvalidInnerTransactionError if inner_transaction.gas_limit != 0
     create_relayed_v2_transaction({
         inner_transaction: ITransaction;
         inner_transaction_gas_limit: uint32;
         relayer_address: IAddress;
-        relayer_nonce: Optional[int];
     });