diff --git a/docs/concepts/identity.md b/docs/concepts/identity.md index bf04712..6239ec3 100644 --- a/docs/concepts/identity.md +++ b/docs/concepts/identity.md @@ -13,7 +13,7 @@ A blob transaction on Hylé includes multiple blobs. One of these blobs must con - Identity proofs include a nonce to prevent replay attacks. - The proof verification process ensures the identity was correctly provided. -![Each blob has a proof. Blob0 being a hydentity contract action for « verify password » on the account bob.hydentity is verified by the contract and by the node. Blob1 is an USDC transfer contract. Another graph under this one shows that each blob is proven and that all proofs are verified by the node; they all have bob.hydentity as their output identity. The identity fields are coherent between all blobs and proofs](../assets/img/how-nodes-ensure-identity.jpg) +![Each blob has a proof. Blob0 being a hydentity contract action for « verify password » on the account bob@hydentity is verified by the contract and by the node. Blob1 is an USDC transfer contract. Another graph under this one shows that each blob is proven and that all proofs are verified by the node; they all have bob@hydentity as their output identity. The identity fields are coherent between all blobs and proofs](../assets/img/how-nodes-ensure-identity.jpg) ## Choosing an identity source @@ -40,7 +40,7 @@ A user authenticates using a private password known only to them. - Proof: only those who know the password can generate a valid proof for these blobs. - The proof is valid only for the blobs in this blob transaction. -![In this blob transaction, bob.hydentity's blob0 has verify password as its action. The proof for Blob1 has the password as private input and compares it with the stored hash. Only those who know the password can generate a valid proof of the identity blob. This proof is valid only for the blobs in this blob transaction.](../assets/img/identity-password.jpg) +![In this blob transaction, bob@hydentity's blob0 has verify password as its action. The proof for Blob1 has the password as private input and compares it with the stored hash. Only those who know the password can generate a valid proof of the identity blob. This proof is valid only for the blobs in this blob transaction.](../assets/img/identity-password.jpg) ### Public signature @@ -49,15 +49,15 @@ A user signs a message with their private key to prove identity. - Signature: public input. No private input is required, since only the owner of the private key can generate a valid signature. - Proof: anyone can generate a proof based on the public signature. -![In this graph, the blob transaction has 0xcafe.ecdsa as an identity. The ECDSA contract in blob0 has the action verify signature. The signature is `sign(hash([blob1])`. There is no private input required, anyone can generate a proof but only the owner of the private key can generate a valid signature.)](../assets/img/identity-public-signature.jpg) +![In this graph, the blob transaction has 0xcafe@ecdsa as an identity. The ECDSA contract in blob0 has the action verify signature. The signature is `sign(hash([blob1])`. There is no private input required, anyone can generate a proof but only the owner of the private key can generate a valid signature.)](../assets/img/identity-public-signature.jpg) ### Private OpenID verification This works just like it does with a private password, except it generally can't be done client-side. -The OpenID provider knows your secret key, so it could be able to generate transactions on your behalf. +The OpenID provider knows your secret key, so it could be able to generate transactions on your behalf. -![A blob transaction where identity is bob@gmail.com.oidc. Blob0 is to verify openID with an OIDC contract; the proof for blob0 has the openID as private input and verify its validity. The other blob is an USDC contract to transfer money. ](../assets/img/identity-openid.jpg) +![A blob transaction where identity is bob@gmail.com@oidc. Blob0 is to verify openID with an OIDC contract; the proof for blob0 has the openID as private input and verify its validity. The other blob is an USDC contract to transfer money. ](../assets/img/identity-openid.jpg) ## Custom identity contracts diff --git a/docs/concepts/transaction.md b/docs/concepts/transaction.md index 2f3ad92..061efcb 100644 --- a/docs/concepts/transaction.md +++ b/docs/concepts/transaction.md @@ -44,21 +44,21 @@ Each blob requires a corresponding proof transaction. ```json { - "identity": "bob.hydentity", - "blobs": [ - { - "contract_name": "hydentity", - // Binary data for the operation of hydentity contract - // VerifyIdentity { account: "bob.hydentity", nonce: "2" } - "data": "[...]" - }, - { - "contract_name": "hyllar", - // Binary data for the operation of hyllar contract - // Transfer { recipient: "alice.hydentity", ammount: "20" } - "data": "[...]" - } - ] + "identity": "bob@hydentity", + "blobs": [ + { + "contract_name": "hydentity", + // Binary data for the operation of hydentity contract + // VerifyIdentity { account: "bob@hydentity", nonce: "2" } + "data": "[...]" + }, + { + "contract_name": "hyllar", + // Binary data for the operation of hyllar contract + // Transfer { recipient: "alice@hydentity", ammount: "20" } + "data": "[...]" + } + ] } ``` @@ -68,28 +68,28 @@ Each blob requires a corresponding proof transaction. ```json { - "contract_name": "hydentity", - "proof": "[...]" + "contract_name": "hydentity", + "proof": "[...]" } ``` The binary proof's output includes: -- Initial state: `bob.hydentity` nonce = 1. -- Next state: `bob.hydentity` nonce = 2. +- Initial state: `bob@hydentity` nonce = 1. +- Next state: `bob@hydentity` nonce = 2. - Index: 0 (first blob in the transaction). and ```json { - "contract_name": "hyllar", - "proof": "[...]" + "contract_name": "hyllar", + "proof": "[...]" } ``` The binary proof's output includes: -- Initial state: `bob.hydentity` balance = 100, `alice.hydentity` balance = 0. -- Next state: `bob.hydentity` balance = 80, `alice.hydentity` balance = 20. +- Initial state: `bob@hydentity` balance = 100, `alice@hydentity` balance = 0. +- Next state: `bob@hydentity` balance = 80, `alice@hydentity` balance = 20. - Index: 1 (second blob in the transaction). diff --git a/docs/quickstart/example/custom-identity-contract.md b/docs/quickstart/example/custom-identity-contract.md index 97136fb..4bbf4f1 100644 --- a/docs/quickstart/example/custom-identity-contract.md +++ b/docs/quickstart/example/custom-identity-contract.md @@ -11,10 +11,10 @@ If you’re new to identity management on Hylé, read the [identity management c ## Run the example !!! warning - Our examples work on Hylé v0.12.1. Later versions may introduce breaking changes which have not yet been reflected in our examples. +Our examples work on Hylé v0.12.1. Later versions may introduce breaking changes which have not yet been reflected in our examples. !!! info - Jump to [Code Snippets](#code-snippets) for an in-depth look at the contract. +Jump to [Code Snippets](#code-snippets) for an in-depth look at the contract. ### Prerequisites @@ -38,14 +38,14 @@ The expected output is `📝 Registering new contract simple_identity`. To register an account with a username (`alice`) and password (`abc123`), execute: ```sh -cargo run -- register-identity alice.simple_identity abc123 +cargo run -- register-identity alice@simple_identity abc123 ``` Expected log output: ```bash INFO hyle::data_availability::node_state::verifiers: ✅ Risc0 proof verified. -INFO hyle::data_availability::node_state::verifiers: 🔎 Program outputs: Successfully registered identity for account: alice.simple_identity +INFO hyle::data_availability::node_state::verifiers: 🔎 Program outputs: Successfully registered identity for account: alice@simple_identity ``` ### Verify identity / Login @@ -53,7 +53,7 @@ INFO hyle::data_availability::node_state::verifiers: 🔎 Program outputs: Succe To verify `alice`'s identity: ```bash -cargo run -- verify-identity alice.simple_identity abc123 0 +cargo run -- verify-identity alice@simple_identity abc123 0 ``` This command: @@ -72,7 +72,7 @@ Expected log output: ```bash INFO hyle::data_availability::node_state::verifiers: ✅ Risc0 proof verified. -INFO hyle::data_availability::node_state::verifiers: 🔎 Program outputs: Identity verified for account: alice.simple_identity +INFO hyle::data_availability::node_state::verifiers: 🔎 Program outputs: Identity verified for account: alice@simple_identity ``` ## Development mode diff --git a/docs/quickstart/example/first-token-contract.md b/docs/quickstart/example/first-token-contract.md index aa131e5..b43776b 100644 --- a/docs/quickstart/example/first-token-contract.md +++ b/docs/quickstart/example/first-token-contract.md @@ -9,7 +9,7 @@ If you’re new to smart contracts on Hylé, read the [anatomy of a smart contra ## Example !!! warning - Our examples work on Hylé v0.12.1. Later versions may introduce breaking changes that are not yet reflected in our examples. +Our examples work on Hylé v0.12.1. Later versions may introduce breaking changes that are not yet reflected in our examples. ### Prerequisites @@ -35,7 +35,7 @@ The expected output is `📝 Registering new contract simple_token`. Transfer 2 tokens from the Hylé `faucet` to `Bob`: ```bash -cargo run -- transfer faucet.simple_token bob.simple_token 2 +cargo run -- transfer faucet@simple_token bob@simple_token 2 ``` This command: @@ -56,7 +56,7 @@ Expected log output: ```bash INFO hyle::data_availability::node_state::verifiers: ✅ Risc0 proof verified. -INFO hyle::data_availability::node_state::verifiers: 🔎 Program outputs: Transferred 2 to bob.simple_token +INFO hyle::data_availability::node_state::verifiers: 🔎 Program outputs: Transferred 2 to bob@simple_token ``` On the following slot: @@ -70,12 +70,12 @@ INFO hyle::data_availability::node_state: Settle tx TxHash("[..]") Verify onchain balances: ```bash -cargo run -- balance faucet.simple_token -cargo run -- balance bob.simple_token +cargo run -- balance faucet@simple_token +cargo run -- balance bob@simple_token ``` !!! note - In this example, we do not verify the identity of the person who initiates the transaction. We use `.simple_token` as a suffix for the "from" and "to" transfer fields, but the correct identity scheme should be used in production. +In this example, we do not verify the identity of the person who initiates the transaction. We use `@simple_token` as a suffix for the "from" and "to" transfer fields, but the correct identity scheme should be used in production. See your contract's state digest at: `https://hyleou.hyle.eu/contract/$CONTRACT_NAME`. @@ -111,7 +111,7 @@ Set up information about your contract. To register the contract, you'll need: ```rs // Build initial state of contract -let initial_state = Token::new(supply, format!("faucet.{}", contract_name).into()); +let initial_state = Token::new(supply, format!("faucet@{}", contract_name).into()); println!("Initial state: {:?}", initial_state); // Send the transaction to register the contract @@ -137,12 +137,12 @@ In [the explorer](https://hyleou.hyle.eu/), this will look like this: ```json { - "tx_hash": "321b7a4b2228904fc92979117e7c2aa6740648e339c97986141e53d967e08097", - "owner": "examples", - "verifier": "risc0", - "program_id":"e085fa46f2e62d69897fc77f379c0ba1d252d7285f84dbcc017957567d1e812f", - "state_digest": "fd00e876481700000001106661756365742e687964656e74697479fd00e876481700000000", - "contract_name": "simple_token" + "tx_hash": "321b7a4b2228904fc92979117e7c2aa6740648e339c97986141e53d967e08097", + "owner": "examples", + "verifier": "risc0", + "program_id": "e085fa46f2e62d69897fc77f379c0ba1d252d7285f84dbcc017957567d1e812f", + "state_digest": "fd00e876481700000001106661756365742e687964656e74697479fd00e876481700000000", + "contract_name": "simple_token" } ``` diff --git a/docs/quickstart/example/proof-composition.md b/docs/quickstart/example/proof-composition.md index 7419a89..0006b98 100644 --- a/docs/quickstart/example/proof-composition.md +++ b/docs/quickstart/example/proof-composition.md @@ -24,9 +24,9 @@ In this example, `Alice` and `Bob` both want to buy a ticket from Ticket App for The Ticket App backend creates and sends a blob transaction to Hylé, including three blobs: -- an *identity blob* (see our [custom identity contract quickstart](./custom-identity-contract.md)) confirming that Bob (`bob.id`) is initiating the transaction; -- a *simple-token blob* transferring 15 simple-tokens from `bob.id`'s balance; -- a *ticket-app blob* sending `bob.id` a ticket if conditions are met. +- an _identity blob_ (see our [custom identity contract quickstart](./custom-identity-contract.md)) confirming that Bob (`bob@id`) is initiating the transaction; +- a _simple-token blob_ transferring 15 simple-tokens from `bob@id`'s balance; +- a _ticket-app blob_ sending `bob@id` a ticket if conditions are met. At this stage, Hylé sequences the transaction, but it’s not yet settled. [Read more about pipelined proving.](../../concepts/pipelined-proving.md) @@ -37,7 +37,7 @@ The Ticket App backend generates ZK proofs of each blob. The `ticket-app` contract is executed, checking whether: - A `simple-token` blob exists; -- The blob attempts to transfer 15 simple-tokens from `bob.id` to `ticket-app`. +- The blob attempts to transfer 15 simple-tokens from `bob@id` to `ticket-app`. At this step, the contract does not verify whether Bob actually has enough tokens: if the token transfer fails in Step 3, the entire transaction fails. @@ -47,18 +47,18 @@ Check out the [source code](https://github.com/Hyle-org/examples/blob/492501ebe6 Once TicketApp has sent the proofs for the previously sequenced blobs, Hylé verifies: -- identity proof: verifies that `bob.id` has initiated the transaction. -- simple-token proof: verifies that `bob.id` paid the correct amount for his ticket. -- ticket-app proof: verifies that `bob.id` has received the ticket. +- identity proof: verifies that `bob@id` has initiated the transaction. +- simple-token proof: verifies that `bob@id` paid the correct amount for his ticket. +- ticket-app proof: verifies that `bob@id` has received the ticket. -If all proofs are valid, the simple-token balance and ticket-app ticket balance are updated simultaneously at transaction settlement: `bob.id` sends 15 simple-tokens and gains one ticket. +If all proofs are valid, the simple-token balance and ticket-app ticket balance are updated simultaneously at transaction settlement: `bob@id` sends 15 simple-tokens and gains one ticket. If any proof fails, the entire transaction fails. Neither state is updated: Bob's token balance does not change and he doesn't get a ticket. ## Run the example !!! warning - Our examples work on Hylé v0.12.1. Later versions introduce breaking changes which have not yet been reflected in our examples. +Our examples work on Hylé v0.12.1. Later versions introduce breaking changes which have not yet been reflected in our examples. ### Prerequisites @@ -86,14 +86,14 @@ cargo run -- --contract-name id register-contract Now we have an identity contract called `id`. We can use it to declare our users: ```sh -cargo run -- --contract-name id register-identity bob.id pass -cargo run -- --contract-name id register-identity alice.id pass +cargo run -- --contract-name id register-identity bob@id pass +cargo run -- --contract-name id register-identity alice@id pass ``` Let's verify it quickly with: ```sh -cargo run -- --contract-name id verify bob.id pass 0 +cargo run -- --contract-name id verify bob@id pass 0 ``` 0 is a nonce: every time we verify successfully bob's identity, it increments. Now if we want to verify it again, we should use 1 as nonce. (We also use "pass" as our default password.) @@ -101,10 +101,10 @@ cargo run -- --contract-name id verify bob.id pass 0 We now do the same for alice: ```sh -cargo run -- --contract-name id verify alice.id pass 0 +cargo run -- --contract-name id verify alice@id pass 0 ``` -`bob.id` is bob's identity on the simple-identity contract. Check out our [Identity management](../../concepts/identity.md) and [custom identity contract](./custom-identity-contract.md) pages to know more. +`bob@id` is bob's identity on the simple-identity contract. Check out our [Identity management](../../concepts/identity.md) and [custom identity contract](./custom-identity-contract.md) pages to know more. ### Simple-token preparation @@ -129,26 +129,26 @@ Now let's transfer some tokens to our user `bob`. To send 50 tokens to `bob` and 10 tokens to `alice`, run: ```bash -cargo run -- -contract-name simple-token transfer faucet.simple-token bob.id 50 -cargo run -- -contract-name simple-token transfer faucet.simple-token alice.id 10 +cargo run -- -contract-name simple-token transfer faucet@simple-token bob@id 50 +cargo run -- -contract-name simple-token transfer faucet@simple-token alice@id 10 ``` The node's log will show: > INFO hyle::data_availability::node_state::verifiers: ✅ Risc0 proof verified. > -> INFO hyle::data_availability::node_state::verifiers: 🔎 Program outputs: Transferred 50 to bob.ticket_app -> INFO hyle::data_availability::node_state::verifiers: 🔎 Program outputs: Transferred 10 to alice.ticket_app +> INFO hyle::data_availability::node_state::verifiers: 🔎 Program outputs: Transferred 50 to bob@ticket_app +> INFO hyle::data_availability::node_state::verifiers: 🔎 Program outputs: Transferred 10 to alice@ticket_app #### Check onchain balance Check onchain balance: ```bash -cargo run -- --contract-name simple-token balance faucet.simple-token +cargo run -- --contract-name simple-token balance faucet@simple-token -cargo run -- --contract-name simple-token balance bob.id -cargo run -- --contract-name simple-token balance alice.id +cargo run -- --contract-name simple-token balance bob@id +cargo run -- --contract-name simple-token balance alice@id ``` You should see that `bob` has a balance of 50 and `alice` has a balance of 10. @@ -172,13 +172,13 @@ ticket-app sells bob a ticket for 15 simple-token. Let's buy a ticket for `bob`: ```bash -cargo run -- --contract-name ticket-app --user bob.id buy-ticket +cargo run -- --contract-name ticket-app --user bob@id buy-ticket ``` Let's try with `alice`: ```bash -cargo run -- --contract-name ticket-app --user alice.id buy-ticket +cargo run -- --contract-name ticket-app --user alice@id buy-ticket ``` You will get an error while executing the TicketApp program: `Execution failed ! Program output: Insufficient balance`. This is because Alice has a balance of 10 and the ticket costs 15. @@ -188,7 +188,7 @@ You will get an error while executing the TicketApp program: `Execution failed ! Check that `bob` has a ticket: ```bash -cargo run -- --contract-name ticket-app --user bob.id has-ticket +cargo run -- --contract-name ticket-app --user bob@id has-ticket ``` You can also check `bob`'s balance and see he now has 35 tokens.