Merge pull request #19 from multiversx/tx-vs-draft

Return "Transaction" from factories

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`**

sdk-core/transaction.md

@@ -20,6 +20,22 @@ 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;
+    receiver: string;
+    value?: string;
+    data?: bytes;
+    gasLimit: uint32;
 ```
 
 ## TransactionComputer

sdk-core/transaction-intents-factories/delegation_transaction_intents_factory.md → 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;
 
     ...
 ```

sdk-core/transaction-intents-factories/smart_contract_transaction_intents_factory.md → 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;
 
     ...