[Rehearsal] Merge "mx-sdk-specs" into "mx-specs"

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.

network-interaction-sdk/README.md

@@ -0,0 +1,49 @@
+# 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.
+
+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`**
+
+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). 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`**
+
+ - 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.
+ - 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:
+  - 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`
+

network-interaction-sdk/sdk-core/address.md

@@ -0,0 +1,99 @@
+## Address
+
+```
+class Address:
+    // Should also validate the length of the provided input.
+    // Can throw:
+    // - ErrInvalidPublicKey
+    constructor(public_key: bytes, hrp: string);
+
+    // Named constructor
+    // Can throw:
+    // - ErrInvalidBech32Address
+    static new_from_bech32(value: string): Address;
+
+    // Named constructor
+    // Can throw:
+    // - ErrInvalidHexString
+    static new_from_hex(value: string, hrp: string): Address;
+
+    // Returns the address as a string (bech32).
+    // 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.
+    to_hex(): string;
+
+    // Returns the underlying public key.
+    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.
+    is_smart_contract(): bool;
+```
+
+Example of usage:
+
+```
+address = Address.new_from_bech32("erd1qyu5wthldzr8wx5c9ucg8kjagg0jfs53s8nr3zpz3hypefsdd8ssycr6th")
+
+print("Address (bech32-encoded)", address.bech32())
+print("Public key (hex-encoded):", address.hex())
+```
+
+## AddressFactory
+
+```
+class AddressFactory:
+    constructor(hrp: string = "erd");
+
+    // Creates an address from a bech32 string.
+    create_from_bech32(value: string): Address;
+
+    // Creates an address from a public key.
+    create_from_public_key(public_key: bytes): Address;
+
+    // Creates an address from a hex string.
+    create_from_hex(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"))
+```
+
+## AddressComputer
+
+```
+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: 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;
+```
+
+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;
+```

network-interaction-sdk/sdk-core/amount.md

@@ -0,0 +1,54 @@
+## Amount
+
+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:
+
+```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:
+    // 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;
+```

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

network-interaction-sdk/sdk-core/tokens.md

@@ -0,0 +1,68 @@
+## Token
+
+```
+dto Token:
+    // E.g. "FOO-abcdef", "EGLD".
+    identifier: string;
+    nonce: number;
+```
+
+## TokenComputer
+
+```
+class TokenComputer:
+    // 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): boolean;
+
+    // Given "FOO-abcdef-0a" returns 10.
+    // Can throw:
+    // - ErrInvalidTokenIdentifier
+    extract_nonce_from_extended_identifier(extended_identifier: string): number;
+
+    // Given "FOO-abcdef-0a" returns "FOO-abcdef".
+    // Can throw:
+    // - ErrInvalidTokenIdentifier
+    extract_identifier_from_extended_identifier(extended_identifier: string): string;
+
+    // Given "FOO-abcdef-0a" returns "FOO".
+    // Given "FOO-abcdef" returns "FOO".
+    // Can throw:
+    // - 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 `TokenIdentifierParts` (see below).
+    // Can throw:
+    // - 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.
+    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: TokenIdentifierParts): string;
+```
+
+An optional structure, if the implementing library defines a `parse_extended_identifier_parts` method:
+
+```
+dto TokenIdentifierParts:
+    ticker: string;
+    random_sequence: string;
+    nonce: number;
+```
+
+## TokenTransfer
+
+```
+dto TokenTransfer:
+    token: Token;
+
+    // Always in atomic units, e.g. for transferring 1.000000 "USDC-c76f1f", it must be "1000000".
+    amount: Amount;
+```

network-interaction-sdk/sdk-core/transaction.md

@@ -0,0 +1,49 @@
+## Transaction
+
+```
+dto Transaction:
+    sender: string;
+    receiver: string;
+    gasLimit: uint32;
+    chainID: string;
+
+    nonce?: uint64;
+    value?: Amount;
+    senderUsername?: string;
+    receiverUsername?: string;
+    gasPrice?: uint32;
+
+    data?: bytes;
+    version?: uint32;
+    options?: uint32;
+    guardian?: string;
+
+    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;
+    chainID: string; // The chain ID from the factory's config (received in the constructor) should be used
+```
+
+## TransactionComputer
+
+```
+class TransactionComputer:
+    compute_transaction_fee(transaction: Transaction, network_config: INetworkConfig): Amount;
+    compute_bytes_for_signing(transaction: Transaction): bytes;
+    compute_transaction_hash(transaction: Transaction): bytes;
+```