Skip to content

Commit dc7bce1

Browse files
Add description and explanation for device-proxy program. (#201)
* Adds placeholder for device-proxy program explanation. * Improves programs concepts page.
1 parent d3a24ff commit dc7bce1

File tree

1 file changed

+22
-14
lines changed

1 file changed

+22
-14
lines changed

content/concepts/programs.md

Lines changed: 22 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,49 @@
11
---
22
title: "Programs"
3-
lead: "The purpose of an Entropy program is to determine whether a group of nodes should generate a signature or not. Developers can create and deploy programs, but validator nodes are the only agents that will directly interact with the programs once deployed. Programs do not return any data other than a success or failed response."
3+
lead: "The purpose of an Entropy program is to determine whether a group of nodes should generate a signature or not. Developers can create and deploy programs, but validator nodes are the only agents that will directly interact with the programs once deployed. Programs do not return any data other than a _success_ or _failed_ response."
44
---
55

6-
## Features and details
6+
## Features and Details
77

8-
More concretely, they are WebAssembly components that implement an Entropy-specific interface. The only function a user must manually implement is `evaluate`, which takes the user's signature request as input and returns it as successful or an error. If no error is returned, then the message in the signature request will be signed using the program's corresponding key pair with the specified hashing algorithm.
8+
In more concrete terms, Entropy programs are WebAssembly components that implement an Entropy-specific interface. The only function that a user must manually implement is `evaluate`, which takes the user's signature request as input and returns a success or an error. If no error is returned, then the message in the signature request will be signed using the program's corresponding key pair with the specified hashing algorithm.
99

1010
### Custom Hashing
1111

1212
As ECDSA schemes sign 256-bit numbers, programs can include a `custom_hash` function so users can utilize less common hashing functions. In its simplest form, the function converts a signature request (which also contains the message) into a 256-bit number.
1313

14-
An example of a custom hash implementation is available in the [entropyxyz/programs repository](https://github.com/entropyxyz/programs/tree/master/examples/custom-hash).
14+
An example of a custom hash implementation is available in the [entropyxyz/programs repository](https://github.com/entropyxyz/programs/).
1515

16-
The list of natively supported hashing algorithms can be found within the [entropyxyz/entropy-core repository](https://github.com/entropyxyz/entropy-core/blob/master/crates/shared/src/types.rs#L101).
16+
The list of natively supported hashing algorithms can be found within the [entropyxyz/entropy-core](https://github.com/entropyxyz/entropy-core/blob/master/crates/shared/src/types.rs#L101) repository.
1717

1818
### Program Configs
1919

2020
Programs can include a configuration, which allows users to modify the `evaluation` behavior without having to recompile and upload a new program to the chain. The format of this is undefined, allowing a configuration to be defined as a serialized C-compatible struct, UTF-8 JSON string, or anything in between.
2121

22-
An example of a program that uses a config can be found within the [entropyxyz/programs repository](https://github.com/entropyxyz/programs/blob/master/examples/basic-transaction/src/lib.rs#L18). In this example; the user specifies an allow-list of Ethereum recipients using a JSON string config.
22+
An example of a program that uses a config can be found within the entropyxyz/programs repository. In this example, the user specifies an allow-list of Ethereum recipients using a JSON string config.
2323

2424
### Auxiliary Data
2525

26-
Programs can require users to include auxiliary data, separate from the message, in their signature request. An example of a program that requires a zero-knowledge proof as auxiliary data can be found within the [entropyxyz/programs repository](https://github.com/entropyxyz/programs/blob/master/examples/risczero-zkvm-verification/src/lib.rs#L24).
26+
Programs can require users to include auxiliary data, separate from the message, in their signature request. An example of a program that requires a zero-knowledge proof as auxiliary data can be found within the entropyxyz/programs repository.
2727

2828
## Upload Programs
2929

3030
Programs are written and compiled to WASM using the [entropyxyz/programs repository](https://github.com/entropyxyz/programs).
3131

3232
The workflow is as follows:
3333

34-
1. A program owner calls `set_program` in the program pallet with
34+
1. A program owner calls `set_program` in the program pallet with:
3535
- the program bytecode
36-
- the configuration interface which is a seralized json object that allows a user to know the configuration of the program then set their own indiviudualized configuration in programsData
37-
- The signing key signs the tx and becomes the deployer key
38-
- A ref counter gets set to 0 when uploading and is used to track how many users are using a program
39-
1. A program then gets stored in the Programs storage slot with the key being `H(bytecode + configuration_interface)`. The hash is used by a user to point to the programs they want applied to their key, everytime a program is referenced the ref counter increments
40-
1. Since the key is a hash there is no editing programs (since that would change the hash)
41-
1. Programs can be removed if the ref count is zero by the deploy key
36+
- the configuration interface, which is a serialized JSON object that allows a user to know the configuration of the program and then set their own individualized configuration in programsData
37+
- The signing key signs the transaction and becomes the deployer key
38+
- A reference counter gets set to 0 when uploading and is used to track how many users are using a program
39+
2. A program then gets stored in the Programs storage slot with the key being `H(bytecode + configuration_interface)`. The hash is used by a user to point to the programs they want applied to their key. Every time a program is referenced, the reference counter increments
40+
3. Since the key is a hash, there is no editing programs (since that would change the hash)
41+
4. Programs can be removed if the ref count is zero by the deploy key
42+
43+
## Device-proxy
44+
45+
The device-proxy program is an Entropy program available at `0000000000000000000000000000000000000000000000000000000000000000`. It's main functionality is to:
46+
47+
1. Verify signatures based on the provided configuration and auxiliary data.
48+
1. Check if a given public key is in the allowed set of keys (from the provided config).
49+
1. Verify the generated signature against the provided message.

0 commit comments

Comments
 (0)