Renaming CVX standard functions

[helins]

@rosejn suggested some standard names could be improved in order to be more intuitive. Let's use this issue to track those. They are really easy to change but it is best doing so before hitting beta. Any suggestion welcome and if it helps, please provide a brief explanation.

• deploy -> deploy-actor: reminds that a new account is created, helps understanding actors
• set-key -> set-account-key or set-public-key: could help better understand key pairs ; they can be confusing to some

[rosejn]

I really appreciate that you guys have put in the work here and will make all these kinds of calls so I just want to provide some ideas as I come to Convex with beginners eyes in hopes that it might make things easier for others in the future. Please take it with a grain of salt, and I won't complain. My main thought on variable and function names, is that unlike typical programs where developers are writing and reading their own code, in an internet of value way more people will hopefully be reading (auditing) smart contract code than will ever write it, so readability is quite important. With that in mind I just tried to use common prefixes and longer, more descriptive names so that a user could ideally read a script and understand something like (account-transfer-convex ...) without having to lookup docs.

;; Account Vars
*address*  => *account-address* ; current account
*key*      => *account-key*     ; public key for this account
*balance*  => *account-balance* ; current account balance
*memory*   => *account-memory-allowance* ; current memory allowance, if zero, allocations will be bought on exchange

;; Actor vars
*caller* => *caller* ; account which called this function (e.g. in an actor)
*offer*  => *caller-offer* ; amount offered by a caller, typically zero
*origin* => *txn-origin*  ; account which initially signed this transaction, typically the same
                                       as *caller*, but possibly not if a chain of calls is made

;; Transaction execution vars
; Maybe use txn instead of transaction for the common prefix?
*juice*    => *transaction-juice-remining* ; amount of juice remaining to run this transaction
*sequence* => *transaction-sequence-number* ; txn seq # for this account
*depth*    => *stack-depth* ; CVM execution stack depth

*timestamp* => *current-time* ; the current timestamp (long, ms since epoch)

;; Account functions
(create-account public-key)  => (account-create public-key)
(account #42)                => (account-info #42)
(balance #46)                => (account-balance #46)
(transfer #41 1000000)       => (account-transfer-convex #41 1000)
(transfer-memory #42 100)    => (account-transfer-memory #42 100)
(set-key public-key)         => (account-update-key public-key)
(set-memory 1024)            => (account-update-memory-allowance 1024)
(set-controller public-key)  => (account-set-controller public-key)

;; Actor functions
(deploy '(defn my-fn [a b] (* a b)))                         => (actor-deploy my-fn)
(schedule (+ *timestamp* 1000) (transfer my-friend 1000000)) => (actor-schedule (+ *current-time* (hours 24)) my-fn args)

;; Peer functions
(create-peer account-key stake-amount)                => (peer-create account-key stake-amount)
(set-peer-data peer-key {:url "originrose.com:4242"}) => (peer-set-metadata {:url "originrose.com:4242"})
(set-peer-stake peer-key 100000)                      => (peer-set-stake 1000)
(stake trusted-peer-account-key 100000)               => (stake-trusted-peer account-key 1000)

[helins]

In my own code I tend to use ENTITY-VERB as well. However, VERB-ENTITY is more common, pragmatically speaking.

One thing to keep in mind is that CVX Lisp allows dots in names. So peer.createor peer.set-metadata are valid. i've done that kind of naming in the past when writing CVX Lisp and I always wondered how good (or bad) of an idea it was. The advantage is that it makes a clear distinction between the entity and what happens, a bit more OOP in a (possibly) good way.

[mikera]

I believe - is more idiomatic in Clojure/Lisp as a word separator, and . is better used to indicate some kind of subdivision of a namespace, at least for consistency with Clojure.

Probably / makes sense if we are splitting things into modules e.g. peer/create, however not sure if we should be creating whole namespaces for small subsets of core functions. This is better for libraries that extend on top of the core, I think?

So we end up with names like some.library/create-foo in the general case.