Sketch a simple facade: the entrypoint #69

andreibancioiu · 2024-05-30T13:37:14Z

Define some higher-level components (e.g. entrypoint, Account, controllers) over the low-level ones.

Useful for getting developers on-board.
Useful for tutorials
Useful for scripting and back-end development
Might also be useful in dApps (e.g. for contract interactions)

andreibancioiu · 2024-06-11T09:56:56Z

facades/account.md

+    // Named constructor
+    // Loads a secret key from a PEM file. PEM files may contain multiple accounts - thus, an (optional) "index" is used to select the desired secret key.
+    // Returns an Account object, initialized with the secret key.
+    static new_from_pem(path: Path, index: Optional[int], hrp: Optional[str]): Account;
+
+    // Named constructor
+    // Loads a secret key from an encrypted keystore file. Handles both keystores that hold a mnemonic and ones that hold a secret key (legacy).
+    // For keystores that hold an encrypted mnemonic, the optional "address_index" parameter is used to derive the desired secret key.
+    // Returns an Account object, initialized with the secret key.
+    static new_from_keystore(path: Path, password: str, address_index: Optional[int], hrp: Optional[str]): Account;
+
+    // Named constructor
+    // Loads (derives) a secret key from a mnemonic. The optional "address_index" parameter is used to guide the derivation.
+    // Returns an Account object, initialized with the secret key.
+    static new_from_mnemonic(mnemonic: str, address_index: Optional[int], hrp: Optional[str]): Account;


Have new_from_wallet as a single method, or separate, explicit functions (as seen here)?

andreibancioiu · 2024-06-11T09:57:59Z

facades/entrypoints.md

+class NetworkEntrypoint:
+    // The constructor is not captured by the specs; it's up to the implementing library to define it.
+    // For example, it can be parametrized with: a network provider URL and kind (proxy, API)
+    constructor(url: str, kind: Optional[str]);


Is the suggested constructor is all right?

If kind is missing, we'd like to infer the kind of network provider based on its URL.

andreibancioiu · 2024-06-11T09:59:01Z

facades/entrypoints.md

+// Broadcast transaction (option 1):
+transaction_hash = entrypoint.send_transaction(transaction);
+// Broadcast transaction (option 2):
+transaction_hash = entrypoint.get_network_provider().send_transaction(transaction);
+
+// Await transaction completion (option 1, await and specialized outcome parsing):
+parsed_outcome = controller.await_completed_transfer(transaction_hash);
+// Await transaction completion (option 2, simple await):
+transaction_on_network = entrypoint.await_completed_transaction(transaction_hash);


Even if creation (and signing) of transactions is done by controllers, broadcasting isn't (see examples).

All good? Alternative: have send_transaction() in each controller, instead of having it in the entrypoint?

I think it's ok as is - maybe if we add them into controller would open discussions about consistency, eg: "why is send_transaction inside the controller but other network related suff like recall_account_nonce is in the entrypoint?"

Maybe I'm too nitpicky and I keep coming back to old talks that maybe we already concluded, but like in this example, we get the get_transfers_controller only to use it once to create a transaction, then never use it again (cause everywhere else we're using the entrypoint).
I will most probably just do entrypoint.get_transfers_controller().create_transaction_for_transfer() to shorten it for single use only and it wouldn't be the end of the world, but the idea of creating that intermediary object to get to the transaction is nagging me ever so slightly, and this leads me to the second point:

Is that a controller? Since it still looks more like a factory, just different in the way that I take it directly from the entrypoint rather than importing it myself.
Much easier to get and use than the base sdk intricacies, nevertheless.

One thing as food for thought that I keep wondering for a while and asked before but maybe lost its point is whether we need to have separate entities for Address and Account. I would rather use Account everywhere with the particularity that some can have signing abilities (if private key is provided to them), others don't (if it only has a public key available like: Account.new_from_bech32("blabla")).
The reason I'm picking at this is because at chain level they're the same entity, but they're not interchangeable in code and they introduce a debateable unnecessary friction in the fact that I have to import them separately and use them differently based on where they go (if I'm a sender, I need to use the account; if i'm the receiver, I have to use the address). Not much effort involved into this, I know, but still an effort that has to be explained and understood.

Should we stick to entrypoint name?

Fair point. In this last version we've thought of not having functions that create transactions directly on the entrypoint, but in the child controllers, instead. Debatable, though 👍

Indeed, it's a controller. The more lower-level factory does not returned signed transactions (the controller signs the transactions). The controller is also able to do a "specialized" await for a transaction's completion - await & properly parse its outcome (the lower level fashion is, now, to await for transaction completion using a transaction awaiter, then use a transaction outcome parser to recover & interpret returned data - e.g. logs).

I'd like to keep Address a different concept, as it is now. Especially because I'm thinking of Brainstorm design of Address #36.

Somehow better than facade.

Understood the point and wasn't aware of those things without seeing the background. For example, entrypoint.await_completed_transaction leave the impression that the await is done here, while the signing is invisible, so the only thing the dev sees is the factory/builder element :)
Maybe we complicate the names too much with the patterns, don't know.

Noted 👍

Additional note: entrypoint.await_completed_transaction does a generic (non-specific) await for transaction completion. The controllers, instead, are more specialized (more informed) in this regard e.g. controller.await_completed_execute() parses the contract outcome (return data) and returns a specific data structure, not a mere TransactionOnNetwork. Another example, for the tokens controller: controller.await_completed_issue_fungible, which not only waits for transaction completion, but also returns data such as the identifier of the newly registered token etc.

oh God. I completely missed this. I think this is reopening up @ccorcoveanu's comment above for debate on consistency. Let's talk in a meet.

andreibancioiu · 2024-06-12T11:44:59Z

facades/entrypoints.md

+    get_account_management__controller(): AccountManagementController;
+```
+
+## Examples


How do you feel about the examples?

All good from my pov 👍

ovidiuolteanu · 2024-06-19T13:04:45Z

facades/entrypoints.md

+// Broadcast transaction (option 1):
+transaction_hash = entrypoint.send_transaction(transaction);
+// Broadcast transaction (option 2):
+transaction_hash = entrypoint.get_network_provider().send_transaction(transaction);
+
+// Await transaction completion (option 1, await and specialized outcome parsing):
+parsed_outcome = controller.await_completed_transfer(transaction_hash);
+// Await transaction completion (option 2, simple await):
+transaction_on_network = entrypoint.await_completed_transaction(transaction_hash);


Maybe I'm too nitpicky and I keep coming back to old talks that maybe we already concluded, but like in this example, we get the get_transfers_controller only to use it once to create a transaction, then never use it again (cause everywhere else we're using the entrypoint).
I will most probably just do entrypoint.get_transfers_controller().create_transaction_for_transfer() to shorten it for single use only and it wouldn't be the end of the world, but the idea of creating that intermediary object to get to the transaction is nagging me ever so slightly, and this leads me to the second point:

Is that a controller? Since it still looks more like a factory, just different in the way that I take it directly from the entrypoint rather than importing it myself.
Much easier to get and use than the base sdk intricacies, nevertheless.

One thing as food for thought that I keep wondering for a while and asked before but maybe lost its point is whether we need to have separate entities for Address and Account. I would rather use Account everywhere with the particularity that some can have signing abilities (if private key is provided to them), others don't (if it only has a public key available like: Account.new_from_bech32("blabla")).
The reason I'm picking at this is because at chain level they're the same entity, but they're not interchangeable in code and they introduce a debateable unnecessary friction in the fact that I have to import them separately and use them differently based on where they go (if I'm a sender, I need to use the account; if i'm the receiver, I have to use the address). Not much effort involved into this, I know, but still an effort that has to be explained and understood.

Should we stick to entrypoint name?

ovidiuolteanu · 2024-06-19T13:11:26Z

facades/entrypoints.md

+```
+entrypoint = MainnetEntrypoint();
+abi = Abi.load("adder.abi.json");
+controller = entrypoint.create_smart_contract_controller(abi);


I believe this is what was bugging me:
create_smart_contract_controller
get_transfers_controller

They have the same purpose in the end but it's not directly intuitive which should be which and we got to this situation in which we actually ended up with both: one with get, another with create.
Even though I am aware that this may happened by mistake because of it being a controller/factory/whatever in the lower layer, this kinda proves my point that I may look for any of those because of this pattern.
And makes me wish that I just could've just done entrypoint.smart_contract_controller.get_me_a_call()

Other controllers - e.g. token management controller, delegation controller - do not have the dependency on "ABI" when created. Their lifetime is managed by the entrypoint itself. The entrypoint creates them once (when initialized), then provides their references when requested by client code.

However, the controller for a smart contract is explicitly instantiated - thus the "create" verb. The caller (client code) provides the ABI.

I see now, but only because you explained it.
In honesty, this would annoy me quite badly because of never knowing what do I have to look for intuitively.

The mental effort for this is too much in my opinion if we're forcing the devs to differentiate a generic thing (creation of a tx) based on the way we implemented the controller. Sorry, but I don't see this as simple enough design.

I think it's one of the differences we had in the lower levels as well, e.g. receiver member vs destination. It's an unnecessary complication in my opinion.

Noted 👍

We can have this with get instead of create, as well, and require the ABI when calling create_transaction_for_execute, query etc. - as it was the idea at first.

Yeah... not very nice, I guess... I would rather instantiate the other controllers only when called, similarly to the contract controller, then call all of them create as well... I don't know. I give up.

Adjusted to use create_* for controllers.

andreibancioiu marked this pull request as draft May 30, 2024 13:37

andreibancioiu changed the base branch from main to queries-30 May 30, 2024 13:37

andreibancioiu self-assigned this May 30, 2024

Base automatically changed from queries-30 to main June 4, 2024 13:00

andreibancioiu added 9 commits June 5, 2024 11:03

Updates post-meetings.

bb00867

Contract upgrade.

4f14ae3

Additional notes.

982cd33

Rename, additional functions etc.

7f374e4

Remove todo.

e2a4a5b

Loading accounts etc.

aa706ce

Examples, renaming, additional notes etc.

45fb9f2

Work in progress, pair design with Alex.

662722b

Facades, work in progress. Controllers.

a272767

andreibancioiu changed the title ~~Sketch a simple facade: the main facade~~ Sketch a simple facade: the entrypoint Jun 11, 2024

Split into two files. Questions will be added in the PR on GH.

e584aab

andreibancioiu commented Jun 11, 2024

View reviewed changes

andreibancioiu marked this pull request as ready for review June 11, 2024 09:59

andreibancioiu added 3 commits June 11, 2024 15:25

Update new account.

a20b37c

Fix new account.

b5b78f6

Additional example: issue a fungible token, do a quick airdrop.

58790ab

andreibancioiu commented Jun 12, 2024

View reviewed changes

ovidiuolteanu requested changes Jun 19, 2024

View reviewed changes

andreibancioiu added 2 commits July 15, 2024 13:28

Merge branch 'main' into facades-01

a043ad3

Using create_* for controllers.

b61c1ca

popenta previously approved these changes Jul 16, 2024

View reviewed changes

danielailie previously approved these changes Jul 16, 2024

View reviewed changes

Merge branch 'main' into facades-01

56fb473

andreibancioiu dismissed danielailie’s stale review via 56fb473 July 18, 2024 13:48

andreibancioiu dismissed popenta’s stale review via 56fb473 July 18, 2024 13:48

Rename wrt. network providers.

1def751

danielailie approved these changes Jul 18, 2024

View reviewed changes

popenta approved these changes Jul 18, 2024

View reviewed changes

ccorcoveanu approved these changes Jul 19, 2024

View reviewed changes

ovidiuolteanu approved these changes Jul 25, 2024

View reviewed changes

andreibancioiu merged commit f4c7c95 into main Jul 25, 2024

andreibancioiu deleted the facades-01 branch July 25, 2024 08:13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Sketch a simple facade: the entrypoint #69

Sketch a simple facade: the entrypoint #69

andreibancioiu commented May 30, 2024 •

edited

Loading

andreibancioiu Jun 11, 2024

andreibancioiu Jun 11, 2024

andreibancioiu Jun 11, 2024

ccorcoveanu Jun 11, 2024

ovidiuolteanu Jun 19, 2024

andreibancioiu Jun 19, 2024

ovidiuolteanu Jun 19, 2024

andreibancioiu Jun 19, 2024 •

edited

Loading

ovidiuolteanu Jun 19, 2024 •

edited

Loading

andreibancioiu Jun 12, 2024

ccorcoveanu Jun 19, 2024

ovidiuolteanu Jun 19, 2024

ovidiuolteanu Jun 19, 2024

andreibancioiu Jun 19, 2024 •

edited

Loading

ovidiuolteanu Jun 19, 2024 •

edited

Loading

andreibancioiu Jun 19, 2024 •

edited

Loading

ovidiuolteanu Jun 19, 2024

andreibancioiu Jul 15, 2024

Sketch a simple facade: the entrypoint #69

Sketch a simple facade: the entrypoint #69

Conversation

andreibancioiu commented May 30, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andreibancioiu Jun 19, 2024 • edited Loading

Choose a reason for hiding this comment

ovidiuolteanu Jun 19, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andreibancioiu Jun 19, 2024 • edited Loading

Choose a reason for hiding this comment

ovidiuolteanu Jun 19, 2024 • edited Loading

Choose a reason for hiding this comment

andreibancioiu Jun 19, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andreibancioiu commented May 30, 2024 •

edited

Loading

andreibancioiu Jun 19, 2024 •

edited

Loading

ovidiuolteanu Jun 19, 2024 •

edited

Loading

andreibancioiu Jun 19, 2024 •

edited

Loading

ovidiuolteanu Jun 19, 2024 •

edited

Loading

andreibancioiu Jun 19, 2024 •

edited

Loading