From 6e3f7a3c50e73f55afcd0012447518fb53220cdb Mon Sep 17 00:00:00 2001 From: Andrianto Lie Date: Wed, 3 Jan 2018 14:35:17 +0800 Subject: [PATCH] Delete CONTRACT_DEVELOPER_API.md EDOCS-25 --- CONTRACT_DEVELOPER_API.md | 125 -------------------------------------- 1 file changed, 125 deletions(-) delete mode 100644 CONTRACT_DEVELOPER_API.md diff --git a/CONTRACT_DEVELOPER_API.md b/CONTRACT_DEVELOPER_API.md deleted file mode 100644 index 8dd71c353..000000000 --- a/CONTRACT_DEVELOPER_API.md +++ /dev/null @@ -1,125 +0,0 @@ -Contract Developer API -------------------------------------------- - -This document will provide the information developers need to write smart contracts in Web Assembly (WASM). It documents all of -the APIs exposed to WebAssembly by the blockchain environment and explains how to write message handlers. - -## Background -All accounts have immutable names and can send messages to other accounts. Every message has the following fields: - -``` -struct message - sender account_name - recipient account_name - notify account_name[] - type type_name - data bytes -``` - -Every message has a `type` which can be viewed like a function name and `data` which could be viewed as arguments. Every account -defines its own message handlers which operate within their own scope with their own private data. The following methods are -called if they are defined within each `account scope`: - - -``` -foreach($account in sender, recipient and notify) { - $account: void onValidate_$type_$recipient() - $account: void onPrecondition_$type_$recipient() - $account: void onApply_$type_$recipient() -} -``` - -### Contract Exports - -The WebAssembly can export these methods with something like the following WAST (Web Assembly Text): - -``` -(module - (export "onValidate_Transfer_simplecoin" (func $onApply_Transfer_simplecoin)) - (export "onPrecondition_Transfer_simplecoin" (func $onApply_Transfer_simplecoin)) - (export "onApply_Transfer_simplecoin" (func $onApply_Transfer_simplecoin)) - (func $onValidate_Transfer_simplecoin) - (func $onPrecondition_Transfer_simplecoin) - (func $onApply_Transfer_simplecoin) -) -``` - -### Contract Imports -A contract can access the blockchain API through methods provided by the virtual machine. - -These are defined by declaring Web Assembly imports: - -``` -(module - (import "env" "assert" (func $assert (param i32 i32))) - (import "env" "load" (func $load (param i32 i32 i32 i32) (result i32))) - (import "env" "memcpy" (func $memcpy (param i32 i32 i32) (result i32))) - (import "env" "readMessage" (func $readMessage (param i32 i32) (result i32))) - (import "env" "remove" (func $remove (param i32 i32) (result i32))) - (import "env" "store" (func $store (param i32 i32 i32 i32))) - ... -) -``` - -All of the available imports are defined in a C header with documentation for developers such as yourself. -We will discuss these APIs later, but first lets discuss the different message handling functions. - -### Message Handler Functions - -#### Validate -This function has the form `void onValidate_$type_$recipient()` where the type and recipient are derived from the -message `type` and `recipient` field. - -The purpose of this method is to verify the internal validity of the message data. This is an operation that -can be performed in parallel and its success or failure cached because it cannot read nor write to the database. Generally -speaking this is where your most computationally intensive calculations should be performed. - -For example, if you need to perform expensive cryptographic operations such as hashing or signature verification then they -should be performed here and result in a success or failure. It is not possible to generate any other output from this method. - -If Validate fails then Preconditon and Apply will be skipped and the transaction will not be propagated nor included in a block. - -When validate is called all Database APIs are disabled and will fail. - -This step is skipped when replaying irreversibly confirmed blockchain transactions. - -#### Precondition -This function has the form `void onPrecondition_$type_$recipient()` where the type and recipient are derived from the -message `type` and `recipient` field. - -The purpose of this method is to perform validation checks that depend upon read-only access to the application state. Like -Validate, precondition checks can only result in a success or failure and may not store or modify state. - -When Precondition is called all Database APIs that would modify state will fail. - -#### Apply -This function has the form `void onApply_$type_$recipient()` where the type and recipient are derived from the -message `type` and `recipient` field. - -This method should contiain the minimal code necessary to effect the desired state transition. It can call all database -APIs and generate new transactions to send to other accounts. - - -### Example - -Suppose there is a currency contract with account name `currency` and a message type called `transfer`. The `currency` account code would implement the following methods: - -``` -void onValidate_transfer_currency(); -void onPrecondition_transfer_currency(); -void onApply_transfer_currency(); -``` - -Suppose there is also a exchange contract with account name `exchange` that wishes to accept deposits any time someone transfers -currency to `exchange`. It would implement the following: - -``` -void onApply_transfer_currency(); -``` - -In this case `exchange` simply trusts the validation of the `currency` contract and therefore only has to credit the depositor. - -Any time the following message was generated all of the methods above would be called (both for `currency` and `exchange`) and if any fail then the entire transaction is discarded and never included in a block. - - - -- GitLab