{"action":"created","issue":{"url":"https://api.github.com/repos/eris-ltd/decerver/issues/95","labels_url":"https://api.github.com/repos/eris-ltd/decerver/issues/95/labels{/name}","comments_url":"https://api.github.com/repos/eris-ltd/decerver/issues/95/comments","events_url":"https://api.github.com/repos/eris-ltd/decerver/issues/95/events","html_url":"https://github.com/eris-ltd/decerver/issues/95","id":55392231,"number":95,"title":"Proper ate-contract interaction","user":{"login":"androlo","id":2809499,"avatar_url":"https://avatars.githubusercontent.com/u/2809499?v=3","gravatar_id":"","url":"https://api.github.com/users/androlo","html_url":"https://github.com/androlo","followers_url":"https://api.github.com/users/androlo/followers","following_url":"https://api.github.com/users/androlo/following{/other_user}","gists_url":"https://api.github.com/users/androlo/gists{/gist_id}","starred_url":"https://api.github.com/users/androlo/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/androlo/subscriptions","organizations_url":"https://api.github.com/users/androlo/orgs","repos_url":"https://api.github.com/users/androlo/repos","events_url":"https://api.github.com/users/androlo/events{/privacy}","received_events_url":"https://api.github.com/users/androlo/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/eris-ltd/decerver/labels/design","name":"design","color":"c7def8"}],"state":"open","locked":false,"assignee":{"login":"androlo","id":2809499,"avatar_url":"https://avatars.githubusercontent.com/u/2809499?v=3","gravatar_id":"","url":"https://api.github.com/users/androlo","html_url":"https://github.com/androlo","followers_url":"https://api.github.com/users/androlo/followers","following_url":"https://api.github.com/users/androlo/following{/other_user}","gists_url":"https://api.github.com/users/androlo/gists{/gist_id}","starred_url":"https://api.github.com/users/androlo/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/androlo/subscriptions","organizations_url":"https://api.github.com/users/androlo/orgs","repos_url":"https://api.github.com/users/androlo/repos","events_url":"https://api.github.com/users/androlo/events{/privacy}","received_events_url":"https://api.github.com/users/androlo/received_events","type":"User","site_admin":false},"milestone":null,"comments":6,"created_at":"2015-01-25T01:59:10Z","updated_at":"2015-01-25T11:53:22Z","closed_at":null,"body":"I've been talking about this for a while, and worked on it. Ate-to-UI has just taken a huge leap forward when we added the RESTful API, and with some updates to websockets that will also be a lot more clear. I would even dare to call it production ready after these changes has been properly worked in, which will not be after the video dapp, but probably after the next few dapps we write. Ate-to-contracts interaction, however, is not good. These are some of the issues:\r\n\r\n1) The \"system\" I/we use for calling contracts from Ate has not been standardized. \r\n\r\n2) The \"system\" I/we use for doing automated tests of contracts from Ate has not been standardized.\r\n\r\n3) The \"system\" we use to frame smart contract back-ends has not been standardized. C3D has not been implemented in ate, nor any other system that's similar.\r\n\r\n4) Contract code documentation has not been standardized.\r\n\r\nSolutions are coming. The changes I'm working on now are significant. I've been working on a document about systems of contracts. It involves C3D and some other things. It is still not done, and will not be done in some time, but it will be a good source of information about how to write systems of contract in general (pointing out different types of contracts and their usage). It will also be useful for ethereum contract writers since it does not really depend on anything external. \r\n\r\nThere will also be another document which will use that document but treat these type of things, like json specs, testing, documenting etc. It'll be the stuff in the first document applied in the Eris system, you could say. This issue will be the basis for that document.\r\n\r\n**Contracts, EPM and Ate**\r\n\r\nI don't like the fact that DApp devs are forced to work with two systems - both ate and epm. That is a source of confusion, even for me. Instead, when epm is wrapped by the decerver, it will be possible to do it all from ate. Same interface for everything (js), and the same system for everything. EPM is a stand-alone library anyways, so using Ate as a front does not mean it can't be used by people who want more low-level control.\r\n\r\nAlso, I don't like that we include LLL contracts in tutorial examples. This also needs to change, and it should happen soon. We're working on it. For example, Ethan has started adding support for and otherwise enabling the use of other languages in his LLLC compiler, and there has been changes to EPM and Thelonious as well.\r\n\r\nWhen it comes to languages, Serpent will likely be a placeholder for some time, but it looks like Solidity will be the best alternative for dapp makers in the long run. It's worked on by several, seemingly competent people, it's coming along nicely, it's clean, it's got very nice features, it's similar to js (which we use in other parts of the stack), and other things. This together with the heavy backing from Ethereum means it will likely become the lingua franca for contract developers, so we might as well jump on board imo.\r\n\r\n*One language to rule them all, one language as placeholder, one language to drag out into the backyard, and in the darkness shoot it, bury it, and forget about it.*\r\n\r\n**Contract specifications**\r\n\r\nAte will support a standardized model for contracts. The specs are written in JSON, and will look something like this:\r\n\r\n``` javascript\r\nContract\r\n{\r\n\t\"name\" : String,\r\n\t\"constants\" : {\r\n\t\t\"const1\" : String,\r\n\t\t\"const2\" : String,\r\n\t\t...\r\n\t},\r\n\t\"functions\" : {\r\n\t\t\"func1\" : Function,\r\n\t\t\"func2\" : Function,\r\n\t\t...\r\n\t}\r\n}\r\n\r\nFunction\r\n{\r\n\t\"id\" : Number,\r\n\t\"params\" : [Variable],\r\n\t\"returns\" : [Variable]\r\n}\r\n\r\nVariable \r\n{\r\n\t\"name\" : String,\r\n\t\"type\" : Type,\r\n\t\"size\" : Number\r\n}\r\n```\r\n\r\nAn example would be the hello world tutorial contract \"test.lll\", which would look something like this:\r\n\r\n``` javascript\r\nHello world:\r\n{\r\n\t\"name\" : helloworld,\r\n\t\"variables\" : { \"deadbeef\" : \"0x10\" },\r\n\t\"functions\" : {\r\n\t\t\"register\" : {\r\n\t\t\t\"id\" : 0,\r\n\t\t\t\"params\" : [{\"name\" : username, \"type\" : String, \"size\", 32}] \r\n\t\t}\r\n\t}\r\n}\r\n```\r\n\r\nYou should probably be able to specify dependencies as well, and ate should be able to write the contract in full, based on these dependencies. I have already made a system for this. Basically it writes the properties of the dependencies from the dependency to the contract, but need to make it a bit more sophisticated to handle diamonds of death etc.\r\n\r\nWhen it comes to 'type' - types here refer to data written into contract storage. There will be built-in types, but there will also be possible to specify custom types. Interaction with contracts, such as calls, reads, and automated tests can makes use of them to get a form of type-safety. A good example of when a type is needed is arrays and linked lists. When you write an array or linked list into storage, they are just a bunch of detached entries. It does not say anywhere in storage that \"the following few addresses are part of a linked list\". Ate, however, can use the contract spec to figure out that it is reading from an array or linked list, or in fact any other possible data structure, and also in the case of collections - what the elements are.\r\n\r\nOk so that's fine, but what about contract reading from contracts. Wouldn't they need to know? Yes, but data structures has been introduced to most languages at this point, so such things would be resolved during compile time. If your contract has a 'getElement' function, it would just return the elements as a data structure. The system I'm talking about here is for the reading of contract storage by ate. Technically it could call that 'getElement' function in the contract and get it that way (at least after some vm improvements?), but it would not just require waiting for a tx, which is annoying, but also a series of gas-guzzling in-contract storage reads where none are needed.\r\n\r\nThis sounds like an ate thing, but it really is not. These specs could be used by other systems as well, since they're just json files. They should also be done in collaboration between contract writers/platform makers, so that we get a good standard that everyone is happy with. I hope for examples that epm can use those contract specs as well, if they would be needed for something. Maybe even other platforms can make use of them.\r\n\r\nFinally, note that these specs aren't like the project douglas action models. They don't contain any actual logic. They're just a description of what functions and pre-set variable slots that the contract uses. Action models would be built on top of these. There will be more on action models later.\r\n\r\n**Testing contracts**\r\n\r\nFirst of all - when we're talking about tests, we're always talking about testing against the database. Some clients lets you get the value that the vm returns as a result of executing the contract code, which can be useful, but not all clients allow that. Writing results to storage is a safe way of doing things, and every client out there supports it. If some functionality of a contract does not produce an entry in some database by default, then we can complement it with an additional test contract.\r\n\r\n**'A simple test example**\r\n\r\nThis is a simple test of a contract which is designed to be called by other contracts, and does not make use of its own storage. Not gonna get into the details of what is written where.\r\n\r\nThe contract takes a 32 byte hex string and checks how many unique bytes it has (maybe for some compression stuff or whatever). The string \"aabb\" would return 3 (null counts too). The string \"acdbba\" would return 5. We call that contract 'dupcheck'.\r\n\r\nWe add a test contract that we call 'dupcheck_test'. It will have three functions. The first one is passing values into its storage-writing routine to make sure it actually works. The second is to call 'dupcheck' N times with predefined values and check that the values that come back are the ones we expect. It will write the results to its storage, so that they can be read. The third function is just to set the address of the 'dupcheck' contract.\r\n\r\nWe will then add a javascript test file. It will do the following things:\r\n\r\n1) Deploy the 'dupcheck' and 'dupcheck_test' contracts on a temporary test chain and commit. \r\n\r\n2) Make sure that both of the contracts exist on the chain after this. That can be done by adding identifiers in their storage as part of the init code.\r\n\r\n3) Set the address of 'dupcheck' in the 'dupcheck_test' contract, and commit.\r\n\r\n4) Make sure the address is properly set (check the storage).\r\n\r\n5) Transact to 'dupcheck_test' in order to call its test functions. commit.\r\n\r\n6) Check the results by reading the storage addresses of the test contract.\r\n\r\n7) Present the test results, for example by printing.\r\n\r\nNote that we would make use of the spec at points 2, 3, 4, 5 and 6. In 2 we will use the id field, which could be named \"id\" in the spec. In 3 we make use of the function that sets the dupcheck address. In 4 check the \"dupcheck_address\" field. In 5 we make use of the test function, and in 6 we check the test results variables.\r\n\r\nThis is a trivial example. A more sophisticated test could be working with several target contracts. Some could be calling other test contracts and act as the entry point of a full-on test suite.\r\n\r\n**Documentation of contracts**\r\n\r\nI have been working with something called 'natural docs' to produce documentation for contracts before, which i think is one candidate. It is fairly simple, cross platform (though you need perl support), and lets you write your documentation any way you like inside the code. Just make a spec and it will extract the comments and turn it into html docs, with indexing, searching - everything. You can even create a script to auto generate documentation based on function sigs and other things. \r\n\r\nAn example of this can be found here, in my old (abandoned) LLL-commons library:  https://github.com/androlo/LLL-commons. You can download and view the documentation at doc/lll/index.html, and check that it matches the documentation in the files.\r\n\r\n**Finally**\r\n\r\nThis should be tied in with the action models and c3d documentation. It will be done in some later document that covers it all."},"comment":{"url":"https://api.github.com/repos/eris-ltd/decerver/issues/comments/71368760","html_url":"https://github.com/eris-ltd/decerver/issues/95#issuecomment-71368760","issue_url":"https://api.github.com/repos/eris-ltd/decerver/issues/95","id":71368760,"user":{"login":"androlo","id":2809499,"avatar_url":"https://avatars.githubusercontent.com/u/2809499?v=3","gravatar_id":"","url":"https://api.github.com/users/androlo","html_url":"https://github.com/androlo","followers_url":"https://api.github.com/users/androlo/followers","following_url":"https://api.github.com/users/androlo/following{/other_user}","gists_url":"https://api.github.com/users/androlo/gists{/gist_id}","starred_url":"https://api.github.com/users/androlo/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/androlo/subscriptions","organizations_url":"https://api.github.com/users/androlo/orgs","repos_url":"https://api.github.com/users/androlo/repos","events_url":"https://api.github.com/users/androlo/events{/privacy}","received_events_url":"https://api.github.com/users/androlo/received_events","type":"User","site_admin":false},"created_at":"2015-01-25T11:53:22Z","updated_at":"2015-01-25T11:53:22Z","body":"I don't think Ate should provide command line access to epm. That would make little sense imo. It should do two things:\r\n\r\n1 - use it to create, remove, and switch between chains.\r\n\r\n2 - leverage its multi-client support to interact with different blockchains, rather then using one module for each like we do now. Just load the chain you want into epm and have at it. :D"}}