certusone
/
wormhole
mirror of https://github.com/certusone/wormhole.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

algo: Update README.md 

The `TmplSig` part was outdated as of the most recent changes
This commit is contained in:
Csongor Kiss 2022-05-01 14:25:10 +01:00 committed by Evan Gray
parent b937eb2ad7
commit a8dab4f428
1 changed files with 24 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
algorand/README.md
View File

@ -8,13 +8,13 @@ This directory contains the components needed to support full Wormhole functiona
This system is comprised of the following main components:
* **Core contract (`wormhole_core.py`)**: Algorand stateful contract with entrypoints for publishing messages (VAAs), verification of VAA signatures, and triggering of governance chores. This will be referred as _CoreContract_ in this document.
* **Core contract ([`wormhole_core.py`](./wormhole_core.py))**: Algorand stateful contract with entrypoints for publishing messages (VAAs), verification of VAA signatures, and triggering of governance chores. This will be referred as _CoreContract_ in this document.
* **Token bridge contract (`token_bridge.py`)**: Algorand stateful contract supporting cross-chain bridging, exposing entrypoints for exchanging attestations, native tokens and ASAs, and triggering of governance. This will be referred as _TokenBridge_ in this document.
* **Token bridge contract ([`token_bridge.py`](./token_bridge.py))**: Algorand stateful contract supporting cross-chain bridging, exposing entrypoints for exchanging attestations, native tokens and ASAs, and triggering of governance. This will be referred as _TokenBridge_ in this document.
* **VAA verification stateless program (`vaa_verify.py`)**: Stateless program for verifying the signatures of a Wormhole VAA payload against the set of active guardian public keys. This will be referred as _VaaVerify_ in this document.
* **VAA verification stateless program ([`vaa_verify.py`](./vaa_verify.py))**: Stateless program for verifying the signatures of a Wormhole VAA payload against the set of active guardian public keys. This will be referred as _VaaVerify_ in this document.
* **Dynamic storage stateless program (`TmplSig.py`)**: A stateless program that is bound to the main core and token bridge contracts to provide dynamic storage spaces addressable as a raw blob of bytes. See `local_blob.py`. This will be referred as _TmplSig_ in this document.
* **Dynamic storage stateless program ([`TmplSig.py`](./TmplSig.py))**: A stateless program that is bound to the main core and token bridge contracts to provide dynamic storage spaces addressable as a raw blob of bytes. See [`local_blob.py`](./local_blob.py). This will be referred as _TmplSig_ in this document.
Helper utilities and code include support PyTEAL code, deployment tools and tests.
@ -24,31 +24,27 @@ Helper utilities and code include support PyTEAL code, deployment tools and tes
### _TmplSig_ details
--------------------
This stateless program code is parametrized with several values that give different output address. The stateless code will check for several transaction group parameters accordingly.
This stateless program code is parameterized with several values that give different output address. The stateless code will check for several transaction parameters accordingly.
|Text |Replaced by |
|------|------------|
|`TMPL_ADDR_IDX`| Where storage starts interpreting the space as a raw array of bytes |
|`TMPL_EMITTER_ID` | Concatenation of chain Id + emitter Id in VAAs to be processed, or a hardcoded string identifying the type of information stored e.g `guardian` utf8 string stored in hex. |
|`TMPL_SEED_AMT` | The amount that is paid in Gtxn[0] transaction group fee |
|`TMPL_APP_ID` | Application Id of _CoreContract_, _TokenBridge_, etc that is specified in Gtxn[1] for **opt-in** transaction |
|`TMPL_APP_ADDRESS`| Escrow address of the stateful contract specified in `APP_ID`. Used for **rekey transaction** in Gtxn[2]|
| Text | Replaced by |
|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `TMPL_ADDR_IDX` | Where storage starts interpreting the space as a raw array of bytes |
| `TMPL_EMITTER_ID` | Concatenation of chain Id + emitter Id in VAAs to be processed, or a hardcoded string identifying the type of information stored e.g `guardian` utf8 string stored in hex. |
| `TMPL_APP_ID` | Application Id of _CoreContract_, _TokenBridge_, etc that is specified as the **opt-in** target transaction
| `TMPL_APP_ADDRESS` | Escrow address of the stateful contract specified in `APP_ID`. Used for **rekey** target in the transaction
* Local-state associated with the _Tmplsig_ accounts are used as dynamic storage. The technique is to access this local storage as a plain array of bytes instead of the typical key/value structure. With the current Algorand parameters, we have 127 * 15 ~ 2K of storage to be used random-access-like.
* The contract accounts addresses are generated by compilation of a stateless code parametrized by several parameters. In the system, the following contract accounts are generated:
* Account (`seq_addr`) for storing verified sequence number bits based on chainId,emitter,`int(vaa.sequence / MAX_BITS)` where MAX_BITS = 15240. This allows the system to reject duplicated VAAs for the last 2K sequence numbers.
* Local-state associated with the _TmplSig_ accounts are used as dynamic storage. The technique is to access this local storage as a plain array of bytes instead of the typical key/value structure. With the current Algorand parameters, we have 127 * 15 ~ 2K of storage to be used random-access-like.
* The contract accounts addresses are generated by compilation of a stateless code parameterized by several parameters. In the system, the following contract accounts are generated:
* Account (`seq_addr`) for storing verified sequence number bits based on `chainId`,`emitter`,`int(vaa.sequence / MAX_BITS)` where MAX_BITS = 15240. This allows the system to reject duplicated VAAs for the last 2K sequence numbers.
* Account (`guardian_addr` and `new_guardian_addr`) for storing total guardian count , the guardian public keys and guardian set expiration time.
* Once generated, the accounts are opted-in and rekeyed to the core application.
Briefly, this is the transaction group when _TmplSig_ is "attached" to a stateful app:
|Tx#| Semantics |
|-|-|
|0 | Payment Txn of `TMPL_SEED_AMT` ALGOs to fund operation |
|1 | Optin of LogicSig to target stateful contract `TMPL_APP_ID` for the app to use Logicsig account local storage |
|2 | Rekey of LogicSig to escrow address for the smart contract to become the sole "governor" of the Logicsig account address |
Briefly, the semantics of the transaction when _TmplSig_ is "attached" to a stateful app is:
1. Optin of LogicSig to target stateful contract `TMPL_APP_ID` for the app to use LogicSig account local storage
2. Rekey of LogicSig to escrow address for the smart contract to become the sole "governor" of the LogicSig account address
> NOTE: A more detailed overview of _TmplSig_ can be found in [MEMORY.md](./MEMORY.md).
## Core Contract: Functional Description
----------------------------------------
@ -80,11 +76,11 @@ A governance request packed in a VAA must be verified by a `verifyVaa` call in t
The VAA verify call will work by design *only* in a transaction group structured as:
| TX | args | accounts | sender |
| ---------- | ------------------------------------------------------- | ----------------------- | -------------------- |
| verifySigs | [sigs<sub>0..n</sub>, keyset<sub>0..n</sub>, digest] | seq_addr, guardian_addr | vaa_verify_stateless |
| verifySigs | ... | seq_addr, guardian_addr | vaa_verify_stateless
| verifyVAA | vaa | seq_addr, guardian_addr | foundation |
| TX | args | accounts | sender |
|------------|------------------------------------------------------|-------------------------|-----------------------|
| verifySigs | [sigs<sub>0..n</sub>, keyset<sub>0..n</sub>, digest] | seq_addr, guardian_addr | vaa_verify_stateless |
| verifySigs | ... | seq_addr, guardian_addr | vaa_verify_stateless |
| verifyVAA | vaa | seq_addr, guardian_addr | foundation |
Keep in mind that depending on the number of signatures to verify there can be one or several _verifySigs_ calls working in tandem with the _VaaVerify_ stateless program. This depends on how many signatures we can verify on a single TX. At time of this writing, considering the opcode budget limitation of AVM 1.1, a total of nine (9) signatures can be verified at once, so for the current 19 guardians three _verifySigs_ calls would be needed for verifying signatures 0..8, 9..17, 18.
@ -93,6 +89,7 @@ A successful call must:
* Retrieve the guardian keys from the proper local dynamic storage
* Validate if the VAA passed in Argument #1 has enough guardians to be verified
* Check that it's not expired.
* Check that each guardian signed at most once
* Verify that each _verifySigs_ TX is validated by the correct stateless _VerifyVaa_
* Verify that each _verifySigs_ TX is verifying the expected signature subset.
* Verify that each _verifySigs_ TX is verifying against the same guardian keys.