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.).
core
: core components (address, transaction, etc.).wallet
: core wallet components (generation, signing).network-providers
: network provider (API, Gateway) components.abi
: ABI components and ABI-aware codecs.adapters
: components that resolve the impedance mismatch between interfaces of different domains.converters
: components that are able to convert concepts (structures, classes) between different domains.
Below, we add specific details for some of the most important packages and sub-components.
These components are located in 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.
The transaction controllers are components built upon the lower-level transaction factories and transaction outcome parsers. They are able to create signed transactions and parse the outcome of these transactions. The controllers are specialized for a "family" of transactions (e.g. transfer transactions, delegation transactions, smart contract transactions), just like the factories and the outcome parsers.
One controller is backed by one transaction factory and one outcome parser (paired).
- All functions that create transactions receive as first parameter the
sender: IAccount
. They also receive an optionalguardian: IAccount
. - All functions that create transactions receive a nonce, which is optional. If not provided, the nonce is fetched from the network.
- All functions that create transactions return already-signed transactions.
- All functions that parse transactions outcomes receive a
TransactionOnNetwork
. - All functions that parse transactions outcomes are paired with an additional function that awaits the completion of the transaction on the network (before parsing the outcome). For example,
parse_deploy
is paired withawait_completed_deploy
.
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).
- For JavaScript / TypeScript,
bytes
should beUint8Array
.
- 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 termserialize
(whether it's part of a class name or a function name) can be replaced bymarshal
, since that is the convention. - Errors should also follow the language convention - e.g.
ErrInvalidPublicKey
vsInvalidPublicKeyError
. Should have the same error message in all implementing libraries, though.
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 directlyinterface{}
(depending on the context) - after Go 1.18:
map[string]any
or directlyany
(depending on the context)
- before Go 1.18:
- in Python:
dict
orAny
- in JavaScript / TypeScript:
object
orany