QPQ-AG/sophia
10
0
Fork 0
Code Issues 41 Pull Requests 5 Actions Packages Projects Releases 16 Wiki Activity

[Ceres]: Update delegation signature documentation (#494)

Browse Source 
* [Ceres]: Update delegation signature documentation

* Fix TYPOs
This commit is contained in:
Hans Svensson 2024-01-23 15:59:30 +01:00
parent 745eeda858
commit 1a80f3faa0
2 changed files with 75 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
docs/sophia_features.md
View File

@ -948,16 +948,18 @@ functions are provided.
## AENS interface ## AENS interface
Contracts can interact with the Contracts can interact with the [æternity naming
[æternity naming system](https://github.com/aeternity/protocol/blob/master/AENS.md). system](https://github.com/aeternity/protocol/blob/master/AENS.md). For this
For this purpose the [AENS](sophia_stdlib.md#aens) library was exposed. purpose the [AENS](sophia_stdlib.md#aens) and later the
[AENSv2](sophia_stdlib.md#aensv2) library was exposed.
### Example ### Example
In this example we assume that the name `name` already exists, and is owned by In this example we assume that the name `name` already exists, and is owned by
an account with address `addr`. In order to allow a contract `ct` to handle an account with address `addr`. In order to allow a contract `ct` to handle
`name` the account holder needs to create a `name` the account holder needs to create a [delegation
[signature](#delegation-signature) `sig` of `addr | name.hash | ct.address`. signature](#delegation-signature) `sig` from the name owner address `addr`, the
name hash and the contract address.
Armed with this information we can for example write a function that extends Armed with this information we can for example write a function that extends
the name if it expires within 1000 blocks: the name if it expires within 1000 blocks:
@ -1099,8 +1101,34 @@ however is in the gas consumption — while `abort` returns unused gas, a call t
## Delegation signature ## Delegation signature
Some chain operations (`Oracle.<operation>` and `AENS.<operation>`) have an Some chain operations (`Oracle.<operation>` and `AENSv2.<operation>`) have an
optional delegation signature. This is typically used when a user/accounts optional delegation signature. This is typically used when a user/accounts
would like to allow a contract to act on it's behalf. The exact data to be would like to allow a contract to act on it's behalf.
signed varies for the different operations, but in all cases you should prepend
the signature data with the `network_id` (`ae_mainnet` for the æternity mainnet, etc.). ### From Ceres
From the Ceres protocol version the delegation signatures have more structure,
including a unique tag, `network_id` and identifiers; there are five different
delegation signatures:
- AENS wildcard - the user signs: `owner account + contract`
- `AENS_PRECLAIM` - the user signs: `owner account + contract`
- `AENS_CLAIM, AENS_UPDATE, AENS_TRANSFER, AENS_REVOKE` - the user signs: `owner account + name hash + contract`
- `ORACLE_REGISTER, ORACLE_EXTEND` - the user signs: `owner account + contract`
- `ORACLE_RESPOND` - the user signs: `query id + contract`
See [Serialized signature
data](https://github.com/aeternity/protocol/blob/master/contracts/fate.md#from-ceres-serialized-signature-data)
for the exact structure used.
### Before ceres
The exact data to be signed varies for the different operations, but in all
cases you should prepend the signature data with the `network_id` (`ae_mainnet`
for the æternity mainnet, etc.).
There are four different delegation signatures:
- `AENS_PRECLAIM` - the user signs: owner `network_id + account + contract`
- `AENS_CLAIM, AENS_UPDATE, AENS_TRANSFER, AENS_REVOKE` - the user signs: `network_id + owner account + name hash + contract`
- `ORACLE_REGISTER, ORACLE_EXTEND` - the user signs: `network_id + owner account + contract`
- `ORACLE_RESPOND` - the user signs: `network_id + query id + contract`

69
docs/sophia_stdlib.md
View File

@ -181,14 +181,14 @@ Note: Changed to produce `AENSv2.name` in v8.0 (Ceres protocol upgrade).
AENSv2.preclaim(owner : address, commitment_hash : hash, <signature : signature>) : unit AENSv2.preclaim(owner : address, commitment_hash : hash, <signature : signature>) : unit
``` ```
The [signature](./sophia_features.md#delegation-signature) should be over The [signature](./sophia_features.md#delegation-signature) should be a
`network id` + `owner address` + `Contract.address` (concatenated as byte arrays). serialized structure containing `network id`, `owner address`, and
`Contract.address`.
From Ceres (i.e. FATE VM version 3) the From Ceres (i.e. FATE VM version 3) the
[signature](./sophia_features.md#delegation-signature) can also be generic [signature](./sophia_features.md#delegation-signature) can also be generic
(allowing _all_, existing and future, names to be delegated with one (allowing _all_, existing and future, names to be delegated with one
signature), i.e. over `network id` + `owner address` + `string "AENS"` + signature), i.e. containing `network id`, `owner address`, `Contract.address`.
`Contract.address`.
##### claim ##### claim
@ -196,14 +196,14 @@ signature), i.e. over `network id` + `owner address` + `string "AENS"` +
AENSv2.claim(owner : address, name : string, salt : int, name_fee : int, <signature : signature>) : unit AENSv2.claim(owner : address, name : string, salt : int, name_fee : int, <signature : signature>) : unit
``` ```
The [signature](./sophia_features.md#delegation-signature) should be over The [signature](./sophia_features.md#delegation-signature) should be a
`network id` + `owner address` + `name_hash` + `Contract.address` (concatenated serialized structure containing `network id`, `owner address`, and
as byte arrays) using the private key of the `owner` account for signing. `Contract.address`. Using the private key of `owner address` for signing.
From Ceres (i.e. FATE VM version 3) the From Ceres (i.e. FATE VM version 3) the
[signature](./sophia_features.md#delegation-signature) can also be generic [signature](./sophia_features.md#delegation-signature) can also be generic
(allowing _all_, existing and future, names to be delegated with one (allowing _all_, existing and future, names to be delegated with one
signature), i.e. over `network id` + `owner address` + `string "AENS"` + signature), i.e. containing `network id`, `owner address`, `name_hash`, and
`Contract.address`. `Contract.address`.
@ -214,15 +214,14 @@ AENSv2.transfer(owner : address, new_owner : address, name : string, <signature
Transfers name to the new owner. Transfers name to the new owner.
The [signature](./sophia_features.md#delegation-signature) should be over The [signature](./sophia_features.md#delegation-signature) should be a
`network id` + `owner address` + `name_hash` + `Contract.address` serialized structure containing `network id`, `owner address`, and
(concatenated as byte arrays) `Contract.address`. Using the private key of `owner address` for signing.
using the private key of the `owner` account for signing.
From Ceres (i.e. FATE VM version 3) the From Ceres (i.e. FATE VM version 3) the
[signature](./sophia_features.md#delegation-signature) can also be generic [signature](./sophia_features.md#delegation-signature) can also be generic
(allowing _all_, existing and future, names to be delegated with one (allowing _all_, existing and future, names to be delegated with one
signature), i.e. over `network id` + `owner address` + `string "AENS"` + signature), i.e. containing `network id`, `owner address`, `name_hash`, and
`Contract.address`. `Contract.address`.
@ -233,15 +232,14 @@ AENSv2.revoke(owner : address, name : string, <signature : signature>) : unit
Revokes the name to extend the ownership time. Revokes the name to extend the ownership time.
The [signature](./sophia_features.md#delegation-signature) should be over The [signature](./sophia_features.md#delegation-signature) should be a
`network id` + `owner address` + `name_hash` + `Contract.address` serialized structure containing `network id`, `owner address`, and
(concatenated as byte arrays) `Contract.address`. Using the private key of `owner address` for signing.
using the private key of the `owner` account for signing.
From Ceres (i.e. FATE VM version 3) the From Ceres (i.e. FATE VM version 3) the
[signature](./sophia_features.md#delegation-signature) can also be generic [signature](./sophia_features.md#delegation-signature) can also be generic
(allowing _all_, existing and future, names to be delegated with one (allowing _all_, existing and future, names to be delegated with one
signature), i.e. over `network id` + `owner address` + `string "AENS"` + signature), i.e. containing `network id`, `owner address`, `name_hash`, and
`Contract.address`. `Contract.address`.
@ -257,6 +255,16 @@ block of the name is not changed.
Note: Changed to consume `AENSv2.pointee` in v8.0 (Ceres protocol upgrade). Note: Changed to consume `AENSv2.pointee` in v8.0 (Ceres protocol upgrade).
The [signature](./sophia_features.md#delegation-signature) should be a
serialized structure containing `network id`, `owner address`, and
`Contract.address`. Using the private key of `owner address` for signing.
From Ceres (i.e. FATE VM version 3) the
[signature](./sophia_features.md#delegation-signature) can also be generic
(allowing _all_, existing and future, names to be delegated with one
signature), i.e. containing `network id`, `owner address`, `name_hash`, and
`Contract.address`.
### Auth ### Auth
@ -944,11 +952,11 @@ Oracle.register(<signature : bytes(64)>, acct : address, qfee : int, ttl : Chain
Registers new oracle answering questions of type `'a` with answers of type `'b`. Registers new oracle answering questions of type `'a` with answers of type `'b`.
* The `acct` is the address of the oracle to register (can be the same as the contract). * The `acct` is the address of the oracle to register (can be the same as the contract).
* `signature` is a signature proving that the contract is allowed to register the account - * The [signature](./sophia_features.md#delegation-signature) should be a
the `network id` + `account address` + `contract address` (concatenated as byte arrays) is serialized structure containing `network id`, `account address`, and
[signed](./sophia_features.md#delegation-signature) with the `contract address`. Using the private key of `account address` for signing.
private key of the account, proving you have the private key of the oracle to be. If the Proving you have the private key of the oracle to be. If the address is the same
address is the same as the contract `sign` is ignored and can be left out entirely. as the contract `sign` is ignored and can be left out entirely.
* The `qfee` is the minimum query fee to be paid by a user when asking a question of the oracle. * The `qfee` is the minimum query fee to be paid by a user when asking a question of the oracle.
* The `ttl` is the Time To Live for the oracle in key blocks, either relative to the current * The `ttl` is the Time To Live for the oracle in key blocks, either relative to the current
key block height (`RelativeTTL(delta)`) or a fixed key block height (`FixedTTL(height)`). key block height (`RelativeTTL(delta)`) or a fixed key block height (`FixedTTL(height)`).
@ -962,7 +970,7 @@ Examples:
``` ```
#### get_question #### get\_question
``` ```
Oracle.get_question(o : oracle('a, 'b), q : oracle_query('a, 'b)) : 'a Oracle.get_question(o : oracle('a, 'b), q : oracle_query('a, 'b)) : 'a
``` ```
@ -975,12 +983,11 @@ Checks what was the question of query `q` on oracle `o`
Oracle.respond(<signature : bytes(64)>, o : oracle('a, 'b), q : oracle_query('a, 'b), 'b) : unit Oracle.respond(<signature : bytes(64)>, o : oracle('a, 'b), q : oracle_query('a, 'b), 'b) : unit
``` ```
Responds to the question `q` on `o`. Responds to the question `q` on `o`. Unless the contract address is the same
Unless the contract address is the same as the oracle address the `signature` as the oracle address the `signature` (which is an optional, named argument)
(which is an optional, named argument)
needs to be provided. Proving that we have the private key of the oracle by needs to be provided. Proving that we have the private key of the oracle by
[signing](./sophia_features.md#delegation-signature) [signing](./sophia_features.md#delegation-signature) should be a serialized
the `network id` + `oracle query id` + `contract address` structure containing `network id`, `oracle query id`, and `contract address`.
#### extend #### extend
@ -993,7 +1000,7 @@ Extends TTL of an oracle.
* `o` is the oracle being extended * `o` is the oracle being extended
* `ttl` must be `RelativeTTL`. The time to live of `o` will be extended by this value. * `ttl` must be `RelativeTTL`. The time to live of `o` will be extended by this value.
#### query_fee #### query\_fee
``` ```
Oracle.query_fee(o : oracle('a, 'b)) : int Oracle.query_fee(o : oracle('a, 'b)) : int
``` ```
@ -1014,7 +1021,7 @@ Asks the oracle a question.
The call fails if the oracle could expire before an answer. The call fails if the oracle could expire before an answer.
#### get_answer #### get\_answer
``` ```
Oracle.get_answer(o : oracle('a, 'b), q : oracle_query('a, 'b)) : option('b) Oracle.get_answer(o : oracle('a, 'b), q : oracle_query('a, 'b)) : option('b)
``` ```