mleku/warp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: internal writes

Browse Source
This commit is contained in:
asiaziola
2022-05-25 15:49:18 +02:00
parent 383c99b5be
commit 058eab7dce
4 changed files with 46 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
README-LEGACY.md
View File

@@ -10,7 +10,6 @@ and modularity (e.g. ability to use different types of caches, imported from ext
We're already using the new SDK on production, both in our webapp and nodes.
However, if you'd like to use it in production as well, please contact us on [discord](https://discord.com/invite/PVxBZKFr46) to ensure a smooth transition and get help with testing.
The base motivation behind rewriting the original SDK (and roadmap proposal) has been described [here](./docs/ROAD_MAP.md).
To further improve contract state evaluation time, one can additionally use AWS CloudFront based Arweave cache described [here](https://github.com/redstone-finance/redstone-smartweave-contracts/blob/main/docs/CACHE.md).
- [Architecture](#architecture)
@@ -24,8 +23,6 @@ To further improve contract state evaluation time, one can additionally use AWS
- [Performance - best practices](#performance---best-practices)
- [Examples](#examples)
- [Migration guide](#migration-guide)
- [Documentation](#documentation)
- [Missing features](#missing-features)
## Architecture
RedStone SmartContracts SDK consists of main 3 layers:
@@ -186,6 +183,11 @@ contract = smartweave.contract(contractTxId).setEvaluationOptions({
useVM2: true
});
```
### Internal writes
SmartWeave protocol currently natively does not support writes between contract - contracts can only read each others' state. This lack of interoperability is a big limitation for real-life applications - especially if you want to implement features like staking/vesting, disputes - or even a standard approve/transferFrom flow from ERC-20 tokens.
We proposed a new solution
### Performance - best practices
In order to get the best performance on production environment (or while performing benchmarks ;-)), please follow these simple rules:
1. Do NOT use the `TsLoggerFactory` - it is good for development, as it formats the logs nicely, but might slow down the state evaluation

52
README.md
View File

@@ -2,8 +2,7 @@
> ⚠️ Following library has been renamed from **redstone-smartweave** to **warp** from version **1.0.0**! If you are using older version please read [README-LEGACY](README-LEGACY.md).
Warp SDK is the new, written from scratch, implementation of
the SmartWeave [Protocol](./docs/SMARTWEAVE_PROTOCOL.md).
Warp SDK is the implementation of the SmartWeave [Protocol](./docs/SMARTWEAVE_PROTOCOL.md).
It works in both web and Node.js environment (requires Node.js 16.5+).
@@ -13,7 +12,6 @@ and modularity (e.g. ability to use different types of caches, imported from ext
We're already using the new SDK on production, both in our webapp and nodes.
However, if you'd like to use it in production as well, please contact us on [discord](https://discord.com/invite/PVxBZKFr46) to ensure a smooth transition and get help with testing.
The base motivation behind rewriting the original SDK (and roadmap proposal) has been described [here](./docs/ROAD_MAP.md).
To further improve contract state evaluation time, one can additionally use AWS CloudFront based Arweave cache described [here](https://github.com/redstone-finance/warp/blob/main/docs/CACHE.md).
- [Architecture](#architecture)
@@ -25,6 +23,7 @@ To further improve contract state evaluation time, one can additionally use AWS
- [Using the Warp Gateway](#using-the-warp-gateway)
- [WASM](#wasm)
- [VM2](#vm2)
- [Internal writes](#internal-writes)
- [Performance - best practices](#performance---best-practices)
- [Examples](#examples)
- [Migration guide](#migration-guide)
@@ -215,6 +214,43 @@ contract = warp.contract(contractTxId).setEvaluationOptions({
});
```
### Internal writes
SmartWeave protocol currently natively does not support writes between contract - contracts can only read each others' state. This lack of interoperability is a big limitation for real-life applications - especially if you want to implement features like staking/vesting, disputes - or even a standard approve/transferFrom flow from ERC-20 tokens.
SmartWeave protocol has been extended in Warp by adding internal writes feature.
A new method has been added to SmartWeave global object. It allows to perform writes on other contracts.
1. The method first evaluates the target (ie. specified by the contractTxId given in the first parameter) contract's state up to the "current" block height (ie. block height of the interaction that is calling the write method) and then applies the input (specified as the secon parameter of the write method). The result is memoized in cache.
```
await SmartWeave.contracts.write(contractTxId, { function: 'add' });
```
2. For each newly created interaction with given contract - a dry run is performed and the call report of the dry-run is analysed. A list of all inner-calls between contracts is generated. For each generated inner call - an additional tag is generated: {'interactWrite': contractTxId}- where contractTxId is the callee contract.
3. When state is evaluated for the given contract ("Contract A") all the interactions - `direct` and `internalWrites`. If it is an `internalWrite` interaction - contract specified in the `internalWrite` ("Contract B") tag is loaded and its state is evaluate. This will cause the `write` method (described in p.1) to be called. After evaluating the "Contract B" contract state - the latest state of the "Contract A" is loaded from cache (it has been updated by the write method) and evaluation moves to next interaction.
In order for internal calls to work you need to set `evaluationOptions` to `true`:
```
const callingContract = smartweave
.contract<ExampleContractState>(calleeTxId)
.setEvaluationOptions({
internalWrites: true
})
.connect(wallet);
```
You can also perform internal read to the contract (originally introduced by the protocol):
```
await SmartWeave.contracts.readContractState(action.input.contractId);
```
You can view some more examples in the [internal writes test directory](https://github.com/redstone-finance/redstone-smartcontracts/tree/main/src/__tests__/integration/internal-writes). If you would like to read whole specification and motivation which stands behind introducing internal writes feature, please read [following issue](https://github.com/redstone-finance/redstone-smartcontracts/issues/37).
### Performance - best practices
In order to get the best performance on production environment (or while performing benchmarks ;-)), please follow these simple rules:
@@ -260,13 +296,3 @@ We've also created an [academy](https://redstone.academy/) that introduces to th
If you're already using Arweave smartweave.js SDK and would like to smoothly migrate to RedStone SmartContracts SDK -
check out the [migration guide](https://github.com/redstone-finance/warp/blob/main/docs/MIGRATION_GUIDE.md).
### Documentation
TSDocs can be found [here](https://smartweave.docs.redstone.finance/).
### Missing features
Some features from the original Arweave's smartweave.js are not yet implemented. They will be either added soon to the core SDK, or as separate libraries, built on top of the SDK:
- CLI (though not sure if that is a necessary - even if, it should be probably a separate lib built on top of the base SDK).

4
docs/MIGRATION_GUIDE.md
View File

@@ -1,6 +1,6 @@
# Migration Guide from Arweave's SmartWeave SDK to Warp SDK
This guide describes <strong>the simplest</strong> way to switch to the new version of SmartWeave. It uses `WebNodeFactory` for Node and `WarpWebFactory` for Web to quickly obtain fully configured, mem-cacheable SmartWeave instance. To see a more detailed explanation of all the core modules visit the [Warp documentation](https://smartweave.docs.redstone.finance/) or check out the [source code.](https://github.com/redstone-finance/warp)
This guide describes <strong>the simplest</strong> way to switch to the new version of SmartWeave. It uses `WebNodeFactory` for Node and `WarpWebFactory` for Web to quickly obtain fully configured, mem-cacheable SmartWeave instance. To see a more detailed explanation of all the core modules check out the [source code.](https://github.com/redstone-finance/warp)
### You can watch this tutorial on YouTube 🎬
- [Youtube link](https://www.youtube.com/watch?v=fNjUV7mHFqw)
@@ -135,7 +135,7 @@ Instead of updaitng all logger options you can simply set the new minimum logger
LoggerFactory.INST.logLevel("info");
```
Available log levels are listed [here.](https://github.com/redstone-finance/redstone-smartweave/blob/main/src/logging/RedStoneLogger.ts#L1)
Available log levels are listed [here.](https://github.com/redstone-finance/warp/blob/main/src/logging/RedStoneLogger.ts#L1)
## 3. Test everything 🔥

55
docs/ROAD_MAP.md
View File

@@ -1,55 +0,0 @@
# RedStone Warp SDK
### The issues with original smartweave.js SDK
* low performance (unnecessary calls to Arweave http api, no easy option to add caching layer, etc.)
* no clearly defined base protocol
* implementation that is really hard (if not impossible...) to unit test
* no tests, very prone to errors (eg. recent issue with input tags format)
* many c/p in the code (like the recent "evolve" feature)
* any change in the base function (i.e. adding cache) basically requires to make a c/p of the base function
and add required changes (eg. Kyve's own version of readContract/interactRead functions)
- this of course makes it really to maintain and keep the code up to date with base implementation
* sometimes a bit "chaotic" implementation (i.e. not sticking to one naming convention, multiple optional function arguments, etc.)
### The "RedStone SmartContracts" approach
1. Clearly defined core protocol layers/interfaces/tags.
2. OOP implementation
3. Each of the base protocol interface can be easily and independently tested
4. The "core" layer should be kept at a bare minimum - to reduce the risk of mistakes in core protocol implementation.
5. All additional features (like "evolve" feature or caching or "dry-runs") should build on top of the core layer ("plugins")
6. Option to easily substitute different implementations of the core layers (ie. with or without caching, different ExecutorFactories, etc.)
7. proper use of types in Typescript
8. strongly typed state and handler's api (i.e. generics)
### Roadmap
#### Phase 1 - in progress
1. Base protocol definition and implementation of the core/protocol layers - done
2. Description of the core building blocks (in the source code) - done
3. Example caching capabilities implementation - done
4. Example "evolve" implementation - done (my concerns re. this feature described in Evolve.ts and in [this analysis](EVOLVE_analysis.md)))
5. Example usage with one of RedStone's contracts - done
6. new readContract and interactWrite implementations - done
7. release as a separate npm library - done
8. updating the SmartWeaveGlobal definition (with updated readContract version) - done
9. Adding ability to call "interactRead" from the contract's source code. - done
10. Kyve cache implementation (probably with collaboration with Kyve team) - done
11. Verifying output results for X currently "most popular" (with most interactions?) contracts - done for all contracts
12. regression tests - done
13. integration tests - done
14. documentation, migration guide, usage examples for node and web env., tutorial - done
15. unit tests for all the core layers and plugins/caches - in progress
#### Phase 2 - TODO
1. Contract's execution environment isolation
2. Generating a stack trace from all the contract interactions
#### Phase 3 - TODO
1. Contract's source code versioning (using standard semantic versioning) - sth. similar to "pragma solidity ^0.8.2;"
2. Alternation ExecutorFactory implementations - the one that would allow create handlers for contract's written
in a more OOP approach (so instead one "big" handle function, contract can define its interface and class-based implementation);
#### Phase 4 - TODO
Thing on top of the SDK eg:
1. Custom Gateway, optimized for interactions with SmartWeave contracts
2. Custom Viewblock-like contracts explorer