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

Merge branch 'gm' into 'master'

Browse Source 
Update docs

See merge request ioecs/aesophia!493
This commit is contained in:
Craig Everett 2024-12-02 20:01:55 +00:00
commit b3e2f687dd
11 changed files with 89 additions and 357 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
.docssite/build Executable file
View File

@ -0,0 +1,16 @@
#! /usr/bin/bash
if mkdocs=$(command -v mkdocs)
then
echo "mkdocs found at $mkdocs"
else
echo "Could not find a mkdocs installation!"
echo "mkdocs must be installed and available in \$PATH to proceed."
exit 95
fi
rm docs/*.md
cp ../docs/*.md docs/
cp ../CHANGELOG.md docs/
mkdocs build

BIN
.docssite/docs/favicon.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.0 KiB

After

Width:  |  Height:  |  Size: 1.5 KiB

7
.docssite/hook.py
View File

@ -1,7 +0,0 @@
import glob
import shutil
def pre_build(**kwargs):
for file in glob.glob('../docs/*.md'):
shutil.copy(file, 'docs')
shutil.copy('../CHANGELOG.md', 'docs')

37
.docssite/mkdocs.yml
View File

@ -1,10 +1,7 @@
site_name: æternity Sophia Language site_name: Sophia Language
plugins: plugins:
- search - search
- mkdocs-simple-hooks: repo_url: 'https://gitlab.com/ioecs/aesophia'
hooks:
on_pre_build: 'hook:pre_build'
repo_url: 'https://github.com/aeternity/aesophia'
edit_uri: '' edit_uri: ''
extra: extra:
@ -13,22 +10,23 @@ extra:
theme: theme:
favicon: favicon.png favicon: favicon.png
name: material # name: material
name: mkdocs
custom_dir: overrides custom_dir: overrides
language: en language: en
palette: palette:
- scheme: default # - scheme: default
primary: pink primary: green
accent: pink # accent: green
toggle: # toggle:
icon: material/weather-night # icon: material/weather-night
name: Switch to dark mode # name: Switch to dark mode
- scheme: slate # - scheme: slate
primary: pink # primary: green
accent: pink # accent: green
toggle: # toggle:
icon: material/weather-sunny # icon: material/weather-sunny
name: Switch to light mode # name: Switch to light mode
features: features:
- content.tabs.link - content.tabs.link
- search.highlight - search.highlight
@ -52,4 +50,7 @@ nav:
- Features: sophia_features.md - Features: sophia_features.md
- Standard library: sophia_stdlib.md - Standard library: sophia_stdlib.md
- Contract examples: sophia_examples.md - Contract examples: sophia_examples.md
- ACI Module: aeso_aci.md
- Compiler Module: aeso_compiler.md
- Sophia: sophia.md
- Changelog: CHANGELOG.md - Changelog: CHANGELOG.md

1
LICENSE
View File

@ -1,5 +1,6 @@
ISC License ISC License
Copyright (c) 2024, QPQ AG
Copyright (c) 2017, æternity developers Copyright (c) 2017, æternity developers
Permission to use, copy, modify, and/or distribute this software for any Permission to use, copy, modify, and/or distribute this software for any

17
README.md
View File

@ -1,11 +1,12 @@
# aesophia # Sophia
This is the __sophia__ compiler for the æternity system which compiles contracts written in __sophia__ to [FATE](https://github.com/aeternity/protocol/blob/master/contracts/fate.md) instructions. This is the __Sophia__ compiler for the Gajumaru system which compiles contracts written in __Sophia__ to [FATE](https://gitlab.com/ioecs/protocol/-/blob/master/contracts/fate.md) instructions.
The compiler is currently being used three places The compiler is being used a few places
- [The command line compiler](https://github.com/aeternity/aesophia_cli) - [The command line compiler](https://gitlab.com/ioecs/sophia_cli)
- [The HTTP compiler](https://github.com/aeternity/aesophia_http) - In [Gajumaru node](https://gitlab.com/ioecs/gajumaru) tests
- In [æternity node](https://github.com/aeternity/aeternity) tests - [Clutch](https://gitlab.com/ioecs/clutch), the desktop wallet
- Various backend systems that implement GRIDS
## Documentation ## Documentation
@ -16,13 +17,13 @@ The compiler is currently being used three places
* [Contract examples](docs/sophia_examples.md) * [Contract examples](docs/sophia_examples.md)
* [Contributing](CONTRIBUTING.md) * [Contributing](CONTRIBUTING.md)
Additionally you can check out the [contracts section](https://github.com/aeternity/protocol/blob/master/contracts/contracts.md) of the æternity blockchain specification. Additionally you can check out the [contracts section](https://gitlab.com/ioecs/protocol/-/tree/master/contracts) of the Gajumaru blockchain specification.
## Versioning ## Versioning
Versioning should follow the [semantic versioning](https://semver.org/spec/v2.0.0) guidelines. Id est, given a version number MAJOR.MINOR.PATCH, increment the: Versioning should follow the [semantic versioning](https://semver.org/spec/v2.0.0) guidelines. Id est, given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible API changes - MAJOR version when you make backward incompatible changes
- MINOR version when you add functionality in a backwards compatible manner - MINOR version when you add functionality in a backwards compatible manner
- PATCH version when you make backwards compatible bug fixes - PATCH version when you make backwards compatible bug fixes

5
docs/index.md
View File

@ -5,8 +5,7 @@ restricted mutable state.
Sophia is customized for smart contracts, which can be published Sophia is customized for smart contracts, which can be published
to a blockchain. Thus some features of conventional to a blockchain. Thus some features of conventional
languages, such as floating point arithmetic, are not present in Sophia, and languages, such as floating point arithmetic, are not present in Sophia, and
some [æternity blockchain](https://aeternity.com) specific primitives, constructions and types have been added. some [blockchain](https://gajumaru.io) specific primitives, constructions and types have been added.
!!! Note !!! Note
- For rapid prototyping of smart contracts check out [AEstudio](https://studio.aepps.com/)! - For playing around and diving deeper into the language itself check out the [REPL](https://gitlab.com/ioecs/aerepl)!
- For playing around and diving deeper into the language itself check out the [REPL](https://repl.aeternity.io/)!

6
docs/sophia_examples.md
View File

@ -65,9 +65,3 @@ contract FundMe =
amount = state.contributions[to]}) amount = state.contributions[to]})
put(state{ contributions @ c = Map.delete(to, c) }) put(state{ contributions @ c = Map.delete(to, c) })
``` ```
## Repositories
This is a list with repositories that include smart contracts written in Sophia:
- [aepp-sophia-examples](https://github.com/aeternity/aepp-sophia-examples)
- A repository that contains lots of different examples. The functionality of these examples is - to some extent - also covered by tests written in JavaScript.

126
docs/sophia_features.md
View File

@ -40,8 +40,8 @@ contract VoteTwice =
``` ```
Contract calls take two optional named arguments `gas : int` and `value : int` Contract calls take two optional named arguments `gas : int` and `value : int`
that lets you set a gas limit and provide tokens to a contract call. If omitted that lets you set a gas limit and provide coins to a contract call. If omitted
the defaults are no gas limit and no tokens. Suppose there is a fee for voting: the defaults are no gas limit and no coins. Suppose there is a fee for voting:
```sophia ```sophia
entrypoint voteTwice(v : VotingType, fee : int, alt : string) = entrypoint voteTwice(v : VotingType, fee : int, alt : string) =
@ -62,7 +62,7 @@ the type of the entrypoint does not match the stated contract type, the call
fails. fails.
To recover the underlying `address` of a contract instance there is a field To recover the underlying `address` of a contract instance there is a field
`address : address`. For instance, to send tokens to the voting contract (given that it is payable) `address : address`. For instance, to send coins to the voting contract (given that it is payable)
without calling it you can write without calling it you can write
```sophia ```sophia
@ -99,7 +99,7 @@ running out of gas it is necessary to set a gas limit using the `gas` argument.
However, note that errors that would normally consume all the gas in the However, note that errors that would normally consume all the gas in the
transaction still only uses up the gas spent running the contract. transaction still only uses up the gas spent running the contract.
Any side effects (state change, token transfers, etc.) made by a failing Any side effects (state change, coin transfers, etc.) made by a failing
protected call is rolled back, just like they would be in the unprotected case. protected call is rolled back, just like they would be in the unprotected case.
@ -274,12 +274,6 @@ counterpart in `Args1`.
- A map type `map(A1, A2)` is a subtype of `map(B1, B2)` if `A1` is a subtype - A map type `map(A1, A2)` is a subtype of `map(B1, B2)` if `A1` is a subtype
of `B1`, and `A2` is a subtype of `B2`. of `B1`, and `A2` is a subtype of `B2`.
- An oracle type `oracle(A1, A2)` is a subtype of `oracle(B1, B2)` if `B1` is
a subtype of `A1`, and `A2` is a subtype of `B2`.
- An oracle_query type `oracle_query(A1, A2)` is a subtype of `oracle_query(B1, B2)`
if `A1` is a subtype of `B1`, and `A2` is a subtype of `B2`.
- A user-defined datatype `t(Args1)` is a subtype of `t(Args2)` - A user-defined datatype `t(Args1)` is a subtype of `t(Args2)`
- When a user-defined type `t('a)` is covariant in `'a`, then `t(A)` is a - When a user-defined type `t('a)` is covariant in `'a`, then `t(A)` is a
@ -340,10 +334,6 @@ Without the `stateful` annotation the compiler does not allow the call to
* Use a stateful primitive function. These are * Use a stateful primitive function. These are
- `put` - `put`
- `Chain.spend` - `Chain.spend`
- `Oracle.register`
- `Oracle.query`
- `Oracle.respond`
- `Oracle.extend`
- `AENS.preclaim` - `AENS.preclaim`
- `AENS.claim` - `AENS.claim`
- `AENS.transfer` - `AENS.transfer`
@ -540,7 +530,7 @@ Sophia has the following types:
| Type | Description | Example | | Type | Description | Example |
|----------------------|---------------------------------------------------------------------------------------------|--------------------------------------------------------------| |----------------------|---------------------------------------------------------------------------------------------|--------------------------------------------------------------|
| int | A 2-complement integer | ```-1``` | | int | A 2-complement integer | ```-1``` |
| address | æternity address, 32 bytes | ```Call.origin``` | | address | on-chain address, 32 bytes | ```Call.origin``` |
| bool | A Boolean | ```true``` | | bool | A Boolean | ```true``` |
| bits | A bit field | ```Bits.none``` | | bits | A bit field | ```Bits.none``` |
| bytes(n) | A byte array with `n` bytes | ```#fedcba9876543210``` | | bytes(n) | A byte array with `n` bytes | ```#fedcba9876543210``` |
@ -556,8 +546,6 @@ Sophia has the following types:
| hash | A 32-byte hash - equivalent to `bytes(32)` | | | hash | A 32-byte hash - equivalent to `bytes(32)` | |
| signature | A signature - equivalent to `bytes(64)` | | | signature | A signature - equivalent to `bytes(64)` | |
| Chain.ttl | Time-to-live (fixed height or relative to current block) | ```FixedTTL(1050)``` ```RelativeTTL(50)``` | | Chain.ttl | Time-to-live (fixed height or relative to current block) | ```FixedTTL(1050)``` ```RelativeTTL(50)``` |
| oracle('a, 'b) | And oracle answering questions of type 'a with answers of type 'b | ```Oracle.register(acct, qfee, ttl)``` |
| oracle_query('a, 'b) | A specific oracle query | ```Oracle.query(o, q, qfee, qttl, rttl)``` |
| contract | A user defined, typed, contract address | ```function call_remote(r : RemoteContract) = r.fun()``` | | contract | A user defined, typed, contract address | ```function call_remote(r : RemoteContract) = r.fun()``` |
## Literals ## Literals
@ -580,8 +568,6 @@ Sophia has the following types:
| hash | `#000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f` | | hash | `#000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f` |
| signature | `sg_MhibzTP1wWzGCTjtPFr1TiPqRJrrJqw7auvEuF5i3FdoALWqXLBDY6xxRRNUSPHK3EQTnTzF12EyspkxrSMxVHKsZeSMj`, `#000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f` | | signature | `sg_MhibzTP1wWzGCTjtPFr1TiPqRJrrJqw7auvEuF5i3FdoALWqXLBDY6xxRRNUSPHK3EQTnTzF12EyspkxrSMxVHKsZeSMj`, `#000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f` |
| Chain.ttl | `FixedTTL(1050)`, `RelativeTTL(50)` | | Chain.ttl | `FixedTTL(1050)`, `RelativeTTL(50)` |
| oracle('a, 'b) | `ok_2YNyxd6TRJPNrTcEDCe9ra59SVUdp9FR9qWC5msKZWYD9bP9z5` |
| oracle_query('a, 'b) | `oq_2oRvyowJuJnEkxy58Ckkw77XfWJrmRgmGaLzhdqb67SKEL1gPY` |
| contract | `ct_Ez6MyeTMm17YnTnDdHTSrzMEBKmy7Uz2sXu347bTDPgVH2ifJ` | | contract | `ct_Ez6MyeTMm17YnTnDdHTSrzMEBKmy7Uz2sXu347bTDPgVH2ifJ` |
## Hole expression ## Hole expression
@ -891,77 +877,10 @@ wrapping a transaction.) The transaction and the transaction hash is available i
`Auth.tx` and `Auth.tx_hash` respectively, they are *only* available during authentication if invoked by a `Auth.tx` and `Auth.tx_hash` respectively, they are *only* available during authentication if invoked by a
normal contract call they return `None`. normal contract call they return `None`.
## Oracle interface
You can attach an oracle to the current contract and you can interact with oracles
through the Oracle interface.
For a full description of how Oracle works see
[Oracles](https://github.com/aeternity/protocol/blob/master/oracles/oracles.md#oracles).
For a functionality documentation refer to the [standard library](sophia_stdlib.md#oracle).
### Example
Example for an oracle answering questions of type `string` with answers of type `int`:
```sophia
contract Oracles =
stateful entrypoint registerOracle(acct : address,
sign : signature, // Signed network id + oracle address + contract address
qfee : int,
ttl : Chain.ttl) : oracle(string, int) =
Oracle.register(acct, signature = sign, qfee, ttl)
entrypoint queryFee(o : oracle(string, int)) : int =
Oracle.query_fee(o)
payable stateful entrypoint createQuery(o : oracle_query(string, int),
q : string,
qfee : int,
qttl : Chain.ttl,
rttl : int) : oracle_query(string, int) =
require(qfee =< Call.value, "insufficient value for qfee")
Oracle.query(o, q, qfee, qttl, RelativeTTL(rttl))
stateful entrypoint extendOracle(o : oracle(string, int),
ttl : Chain.ttl) : unit =
Oracle.extend(o, ttl)
stateful entrypoint signExtendOracle(o : oracle(string, int),
sign : signature, // Signed network id + oracle address + contract address
ttl : Chain.ttl) : unit =
Oracle.extend(o, signature = sign, ttl)
stateful entrypoint respond(o : oracle(string, int),
q : oracle_query(string, int),
sign : signature, // Signed network id + oracle query id + contract address
r : int) =
Oracle.respond(o, q, signature = sign, r)
entrypoint getQuestion(o : oracle(string, int),
q : oracle_query(string, int)) : string =
Oracle.get_question(o, q)
entrypoint hasAnswer(o : oracle(string, int),
q : oracle_query(string, int)) =
switch(Oracle.get_answer(o, q))
None => false
Some(_) => true
entrypoint getAnswer(o : oracle(string, int),
q : oracle_query(string, int)) : option(int) =
Oracle.get_answer(o, q)
```
### Sanity checks
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)
functions are provided.
## AENS interface ## AENS interface
Contracts can interact with the [æternity naming Contracts can interact with the [on-chain naming
system](https://github.com/aeternity/protocol/blob/master/AENS.md). For this system](https://gitlab.com/ioecs/protocol/-/blob/master/AENS.md). For this
purpose the [AENS](sophia_stdlib.md#aens) and later the purpose the [AENS](sophia_stdlib.md#aens) and later the
[AENSv2](sophia_stdlib.md#aensv2) library was exposed. [AENSv2](sophia_stdlib.md#aensv2) library was exposed.
@ -1012,7 +931,7 @@ automatically removed so they will not appear in the pointers map.
Sophia contracts log structured messages to an event log in the resulting Sophia contracts log structured messages to an event log in the resulting
blockchain transaction. The event log is quite similar to [Events in blockchain transaction. The event log is quite similar to [Events in
Solidity](https://solidity.readthedocs.io/en/v0.4.24/contracts.html#events). Solidity](https://solidity.readthedocs.io/en/v0.4.24/contracts.html#events).
Events are further discussed in the [protocol](https://github.com/aeternity/protocol/blob/master/contracts/events.md). Events are further discussed in the [protocol](https://gitlab.com/ioecs/protocol/-/blob/master/contracts/events.md).
To use events a contract must declare a datatype `event`, and events are then To use events a contract must declare a datatype `event`, and events are then
@ -1032,15 +951,13 @@ field is indexed if it fits in a 32-byte word, i.e.
- `int` - `int`
- `bits` - `bits`
- `address` - `address`
- `oracle(_, _)`
- `oracle_query(_, _)`
- contract types - contract types
- `bytes(n)` for `n` ≤ 32, in particular `hash` - `bytes(n)` for `n` ≤ 32, in particular `hash`
The payload field must be either a string or a byte array of more than 32 bytes. The payload field must be either a string or a byte array of more than 32 bytes.
The fields can appear in any order. The fields can appear in any order.
*NOTE:* Indexing is not part of the core æternity node. *NOTE:* Indexing is not part of the core node.
Events are emitted by using the `Chain.event` function. The following function Events are emitted by using the `Chain.event` function. The following function
will emit one Event of each kind in the example. will emit one Event of each kind in the example.
@ -1113,34 +1030,17 @@ however is in the gas consumption — while `abort` returns unused gas, a call t
## Delegation signature ## Delegation signature
Some chain operations (`Oracle.<operation>` and `AENSv2.<operation>`) have an Some chain operations (`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. would like to allow a contract to act on it's behalf.
### From Ceres The signature structure includes a unique tag, `network_id` and identifiers; there
are three different delegation signatures:
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 wildcard - the user signs: `owner account + contract`
- `AENS_PRECLAIM` - 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` - `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 See [Serialized signature
data](https://github.com/aeternity/protocol/blob/master/contracts/fate.md#from-ceres-serialized-signature-data) data](https://gitlab.com/ioecs/protocol/-/blob/master/contracts/fate.md#appendix-1-fate-serialization)
for the exact structure used. 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`

226
docs/sophia_stdlib.md
View File

@ -14,7 +14,6 @@ The out-of-the-box namespaces are:
- [Address](#address) - [Address](#address)
- [AENS](#aens) - [AENS](#aens)
- [AENSv2](#aensv2)
- [Auth](#auth) - [Auth](#auth)
- [Bits](#bits) - [Bits](#bits)
- [Bytes](#bytes) - [Bytes](#bytes)
@ -25,14 +24,12 @@ The out-of-the-box namespaces are:
- [Crypto](#crypto) - [Crypto](#crypto)
- [Int](#int) - [Int](#int)
- [Map](#map) - [Map](#map)
- [Oracle](#oracle)
The following ones need to be included as regular files with `.aes` suffix, for example The following ones need to be included as regular files with `.aes` suffix, for example
``` ```
include "List.aes" include "List.aes"
``` ```
- [AENSCompat](#aenscompat)
- [Bitwise](#bitwise) - [Bitwise](#bitwise)
- [BLS12_381](#bls12_381) - [BLS12_381](#bls12_381)
- [Func](#func) - [Func](#func)
@ -71,15 +68,6 @@ Address.is_contract(a : address) : bool
Is the address a contract Is the address a contract
#### is_oracle
```
Address.is_oracle(a : address) : bool
```
Is the address a registered oracle
#### is_payable #### is_payable
``` ```
Address.is_payable(a : address) : bool Address.is_payable(a : address) : bool
@ -98,10 +86,14 @@ Cast address to contract type C (where `C` is a contract)
### AENS ### AENS
The old AENS namespace, kept in the compiler to be able to interact with Note: introduced in v8.0
contracts from before Ceres, compiled using aesophia compiler version 7.x and
earlier. Used in [AENSCompat](#aenscompat) when converting between old and new The following functionality is available for interacting with the
pointers. naming system (AENS). 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 a signature to prove that we are allowed to do AENS
operations on behalf of `owner`. The [signature is tied to a networkid](https://gitlab.com/ioecs/protocol/-/blob/master/consensus/README.md#transaction-signature),
i.e. the signature material should be prefixed by the network id.
#### Types #### Types
@ -114,35 +106,7 @@ datatype name = Name(address, Chain.ttl, map(string, AENS.pointee))
##### pointee ##### pointee
``` ```
datatype pointee = AccountPt(address) | OraclePt(address) datatype pointee = AccountPt(address) | ContractPt(address) | ChannelPt(address) | DataPt(bytes())
| ContractPt(address) | ChannelPt(address)
```
### AENSv2
Note: introduced in v8.0
The following functionality is available for interacting with the æternity
naming system (AENS). 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 a signature to prove that we are allowed to do AENS
operations on behalf of `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.
#### Types
##### name
```
datatype name = Name(address, Chain.ttl, map(string, AENSv2.pointee))
```
##### pointee
```
datatype pointee = AccountPt(address) | OraclePt(address)
| ContractPt(address) | ChannelPt(address) | DataPt(bytes())
``` ```
Note: on-chain there is a maximum length enforced for `DataPt`, it is 1024 bytes. Note: on-chain there is a maximum length enforced for `DataPt`, it is 1024 bytes.
@ -152,7 +116,7 @@ Sophia itself does _not_ check for this.
##### resolve ##### resolve
``` ```
AENSv2.resolve(name : string, key : string) : option('a) AENS.resolve(name : string, key : string) : option('a)
``` ```
Name resolution. Here `name` should be a registered name and `key` one of the attributes Name resolution. Here `name` should be a registered name and `key` one of the attributes
@ -163,29 +127,29 @@ type checked against this type at run time.
##### lookup ##### lookup
``` ```
AENSv2.lookup(name : string) : option(AENSv2.name) AENS.lookup(name : string) : option(AENS.name)
``` ```
If `name` is an active name `AENSv2.lookup` returns a name object. If `name` is an active name `AENS.lookup` returns a name object.
The three arguments to `Name` are `owner`, `expiry` and a map of the The three arguments to `Name` are `owner`, `expiry` and a map of the
`pointees` for the name. Note: the expiry of the name is always a fixed TTL. `pointees` for the name. Note: the expiry of the name is always a fixed TTL.
For example: For example:
``` ```
let Some(AENSv2.Name(owner, FixedTTL(expiry), ptrs)) = AENSv2.lookup("example.chain") let Some(AENS.Name(owner, FixedTTL(expiry), ptrs)) = AENS.lookup("example.chain")
``` ```
Note: Changed to produce `AENSv2.name` in v8.0 (Ceres protocol upgrade). Note: Changed to produce `AENS.name` in v8.0
##### preclaim ##### preclaim
``` ```
AENSv2.preclaim(owner : address, commitment_hash : hash, <signature : signature>) : unit AENS.preclaim(owner : address, commitment_hash : hash, <signature : signature>) : unit
``` ```
The [signature](./sophia_features.md#delegation-signature) should be a The [signature](./sophia_features.md#delegation-signature) should be a
serialized structure containing `network id`, `owner address`, and serialized structure containing `network id`, `owner address`, and
`Contract.address`. `Contract.address`.
From Ceres (i.e. FATE VM version 3) the 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. containing `network id`, `owner address`, `Contract.address`. signature), i.e. containing `network id`, `owner address`, `Contract.address`.
@ -193,14 +157,14 @@ signature), i.e. containing `network id`, `owner address`, `Contract.address`.
##### claim ##### claim
``` ```
AENSv2.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](./sophia_features.md#delegation-signature) should be a The [signature](./sophia_features.md#delegation-signature) should be a
serialized structure containing `network id`, `owner address`, and serialized structure containing `network id`, `owner address`, and
`Contract.address`. Using the private key of `owner address` for signing. `Contract.address`. Using the private key of `owner address` for signing.
From Ceres (i.e. FATE VM version 3) the 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. containing `network id`, `owner address`, `name_hash`, and signature), i.e. containing `network id`, `owner address`, `name_hash`, and
@ -209,7 +173,7 @@ signature), i.e. containing `network id`, `owner address`, `name_hash`, and
##### transfer ##### transfer
``` ```
AENSv2.transfer(owner : address, new_owner : address, name : string, <signature : signature>) : unit AENS.transfer(owner : address, new_owner : address, name : string, <signature : signature>) : unit
``` ```
Transfers name to the new owner. Transfers name to the new owner.
@ -218,7 +182,7 @@ The [signature](./sophia_features.md#delegation-signature) should be a
serialized structure containing `network id`, `owner address`, and serialized structure containing `network id`, `owner address`, and
`Contract.address`. Using the private key of `owner address` for signing. `Contract.address`. Using the private key of `owner address` for signing.
From Ceres (i.e. FATE VM version 3) the 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. containing `network id`, `owner address`, `name_hash`, and signature), i.e. containing `network id`, `owner address`, `name_hash`, and
@ -227,7 +191,7 @@ signature), i.e. containing `network id`, `owner address`, `name_hash`, and
##### revoke ##### revoke
``` ```
AENSv2.revoke(owner : address, name : string, <signature : signature>) : unit 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.
@ -236,7 +200,7 @@ The [signature](./sophia_features.md#delegation-signature) should be a
serialized structure containing `network id`, `owner address`, and serialized structure containing `network id`, `owner address`, and
`Contract.address`. Using the private key of `owner address` for signing. `Contract.address`. Using the private key of `owner address` for signing.
From Ceres (i.e. FATE VM version 3) the 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. containing `network id`, `owner address`, `name_hash`, and signature), i.e. containing `network id`, `owner address`, `name_hash`, and
@ -245,21 +209,21 @@ signature), i.e. containing `network id`, `owner address`, `name_hash`, and
##### update ##### update
``` ```
AENSv2.update(owner : address, name : string, expiry : option(Chain.ttl), client_ttl : option(int), AENS.update(owner : address, name : string, expiry : option(Chain.ttl), client_ttl : option(int),
new_ptrs : option(map(string, AENSv2.pointee)), <signature : signature>) : unit new_ptrs : option(map(string, AENS.pointee)), <signature : signature>) : unit
``` ```
Updates the name. If the optional parameters are set to `None` that parameter Updates the name. If the optional parameters are set to `None` that parameter
will not be updated, for example if `None` is passed as `expiry` the expiry will not be updated, for example if `None` is passed as `expiry` the expiry
block of the name is not changed. block of the name is not changed.
Note: Changed to consume `AENSv2.pointee` in v8.0 (Ceres protocol upgrade). Note: Changed to consume `AENS.pointee` in v8.0
The [signature](./sophia_features.md#delegation-signature) should be a The [signature](./sophia_features.md#delegation-signature) should be a
serialized structure containing `network id`, `owner address`, and serialized structure containing `network id`, `owner address`, and
`Contract.address`. Using the private key of `owner address` for signing. `Contract.address`. Using the private key of `owner address` for signing.
From Ceres (i.e. FATE VM version 3) the 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. containing `network id`, `owner address`, `name_hash`, and signature), i.e. containing `network id`, `owner address`, `name_hash`, and
@ -287,7 +251,6 @@ namespace Chain =
datatype ga_meta_tx = GAMetaTx(address, int) datatype ga_meta_tx = GAMetaTx(address, int)
datatype paying_for_tx = PayingForTx(address, int) datatype paying_for_tx = PayingForTx(address, int)
datatype base_tx = SpendTx(address, int, string) datatype base_tx = SpendTx(address, int, string)
| OracleRegisterTx | OracleQueryTx | OracleResponseTx | OracleExtendTx
| NamePreclaimTx | NameClaimTx(hash) | NameUpdateTx(string) | NamePreclaimTx | NameClaimTx(hash) | NameUpdateTx(string)
| NameRevokeTx(hash) | NameTransferTx(address, string) | NameRevokeTx(hash) | NameTransferTx(address, string)
| ChannelCreateTx(address) | ChannelDepositTx(address, int) | ChannelWithdrawTx(address, int) | | ChannelCreateTx(address) | ChannelDepositTx(address, int) | ChannelWithdrawTx(address, int) |
@ -303,10 +266,7 @@ namespace Chain =
Auth.tx_hash : option(hash) Auth.tx_hash : option(hash)
``` ```
Gets the transaction hash during authentication. Note: `Auth.tx_hash` Gets the transaction hash during authentication.
computation differs between protocol versions (changed in Ceres!), see
[aeserialisation](https://github.com/aeternity/protocol/blob/master/serializations.md)
specification for details.
### Bits ### Bits
@ -537,7 +497,6 @@ datatype paying_for_tx = PayingForTx(address, int)
##### base_tx ##### base_tx
``` ```
datatype base_tx = SpendTx(address, int, string) datatype base_tx = SpendTx(address, int, string)
| OracleRegisterTx | OracleQueryTx | OracleResponseTx | OracleExtendTx
| NamePreclaimTx | NameClaimTx(hash) | NameUpdateTx(string) | NamePreclaimTx | NameClaimTx(hash) | NameUpdateTx(string)
| NameRevokeTx(hash) | NameTransferTx(address, string) | NameRevokeTx(hash) | NameTransferTx(address, string)
| ChannelCreateTx(address) | ChannelDepositTx(address, int) | ChannelWithdrawTx(address, int) | | ChannelCreateTx(address) | ChannelDepositTx(address, int) | ChannelWithdrawTx(address, int) |
@ -944,140 +903,11 @@ Returns a list containing pairs of keys and their respective elements.
Turns a list of pairs of form `(key, value)` into a map Turns a list of pairs of form `(key, value)` into a map
### Oracle
#### register
```
Oracle.register(<signature : bytes(64)>, acct : address, qfee : int, ttl : Chain.ttl) : oracle('a, '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 [signature](./sophia_features.md#delegation-signature) should be a
serialized structure containing `network id`, `account address`, and
`contract address`. Using the private key of `account address` for signing.
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.
* 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
key block height (`RelativeTTL(delta)`) or a fixed key block height (`FixedTTL(height)`).
* The type `'a` is the type of the question to ask.
* The type `'b` is the type of the oracle answers.
Examples:
```
Oracle.register(addr0, 25, RelativeTTL(400))
Oracle.register(addr1, 25, RelativeTTL(500), signature = sign1)
```
#### get\_question
```
Oracle.get_question(o : oracle('a, 'b), q : oracle_query('a, 'b)) : 'a
```
Checks what was the question of query `q` on oracle `o`
#### respond
```
Oracle.respond(<signature : bytes(64)>, o : oracle('a, 'b), q : oracle_query('a, 'b), 'b) : unit
```
Responds to the question `q` on `o`. Unless the contract address is the same
as the oracle address the `signature` (which is an optional, named argument)
needs to be provided. Proving that we have the private key of the oracle by
[signing](./sophia_features.md#delegation-signature) should be a serialized
structure containing `network id`, `oracle query id`, and `contract address`.
#### extend
```
Oracle.extend(<signature : bytes(64)>, o : oracle('a, 'b), ttl : Chain.ttl) : unit
```
Extends TTL of an oracle.
* `singature` is a named argument and thus optional. Must be the same as for `Oracle.register`
* `o` is the oracle being extended
* `ttl` must be `RelativeTTL`. The time to live of `o` will be extended by this value.
#### query\_fee
```
Oracle.query_fee(o : oracle('a, 'b)) : int
```
Returns the query fee of the oracle
#### query
```
Oracle.query(o : oracle('a, 'b), q : 'a, qfee : int, qttl : Chain.ttl, rttl : Chain.ttl) : oracle_query('a, 'b)
```
Asks the oracle a question.
* The `qfee` is the query fee debited to the contract account (`Contract.address`).
* The `qttl` controls the last height at which the oracle can submit a response
and can be either fixed or relative.
* The `rttl` must be relative and controls how long an answer is kept on the chain.
The call fails if the oracle could expire before an answer.
#### get\_answer
```
Oracle.get_answer(o : oracle('a, 'b), q : oracle_query('a, 'b)) : option('b)
```
Checks what is the optional query answer
#### expiry
```
Oracle.expiry(o : oracle('a, 'b)) : int
```
Ask the oracle when it expires. The result is the block height at which it will happen.
#### check
```
Oracle.check(o : oracle('a, 'b)) : bool
```
Returns `true` iff the oracle `o` exists and has correct type
#### check_query
```
Oracle.check_query(o : oracle('a, 'b), q : oracle_query('a, 'b)) : bool
```
It returns `true` iff the oracle query exist and has the expected type.
## Includable namespaces ## Includable namespaces
These need to be explicitly included (with `.aes` suffix) These need to be explicitly included (with `.aes` suffix)
### AENSCompat
#### pointee\_to\_V2
```
AENSCompat.pointee_to_V2(p : AENS.pointee) : AENSv2.pointee
```
Translate old pointee format to new, this is always possible.
#### pointee\_from\_V2
```
AENSCompat.pointee_from_V2(p2 : AENSv2.pointee) : option(AENS.pointee)
```
Translate new pointee format to old, `DataPt` can't be translated, so `None` is returned in this case.
### BLS12\_381 ### BLS12\_381
#### Types #### Types
@ -1664,7 +1494,7 @@ point where the error would exceed the `loss` value.
For debugging. If it ever returns false in a code that doesn't call `frac` constructors or For debugging. If it ever returns false in a code that doesn't call `frac` constructors or
accept arbitrary `frac`s from the surface you should report it as a accept arbitrary `frac`s from the surface you should report it as a
[bug](https://github.com/aeternity/aesophia/issues/new) [bug](https://gitlab.com/ioecs/gajumaru/-/issues/new)
If you expect getting calls with malformed `frac`s in your contract, you should use If you expect getting calls with malformed `frac`s in your contract, you should use
this function to verify the input. this function to verify the input.

5
docs/sophia_syntax.md
View File

@ -28,8 +28,6 @@ interface main using as for hiding
- `Char` character literal enclosed in `'` with escape character `\` - `Char` character literal enclosed in `'` with escape character `\`
- `AccountAddress` base58-encoded 32 byte account pubkey with `ak_` prefix - `AccountAddress` base58-encoded 32 byte account pubkey with `ak_` prefix
- `ContractAddress` base58-encoded 32 byte contract address with `ct_` prefix - `ContractAddress` base58-encoded 32 byte contract address with `ct_` prefix
- `OracleAddress` base58-encoded 32 byte oracle address with `ok_` prefix
- `OracleQueryId` base58-encoded 32 byte oracle query id with `oq_` prefix
- `Signature` base58-encoded 64 byte cryptographic signature with `sg_` prefix - `Signature` base58-encoded 64 byte cryptographic signature with `sg_` prefix
Valid string escape codes are Valid string escape codes are
@ -46,7 +44,7 @@ Valid string escape codes are
| `\xHexDigits` | *HexDigits* | | | `\xHexDigits` | *HexDigits* | |
See the [identifier encoding scheme](https://github.com/aeternity/protocol/blob/master/node/api/api_encoding.md) for the See the [identifier encoding scheme](https://gitlab.com/ioecs/protocol/-/blob/master/node/api/api_encoding.md) for the
details on the base58 literals. details on the base58 literals.
## Layout blocks ## Layout blocks
@ -239,7 +237,6 @@ Expr ::= '(' LamArgs ')' '=>' Block(Stmt) // Anonymous function (x) => x +
| Id | Con | QId | QCon // Identifiers x, None, Map.member, AELib.Token | Id | Con | QId | QCon // Identifiers x, None, Map.member, AELib.Token
| Int | Bytes | String | Char // Literals 123, 0xff, #00abc123, "foo", '%' | Int | Bytes | String | Char // Literals 123, 0xff, #00abc123, "foo", '%'
| AccountAddress | ContractAddress // Chain identifiers | AccountAddress | ContractAddress // Chain identifiers
| OracleAddress | OracleQueryId // Chain identifiers
| Signature // Signature | Signature // Signature
| '???' // Hole expression 1 + ??? | '???' // Hole expression 1 + ???