-
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #76 from kryptokrauts/docs/mkdocs
Docs/mkdocs
- Loading branch information
Showing
11 changed files
with
289 additions
and
12 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
| # Contract interaction | ||
|
|
||
| ## Local node example | ||
| The generated Java classes hide all the operations needed to interact with smart contracts on the aeternity blockchain. The only thing you need to do is create an instance of the generated class and provide an ***AeternityServiceConfiguration*** within the constructor of the generated class. | ||
|
|
||
| Without this configuration we wouldn't know to which compiler and to which node we should perform the necessary requests. | ||
|
|
||
| In this example we use the CryptoHamster sample from the [contræcts app](https://studio.aepps.com/) which we want to execute on our local æternity node | ||
| ```java | ||
| KeyPairService keyPairService = new KeyPairServiceFactory().getService(); | ||
| KeyPair keyPair = keyPairService.recoverKeyPair(<privateKey>); | ||
|
|
||
| AeternityServiceConfiguration config = AeternityServiceConfiguration | ||
| .configure() | ||
| .baseUrl("http://localhost") | ||
| .compilerBaseUrl("http://localhost:3080") | ||
| .mdwBaseUrl("http://localhost:4000") | ||
| .network(Network.DEVNET) | ||
| .keyPair(keyPair) | ||
| .compile(); | ||
|
|
||
| // get an instance of the generated contract object | ||
| CryptoHamster cryptoHamsterInstance = new CryptoHamster(config, null); | ||
|
|
||
| // deploy the contract on the local node | ||
| Pair<String, String> deployment = cryptoHamsterInstance.deploy(); | ||
| String txHash = deployment.getValue0(); | ||
| String contractId = deployment.getValue1(); | ||
| log.info("Deployed contract id - {} ", contractId ); | ||
|
|
||
| // call a function of the contract | ||
| log.info("Call create hamster {}", cryptoHamsterInstance.createHamster("kryptokrauts")); | ||
| log.info("Call nameExists {}", cryptoHamsterInstance.nameExists("kryptokrauts")); | ||
| log.info("Call getHamsterDNA {}", cryptoHamsterInstance.getHamsterDNA("kryptokrauts")); | ||
| ``` | ||
|
|
||
| ## Further examples | ||
|
|
||
| The [contræct-showcase-maven](https://github.com/kryptokrauts/contraect-showcase-maven) repository showcases how to use the contræct-maven-plugin to easily interact with smart contracts in Java. One of the examples is a MultiSig contract to be used with the Generalized Accounts feature. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,17 +1,66 @@ | ||
| # Getting started | ||
|
|
||
| ## Requirements | ||
| The **contræct-maven-plugin** is a maven plugin that simplifies interacting with smart contracts on the aeternity blockchain. It generates Java classes out of the sophia contract sourcecode which provide a convenient to deploy a contract on the chain or call a function. | ||
|
|
||
| ## Include dependency | ||
| It also wraps the input and output objects of those function calls - no parsing is necessary. | ||
|
|
||
| ### Release | ||
| ## Detail description | ||
|
|
||
| #### Maven | ||
| The plugin takes a contract written in sophia language as input and generates a Java class representing the contract and its methods. The following statements apply due to the code generation: | ||
|
|
||
| #### Gradle | ||
| - creates a method to deploy the contract on the chain | ||
| - create method for every entrypoint to call entrypoints of a deployed contract | ||
| - methods will be executed using dryRun - which means it will not be committed and thus included in a block | ||
| - if a method is stateful - transaction additionally will be committed and thus included in a block. The method waits until the transaction is confirmed | ||
| - if a method is payable - an additional parameter is available to set the amount to deposit | ||
| - all input parameters are parsed to a typed Java classes (if possible), | ||
| also the result is parsed to a Java type (if possible) | ||
| - in case of errors during dryRun call or committing the transaction, exceptions are raised with details from the node | ||
| - initialization of an instance can be done using an existing contractId, thus the methods of an already deployed contract can be called | ||
|
|
||
| ### Snapshot | ||
| ### Gas estimation | ||
| Whenever stateful entrypoints are called using the generated classes, at first a dryRun is done. Therefore a fixed gas limit (default: 50000) is passed as parameter, which should be sufficient for almost all contract calls. After performing the dryRun the exact gas used is returned and the corresponding contractCallModel is updated. The following sample shows the relevant part of the Java class generated by the plugin: | ||
| ```java | ||
| contractCallModel = contractCallModel.toBuilder() | ||
| .gasLimit(dryRunResult.getContractCallObject() | ||
| .getGasUsed()).build(); | ||
| ``` | ||
|
|
||
| #### Maven | ||
| ## System requirements | ||
|
|
||
| #### Gradle | ||
| - System requirements of the [Java SDK](https://kryptokrauts.github.io/aepp-sdk-java/v3.0.0/index.html#system-requirements) | ||
|
|
||
|
|
||
| ## Include dependencies | ||
|
|
||
| ### contraect-maven-plugin | ||
|
|
||
| To add the contræct-maven-plugin to you build, simply add the following snippet to your *pom.xml* | ||
|
|
||
| ```xml | ||
| <build> | ||
| <plugins> | ||
| <plugin> | ||
| <groupId>com.kryptokrauts</groupId> | ||
| <artifactId>contraect-maven-plugin</artifactId> | ||
| <version>2.0.0</version> | ||
| <configuration> | ||
| ... | ||
| </configuration> | ||
| </plugin> | ||
| </plugins> | ||
| </build> | ||
| ``` | ||
| The content of the `<configuration>` section is covered in the Plugin configuration | ||
|
|
||
| ### aepp-sdk-java | ||
|
|
||
| Under the hood the plugin as well as the generated classes make use of the aepp-sdk-java to implement the interaction with the aeternity node. Therefore the dependency needs to be declared in the corresponding section - please make sure to always use the latest version of the SDK. | ||
|
|
||
| ```xml | ||
| <dependency> | ||
| <groupId>com.kryptokrauts</groupId> | ||
| <artifactId>aepp-sdk-java</artifactId> | ||
| <version>3.0.0</version | ||
| </dependency> | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,12 @@ | ||
| # Roadmap | ||
|
|
||
| The following improvements and enhancements are planned for the next release. | ||
|
|
||
| ### Consolidation with SDK | ||
| The generated classes will make use of the convienence methods performing contract create and contract calls included in the Java SDK. | ||
|
|
||
| ### Sophia Types | ||
| To further consolidate logic with the Java SDK, Sophia Types will be moved to the SDK and reused instead of being generated within every class. This will help keeping the code clean and readable and avoid class clashes and confusion when working with multiple generated contracts in one project. | ||
|
|
||
| ### Enhanced result object | ||
| Currently a contract call returns a pair of transaction hash and typed result. It is planned that every contract call returns a special return object (ContractTxResult) which holds more information about the contract call including the raw node result. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| #Error codes | ||
| During the contract class generation process, on of the following error codes might occur. In every case, a detailed message is displayed. | ||
|
|
||
| If you face such an error, you're welcome to help improving the contraect-maven-plugin. Therefore, please create an issue on [contraect-maven-plugin](https://github.com/kryptokrauts/contraect-maven-plugin) along with your contract code and the arguments displayed in the error message. | ||
|
|
||
| #### 005 - FAIL_IMPORT_INCLUDES | ||
| Indicates an error concering a library or contract include | ||
| #### 010 - FAIL_CREATE_ABI | ||
| Indicates an error concering parsing the contract code to abi/json representation | ||
| #### 020 - FAIL_PARSE_ROOT | ||
| Indicates an error concering parsing the contract's json tree | ||
| #### 030 - FAIL_GENERATE_CONTRACT | ||
| Indicates a general error creating the Java class out of the contract | ||
| #### 100 - FAIL_READ_CONTRACT_FILE | ||
| Indicates an error reading the contract file | ||
| #### 200 - UNFORSEEN_MAPPING | ||
| Indicates an unforseen or unimplemented case of type mapping | ||
| #### 300 - UNFORSEEN_CUSTOM_TYPEDEF | ||
| Indicates, that custom type definition cannot be parsed |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,70 @@ | ||
| # Plugin configuration | ||
|
|
||
| ## Parameters | ||
| Most of the configuration parameters are shipped with default values, which in almost all cases don't need to be explicitly set. The following list gives an overview over the configurable parameters of the plugin. | ||
|
|
||
| ### Example | ||
| This is an example for the minimal required configuration that only provides the required parameters: | ||
| ```xml | ||
| <plugin> | ||
| <groupId>com.kryptokrauts</groupId> | ||
| <artifactId>contraect-maven-plugin</artifactId> | ||
| <version>2.0.0</version> | ||
| <configuration> | ||
| <codegen> | ||
| <compilerBaseUrl>https://compiler.aepps.com</compilerBaseUrl> | ||
| <directories> | ||
| <directory>${project.basedir}/src/main/resources</directory> | ||
| </directories> | ||
| </codegen> | ||
| </configuration> | ||
| <executions> | ||
| <execution> | ||
| <goals> | ||
| <goal>generate-contraects</goal> | ||
| </goals> | ||
| </execution> | ||
| </executions> | ||
| </plugin> | ||
| ``` | ||
|
|
||
| ### Codegen configuration block | ||
| The `<codegen>` configuration block contains the general parameters for the plugin. | ||
|
|
||
| | Parameter | Description | Default | Sample | | ||
| | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------- | | ||
| | initFunctionName | Name of the deploy init function to call right after deploy | `init` | | | ||
| | targetPackage | Java package of the generated contraect classes | `com.kryptokrauts.contraect.generated` | | | ||
| | datatypePackage | Java package of the generated datatypes | `com.kryptokrauts.contraect.generated.datatypes` | | | ||
| | targetPath | Generated Java classes will be stored in this folder | `target/generated-sources/contraect` | | | ||
| | compilerBaseUrl (*) | The base url of the sophia compiler | `https://compiler.aeternity.io` | `http://localhost:3000` | | ||
| | numTrials | Number of trials (with 1 sec delay) to wait for transaction to be mined (relevant for stateful calls and the deploy method) | `60` | | | ||
| | directories (*) | List of directories to be scanned for contract files | | `<directory>${project.basedir}/src/main/resources\<directory>` | | ||
| | contractSuffix | File suffix identifying a contract code file | `aes` | | | ||
| | resultAbortKey | indicates the abort case of a function call, also applies for dryRun call | `abort` | | | ||
| | resultErrorKeyindicates the error case of a function call, also applies for dryRun call | error | | | | ||
| | resultRevertKey | indicates an revert of a contract deploy | `revert` | | | ||
| | dryRunDeployGas | gas limit for the contract deploy method | 50000 | | ||
|
|
||
| ### ABI-JSON configuration block | ||
| The `<abi-json>` configuration block defines the json key names which are used to parse the contract code. The listed elements are used to parse the contracts JSON ABI and further transform this into the resulting contract java class. Typically this part of the configuration can be completely ommitted unless the basic layout of the sophia contract ABI does not change. | ||
|
|
||
| | Parameter | Description | Default | | ||
| | ---------------------------- | ------------------------------------------------ | --------- | | ||
| | rootElement | key for contract root | contract | | ||
| | eventElement | key for events | events | | ||
| | functionsElement | key for contract functions | functions | | ||
| | contractNameElement | key for contract name element | name | | ||
| | payableElement | key for contract payable flag | payable | | ||
| | stateElement | key for contracts state definition | state | | ||
| | customTypeElement | key for contracts custom types | type_defs | | ||
| | functionNameElement | key for a custom functions name | name | | ||
| | functionReturnTypeElement | key for a custom functions return type | returns | | ||
| | functionArgumentsElement | key for a custom functions arguments | arguments | | ||
| | functionArgumentTypeElement | key for a custom functions argument type | type | | ||
| | functionArgumentNameElement | key for a custom functions argument name | name | | ||
| | functionStatefulElement | key for a custom function flagging stateful type | stateful | | ||
| | customTypeNameElement | key for a custom types name | name | | ||
| | customTypeTypedefElement | key for a custom types typedefinition list | typedef | | ||
| | customTypeTypedefNameElement | key for one custom types typedefintion name | name | | ||
| | customTypeTypedefTypeElement | key for one custom types typedefinition type | type | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,56 @@ | ||
| # Plugin execution | ||
| ## Generate Java classes | ||
| The following mvn command can be used to explicitly generate the Java classes based on given contracts: | ||
| ```sh | ||
| mvn contraect:generate-contraects | ||
| ``` | ||
|
|
||
| After the plugin execution you should find the generated Java classes in the folder you specified through the configuration property targetPath. | ||
|
|
||
| Alternatively the default maven lifecycle phase generate-sources can be called - therefore the plugin configuration has to be as follows: | ||
| ```xml | ||
| <plugin> | ||
| <groupId>com.kryptokrauts</groupId> | ||
| <artifactId>contraect-maven-plugin</artifactId> | ||
| <version>2.0.0</version> | ||
| ... | ||
| <executions> | ||
| <execution> | ||
| <goals> | ||
| <goal>generate-contraects</goal> | ||
| </goals> | ||
| </execution> | ||
| </executions> | ||
| </plugin> | ||
| ``` | ||
|
|
||
| ## Add generated Java classes as sources | ||
| ### Option 1 | ||
| Add the folder containing the generated Java classes manually as source-folder within your IDE. | ||
|
|
||
| ### Option 2 | ||
| Generate classes directly into the regular source folder by defining `src/main/java` as `targetPath`. | ||
|
|
||
| **Note**: with this solution you will probably end up having the generated files committed to the repo. | ||
| ### Option 3 | ||
| Add the resources using the [build-helper-maven-plugin](https://www.mojohaus.org/build-helper-maven-plugin/index.html) | ||
| ```xml | ||
| <plugin> | ||
| <groupId>org.codehaus.mojo</groupId> | ||
| <artifactId>build-helper-maven-plugin</artifactId> | ||
| <version>3.0.0</version> | ||
| <executions> | ||
| <execution> | ||
| <phase>generate-sources</phase> | ||
| <goals> | ||
| <goal>add-source</goal> | ||
| </goals> | ||
| <configuration> | ||
| <sources> | ||
| <source>${project.build.directory}/generated-sources/contraect</source> | ||
| </sources> | ||
| </configuration> | ||
| </execution> | ||
| </executions> | ||
| </plugin> | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.