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

Merge pull request #265 from aeternity/improve_docs

Browse Source 
Make the network id an explicit part of the signature material
This commit is contained in:
Hans Svensson 2020-06-05 13:00:42 +02:00 committed by GitHub
commit eff1ad4688
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 18 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
docs/sophia.md
View File

@ -78,7 +78,7 @@ The main unit of code in Sophia is the *contract*.
- A contract may define a type `state` encapsulating its local - A contract may define a type `state` encapsulating its local
state. When creating a new contract the `init` entrypoint is executed and the state. When creating a new contract the `init` entrypoint is executed and the
state is initialized to its return value. state is initialized to its return value.
The language offers some primitive functions to interact with the blockchain and contracts. The language offers some primitive functions to interact with the blockchain and contracts.
Please refer to the [Chain](sophia_stdlib.md#Chain), [Contract](sophia_stdlib.md#Contract) Please refer to the [Chain](sophia_stdlib.md#Chain), [Contract](sophia_stdlib.md#Contract)
and the [Call](sophia_stdlib.md#Call) namespaces in the documentation. and the [Call](sophia_stdlib.md#Call) namespaces in the documentation.
@ -279,7 +279,7 @@ so even cyclic includes should be working without any special tinkering.
### Standard library ### Standard library
Sophia offers [standard library](sophia_stdlib.md) which exposes some Sophia offers [standard library](sophia_stdlib.md) which exposes some
primitive operations and some higher level utilities. The builtin primitive operations and some higher level utilities. The builtin
namespaces like `Chain`, `Contract`, `Map` namespaces like `Chain`, `Contract`, `Map`
are included by default and are supported internally by the compiler. are included by default and are supported internally by the compiler.
@ -446,7 +446,7 @@ Example syntax:
Lists can be constructed using the range syntax using special `..` operator: Lists can be constructed using the range syntax using special `..` operator:
``` ```
[1..4] == [1,2,3,4] [1..4] == [1,2,3,4]
``` ```
The ranges are always ascending and have step equal to 1. The ranges are always ascending and have step equal to 1.
@ -551,7 +551,7 @@ Please refer to the `Bytes` [library documentation](sophia_stdlib.md#Bytes).
### Cryptographic builins ### Cryptographic builins
Libraries [Crypto](sophia_stdlib.md#Crypto) and [String](sophia_stdlib.md#String) provide functions to Libraries [Crypto](sophia_stdlib.md#Crypto) and [String](sophia_stdlib.md#String) provide functions to
hash objects, verify signatures etc. The `hash` is a type alias for `bytes(32)`. hash objects, verify signatures etc. The `hash` is a type alias for `bytes(32)`.
#### AEVM note #### AEVM note
@ -587,7 +587,7 @@ Example for an oracle answering questions of type `string` with answers of type
contract Oracles = contract Oracles =
stateful entrypoint registerOracle(acct : address, stateful entrypoint registerOracle(acct : address,
sign : signature, // Signed oracle address + contract address sign : signature, // Signed network id + oracle address + contract address
qfee : int, qfee : int,
ttl : Chain.ttl) : oracle(string, int) = ttl : Chain.ttl) : oracle(string, int) =
Oracle.register(acct, signature = sign, qfee, ttl) Oracle.register(acct, signature = sign, qfee, ttl)
@ -608,13 +608,13 @@ contract Oracles =
Oracle.extend(o, ttl) Oracle.extend(o, ttl)
stateful entrypoint signExtendOracle(o : oracle(string, int), stateful entrypoint signExtendOracle(o : oracle(string, int),
sign : signature, // Signed oracle address + contract address sign : signature, // Signed network id + oracle address + contract address
ttl : Chain.ttl) : unit = ttl : Chain.ttl) : unit =
Oracle.extend(o, signature = sign, ttl) Oracle.extend(o, signature = sign, ttl)
stateful entrypoint respond(o : oracle(string, int), stateful entrypoint respond(o : oracle(string, int),
q : oracle_query(string, int), q : oracle_query(string, int),
sign : signature, // Signed oracle query id + contract address sign : signature, // Signed network id + oracle query id + contract address
r : int) = r : int) =
Oracle.respond(o, q, signature = sign, r) Oracle.respond(o, q, signature = sign, r)
@ -635,7 +635,7 @@ contract Oracles =
#### Sanity checks #### Sanity checks
When an Oracle literal is passed to a contract, no deep checks are performed. When an Oracle literal is passed to a contract, no deep checks are performed.
For extra safety [Oracle.check](sophia_stdlib.md#check) and [Oracle.check_query](sophia_stdlib.md#check_query) For extra safety [Oracle.check](sophia_stdlib.md#check) and [Oracle.check_query](sophia_stdlib.md#check_query)
functions are provided. functions are provided.
@ -658,7 +658,7 @@ To use events a contract must declare a datatype `event`, and events are then
logged using the `Chain.event` function: logged using the `Chain.event` function:
``` ```
datatype event datatype event
= Event1(int, int, string) = Event1(int, int, string)
| Event2(string, address) | Event2(string, address)

15
docs/sophia_stdlib.md
View File

@ -369,7 +369,7 @@ 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 - * `signature` is a signature proving that the contract is allowed to register the account -
the account address + the contract address (concatenated as byte arrays) is the `network id` + `account address` + `contract address` (concatenated as byte arrays) is
signed with the signed with the
private key of the account, proving you have the private key of the oracle to be. If the private key of the account, proving you have the private key of the oracle to be. If the
address is the same as the contract `sign` is ignored and can be left out entirely. address is the same as the contract `sign` is ignored and can be left out entirely.
@ -403,7 +403,7 @@ Responds to the question `q` on `o`.
Unless the contract address is the same as the oracle address the `signature` Unless the contract address is the same 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 the oracle query id + contract address signing the `network id` + `oracle query id` + `contract address`
### extend ### extend
@ -468,7 +468,8 @@ Naming System (AENS).
If `owner` is equal to `Contract.address` the signature `signature` is If `owner` is equal to `Contract.address` the signature `signature` is
ignored, and can be left out since it is a named argument. Otherwise we need ignored, and can be left out since it is a named argument. Otherwise we need
a signature to prove that we are allowed to do AENS operations on behalf of a signature to prove that we are allowed to do AENS operations on behalf of
`owner` `owner`. The [signature is tied to a network id](https://github.com/aeternity/protocol/blob/iris/consensus/consensus.md#transaction-signature),
i.e. the signature material should be prefixed by the network id.
### resolve ### resolve
``` ```
@ -486,7 +487,7 @@ type checked against this type at run time.
AENS.preclaim(owner : address, commitment_hash : hash, <signature : signature>) : unit AENS.preclaim(owner : address, commitment_hash : hash, <signature : signature>) : unit
``` ```
The signature should be over `owner address` + `Contract.address` The signature should be over `network id` + `owner address` + `Contract.address`
(concatenated as byte arrays). (concatenated as byte arrays).
@ -495,7 +496,7 @@ The signature should be over `owner address` + `Contract.address`
AENS.claim(owner : address, name : string, salt : int, name_fee : int, <signature : signature>) : unit AENS.claim(owner : address, name : string, salt : int, name_fee : int, <signature : signature>) : unit
``` ```
The signature should be over `owner address` + `name_hash` + `Contract.address` The signature should be over `network id` + `owner address` + `name_hash` + `Contract.address`
using the private key of the `owner` account for signing. using the private key of the `owner` account for signing.
@ -506,7 +507,7 @@ AENS.transfer(owner : address, new_owner : address, name : string, <signature :
Transfers name to the new owner. Transfers name to the new owner.
The signature should be over `owner address` + `name_hash` + `Contract.address` The signature should be over `network id` + `owner address` + `name_hash` + `Contract.address`
using the private key of the `owner` account for signing. using the private key of the `owner` account for signing.
@ -517,7 +518,7 @@ AENS.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 should be over `owner address` + `name_hash` + `Contract.address` The signature should be over `network id` + `owner address` + `name_hash` + `Contract.address`
using the private key of the `owner` account for signing. using the private key of the `owner` account for signing.