[Protocol technical on-boarding series] NEAR protocol as a user (February 17th, 2023)

Captions as YouTube publishes them, usually machine-generated, so product and people names can be misheard.

1. 0:00

   after we get all of these initial ones completed and then figure out like what would be best moving forward how do we update these how do we add to the library as new topics come up that kind of thing yep indeed they've been amazing so far so let me start screen sharing as uh as we are still waiting for for folks to join I'm going to share my uh um laptop screen and the goal for today the way

2. 0:32

   the way I see this happening is I'm going to use the slides more so now we have the recording on right yes let's start all over hey everyone so um the the way I see the session happening today is I plan to use the slides more like notes and reproduce live most of the things that happen on the slides the slides I'll share them so you can use them as a reference um in case you want to revisit some of these things in the future I have a few Links at the end um

3. 1:04

   in case you want to dive way deeper than we're going to do it today in whichever um parts of of the RPC or or the near CLI you want to do it um and I'm going to use my um actually let's clean it up I'm going to use my my terminal for most of the things that we're going to um see today and we may actually poke around a bit more than than what the slides are are saying as support um as a support

4. 1:30

   I'm using a umuntu VM not my own Mac uh since honestly for the develop for for everything year related I preferred initially to use something off the shelf and then to figure out how I'm going to if needed apply and use it on the arm architecture I played it safe so um let's get started please feel free to stop and ask me anything at any moment uh don't feel shy I do have a slide at the end with questions but it's way more fun to actually stop whenever

5. 2:09

   you have something you want to ask and raise your hand and ask it and uh explore then uh we can store together at that point hey Marcelo so um let's uh let's get started the goal for today is to see how users interact within your network um I made a sketch here an imperfect sketch of how how the the network looks like and we're going to see um which ways we have to actually uh

6. 2:47

   interact with it to um query accounts to um other contract to r a contract uh through various ways overall the blockchain is a peer-to-peer Network it's composed of multiple machines I call them all nodes here some of them are simple machines which stay around and Route messages all the other sessions regarding networking and everything else will dive way deeper into these these roles some of these machines have an active role in um creating the blockchain and in um moving

7. 3:20

   the blockchain forward by adding new blocks to it and those are the Chun of block producers we call them validators but in the interest of space actually I call them notes Here um we have the the special archival notes which are supposed to store an archive of everything that happened in the past when when they work and they usually work uh and in order to query and to benefit from the services that

8. 3:44

   the network offers we need to have um on set of RPC nodes uh these RPC nodes have apis that are easier to to interact with uh from different languages and uh yes y uh sorry kind of quick dumb um I so RPC node is different from nonv validator node is that correct or are they to see uh it's a nonv validator node one that exposes an API um I think you need to have a a dedicated config to run an explicit RPC I don't think that the the RPC API is exposed by default by every node okay

9. 4:27

   so it's a kind of subset of a nonv validator no yes it's a subset of the nonv validator node okay thank you exactly uh and then the user interacts with the RPC nod and um the requests that the user sends are propagated through the the network and the replies are being sent back so um while the presentation is intended to offer the perspective of an user um and I don't expect the user to actually start with the RPC API we are all engineers and um it's more natural to

10. 4:59

    actually build from ground up in terms of how different layers stay on top of each other so let's look first at the RPC um the RPC layer uh I'm assuming you all know what an RPC uh does it's a remote procedure call server you it exposes an API you make calls to that API and you get replies back uh there are a few um different RPC providers that that you can choose from this is a a small subset of what you

11. 5:28

    have in um in mainnet by the way for every uh thing demo today we're going to use testnet uh this list is specifically for for mainnet and and you can pick any uh uh any from of those should respect the same RPC API there's a very very good documentation um regarding everything that the RPC nodes have and you can dive deep into all these things um let's look at I think I have here in the slides uh i'

12. 6:02

    I've copied that table uh to to give you a glimpse of what RPC and then what near CLI since it's build on top of the RPC what what they offer as capability so uh let's start with accounts you can manage accounts create delete uh update accounts um deploy contracts into accounts uh you can query the network regarding different uh capabil capabilities that network has which is what was the current block what's was the current chunk and so on um you can look at Guest

13. 6:32

    prices or different protocol configurations uh you can send transactions and quer the status um and you can manage access Keys which is a pretty important part in order to be able to use those accounts in different ways um so let let's try to do a very very simple example this is uh a python script which um I think I I can actually open it from here uh this is a python script this is the most important part of it it it sends a

14. 7:09

    request a post request to RPC that includes uh a method which it's query uh include some arguments in our case is the request type it's the view account that that we have with an account ID which is created uh it's it's um said as being blueprint testet which is the the account we're going to use through through the session today uh and let's see what happens when when we run this oh I did something I forgotten H there we go uh nothing that

15. 7:56

    spectacular but if you look at it here we actually get uh a piece of information that we will see later on in the near CLI uh for example the amount is the amount of near in y near that the account has um this is the hash of the block and the height of the block when the account was created and a few other things that um that are placed here uh again we're going to look at this information from the near CS perspective a b onwards there are other things that

16. 8:25

    we can do here um for example what uh another thing that you're going to see later on is uh playing with a list of keys that are configured in an account and offer access to that account so we can actually list the full list of keys if we're going to execute it again we're going to get the the public um the public part of uh of all the keys that are configured and the type of access that they have in this case it's access key as you can see here for most of

17. 9:06

    them so that's the uh uh um that's the RPC API again in the documentation there's uh a very very detailed um information together with examples of how you can run it and everything so you can quickly put things together in case you want to play with as I said this is the first layer of interaction with the network now let's move on to the juicy part or to the more user friendly part to be honest um near CLI near CLI is built actually on top of um a JavaScript API

18. 9:48

    it's a library it's a library that makes it easier to interact with the RPC so think of it as the client side code which runs into interacts with the RPC and offers um an easy to ouse interface hiding a part of the complexity doing the have lifting inside the Library so that it as an user you don't need to to handle all those complicated uh not complicated but all those cumbers some things that you've seen in my in my pathon script earlier uh this this Library can be used

19. 10:21

    in a browser or in a noj run time you know NOS run time exactly where do your CLI use it and it gives you the same capabilities that we've just seen on the RPC API which is interacting uh with the uh with accounts to do transactions sending tokens to deploy contracts to inspect to create or delete accounts to do all the regular operations um near C build on top of it and it's a

20. 10:52

    fully featured njs command L interface it's way easier to use uh than the python script or obviously than the library uh and we're going to see a few examples and we're going to play with it in the subsequent um in the subsequent slides again is the same type of functionality that's exposed as at this um at this layer as well so let's start first with how you install it now I have

21. 11:16

    it installed on my machine you need first to install npm which is a node package manager nodejs package manager and once you've done that at least in my case it was with um with the dbn package manager uh that I've installed it if I recall correctly if you uninstall it on a Mac I think you can install it with Brew um but if uh let's see I think I've installed it with yep AP get installed um and once you have that

22. 11:50

    installed uh the first thing that's very useful to do is to actually specify the environment you want to use the near C with which is test net Manet or guil net and you can do that by exporting an environment variable uh which I have configured to test net and then you just call near and you have the CLI um fully available if you look at it you're going to see the same um uh uh the same type of functionality

23. 12:25

    that i' I've mentioned with managing keys or calling a contract viewing a certain contract viewing the state of an account um logging in let's let's start actually with logging in um which which command Yun actually um you know what I can do it like this let me do it with anyone with a link can view you can comment and I can share the slides here so you can have access to to all the uh all the commands

24. 13:18

    here um this is a summary of the um let it the most relevant commands for an end user there are others as well for more proficient Advanced users but what you usually have is um managing the keys as I said managing accounts um managing contracts deploying doing a Dev deploy call view view State doing transactions seeing information around the network validators for example and proposals to see which are

25. 13:50

    the notes that want to become a validator in the next dep and RL which is an interactive node js environment you can use that as well if you want I'm assuming that's for more um more advanced users so the first thing is when you want to use near CLI is to actually attach it as as an application to an account which you have which which an account that exists uh in the network what I did uh in terms of the order in

26. 14:22

    which I did things I went on um I I created an account in testnet U using the testnet wall and after that I logged into the account using the near CLI how you do it is like this you you let me copy paste it you write in your login and what happens behind the scene is the following locally if you don't have any public private key pair of the near CLI instance you're running on your machine you're going to have one created for you

27. 15:13

    and at that point once you have one you need to attach that the that key to your account the way you do it if you're running on the same machine you get a popup window with a browser that takes you um to testnet wallet since I'm running on a different machine this is via SSH doesn't work for me so what I'm going to do I'm going to just copy this link by the way look at the link what what it says it says like this uh it opens uh testnet

28. 15:45

    and it adds a referral which is near CLI it adds as an as a parameter the public key of uh the Keir that we're going to use and is the one here and then uh it wants to add that to to the account and if it succeeds then it it tries to redirect to um a local IP which won't work since again this is via SSH so I'm doing I'm copy pasting that link manually now this is the the page from wallet where I am into I'm logged via wallet

29. 16:26

    into my account and I'm adding access for the near CLI that will be able to use my account and this is by the way you can pay attention here this is full access we're going to talk about it a bit later it offers um basically full control over the account so always be careful when you're doing it if it's a test net it's likely less impactful if it's main net you need to be really careful when and to whom to

30. 16:51

    who you're offering a full access so um you can see here the full list of things that the app is allowed to do in the app by the way it's the the near C that I have on my machine it asks me my name again my they account name again to to make sure that um I really intend to do this and now everything went well unfortunately due to the setup I don't see a very fancy P page at the end um but let

31. 17:27

    me right the same here and now I'm logged in successfully which means the near C on this machine has full control over the account and can can act in the name of the account uh completely so we we now have connected the CLI with uh uh with the account yes Yun so um after I successfully log in if I uh do the near login again then I think it generates a new public key and just let me do this same thing all over is it

32. 18:06

    yes is it expected yes it overwrites the key I see the key is here um let me see uh let me show you uh no it's a hidden folder the SE it's in in your CR the keys in your credentials and I'm going to put this higher since I have a window here saying that I'm screen sharing um if you look oh it's in test net uh this is this is the key so what we can do the easiest thing that that we can do is to actually um rate the state of a of a certain

33. 18:57

    account so so let's do that this is the reply that we're getting and if you recall it's the same type of information we got back from the RPC which is the amount of tokens that the account has which is in yton here and this is formatted in a more human readable uh way the the hash of the block where the account was created and the block hide a few very high level information around the block what we can do on top of it now if you want to have uh

34. 19:29

    um view of what happens behind the scene is to add minus V from verbus and we're going to see the the end point that was used uh as an RPC and then other contextual parameters regarding the network that we're having which is wallet and helper the um the network name the one that we configured uh through the environment variable um and the account ID that that we're using you can add minus V to every uh um

35. 19:58

    every query it will give you a bit more information and that's what we have on on this slide as well uh now another thing we can do with the keys is to list the keys that we have for a certain account uh we've done that uh we we've done that in um through the RPC let's do it here the output is a bit more pretty pretty to read so this is the the full list of keys that was added uh for the account blueprint uh test net let's see the the key that I

36. 20:41

    have uh here uh near credentials test n blueprint Jason so this is this is my local key the the public one uh ands with rui as you can see which is exactly this one rui and now the private one is the private one uh and by the way since you're going to see that it's it's different from the slides I think I I have somewhere in the slides the same um uh step where we look at the key and it has a different value I've just overwritten it when I executed login again it if there is a file with

37. 21:26

    the same name it just over WR it so be careful when when you do that um I mentioned about the key types as you can see here all all keys that I have in this account are full access keys from various moments when I played with a with the CLI and they offer as I mentioned oops sorry they they offer full control over net over the account they can do anything um an alternative to it is and

38. 21:57

    actually we use that more frequently when we are deploying and executing smart contracts is a function call Key which allows only a limited number of operations to to be executed on behalf of the account uh and those reside to non-p payable methods so you can't uh change token balance with the function call Keys um so this is this is the the basic um uh uh the basic way we're going to uh work with is I I have a few slides later on when we're going to add a new key and we're going to see how how that happens

39. 22:41

    um until then let's see how we're going to how we can run a contract how we can deploy a run a contract through the near CLI so if you look in the documentation um you can see there is a pre-existing contract that you can play around with with uh which is this one the guest book testet and we can add a message in that uh in that guest book uh hello from near I demo or session I'm using my account my blueprint testet account and I'm making a call to the contract that stays

40. 23:28

    into the guest book account and from that contract I'm calling the add message method now um as you've seen in the in the session uh regarding contracts that Anthony had you can only add one contract per account and the name of the contract becomes the name of the account so in this case if you think about it naturally when you make a call you want to specify the contract you're calling and then the method from the contract and the contract you're calling is exactly the name of the account that

41. 24:00

    deployed that deployed a contract so that's why we have account names here as well and in the end you have the account ID that makes the call which is the account ID we just logged in earlier so um you you get the uh uh uh the transaction uh that captures the call so we can have a quick look at it so signed by blueprint uh called uh guest book you can see the block hash and the arguments that we sent hello from the nearest CLI session and

42. 24:42

    the few other data how much gas consum and and and everything so let's see if it worked let's see if we were able to add our string in the guest book there are two ways in which you can call a contract uh the the actual call method uh allows you to do read write operations and the view method allows you to do only view operations so let's see what are the messages we're going to make a call to get

43. 25:16

    messages um so Near View name of contract uh get messages as you can see the uh the accountant makes a call is not always required especially for view when the view calls are read only are basically free from the perspective of the network so you don't need to have um an account ID there and as you can see the the last um M the last entry in uh in that contract was coming from us

44. 25:48

    hello from the nearest life session oh and we can see the one from mun he also said hello from the near C thank you for doing this in parallel y it's fun the what does the last parameter do if I it's still working like if I don't do that and this is the set of arguments now the argument sent to the method which if the method doesn't expect any arguments can you can omit it uh you can it depends on how you want you can either place it like this which is empty no arguments or you can emit it and you

45. 26:32

    get the same thing you can see here an example this is the uh a text field and then the string that we sent to the contract so let's see how we deploy contract now in order to deploy one we need to have one uh so I have locally an an example of a contract um I think I've stripped it down significantly only to the better uh the better part of it uh let's open it in VI and contract example and we use the hello

46. 27:22

    here H here there's a lot of boiler plate that you need before you can actually have a contract um but in this boiler plate this is the actual code of the contract that gets executed which in our case is simply blog is like the most simple hello world you can have it's logging a message um saving greetings from the demo set s let's compile it with npm and it's going to take it's going to take the code and it's going to compile it to wasm

47. 28:31

    and after that we're going to take the wasm file and we can actually deploy it into our into our account so basically what happens here is if you look at the code it simply uh setting the greeting logs a text it's like the most simple hello world you can have and this is how we're deploying it which is uh deploy and then actually let let me type the command first yeah um let's look at arguments and then we're going to see the message which is is is not rocket science so uh

48. 29:19

    the account ID where we want to deploy the contract into uh and then the wasm file that contains the contract which is be deployed uh now there is already a contract uh deployed there which I deployed earlier on so it asks us if we want to override yes we do we want to override and then an an error occurred um let's see what happens no such file or directory oh because I am in the wrong folder yes

49. 29:57

    you so um does this mean that let's say if there's any anyone who's depending on our smart contract like by overwriting this that all of those can be broken essentially right and um we do not we I guess this is the best thing or the most thing we provide to prevent that like RMS like there some like warning message or is there anything else we do I don't think there's anything else that we do I

50. 30:29

    see so you need to be really careful the era I had earlier was due to the fact that uh the path to uh to the wasm file was was wrong um I was I was in another folder than I was directory than I was expecting so uh when I provided that the correct uh path it actually U asking the same thing hey you want to override yes I want to override to start deployment um if use the RPC test net node uh this is the transaction you can look at it there uh

51. 31:06

    and we can actually make a call to that method at the beginning and as you can see we have the log line here now I did send some arguments because the the hello world example I had there expected some arguments uh but those are ignored for now and we just log uh a plain text the same text every single time uh what I did here I did a call on the again the contract name is the same as the account name

52. 31:58

    uh the method is set reading which is the method you can see here and the method just logs uh and the account that makes the call which is blueprint tet let's see what else we can do oh we can um we can have a a a quick overview around uh the the nodes in the network the the validator nodes and the nodes that uh will are proposed join in the next Epoch got a very nice uh human readable

53. 32:52

    set of of data regarding the state that each node has and you can do this for minut as well by the way everything that we're doing now in testet works is the same for minut uh the percentage online this is this information you can find it in Explorer as well it's not specific to to uh to the near CLI but you can get it in the CLI if you want to the blocks expected to produce chunks

54. 33:17

    expected to produce and so on yes Yun sorry for keep asking questions um it's fun session is it to happen is there a way to find that available method from the CLI from the uh given smart contract you can look at a smart contract let's see uh view State view um h I don't know that let's take that offline or anybody in uh in the Forum knows if there's a way you can list all the methods of a certain contract okay I'll take it as now so

55. 34:15

    what what is um what the uh the CLI offers is deploy Dev deploy by the way Dev deploy um just skips the um authentication part it's easier if you want just to uh if you have a a development account and you don't you don't bother about the keys and and um you want to quickly deploy something to test you can use Dev deploy call in view call is uh you can invoke change your view methods you can just invoke view method here so this is like a read write call this is a um readon call and view

56. 34:47

    State Returns the the contract State let's see what view state says for us I tried that and ask me to put some like block block height ID and prefix H let's see I haven't played with it yet so view State minus minus finality I'll take it offline I have no idea what this is and um if I'm able to do some video editing I'll I may add a popup somewhere in in one of the corners uh with a link that explains what this is so that for

57. 35:56

    our future viewers can actually uh have the uh the answer so let's move to to managing Keys which is so far what what we've seen in terms of managing Keys is uh we have a a local key it's the one from your credentials that that you've seen me um listing so far near near credentials to get a subfolder for each environment I've only used it for I've only used it for test on this machine and uh this is where you get the keys that that you

58. 36:36

    have uh blueprint again contains the public and the private key uh that are the private and public key of the client of the of the nearest CLI that I have locally here uh and I can configure that on multiple accounts if I want to um So What What In order to create a key uh there's the the option near generate key that will create an implicit account which means the name of the account that the key will use is going to be the hash of the public uh of the public part it's

59. 37:17

    less human readable if you want to play with it fine that it's it's exactly uh the key that you see here that you get but I find it a bit more interesting uh or a more useful to to use the named account so let's try to do this let's try to generate a key which is um since r with blue blue horse you generated the key the public private key here key pair so if you look here you're going to find the same structure and now let's see how we can

60. 38:06

    add this to our account uh via the CLI so what we're going to do we're going to do exactly like this uh add key to the account and then the public part of the key I have a different public part I'm not going to copy the one from the slide so add key to the blueprint test net with the public one is this one adding full access key and now that key exists in our account so when when we're going to list the account uh the account

61. 38:53

    um well I forgot which one was it w pz wpz it was added as full access key into the blueprint testnet account now the way we added it by the way if if you be careful so we used the the the blueprint key we used this one in order to gain full access control and to add the blue horse one and now we can use the blue horse one as well if you want so what we've done now it's it's basically the same thing that happened in the browser initially when we logged in and where we if you if you

62. 39:37

    recall going back a bit at the slide with the near login we had this very very nice URL which was exactly the public part of the key here so it was basically the same operation that that happened but in a different way uh we can delete a key if you want so let's try to delete one um let's try to delete the one that we just added with the blue horse I think the easiest way to compose

63. 40:20

    is like this Lo delete near delete key and then let's put the private part of it if I recall was wpz it's this one let's copy it uh account ID obviously from where do we want to delete it is deleting the key so let's see if if it's still it's still there NOP it was deleted so that's how you remove a key any questions uh I have a question so what does it mean to add the blue hores key to blueprints

64. 41:16

    account well we we just did that earlier so when we added the key it was exactly this command uh no I mean like what I mean like what does it mean to for the blueprint to have this key does it mean it can access bluehorse accounts stuff or does it mean something else it means that the the key which was let me list file so the key that was listed in this file had access to the blueprint account I see I I can take the key from

65. 41:50

    here move it to a different machine and that machine will have access okay got it so it was just adding a new key there and the key um and as long as I have the the public part of the key the file can exist anywhere so I don't it's less relevant yes Yun so it sounds like based on what you're describing it's like um creating a separate password for a same account right it doesn't it is not like we're creating a whole new new account called

66. 42:23

    Blue Horse exactly the blue course is the name of the file sure uh ideally the name of the file should be the same one with the name of the account so you can quickly use them but you can the name is is less relevant by default near CLI looks for a file in this folder which uses the same name as is the account let's let's see that so if I do this uh blueprint test net contains the key

67. 43:03

    uh the the key that that I have configured for the account so if I'm going to move it to like this now blueprint. test.js no longer exists let's see if I can add the key this is the operation that we've done earlier and it's going to throw an error saying key not found it expected a key to use to authenticate to blueprint test net it expected that key to specifically be in the file uh blueprint test net Json you

68. 43:43

    didn't find it it thrown it has thrown an error is it a bit more clear now hope it is so um let's move in back so so when you're when you're deleting uh deleting a key right the Blu horse key did it actually delete the file as well no the file state it deleted the key from the account sure sure sure the blockchain so it removed the public part of the key from the account sure okay so so the file still exist and now it is up to the

69. 44:20

    the caller to decide like whether they want to just keep the file or completely deleted okay exactly so when when you generate a key you basically generate a generic public private key now what you do with it is separate from how you configure it into the account then it's up to you to to manage it and to to keep it safe this is for for those of you that use SSH this is a very similar system to the way SSH works and SSH Keys work you have locally a key that gives you access from the local

70. 44:54

    machine to a server if you have the proper SSH configuration so it's very much similar to that okay any other questions this kind of sums up what what I had intended in mind for for today so anything else that you would like to to talk about I think I can I that that was maybe maybe we just didn't find a way to do it but it was pretty surprising to me like there is no easy way for a user to find out like what are the available method

71. 45:40

    or what are the arguments that I need to pass to call a given smart contract um um I don't know yeah that we need we need to to check that maybe we can ask Anthony how you can list the the methods that a certain contract exposes I guess you need access to the contract to say it but um that's that's a good thing to to explore or maybe we can ask Chad gbt by the way regarding that uh I left

72. 46:18

    it here in the slides fun stuff let me zoom in a bit I was very positively surprised um so I've asked chat GPT to actually give me a simple Python program no uh a simple program that interacts with the near RPC API and it gave me the code that I use in the slides I was surprised that uh it actually worked I with zero things changed apart from the uh account name and with very good explanations underneath which helps you understand

73. 46:55

    the code and even more surprising if you look at this what is near C you can summarizing text has been there for a while and not that surprised but write a hello world smart contract for the new protocol and to get this which is exactly the um uh the JavaScript the the core part of the JavaScript doesn't have the boiler plate you can't easily compile it let's say you can't take that and compile it in in in less than a second however it's there

74. 47:27

    and it also tells you what are the the the CLI commands that you can use to deploy it and then how to call it so I'm surprised positively uh I was not expecting things to progress that fast with AI uh in case you want to dive deeper uh these are the links uh the documentation that I had open here that that you can use and for the hello world smart contract I use a tutorial that you can

75. 47:58

    see here uh basically in less than five minutes you can have that that smart contract um create it with a boiler plate and everything and you can compile it and from there you can just start building on top so if you want to redo what I did just follow the steps from here okay so any other questions before we close it if not thank you everyone for joining have a nice weekend and look forward to to chatting with you again time to ask

76. 48:37

    DPT how I can earn one billion year token y that that's a good that's a good question uh you