Sophia is a functional language designed for smart contract development. It is strongly typed and has restricted mutable state.
Sophia is customized for smart contracts, which can be published to a blockchain. Thus some features of conventional languages, such as floating point arithmetic, are not present in Sophia, and some \u00e6ternity blockchain specific primitives, constructions and types have been added.
Note
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
"},{"location":"CHANGELOG/#unreleased","title":"Unreleased","text":""},{"location":"CHANGELOG/#added","title":"Added","text":""},{"location":"CHANGELOG/#changed","title":"Changed","text":""},{"location":"CHANGELOG/#removed","title":"Removed","text":""},{"location":"CHANGELOG/#fixed","title":"Fixed","text":""},{"location":"CHANGELOG/#721","title":"7.2.1","text":""},{"location":"CHANGELOG/#fixed_1","title":"Fixed","text":"namespace N =\n let nc = 1\ncontract C =\n let cc = 2\ncontract Main =\n entrypoint spend(x : int) : int = x\n entrypoint f(c : Main) : int = c.spend(10)\ntypedefs field instead of type_defs to increase compatibility.EXIT opcode via exit : (string) => 'a function (behaves same as ABORT, but consumes all gas).[1, 2, 3] |> List.first |> Option.is_some // Option.is_some(List.first([1, 2, 3]))\nfunction sum(l : list(int)) : int = foldl((+), 0, l)\nfunction logical_and(x, y) = (&&)(x, y)\npp_oneline/1 has been added.record r = {} would give an error).Bitwise stdlibSet stdlibOption.force_msgusing Pair)let x::(t = y::_) = [1, 2, 3, 4] where t == [2, 3, 4])AENS.name, AENS.pointee, Chain.ttl, Chain.base_tx, Chain.ga_meta_tx, Chain.paying_for_tx) to the calldata and result decoderswitch(x)\n a::[] | a > 10 => 1\n _ => 2\nfunction\n f(a::[]) | a > 10 = 1\n f(_) = 2\nstateful modifierList.from_to_step now forbids non-positive step (this change does not alter the behavior of the previously deployed contracts)include in the Frac standard libraryChain.cloneChain.createChain.bytecode_hashvoid type that represents an empty typeCall.fee builtincontract interface keywordsmain keyword to indicate the main contract in case there are child contracts aroundList.sum and List.product no longer use List.foldlString standard library has been added. Use it by include \"String.aes\". It includes functions for turning strings into lists of characters for detailed manipulation. For example: include \"String.aes\"\ncontract C =\n entrypoint filter_all_a(s: string) : string =\n String.from_list(List.filter((c : char) => c != 'a', String.to_list(s)))\na's removed.There are also convenience functions split, concat, to_upper, to_lower, etc.
All String functions in FATEv2 operate on unicode code points. - Operations for pairing-based cryptography has been added the operations are in the standard library BLS12_381. With these operations it is possible to do Zero Knowledge-proofs, etc. The operations are for the BLS12-381 curve (as the name suggests). - Calls to functions in other contracts (i.e. remote calls) can now be protected. If a contract call fails for any reason (for instance, the remote contract crashes or runs out of gas, or the entrypoint doesn't exist or has the wrong type) the parent call also fails. To make it possible to recover from failures, contract calls takes a named argument protected : bool (default false).
If protected = true the result of the contract call is wrapped in an option, and Some(value) indicates a succesful execution and None indicates that the contract call failed. Note: any gas consumed until the failure is still charged, but all side effects in the remote contract are rolled back on failure. - A new chain operation AENS.update is supported. - New chain exploring operations AENS.lookup and Oracle.expiry to look up an AENS record and the expiry of an Oracle respectively, are added. - Transaction introspection (Auth.tx) has been added. When a Generalized account is authorized, the authorization function needs access to the transaction (and the transaction hash) for the wrapped transaction. The transaction and the transaction hash is available Auth.tx, it is only available during authentication if invoked by a normal contract call it returns None. Example:
switch(Auth.tx)\n None => abort(\"Not in Auth context\")\n Some(tx0) =>\n switch(tx0.tx)\n Chain.SpendTx(_, amount, _) => amount > 400\n Chain.ContractCallTx(_, _) => true\n _ => false\nChain.block_hash(height) is now (in FATEv2) defined for the current height - this used to be an error.mergesort and a contains function is added.protocol)Frac.aes \u2013 library for rational numberskeep_included it is possible to see which files were included during the parserun_parser that be used to evaluate any parsing rulebody, type and decl- unary operatorlet definitions are no longer supported in the toplevel of the contract function\n length : list('a) => int\n length([]) = 0\n length(x :: xs) = 1 + length(xs)\n function somes(xs : list(option('a))) : list('a) =\n [ x | Some(x) <- xs ]\n function test(m : map(int, int)) =\n let Some(x) = Map.lookup(m, 0)\n x\nAddress.to_contract - casts an address to a (any) contract type.@compiler >= 4.0.\"\\x19Ethereum Signed Message:\\n\", and similar strings.Bytes.concat and Bytes.split are added to be able to (de-)construct byte arrays.[a..b] language construct, returning the list of numbers between a and b (inclusive). Returns the empty list if a > b.init is not called from other functions.AEVM and FATE. Many of the APIs now take {backend, aevm | fate} to decide wich backend to produce artifacts for.Crypto.ecrecover_secp256k1: (hash, bytes(65)) => option(bytes(20)) and Crypto.ecverify_secp256k1 : (hash, bytes(20), bytes(65)) => bool for recovering and verifying an Ethereum address for a message hash and a signature.[x + y | x <- [1,2,3,4,5], let k = x*x, if (k > 5), y <- [k, k+1, k+2]]\n// yields [12,13,14,20,21,22,30,31,32]\npayable is introduced. Contracts, and enpoints, that shall be able to receive funds should be marked as payable. Address.is_payable(a) can be used to check if an (contract) address is payable or not.Crypto.<hash_fun> and String.<hash_fun> for byte arrays now only hash the actual byte array - not the internal ABI format.AENS.claim is updated with a NameFee field - to be able to do name auctions within contracts.Bytes.to_str for AEVM.unit instead of () and regular tuples are encoded by interspersing inner types with *, for instance int * string. Parens are not necessary. Note it only affects the types, values remain as their were before, so (1, \"a\") : int * stringAENS.transfer and AENS.revoke functions have been updated to take a name string instead of a name hash.AEVM backend complained about a missing init function when trying to generate calldata from an ACI-generated interface.Crypto.ecverify and Crypto.ecverify_secp256k1 into Crypto.verify_sig and Crypto.verify_sig_secp256k1 respectively.require : (bool, string) => (). Defined as function require(b, err) = if(!b) abort(err)\nBytes.to_str : bytes(_) => string\nBytes.to_int : bytes(_) => int\ncontract Example =\n // Exported\n entrypoint exported_fun(x) = local_fun(x)\n // Not exported\n function local_fun(x) = x\nfunction (and private function for private functions).Chain.block_hash(height) has changed, it used to be int, where 0 denoted an incorrect height. New return type is option(hash), where None represents an incorrect height.indexed is now optional for word typed (bool, int, address, ...) event arguments.'a, 'b, ... instead of '1, '2, ....state and event types (if present) now appear at the top level.contract_interface and render_aci_json.create_calldata/to_sophia_value - it can now handle negative literals.stateful annotations are now properly enforced. Functions must be marked stateful in order to update the state or spend tokens.Contract.creator, Address.is_contract, Address.is_oracle, Oracle.check and Oracle.check_query has been added to Sophia.bytes(N) has been added to generalize hash (== bytes(32)) and signature (== bytes(64)) and allow for byte arrays of arbitrary fixed length.Crypto.ecverify_secp256k1 has been added.#<hex> to address as ak_<base58check>, oracle ok_<base58check>, oracle query oq_<base58check> and remote contract ct_<base58check>.letfun (e.g. let m(f, xs) = map(f, xs)) was not working properly and has been fixed.let rec has been removed from the language, it has never worked.aeternity/aesophia_cli and has been completely removed from aesophia.Auth.tx_hash, not available in AEVM until Fortuna releaseCrypto.ecverify to the compiler.Crypto.sha3, Crypto.blake2, Crypto.sha256, String.blake2 and String.sha256 to the compiler.bits type for working with bit fields in Sophia.init function - detects programmer errors earlier.record fields - generates more understandable error messages.The ACI interface encoder and decoder.
"},{"location":"aeso_aci/#description","title":"Description","text":"This module provides an interface to generate and convert between Sophia contracts and a suitable JSON encoding of contract interface. As yet the interface is very basic.
Encoding this contract:
contract Answers =\n record state = { a : answers }\n type answers() = map(string, int)\n\n stateful function init() = { a = {} }\n private function the_answer() = 42\n function new_answer(q : string, a : int) : answers() = { [q] = a }\ngenerates the following JSON structure representing the contract interface:
{\n\"contract\": {\n\"functions\": [\n{\n\"arguments\": [],\n\"name\": \"init\",\n\"returns\": \"Answers.state\",\n\"stateful\": true\n},\n{\n\"arguments\": [\n{\n\"name\": \"q\",\n\"type\": \"string\"\n},\n{\n\"name\": \"a\",\n\"type\": \"int\"\n}\n],\n\"name\": \"new_answer\",\n\"returns\": {\n\"map\": [\n\"string\",\n\"int\"\n]\n},\n\"stateful\": false\n}\n],\n\"name\": \"Answers\",\n\"state\": {\n\"record\": [\n{\n\"name\": \"a\",\n\"type\": \"Answers.answers\"\n}\n]\n},\n\"typedefs\": [\n{\n\"name\": \"answers\",\n\"typedef\": {\n\"map\": [\n\"string\",\n\"int\"\n]\n},\n\"vars\": []\n}\n]\n}\n}\nWhen that encoding is decoded the following include definition is generated:
contract Answers =\n record state = {a : Answers.answers}\n type answers = map(string, int)\n function init : () => Answers.state\n function new_answer : (string, int) => map(string, int)\n-type aci_type() :: json | string.\n-type json() :: jsx:json_term().\n-type json_text() :: binary().\nGenerate the JSON encoding of the interface to a contract. The type definitions and non-private functions are included in the JSON string.
"},{"location":"aeso_aci/#render_aci_jsonjson-json_text-string","title":"render_aci_json(json() | json_text()) -> string().","text":"Take a JSON encoding of a contract interface and generate a contract interface that can be included in another contract.
"},{"location":"aeso_aci/#example-run","title":"Example run","text":"This is an example of using the ACI generator from an Erlang shell. The file called aci_test.aes contains the contract in the description from which we want to generate files aci_test.json which is the JSON encoding of the contract interface and aci_test.include which is the contract definition to be included inside another contract.
1> {ok,Contract} = file:read_file(\"aci_test.aes\").\n{ok,<<\"contract Answers =\\n record state = { a : answers }\\n type answers() = map(string, int)\\n\\n stateful function\"...>>}\n2> {ok,JsonACI} = aeso_aci:contract_interface(json, Contract).\n{ok,[#{contract =>\n#{functions =>\n[#{arguments => [],name => <<\"init\">>,\nreturns => <<\"Answers.state\">>,stateful => true},\n#{arguments =>\n[#{name => <<\"q\">>,type => <<\"string\">>},\n#{name => <<\"a\">>,type => <<\"int\">>}],\nname => <<\"new_answer\">>,\nreturns => #{<<\"map\">> => [<<\"string\">>,<<\"int\">>]},\nstateful => false}],\nname => <<\"Answers\">>,\nstate =>\n#{record =>\n[#{name => <<\"a\">>,type => <<\"Answers.answers\">>}]},\ntypedefs =>\n[#{name => <<\"answers\">>,\ntypedef => #{<<\"map\">> => [<<\"string\">>,<<\"int\">>]},\nvars => []}]}}]}\n3> file:write_file(\"aci_test.aci\", jsx:encode(JsonACI)).\nok\n4> {ok,InterfaceStub} = aeso_aci:render_aci_json(JsonACI).\n{ok,<<\"contract Answers =\\n record state = {a : Answers.answers}\\n type answers = map(string, int)\\n function init \"...>>}\n5> file:write_file(\"aci_test.include\", InterfaceStub).\nok\n6> jsx:prettify(jsx:encode(JsonACI)).\n<<\"[\\n {\\n \\\"contract\\\": {\\n \\\"functions\\\": [\\n {\\n \\\"arguments\\\": [],\\n \\\"name\\\": \\\"init\\\",\\n \"...>>\nThe final call to jsx:prettify(jsx:encode(JsonACI)) returns the encoding in a more easily readable form. This is what is shown in the description above.
The Sophia compiler
"},{"location":"aeso_compiler/#description","title":"Description","text":"This module provides the interface to the standard Sophia compiler. It returns the compiled module in a map which can then be loaded.
"},{"location":"aeso_compiler/#types","title":"Types","text":"contract_string() = string() | binary()\ncontract_map() = #{bytecode => binary(),\ncompiler_version => binary(),\ncontract_souce => string(),\ntype_info => type_info()}\ntype_info()\nerrorstring() = binary()\nTypes
ContractString = contract_string()\nOptions = [Option]\nCompRet = {ok,ContractMap} | {error,ErrorString}\nContractMap = contract_map()\nErrorString = errorstring()\nCompile a contract defined in a file or in a string.
The pp_ options all print to standard output the following:
pp_sophia_code - print the input Sophia code.
pp_ast - print the AST of the code
pp_types - print information about the types
pp_typed_ast - print the AST with type information at each node
pp_assembler - print the generated assembler code
The option include_child_contract_symbols includes the symbols of child contracts functions in the generated fate code. It is turned off by default to avoid making contracts bigger on chain.
By default all optimizations are turned on, to disable an optimization, it should be explicitly set to false and passed as a compiler option.
List of optimizations:
Types
ContractString = string() | binary()\nCheckRet = {ok,string(),{Types,Type | any()},Terms} | {error,Term}\nTypes = [Type]\nType = term()\n__call function."},{"location":"aeso_compiler/#version-ok-version-error-term","title":"version() -> {ok, Version} | {error, term()}","text":"Types
Version = binary()\nGet the current version of the Sophia compiler.
"},{"location":"sophia/","title":"Sophia","text":"This file has been moved here
"},{"location":"sophia_examples/","title":"Contract examples","text":""},{"location":"sophia_examples/#crowdfunding","title":"Crowdfunding","text":"/*\n * A simple crowd-funding example\n */\ncontract FundMe =\n\nrecord spend_args = { recipient : address,\namount : int }\n\nrecord state = { contributions : map(address, int),\ntotal : int,\nbeneficiary : address,\ndeadline : int,\ngoal : int }\n\nstateful function spend(args : spend_args) =\nChain.spend(args.recipient, args.amount)\n\nentrypoint init(beneficiary, deadline, goal) : state =\n{ contributions = {},\nbeneficiary = beneficiary,\ndeadline = deadline,\ntotal = 0,\ngoal = goal }\n\nfunction is_contributor(addr) =\nMap.member(addr, state.contributions)\n\nstateful entrypoint contribute() =\nif(Chain.block_height >= state.deadline)\nspend({ recipient = Call.caller, amount = Call.value }) // Refund money\nfalse\nelse\nlet amount =\nswitch(Map.lookup(Call.caller, state.contributions))\nNone => Call.value\nSome(n) => n + Call.value\nput(state{ contributions[Call.caller] = amount,\ntotal @ tot = tot + Call.value })\ntrue\n\nstateful entrypoint withdraw() =\nif(Chain.block_height < state.deadline)\nabort(\"Cannot withdraw before deadline\")\nif(Call.caller == state.beneficiary)\nwithdraw_beneficiary()\nelif(is_contributor(Call.caller))\nwithdraw_contributor()\nelse\nabort(\"Not a contributor or beneficiary\")\n\nstateful function withdraw_beneficiary() =\nrequire(state.total >= state.goal, \"Project was not funded\")\nspend({recipient = state.beneficiary,\namount = Contract.balance })\n\nstateful function withdraw_contributor() =\nif(state.total >= state.goal)\nabort(\"Project was funded\")\nlet to = Call.caller\nspend({recipient = to,\namount = state.contributions[to]})\nput(state{ contributions @ c = Map.delete(to, c) })\nThis is a list with repositories that include smart contracts written in Sophia:
The main unit of code in Sophia is the contract.
state encapsulating its local state. When creating a new contract the init entrypoint is executed and the state is initialized to its return value.The language offers some primitive functions to interact with the blockchain and contracts. Please refer to the Chain, Contract and the Call namespaces in the documentation.
"},{"location":"sophia_features/#calling-other-contracts","title":"Calling other contracts","text":"To call a function in another contract you need the address to an instance of the contract. The type of the address must be a contract type, which consists of a number of type definitions and entrypoint declarations. For instance,
// A contract type\ncontract interface VotingType =\nentrypoint vote : string => unit\nNow given contract address of type VotingType you can call the vote entrypoint of that contract:
contract VoteTwice =\nentrypoint voteTwice(v : VotingType, alt : string) =\nv.vote(alt)\nv.vote(alt)\nContract 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 the defaults are no gas limit and no tokens. Suppose there is a fee for voting:
entrypoint voteTwice(v : VotingType, fee : int, alt : string) =\nv.vote(value = fee, alt)\nv.vote(value = fee, alt)\nNamed arguments can be given in any order.
Note that reentrant calls are not permitted. In other words, when calling another contract it cannot call you back (directly or indirectly).
To construct a value of a contract type you can give a contract address literal (for instance ct_2gPXZnZdKU716QBUFKaT4VdBZituK93KLvHJB3n4EnbrHHw4Ay), or convert an account address to a contract address using Address.to_contract. Note that if the contract does not exist, or it doesn't have the entrypoint, or the type of the entrypoint does not match the stated contract type, the call fails.
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) without calling it you can write
entrypoint pay(v : VotingType, amount : int) =\nChain.spend(v.address, amount)\nIf a contract call fails for any reason (for instance, the remote contract crashes or runs out of gas, or the entrypoint doesn't exist or has the wrong type) the parent call also fails. To make it possible to recover from failures, contract calls takes a named argument protected : bool (default false).
The protected argument must be a literal boolean, and when set to true changes the type of the contract call, wrapping the result in an option type. If the call fails the result is None, otherwise it's Some(r) where r is the return value of the call.
contract interface VotingType =\nentrypoint : vote : string => unit\n\ncontract Voter =\nentrypoint tryVote(v : VotingType, alt : string) =\nswitch(v.vote(alt, protected = true) : option(unit))\nNone => \"Voting failed\"\nSome(_) => \"Voting successful\"\nAny gas that was consumed by the contract call before the failure stays consumed, which means that in order to protect against the remote contract 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 transaction still only uses up the gas spent running the contract.
Any side effects (state change, token transfers, etc.) made by a failing protected call is rolled back, just like they would be in the unprotected case.
"},{"location":"sophia_features/#contract-factories-and-child-contracts","title":"Contract factories and child contracts","text":"Since the version 6.0.0 Sophia supports deploying contracts by other contracts. This can be done in two ways:
Chain.cloneChain.createThese functions take variable number of arguments that must match the created contract's init function. Beside that they take some additional named arguments \u2013 please refer to their documentation for the details.
While Chain.clone requires only a contract interface and a living instance of a given contract on the chain, Chain.create needs a full definition of a to-create contract defined by the standard contract syntax, for example
contract IntHolder =\ntype state = int\nentrypoint init(x) = x\nentrypoint get() = state\n\nmain contract IntHolderFactory =\nstateful entrypoint new(x : int) : IntHolder =\nlet ih = Chain.create(x) : IntHolder\nih\nIn case of a presence of child contracts (IntHolder in this case), the main contract must be pointed out with the main keyword as shown in the example.
Contracts can implement one or multiple interfaces, the contract has to define every entrypoint from the implemented interface and the entrypoints in both the contract and implemented interface should have compatible types.
contract interface Animal =\n entrypoint sound : () => string\n\n contract Cat : Animal =\n entrypoint sound() = \"Cat sound\"\nContract interfaces can extend other interfaces. An extended interface has to declare all entrypoints from every parent interface. All the declarations in the extended interface must have types compatible with the declarations from the parent interface.
contract interface II =\n entrypoint f : () => unit\n\ncontract interface I : II =\n entrypoint f : () => unit\n entrypoint g : () => unit\n\ncontract C : I =\n entrypoint f() = ()\n entrypoint g() = ()\nIt is only possible to implement (or extend) an interface that has been already defined earlier in the file (or in an included file). Therefore recursive interface implementation is not allowed in Sophia.
// The following code would show an error\n\ncontract interface X : Z =\n entrypoint x : () => int\n\n contract interface Y : X =\n entrypoint x : () => int\n entrypoint y : () => int\n\n contract interface Z : Y =\n entrypoint x : () => int\n entrypoint y : () => int\n entrypoint z : () => int\n\n contract C : Z =\n entrypoint x() = 1\n entrypoint y() = 1\n entrypoint z() = 1\nWhen a contract or a contract interface implements another contract interface, the payable and stateful modifiers can be kept or changed, both in the contract and in the entrypoints, according to the following rules:
payable contract or interface can implement a payable interface or a non-payable interface.payable contract or interface can only implement a non-payable interface, and cannot implement a payable interface.payable entrypoint can implement a payable entrypoint or a non-payable entrypoint.payable entrypoint can only implement a non-payable entrypoint, and cannot implement a payable entrypoint.stateful entrypoint can implement a stateful entrypoint or a non-stateful entrypoint.stateful entrypoint can only implement a stateful entrypoint, and cannot implement a non-stateful entrypoint.Subtyping in Sophia follows common rules that take type variance into account. As described by Wikipedia,
Variance refers to how subtyping between more complex types relates to subtyping between their components.
This concept plays an important role in complex types such as tuples, datatypes and functions. Depending on the context, it can apply to positions in the structure of a type, or type parameters of generic types. There are four kinds of variances:
A type is said to be on a \"covariant\" position when it describes output or a result of some computation. Analogously, position is \"contravariant\" when it is an input, or a parameter. Intuitively, when a part of the type is produced by values of it, it is covariant. When it is consumed, it is contravariant. When a type appears to be simultaneously input and output, it is described as invariant. If a type is neither of those (that is, it's unused) it's bivariant. Furthermore, whenever a complex type appears on a contravariant position, all its covariant components become contravariant and vice versa.
Variance influences how subtyping is applied. Types on covariant positions are subtyped normally, while contravariant the opposite way. Invariant types have to be exactly the same in order for subtyping to work. Bivariant types are always compatible.
A good example of where it matters can be pictured by subtyping of function types. Let us assume there is a contract interface Animal and two contracts that implement it: Dog and Cat.
contract interface Animal =\nentrypoint age : () => int\n\ncontract Dog : Animal =\nentrypoint age() = // ...\nentrypoint woof() = \"woof\"\n\ncontract Cat : Animal =\nentrypoint age() = // ...\nentrypoint meow() = \"meow\"\nThe assumption of this exercise is that cats do not bark (because Cat does not define the woof entrypoint). If subtyping rules were applied naively, that is if we let Dog => Dog be a subtype of Animal => Animal, the following code would break:
let f : (Dog) => string = d => d.woof()\nlet g : (Animal) => string = f\nlet c : Cat = Chain.create()\ng(c) // Cat barking!\nThat is because arguments of functions are contravariant, as opposed to return the type which is covariant. Because of that, the assignment of f to g is invalid - while Dog is a subtype of Animal, Dog => string is not a subtype of Animal => string. However, Animal => string is a subtype of Dog => string. More than that, (Dog => Animal) => Dog is a subtype of (Animal => Dog) => Animal.
This has consequences on how user-defined generic types work. A type variable gains its variance from its role in the type definition as shown in the example:
datatype co('a) = Co('a) // co is covariant on 'a\ndatatype ct('a) = Ct('a => unit) // ct is contravariant on 'a\ndatatype in('a) = In('a => 'a) // in is invariant on 'a\ndatatype bi('a) = Bi // bi is bivariant on 'a\nThe following facts apply here:
co('a) is a subtype of co('b) when 'a is a subtype of 'bct('a) is a subtype of ct('b) when 'b is a subtype of 'ain('a) is a subtype of in('b) when 'a is equal to 'bbi('a) is a subtype of bi('b) alwaysThat altogether induce the following rules of subtyping in Sophia:
A function type (Args1) => Ret1 is a subtype of (Args2) => Ret2 when Ret1 is a subtype of Ret2 and each argument type from Args2 is a subtype of its counterpart in Args1.
A list type list(A) is a subtype of list(B) if A is a subtype of B.
An option type option(A) is a subtype of option(B) if A is a subtype of B.
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.
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)
When a user-defined type t('a) is covariant in 'a, then t(A) is a subtype of t(B) when A is a subtype of B.
When a user-defined type t('a) is contravariant in 'a, then t(A) is a subtype of t(B) when B is a subtype of A.
When a user-defined type t('a) is binvariant in 'a, then t(A) is a subtype of t(B) when either A is a subtype of B or when B is a subtype of A.
When a user-defined type t('a) is invariant in 'a, then t(A) can never be a subtype of t(B).
Sophia does not have arbitrary mutable state, but only a limited form of state associated with each contract instance.
state encapsulating its mutable state. The type state defaults to the unit.init function. The init function is pure and returns the initial state as its return value. If the type state is unit, the init function defaults to returning the value (). At contract creation time, the init function is executed and its result is stored as the contract state.state.put : state => unit.put function (and similar functions for transactions and events), the language is purely functional.stateful keyword (see below).To make it convenient to update parts of a deeply nested state Sophia provides special syntax for map/record updates.
"},{"location":"sophia_features/#stateful-functions","title":"Stateful functions","text":"Top-level functions and entrypoints must be annotated with the stateful keyword to be allowed to affect the state of the running contract. For instance,
stateful entrypoint set_state(s : state) =\nput(s)\nWithout the stateful annotation the compiler does not allow the call to put. A stateful annotation is required to
putChain.spendOracle.registerOracle.queryOracle.respondOracle.extendAENS.preclaimAENS.claimAENS.transferAENS.revokeAENS.updatestateful function in the current contractvalue argument.A stateful annotation is not required to
event function.value = 0, even if the called function is stateful.A concrete contract is by default not payable. Any attempt at spending to such a contract (either a Chain.spend or a normal spend transaction) will fail. If a contract shall be able to receive funds in this way it has to be declared payable:
// A payable contract\npayable contract ExampleContract =\nstateful entrypoint do_stuff() = ...\nIf in doubt, it is possible to check if an address is payable using Address.is_payable(addr).
A contract entrypoint is by default not payable. Any call to such a function (either a Remote call or a contract call transaction) that has a non-zero value will fail. Contract entrypoints that should be called with a non-zero value should be declared payable.
payable stateful entrypoint buy(to : address) =\nif(Call.value > 42)\ntransfer_item(to)\nelse\nabort(\"Value too low\")\nCode can be split into libraries using the namespace construct. Namespaces can appear at the top-level and can contain type and function definitions, but not entrypoints. Outside the namespace you can refer to the (non-private) names by qualifying them with the namespace (Namespace.name). For example,
namespace Library =\ntype number = int\nfunction inc(x : number) : number = x + 1\n\ncontract MyContract =\nentrypoint plus2(x) : Library.number =\nLibrary.inc(Library.inc(x))\nFunctions in namespaces have access to the same environment (including the Chain, Call, and Contract, builtin namespaces) as function in a contract, with the exception of state, put and Chain.event since these are dependent on the specific state and event types of the contract.
To avoid mentioning the namespace every time it is used, Sophia allows including the namespace in the current scope with the using keyword:
include \"Pair.aes\"\nusing Pair\ncontract C =\n type state = int\n entrypoint init() =\n let p = (1, 2)\n fst(p) // this is the same as Pair.fst(p)\nIt is also possible to make an alias for the namespace with the as keyword:
include \"Pair.aes\"\ncontract C =\n using Pair as P\n type state = int\n entrypoint init() =\n let p = (1, 2)\n P.fst(p) // this is the same as Pair.fst(p)\nHaving the same alias for multiple namespaces is possible and it allows referening functions that are defined in different namespaces and have different names with the same alias:
namespace Xa = function f() = 1\nnamespace Xb = function g() = 2\ncontract Cntr =\n using Xa as A\n using Xb as A\n type state = int\n entrypoint init() = A.f() + A.g()\nNote that using functions with the same name would result in an ambiguous name error:
namespace Xa = function f() = 1\nnamespace Xb = function f() = 2\ncontract Cntr =\n using Xa as A\n using Xb as A\n type state = int\n\n // the next line has an error because f is defined in both Xa and Xb\n entrypoint init() = A.f()\nImporting specific parts of a namespace or hiding these parts can also be done like this:
using Pair for [fst, snd] // this will only import fst and snd\nusing Triple hiding [fst, snd] // this will import everything except for fst and snd\nNote that it is possible to use a namespace in the top level of the file, in the contract level, namespace level, or in the function level.
"},{"location":"sophia_features/#splitting-code-over-multiple-files","title":"Splitting code over multiple files","text":"Code from another file can be included in a contract using an include statement. These must appear at the top-level (outside the main contract). The included file can contain one or more namespaces and abstract contracts. For example, if the file library.aes contains
namespace Library =\nfunction inc(x) = x + 1\nyou can use it from another file using an include:
include \"library.aes\"\ncontract MyContract =\nentrypoint plus2(x) = Library.inc(Library.inc(x))\nThis behaves as if the contents of library.aes was textually inserted into the file, except that error messages will refer to the original source locations. The language will try to include each file at most one time automatically, so even cyclic includes should be working without any special tinkering.
Sophia offers standard library which exposes some primitive operations and some higher level utilities. The builtin namespaces like Chain, Contract, Map are included by default and are supported internally by the compiler. Others like List, Frac, Option need to be manually included using the include directive. For example
include \"List.aes\"\ninclude \"Pair.aes\"\n-- Map is already there!\n\nnamespace C =\nentrypoint keys(m : map('a, 'b)) : list('a) =\nList.map(Pair.fst, (Map.to_list(m)))\nSophia has the following types:
Type Description Example int A 2-complement integer-1 address \u00e6ternity address, 32 bytes Call.origin bool A Boolean true bits A bit field Bits.none bytes(n) A byte array with n bytes #fedcba9876543210 string An array of bytes \"Foo\" list A homogeneous immutable singly linked list. [1, 2, 3] ('a, 'b) => 'c A function. Parentheses can be skipped if there is only one argument (x : int, y : int) => x + y tuple An ordered heterogeneous array (42, \"Foo\", true) record An immutable key value store with fixed key names and typed values record balance = { owner: address, value: int } map An immutable key value store with dynamic mapping of keys of one type to values of one type type accounts = map(string, address) option('a) An optional value either None or Some('a) Some(42) state A user defined type holding the contract state record state = { owner: address, magic_key: bytes(4) } event An append only list of blockchain events (or log entries) datatype event = EventX(indexed int, string) hash A 32-byte hash - equivalent to bytes(32) signature A signature - equivalent to bytes(64) 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()"},{"location":"sophia_features/#literals","title":"Literals","text":"Type Constant/Literal example(s) int -1, 2425, 4598275923475723498573485768 address ak_2gx9MEFxKvY9vMG5YnqnXWv1hCsX7rgnfvBLJS4aQurustR1rt bool true, false bits Bits.none, Bits.all bytes(8) #fedcba9876543210 string \"This is a string\" list [1, 2, 3], [(true, 24), (false, 19), (false, -42)] tuple (42, \"Foo\", true) record { owner = Call.origin, value = 100000000 } map {[\"foo\"] = 19, [\"bar\"] = 42}, {} option(int) Some(42), None state state{ owner = Call.origin, magic_key = #a298105f } event EventX(0, \"Hello\") hash #000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f signature #000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f Chain.ttl FixedTTL(1050), RelativeTTL(50) oracle('a, 'b) ok_2YNyxd6TRJPNrTcEDCe9ra59SVUdp9FR9qWC5msKZWYD9bP9z5 oracle_query('a, 'b) oq_2oRvyowJuJnEkxy58Ckkw77XfWJrmRgmGaLzhdqb67SKEL1gPY contract ct_Ez6MyeTMm17YnTnDdHTSrzMEBKmy7Uz2sXu347bTDPgVH2ifJ"},{"location":"sophia_features/#hole-expression","title":"Hole expression","text":"Hole expressions, written as ???, are expressions that are used as a placeholder. During compilation, the compiler will generate a type error indication the type of the hole expression.
include \"List.aes\"\ncontract C =\n entrypoint f() =\n List.sum(List.map(???, [1,2,3]))\nA hole expression found in the example above will generate the error Found a hole of type `(int) => int`. This says that the compiler expects a function from int to int in place of the ??? placeholder.
Constants in Sophia are contract-level bindings that can be used in either contracts or namespaces. The value of a constant can be a literal, another constant, or arithmetic operations applied to other constants. Lists, tuples, maps, and records can also be used to define a constant as long as their elements are also constants.
The following visibility rules apply to constants: * Constants defined inside a contract are private in that contract. Thus, cannot be accessed through instances of their defining contract. * Constants defined inside a namespace are public. Thus, can be used in other contracts or namespaces. * Constants cannot be defined inside a contract interface.
When a constant is shadowed, it can be accessed using its qualified name:
contract C =\n let c = 1\n entrypoint f() =\n let c = 2\n c + C.c // the result is 3\nThe name of the constant must be an id; therefore, no pattern matching is allowed when defining a constant:
contract C\n let x::y::_ = [1,2,3] // this will result in an error\nSophia integers (int) are represented by arbitrary-sized signed words and support the following arithmetic operations: - addition (x + y) - subtraction (x - y) - multiplication (x * y) - division (x / y), truncated towards zero - remainder (x mod y), satisfying y * (x / y) + x mod y == x for non-zero y - exponentiation (x ^ y)
All operations are safe with respect to overflow and underflow. The division and modulo operations throw an arithmetic error if the right-hand operand is zero.
"},{"location":"sophia_features/#bit-fields","title":"Bit fields","text":"Sophia integers do not support bit arithmetic. Instead there is a separate type bits. See the standard library documentation.
A bit field can be of arbitrary size (but it is still represented by the corresponding integer, so setting very high bits can be expensive).
"},{"location":"sophia_features/#type-aliases","title":"Type aliases","text":"Type aliases can be introduced with the type keyword and can be parameterized. For instance
type number = int\ntype string_map('a) = map(string, 'a)\nA type alias and its definition can be used interchangeably. Sophia does not support higher-kinded types, meaning that following type alias is invalid: type wrap('f, 'a) = 'f('a)
Sophia supports algebraic data types (variant types) and pattern matching. Data types are declared by giving a list of constructors with their respective arguments. For instance,
datatype one_or_both('a, 'b) = Left('a) | Right('b) | Both('a, 'b)\nElements of data types can be pattern matched against, using the switch construct:
function get_left(x : one_or_both('a, 'b)) : option('a) =\nswitch(x)\nLeft(x) => Some(x)\nRight(_) => None\nBoth(x, _) => Some(x)\nor directly in the left-hand side:
function\nget_left : one_or_both('a, 'b) => option('a)\nget_left(Left(x)) = Some(x)\nget_left(Right(_)) = None\nget_left(Both(x, _)) = Some(x)\nNOTE: Data types cannot currently be recursive.
Sophia also supports the assignment of patterns to variables:
function f(x) = switch(x)\nh1::(t = h2::_) => (h1 + h2)::t // same as `h1::h2::k => (h1 + h2)::h2::k`\n_ => x\n\nfunction g(p : int * option(int)) : int =\nlet (a, (o = Some(b))) = p // o is equal to Pair.snd(p)\nb\nGuards are boolean expressions that can be used on patterns in both switch statements and functions definitions. If a guard expression evaluates to true, then the corresponding body will be used. Otherwise, the next pattern will be checked:
function get_left_if_positive(x : one_or_both(int, 'b)) : option(int) =\nswitch(x)\nLeft(x) | x > 0 => Some(x)\nBoth(x, _) | x > 0 => Some(x)\n_ => None\nfunction\nget_left_if_positive : one_or_both(int, 'b) => option(int)\nget_left_if_positive(Left(x)) | x > 0 = Some(x)\nget_left_if_positive(Both(x, _)) | x > 0 = Some(x)\nget_left_if_positive(_) = None\nGuards cannot be stateful even when used inside a stateful function.
"},{"location":"sophia_features/#lists","title":"Lists","text":"A Sophia list is a dynamically sized, homogenous, immutable, singly linked list. A list is constructed with the syntax [1, 2, 3]. The elements of a list can be any of datatype but they must have the same type. The type of lists with elements of type 'e is written list('e). For example we can have the following lists:
[1, 33, 2, 666] : list(int)\n[(1, \"aaa\"), (10, \"jjj\"), (666, \"the beast\")] : list(int * string)\n[{[1] = \"aaa\", [10] = \"jjj\"}, {[5] = \"eee\", [666] = \"the beast\"}] : list(map(int, string))\nNew elements can be prepended to the front of a list with the :: operator. So 42 :: [1, 2, 3] returns the list [42, 1, 2, 3]. The concatenation operator ++ appends its second argument to its first and returns the resulting list. So concatenating two lists [1, 22, 33] ++ [10, 18, 55] returns the list [1, 22, 33, 10, 18, 55].
Sophia supports list comprehensions known from languages like Python, Haskell or Erlang. Example syntax:
[x + y | x <- [1,2,3,4,5], let k = x*x, if (k > 5), y <- [k, k+1, k+2]]\n// yields [12,13,14,20,21,22,30,31,32]\nLists can be constructed using the range syntax using special .. operator:
[1..4] == [1,2,3,4]\nPlease refer to the standard library for the predefined functionalities.
"},{"location":"sophia_features/#maps-and-records","title":"Maps and records","text":"A Sophia record type is given by a fixed set of fields with associated, possibly different, types. For instance
record account = { name : string,\nbalance : int,\nhistory : list(transaction) }\nMaps, on the other hand, can contain an arbitrary number of key-value bindings, but of a fixed type. The type of maps with keys of type 'k and values of type 'v is written map('k, 'v). The key type can be any type that does not contain a map or a function type.
Please refer to the standard library for the predefined functionalities.
"},{"location":"sophia_features/#constructing-maps-and-records","title":"Constructing maps and records","text":"A value of record type is constructed by giving a value for each of the fields. For the example above,
function new_account(name) =\n{name = name, balance = 0, history = []}\n function example_map() : map(string, int) =\n{[\"key1\"] = 1, [\"key2\"] = 2}\n{}."},{"location":"sophia_features/#accessing-values","title":"Accessing values","text":"Record fields access is written r.f and map lookup m[k]. For instance,
function get_balance(a : address, accounts : map(address, account)) =\naccounts[a].balance\nm[k = default]. See also Map.member and Map.lookup below."},{"location":"sophia_features/#updating-a-value","title":"Updating a value","text":"Record field updates are written r{f = v}. This creates a new record value which is the same as r, but with the value of the field f replaced by v. Similarly, m{[k] = v} constructs a map with the same values as m except that k maps to v. It makes no difference if m has a mapping for k or not.
It is possible to give a name to the old value of a field or mapping in an update: instead of acc{ balance = acc.balance + 100 } it is possible to write acc{ balance @ b = b + 100 }, binding b to acc.balance. When giving a name to a map value (m{ [k] @ x = v }), the corresponding key must be present in the map or execution fails, but a default value can be provided: m{ [k = default] @ x = v }. In this case x is bound to default if k is not in the map.
Updates can be nested:
function clear_history(a : address, accounts : map(address, account)) : map(address, account) =\naccounts{ [a].history = [] }\naccounts{ [a] @ acc = acc{ history = [] } } and thus requires a to be present in the accounts map. To have clear_history create an account if a is not in the map you can write (given a function empty_account): accounts{ [a = empty_account()].history = [] }\nInternally in the VM maps are implemented as hash maps and support fast lookup and update. Large maps can be stored in the contract state and the size of the map does not contribute to the gas costs of a contract call reading or updating it.
"},{"location":"sophia_features/#strings","title":"Strings","text":"There is a builtin type string, which can be seen as an array of bytes. Strings can be compared for equality (==, !=), used as keys in maps and records, and used in builtin functions String.length, String.concat and the hash functions described below.
Please refer to the String library documentation.
There is a builtin type char (the underlying representation being an integer), mainly used to manipulate strings via String.to_list/String.from_list.
Characters can also be introduced as character literals (`'x', '+', ...).
Please refer to the Char library documentation.
Byte arrays are fixed size arrays of 8-bit integers. They are described in hexadecimal system, for example the literal #cafe creates a two-element array of bytes ca (202) and fe (254) and thus is a value of type bytes(2).
Please refer to the Bytes library documentation.
Libraries Crypto and String provide functions to hash objects, verify signatures etc. The hash is a type alias for bytes(32).
When a Generalized account is authorized, the authorization function needs access to the transaction and the transaction hash for the wrapped transaction. (A GAMetaTx wrapping a transaction.) The transaction and the transaction hash is available in the primitive Auth.tx and Auth.tx_hash respectively, they are only available during authentication if invoked by a normal contract call they return None.
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. For a functionality documentation refer to the standard library.
"},{"location":"sophia_features/#example","title":"Example","text":"Example for an oracle answering questions of type string with answers of type int:
contract Oracles =\n\nstateful entrypoint registerOracle(acct : address,\nsign : signature, // Signed network id + oracle address + contract address\nqfee : int,\nttl : Chain.ttl) : oracle(string, int) =\nOracle.register(acct, signature = sign, qfee, ttl)\n\nentrypoint queryFee(o : oracle(string, int)) : int =\nOracle.query_fee(o)\n\npayable stateful entrypoint createQuery(o : oracle_query(string, int),\nq : string,\nqfee : int,\nqttl : Chain.ttl,\nrttl : int) : oracle_query(string, int) =\nrequire(qfee =< Call.value, \"insufficient value for qfee\")\nOracle.query(o, q, qfee, qttl, RelativeTTL(rttl))\n\nstateful entrypoint extendOracle(o : oracle(string, int),\nttl : Chain.ttl) : unit =\nOracle.extend(o, ttl)\n\nstateful entrypoint signExtendOracle(o : oracle(string, int),\nsign : signature, // Signed network id + oracle address + contract address\nttl : Chain.ttl) : unit =\nOracle.extend(o, signature = sign, ttl)\n\nstateful entrypoint respond(o : oracle(string, int),\nq : oracle_query(string, int),\nsign : signature, // Signed network id + oracle query id + contract address\nr : int) =\nOracle.respond(o, q, signature = sign, r)\n\nentrypoint getQuestion(o : oracle(string, int),\nq : oracle_query(string, int)) : string =\nOracle.get_question(o, q)\n\nentrypoint hasAnswer(o : oracle(string, int),\nq : oracle_query(string, int)) =\nswitch(Oracle.get_answer(o, q))\nNone => false\nSome(_) => true\n\nentrypoint getAnswer(o : oracle(string, int),\nq : oracle_query(string, int)) : option(int) =\nOracle.get_answer(o, q)\nWhen an Oracle literal is passed to a contract, no deep checks are performed. For extra safety Oracle.check and Oracle.check_query functions are provided.
"},{"location":"sophia_features/#aens-interface","title":"AENS interface","text":"Contracts can interact with the \u00e6ternity naming system. For this purpose the AENS library was exposed.
"},{"location":"sophia_features/#example_1","title":"Example","text":"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 name the account holder needs to create a signature sig of addr | name.hash | ct.address.
Armed with this information we can for example write a function that extends the name if it expires within 1000 blocks:
stateful entrypoint extend_if_necessary(addr : address, name : string, sig : signature) =\nswitch(AENS.lookup(name))\nNone => ()\nSome(AENS.Name(_, FixedTTL(expiry), _)) =>\nif(Chain.block_height + 1000 > expiry)\nAENS.update(addr, name, Some(RelativeTTL(50000)), None, None, signature = sig)\nAnd we can write functions that adds and removes keys from the pointers of the name:
stateful entrypoint add_key(addr : address, name : string, key : string,\npt : AENS.pointee, sig : signature) =\nswitch(AENS.lookup(name))\nNone => ()\nSome(AENS.Name(_, _, ptrs)) =>\nAENS.update(addr, name, None, None, Some(ptrs{[key] = pt}), signature = sig)\n\nstateful entrypoint delete_key(addr : address, name : string,\nkey : string, sig : signature) =\nswitch(AENS.lookup(name))\nNone => ()\nSome(AENS.Name(_, _, ptrs)) =>\nlet ptrs = Map.delete(key, ptrs)\nAENS.update(addr, name, None, None, Some(ptrs), signature = sig)\nNote: From the Iris hardfork more strict rules apply for AENS pointers, when a Sophia contract lookup or update (bad) legacy pointers, the bad keys are automatically removed so they will not appear in the pointers map.
"},{"location":"sophia_features/#events","title":"Events","text":"Sophia contracts log structured messages to an event log in the resulting blockchain transaction. The event log is quite similar to Events in Solidity. Events are further discussed in the protocol.
To use events a contract must declare a datatype event, and events are then logged using the Chain.event function:
datatype event\n= Event1(int, int, string)\n| Event2(string, address)\n\nChain.event(e : event) : unit\nThe event can have 0-3 indexed fields, and an optional payload field. A field is indexed if it fits in a 32-byte word, i.e. - bool - int - bits - address - oracle(_, _) - oracle_query(_, _) - contract types - bytes(n) for n \u2264 32, in particular hash
The payload field must be either a string or a byte array of more than 32 bytes. The fields can appear in any order.
NOTE: Indexing is not part of the core \u00e6ternity node.
Events are emitted by using the Chain.event function. The following function will emit one Event of each kind in the example.
entrypoint emit_events() : () =\nChain.event(Event1(42, 34, \"foo\"))\nChain.event(Event2(\"This is not indexed\", Contract.address))\nIt is only possible to have one (1) string parameter in the event, but it can be placed in any position (and its value will end up in the data field), i.e.
AnotherEvent(string, indexed address)\n\n...\n\nChain.event(AnotherEvent(\"This is not indexed\", Contract.address))\nTo enforce that a contract is only compiled with specific versions of the Sophia compiler, you can give one or more @compiler pragmas at the top-level (typically at the beginning) of a file. For instance, to enforce that a contract is compiled with version 4.3 of the compiler you write
@compiler >= 4.3\n@compiler < 4.4\nValid operators in compiler pragmas are <, =<, ==, >=, and >. Version numbers are given as a sequence of non-negative integers separated by dots. Trailing zeros are ignored, so 4.0.0 == 4. If a constraint is violated an error is reported and compilation fails.
Contracts can fail with an (uncatchable) exception using the built-in function
abort(reason : string) : 'a\nCalling abort causes the top-level call transaction to return an error result containing the reason string. Only the gas used up to and including the abort call is charged. This is different from termination due to a crash which consumes all available gas.
For convenience the following function is also built-in:
function require(b : bool, err : string) =\nif(!b) abort(err)\nAside from that, there is an almost equivalent function exit
exit(reason : string) : 'a\nJust like abort, it breaks the execution with the given reason. The difference however is in the gas consumption \u2014 while abort returns unused gas, a call to exit burns it all.
Some chain operations (Oracle.<operation> and AENS.<operation>) have an 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 signed varies for the different operations, but in all cases you should prepend the signature data with the network_id (ae_mainnet for the \u00e6ternity mainnet, etc.).
Sophia language offers standard library that consists of several namespaces. Some of them are already in the scope and do not need any actions to be used, while the others require some files to be included.
The out-of-the-box namespaces are:
The following ones need to be included as regular files with .aes suffix, for example
include \"List.aes\"\nThey are available without any explicit includes.
"},{"location":"sophia_stdlib/#address","title":"Address","text":""},{"location":"sophia_stdlib/#to_str","title":"to_str","text":"Address.to_str(a : address) : string\nBase58 encoded string
"},{"location":"sophia_stdlib/#is_contract","title":"is_contract","text":"Address.is_contract(a : address) : bool\nIs the address a contract
"},{"location":"sophia_stdlib/#is_oracle","title":"is_oracle","text":"Address.is_oracle(a : address) : bool\nIs the address a registered oracle
"},{"location":"sophia_stdlib/#is_payable","title":"is_payable","text":"Address.is_payable(a : address) : bool\nCan the address be spent to
"},{"location":"sophia_stdlib/#to_contract","title":"to_contract","text":"Address.to_contract(a : address) : C\nCast address to contract type C (where C is a contract)
The following functionality is available for interacting with the \u00e6ternity 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, i.e. the signature material should be prefixed by the network id.
datatype name = Name(address, Chain.ttl, map(string, AENS.pointee))\ndatatype pointee = AccountPt(address) | OraclePt(address)\n | ContractPt(address) | ChannelPt(address)\nAENS.resolve(name : string, key : string) : option('a)\nName resolution. Here name should be a registered name and key one of the attributes associated with this name (for instance \"account_pubkey\"). The return type ('a) must be resolved at compile time to an atomic type and the value is type checked against this type at run time.
AENS.lookup(name : string) : option(AENS.name)\nIf name is an active name AENS.lookup returns a name object. 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. For example:
let Some(Name(owner, FixedTTL(expiry), ptrs)) = AENS.lookup(\"example.chain\")\nAENS.preclaim(owner : address, commitment_hash : hash, <signature : signature>) : unit\nThe signature should be over network id + owner address + Contract.address (concatenated as byte arrays).
AENS.claim(owner : address, name : string, salt : int, name_fee : int, <signature : signature>) : unit\nThe signature should be over network id + owner address + name_hash + Contract.address (concatenated as byte arrays) using the private key of the owner account for signing.
AENS.transfer(owner : address, new_owner : address, name : string, <signature : signature>) : unit\nTransfers name to the new owner.
The signature should be over network id + owner address + name_hash + Contract.address (concatenated as byte arrays) using the private key of the owner account for signing.
AENS.revoke(owner : address, name : string, <signature : signature>) : unit\nRevokes the name to extend the ownership time.
The signature should be over network id + owner address + name_hash + Contract.address (concatenated as byte arrays) using the private key of the owner account for signing.
AENS.update(owner : address, name : string, expiry : option(Chain.ttl), client_ttl : option(int),\n new_ptrs : option(map(string, AENS.pointee)), <signature : signature>) : unit\nUpdates 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 block of the name is not changed.
Auth.tx : option(Chain.tx)\nWhere Chain.tx is (built-in) defined like:
namespace Chain =\n record tx = { paying_for : option(Chain.paying_for_tx)\n , ga_metas : list(Chain.ga_meta_tx)\n , actor : address\n , fee : int\n , ttl : int\n , tx : Chain.base_tx }\n\n datatype ga_meta_tx = GAMetaTx(address, int)\n datatype paying_for_tx = PayingForTx(address, int)\n datatype base_tx = SpendTx(address, int, string)\n | OracleRegisterTx | OracleQueryTx | OracleResponseTx | OracleExtendTx\n | NamePreclaimTx | NameClaimTx(hash) | NameUpdateTx(string)\n | NameRevokeTx(hash) | NameTransferTx(address, string)\n | ChannelCreateTx(address) | ChannelDepositTx(address, int) | ChannelWithdrawTx(address, int) |\n | ChannelForceProgressTx(address) | ChannelCloseMutualTx(address) | ChannelCloseSoloTx(address)\n | ChannelSlashTx(address) | ChannelSettleTx(address) | ChannelSnapshotSoloTx(address)\n | ContractCreateTx(int) | ContractCallTx(address, int)\n | GAAttachTx\nAuth.tx_hash : option(hash)\nGets the transaction hash during authentication.
"},{"location":"sophia_stdlib/#bits","title":"Bits","text":""},{"location":"sophia_stdlib/#none","title":"none","text":"Bits.none : bits\nA bit field with all bits cleared
"},{"location":"sophia_stdlib/#all","title":"all","text":"Bits.all : bits\nA bit field with all bits set
"},{"location":"sophia_stdlib/#set","title":"set","text":"Bits.set(b : bits, i : int) : bits\nSet bit i
"},{"location":"sophia_stdlib/#clear","title":"clear","text":"Bits.clear(b : bits, i : int) : bits\nClear bit i
"},{"location":"sophia_stdlib/#test","title":"test","text":"Bits.test(b : bits, i : int) : bool\nCheck if bit i is set
"},{"location":"sophia_stdlib/#sum","title":"sum","text":"Bits.sum(b : bits) : int\nCount the number of set bits
"},{"location":"sophia_stdlib/#union","title":"union","text":"Bits.union(a : bits, b : bits) : bits\nBitwise disjunction
"},{"location":"sophia_stdlib/#intersection","title":"intersection","text":"Bits.intersection(a : bits, b : bits) : bits\nBitwise conjunction
"},{"location":"sophia_stdlib/#difference","title":"difference","text":"Bits.difference(a : bits, b : bits) : bits\nEach bit is true if and only if it was 1 in a and 0 in b
Bytes.to_int(b : bytes(n)) : int\nInterprets the byte array as a big endian integer
"},{"location":"sophia_stdlib/#to_str_1","title":"to_str","text":"Bytes.to_str(b : bytes(n)) : string\nReturns the hexadecimal representation of the byte array
"},{"location":"sophia_stdlib/#concat","title":"concat","text":"Bytes.concat : (a : bytes(m), b : bytes(n)) => bytes(m + n)\nConcatenates two byte arrays
"},{"location":"sophia_stdlib/#split","title":"split","text":"Bytes.split(a : bytes(m + n)) : bytes(m) * bytes(n)\nSplits a byte array at given index
"},{"location":"sophia_stdlib/#call","title":"Call","text":"Values related to the call to the current contract
"},{"location":"sophia_stdlib/#origin","title":"origin","text":"Call.origin : address\nThe address of the account that signed the call transaction that led to this call.
"},{"location":"sophia_stdlib/#caller","title":"caller","text":"Call.caller : address\nThe address of the entity (possibly another contract) calling the contract.
"},{"location":"sophia_stdlib/#value","title":"value","text":"Call.value : int\nThe amount of coins transferred to the contract in the call.
"},{"location":"sophia_stdlib/#gas_price","title":"gas_price","text":"Call.gas_price : int\nThe gas price of the current call.
"},{"location":"sophia_stdlib/#fee","title":"fee","text":"Call.fee : int\nThe fee of the current call.
"},{"location":"sophia_stdlib/#gas_left","title":"gas_left","text":"Call.gas_left() : int\nThe amount of gas left for the current call.
"},{"location":"sophia_stdlib/#chain","title":"Chain","text":"Values and functions related to the chain itself and other entities that live on it.
"},{"location":"sophia_stdlib/#types_1","title":"Types","text":""},{"location":"sophia_stdlib/#tx_1","title":"tx","text":"record tx = { paying_for : option(Chain.paying_for_tx)\n , ga_metas : list(Chain.ga_meta_tx)\n , actor : address\n , fee : int\n , ttl : int\n , tx : Chain.base_tx }\ndatatype ga_meta_tx = GAMetaTx(address, int)\ndatatype paying_for_tx = PayingForTx(address, int)\ndatatype base_tx = SpendTx(address, int, string)\n | OracleRegisterTx | OracleQueryTx | OracleResponseTx | OracleExtendTx\n | NamePreclaimTx | NameClaimTx(hash) | NameUpdateTx(string)\n | NameRevokeTx(hash) | NameTransferTx(address, string)\n | ChannelCreateTx(address) | ChannelDepositTx(address, int) | ChannelWithdrawTx(address, int) |\n | ChannelForceProgressTx(address) | ChannelCloseMutualTx(address) | ChannelCloseSoloTx(address)\n | ChannelSlashTx(address) | ChannelSettleTx(address) | ChannelSnapshotSoloTx(address)\n | ContractCreateTx(int) | ContractCallTx(address, int)\n | GAAttachTx\nChain.balance(a : address) : int\nThe balance of account a.
Chain.block_hash(h : int) : option(bytes(32))\nThe hash of the block at height h. h has to be within 256 blocks from the current height of the chain or else the function will return None.
NOTE: In FATE VM version 1 Chain.block_height was not considered an allowed height. From FATE VM version 2 (IRIS) it will return the block hash of the current generation.
Chain.block_height : int\"\nThe height of the current block (i.e. the block in which the current call will be included).
"},{"location":"sophia_stdlib/#bytecode_hash","title":"bytecode_hash","text":"Chain.bytecode_hash : 'c => option(hash)\nReturns the hash of the contract's bytecode (or None if it is nonexistent or deployed before FATE2). The type 'c must be instantiated with a contract. The charged gas increases linearly to the size of the serialized bytecode of the deployed contract.
Chain.create(value : int, ...) => 'c\nCreates and deploys a new instance of a contract 'c. All of the unnamed arguments will be passed to the init function. The charged gas increases linearly with the size of the compiled child contract's bytecode. The source_hash on-chain entry of the newly created contract will be the SHA256 hash over concatenation of
The resulting contract's public key can be predicted and in case it happens to have some funds before its creation, its balance will be increased by the value parameter.
The value argument (default 0) is equivalent to the value in the contract creation transaction \u2013 it sets the initial value of the newly created contract charging the calling contract. Note that this won't be visible in Call.value in the init call of the new contract. It will be included in Contract.balance, however.
The type 'c must be instantiated with a contract.
Example usage:
payable contract Auction =\n record state = {supply: int, name: string}\n entrypoint init(supply, name) = {supply: supply, name: name}\n stateful payable entrypoint buy(amount) =\n require(Call.value == amount, \"amount_value_mismatch\")\n ...\n stateful entrypoint sell(amount) =\n require(amount >= 0, \"negative_amount\")\n ...\n\nmain contract Market =\n type state = list(Auction)\n entrypoint init() = []\n stateful entrypoint new(name : string) =\n let new_auction = Chain.create(0, name) : Auction\n put(new_auction::state)\nThe typechecker must be certain about the created contract's type, so it is worth writing it explicitly as shown in the example.
"},{"location":"sophia_stdlib/#clone","title":"clone","text":"Chain.clone : ( ref : 'c, gas : int, value : int, protected : bool, ...\n ) => if(protected) option('c) else 'c\nClones the contract under the mandatory named argument ref. That means a new contract of the same bytecode and the same payable parameter shall be created. NOTE: the state won't be copied and the contract will be initialized with a regular call to the init function with the remaining unnamed arguments. The resulting contract's public key can be predicted and in case it happens to have some funds before its creation, its balance will be increased by the value parameter. This operation is significantly cheaper than Chain.create as it costs a fixed amount of gas.
The gas argument (default Call.gas_left) limits the gas supply for the init call of the cloned contract.
The value argument (default 0) is equivalent to the value in the contract creation transaction \u2013 it sets the initial value of the newly created contract charging the calling contract. Note that this won't be visible in Call.value in the init call of the new contract. It will be included in Contract.balance, however.
The protected argument (default false) works identically as in remote calls. If set to true it will change the return type to option('c) and will catch all errors such as abort, out of gas and wrong arguments. Note that it can only take a boolean literal, so other expressions such as variables will be rejected by the compiler.
The type 'c must be instantiated with a contract.
Example usage:
payable contract interface Auction =\n entrypoint init : (int, string) => void\n stateful payable entrypoint buy : (int) => ()\n stateful entrypoint sell : (int) => ()\n\nmain contract Market =\n type state = list(Auction)\n entrypoint init() = []\n stateful entrypoint new_of(template : Auction, name : string) =\n switch(Chain.clone(ref=template, protected=true, 0, name))\n None => abort(\"Bad auction!\")\n Some(new_auction) =>\n put(new_auction::state)\nWhen cloning by an interface, init entrypoint declaration is required. It is a good practice to set its return type to void in order to indicate that this function is not supposed to be called and is state agnostic. Trivia: internal implementation of the init function does not actually return state, but calls put instead. Moreover, FATE prevents even handcrafted calls to init.
Chain.coinbase : address\nThe address of the account that mined the current block.
"},{"location":"sophia_stdlib/#difficulty","title":"difficulty","text":"Chain.difficulty : int\nThe difficulty of the current block.
"},{"location":"sophia_stdlib/#event","title":"event","text":"Chain.event(e : event) : unit\nEmits the event. To use this function one needs to define the event type as a datatype in the contract.
Chain.gas_limit : int\nThe gas limit of the current block.
"},{"location":"sophia_stdlib/#spend","title":"spend","text":"Chain.spend(to : address, amount : int) : unit\nSpend amount tokens to to. Will fail (and abort the contract) if contract doesn't have amount tokens to transfer, or, if to is not payable.
Chain.timestamp : int\nThe timestamp of the current block (unix time, milliseconds).
"},{"location":"sophia_stdlib/#char","title":"Char","text":""},{"location":"sophia_stdlib/#to_int_1","title":"to_int","text":"Char.to_int(c : char) : int
Char.from_int(i : int) : option(char)Returns the UTF-8 codepoint of a character\n\n\n#### from_int\n
Opposite of to_int. Returns None if the integer doesn't correspond to a single (normalized) codepoint.
Values related to the current contract
"},{"location":"sophia_stdlib/#creator","title":"creator","text":"Contract.creator : address\nAddress of the entity that signed the contract creation transaction
"},{"location":"sophia_stdlib/#address_1","title":"address","text":"Contract.address : address\nAddress of the contract account
"},{"location":"sophia_stdlib/#balance_1","title":"balance","text":"Contract.balance : int\nAmount of coins in the contract account
"},{"location":"sophia_stdlib/#crypto","title":"Crypto","text":""},{"location":"sophia_stdlib/#sha3","title":"sha3","text":"Crypto.sha3(x : 'a) : hash\nHash any object to SHA3
"},{"location":"sophia_stdlib/#sha256","title":"sha256","text":"Crypto.sha256(x : 'a) : hash\nHash any object to SHA256
"},{"location":"sophia_stdlib/#blake2b","title":"blake2b","text":"Crypto.blake2b(x : 'a) : hash\nHash any object to blake2b
"},{"location":"sophia_stdlib/#verify_sig","title":"verify_sig","text":"Crypto.verify_sig(msg : hash, pubkey : address, sig : signature) : bool\nChecks if the signature of msg was made using private key corresponding to the pubkey
Crypto.ecverify_secp256k1(msg : hash, addr : bytes(20), sig : bytes(65)) : bool\nVerifies a signature for a msg against an Ethereum style address. Note that the signature should be 65 bytes and include the recovery identifier byte V. The expected organization of the signature is (V || R || S).
Crypto.ecrecover_secp256k1(msg : hash, sig : bytes(65)) : option(bytes(20))\nRecovers the Ethereum style address from a msg hash and respective ECDSA-signature. Note that the signature should be 65 bytes and include the recovery identifier byte V. The expected organization of the signature is (V || R || S).
Crypto.verify_sig_secp256k1(msg : hash, pubkey : bytes(64), sig : bytes(64)) : bool\nVerifies a standard 64-byte ECDSA signature (R || S).
Int.to_str : int => string\nCasts integer to string using decimal representation
"},{"location":"sophia_stdlib/#map","title":"Map","text":""},{"location":"sophia_stdlib/#lookup_1","title":"lookup","text":"Map.lookup(k : 'k, m : map('k, 'v)) : option('v)
Returns the value under a key in given map as Some or None if the key is not present
Map.lookup_default(k : 'k, m : map('k, 'v), v : 'v) : 'v
Returns the value under a key in given map or the default value v if the key is not present
Map.member(k : 'k, m : map('k, 'v)) : bool
Checks if the key is present in the map
"},{"location":"sophia_stdlib/#delete","title":"delete","text":"Map.delete(k : 'k, m : map('k, 'v)) : map('k, 'v)
Removes the key from the map
"},{"location":"sophia_stdlib/#size","title":"size","text":"Map.size(m : map('k, 'v)) : int
Returns the number of elements in the map
"},{"location":"sophia_stdlib/#to_list","title":"to_list","text":"Map.to_list(m : map('k, 'v)) : list('k * 'v)
Returns a list containing pairs of keys and their respective elements.
"},{"location":"sophia_stdlib/#from_list","title":"from_list","text":"Map.from_list(m : list('k * 'v)) : map('k, 'v)
Turns a list of pairs of form (key, value) into a map
Oracle.register(<signature : bytes(64)>, acct : address, qfee : int, ttl : Chain.ttl) : oracle('a, 'b)\nRegisters new oracle answering questions of type 'a with answers of type 'b.
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 network id + account address + contract address (concatenated as byte arrays) is signed with 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.qfee is the minimum query fee to be paid by a user when asking a question of the oracle.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)).'a is the type of the question to ask.'b is the type of the oracle answers.Examples:
Oracle.register(addr0, 25, RelativeTTL(400))\n Oracle.register(addr1, 25, RelativeTTL(500), signature = sign1)\nOracle.get_question(o : oracle('a, 'b), q : oracle_query('a, 'b)) : 'a\nChecks 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\nResponds 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 the network id + oracle query id + contract address
Oracle.extend(<signature : bytes(64)>, o : oracle('a, 'b), ttl : Chain.ttl) : unit\nExtends 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.
Oracle.query_fee(o : oracle('a, 'b)) : int\nReturns the query fee of the oracle
"},{"location":"sophia_stdlib/#query","title":"query","text":"Oracle.query(o : oracle('a, 'b), q : 'a, qfee : int, qttl : Chain.ttl, rttl : Chain.ttl) : oracle_query('a, 'b)\nAsks 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.
Oracle.get_answer(o : oracle('a, 'b), q : oracle_query('a, 'b)) : option('b)\nChecks what is the optional query answer
"},{"location":"sophia_stdlib/#expiry","title":"expiry","text":"Oracle.expiry(o : oracle('a, 'b)) : int\nAsk the oracle when it expires. The result is the block height at which it will happen.
"},{"location":"sophia_stdlib/#check","title":"check","text":"Oracle.check(o : oracle('a, 'b)) : bool\nReturns true iff the oracle o exists and has correct type
Oracle.check_query(o : oracle('a, 'b), q : oracle_query('a, 'b)) : bool\nIt returns true iff the oracle query exist and has the expected type.
These need to be explicitly included (with .aes suffix)
Bitwise operations on arbitrary precision integers.
"},{"location":"sophia_stdlib/#bsr","title":"bsr","text":"Bitwise.bsr(n : int, x : int) : int\nLogical bit shift x right n positions.
Bitwise.bsl(n : int, x : int) : int\nLogical bit shift x left n positions.
Bitwise.bsli(n : int, x : int, lim : int) : int\nLogical bit shift x left n positions, limit to lim bits.
Bitwise.band(x : int, y : int) : int\nBitwise and of x and y.
Bitwise.bor(x : int, y : int) : int\nBitwise or of x and y.
Bitwise.bxor(x : int, y : int) : int\nBitwise xor of x and y.
Bitwise.bnot(x : int) : int\nBitwise not of x. Defined and implemented as bnot(x) = bxor(x, -1).
Bitwise.uband(x : int, y : int) : int\nBitwise and of non-negative numbers x and y.
Bitwise.ubor(x : int, y : int) : int\nBitwise or of non-negative x and y.
Bitwise.ubxor(x : int, y : int) : int\nBitwise xor of non-negative x and y.
Built-in (Montgomery) integer representation 32 bytes
"},{"location":"sophia_stdlib/#fp","title":"fp","text":"Built-in (Montgomery) integer representation 48 bytes
"},{"location":"sophia_stdlib/#fp2","title":"fp2","text":"record fp2 = { x1 : fp, x2 : fp }`\nrecord g1 = { x : fp, y : fp, z : fp }\nrecord g2 = { x : fp2, y : fp2, z : fp2 }\nrecord gt = { x1 : fp, x2 : fp, x3 : fp, x4 : fp, x5 : fp, x6 : fp, x7 : fp, x8 : fp, x9 : fp, x10 : fp, x11 : fp, x12 : fp }\nBLS12_381.pairing_check(xs : list(g1), ys : list(g2)) : bool\nPairing check of a list of points, xs and ys should be of equal length.
BLS12_381.int_to_fr(x : int) : fr\nConvert an integer to an fr - a 32 bytes internal (Montgomery) integer representation.
BLS12_381.int_to_fp(x : int) : fp\nConvert an integer to an fp - a 48 bytes internal (Montgomery) integer representation.
BLS12_381.fr_to_int(x : fr) : int\nConvert a fr value into an integer.
BLS12_381.fp_to_int(x : fp) : int\nConvert a fp value into an integer.
BLS12_381.mk_g1(x : int, y : int, z : int) : g1\nConstruct a g1 point from three integers.
BLS12_381.mk_g2(x1 : int, x2 : int, y1 : int, y2 : int, z1 : int, z2 : int) : g2\nConstruct a g2 point from six integers.
BLS12_381.g1_neg(p : g1) : g1\nNegate a g1 value.
BLS12_381.g1_norm(p : g1) : g1\nNormalize a g1 value.
BLS12_381.g1_valid(p : g1) : bool\nCheck that a g1 value is a group member.
BLS12_381.g1_is_zero(p : g1) : bool\nCheck if a g1 value corresponds to the zero value of the group.
BLS12_381.g1_add(p : g1, q : g1) : g1\nAdd two g1 values.
BLS12_381.g1_mul(k : fr, p : g1) : g1\nScalar multiplication for g1.
BLS12_381.g2_neg(p : g2) : g2\nNegate a g2 value.
BLS12_381.g2_norm(p : g2) : g2\nNormalize a g2 value.
BLS12_381.g2_valid(p : g2) : bool\nCheck that a g2 value is a group member.
BLS12_381.g2_is_zero(p : g2) : bool\nCheck if a g2 value corresponds to the zero value of the group.
BLS12_381.g2_add(p : g2, q : g2) : g2\nAdd two g2 values.
BLS12_381.g2_mul(k : fr, p : g2) : g2\nScalar multiplication for g2.
BLS12_381.gt_inv(p : gt) : gt\nInvert a gt value.
BLS12_381.gt_add(p : gt, q : gt) : gt\nAdd two gt values.
BLS12_381.gt_mul(p : gt, q : gt) : gt\nMultiply two gt values.
BLS12_381.gt_pow(p : gt, k : fr) : gt\nCalculate exponentiation p ^ k.
BLS12_381.gt_is_one(p : gt) : bool\nCompare a gt value to the unit value of the Gt group.
BLS12_381.pairing(p : g1, q : g2) : gt\nCompute the pairing of a g1 value and a g2 value.
BLS12_381.miller_loop(p : g1, q : g2) : gt\nDo the Miller loop stage of pairing for g1 and g2.
BLS12_381.final_exp(p : gt) : gt\nPerform the final exponentiation step of pairing for a gt value.
Functional combinators.
"},{"location":"sophia_stdlib/#id","title":"id","text":"Func.id(x : 'a) : 'a\nIdentity function. Returns its argument.
"},{"location":"sophia_stdlib/#const","title":"const","text":"Func.const(x : 'a) : 'b => 'a = (y) => x\nConstant function constructor. Given x returns a function that returns x regardless of its argument.
Func.flip(f : ('a, 'b) => 'c) : ('b, 'a) => 'c\nSwitches order of arguments of arity 2 function.
"},{"location":"sophia_stdlib/#comp","title":"comp","text":"Func.comp(f : 'b => 'c, g : 'a => 'b) : 'a => 'c\nFunction composition. comp(f, g)(x) == f(g(x)).
Func.pipe(f : 'a => 'b, g : 'b => 'c) : 'a => 'c\nFlipped function composition. pipe(f, g)(x) == g(f(x)).
Func.rapply(x : 'a, f : 'a => 'b) : 'b\nReverse application. rapply(x, f) == f(x).
Func.recur(f : ('arg => 'res, 'arg) => 'res) : 'arg => 'res\nThe Z combinator. Allows performing local recursion and having anonymous recursive lambdas. To make function A => B recursive the user needs to transform it to take two arguments instead \u2013 one of type A => B which is going to work as a self-reference, and the other one of type A which is the original argument. Therefore, transformed function should have (A => B, A) => B signature.
Example usage:
let factorial = recur((fac, n) => if(n < 2) 1 else n * fac(n - 1))\nIf the function is going to take more than one argument it will need to be either tuplified or have curried out latter arguments.
Example (factorial with custom step):
// tuplified version\nlet factorial_t(n, step) =\n let fac(rec, args) =\n let (n, step) = args\n if(n < 2) 1 else n * rec((n - step, step))\n recur(fac)((n, step))\n\n// curried version\nlet factorial_c(n, step) =\n let fac(rec, n) = (step) =>\n if(n < 2) 1 else n * rec(n - 1)(step)\n recur(fac)(n)(step)\nFunc.iter(n : int, f : 'a => 'a) : 'a => 'a\nnth composition of f with itself, for instance iter(3, f) is equivalent to (x) => f(f(f(x))).
Func.curry2(f : ('a, 'b) => 'c) : 'a => ('b => 'c)\nFunc.curry3(f : ('a, 'b, 'c) => 'd) : 'a => ('b => ('c => 'd))\nTurns a function that takes n arguments into a curried function that takes one argument and returns a function that waits for the rest in the same manner. For instance curry2((a, b) => a + b)(1)(2) == 3.
Func.uncurry2(f : 'a => ('b => 'c)) : ('a, 'b) => 'c\nFunc.uncurry3(f : 'a => ('b => ('c => 'd))) : ('a, 'b, 'c) => 'd\nOpposite to curry.
"},{"location":"sophia_stdlib/#tuplify","title":"tuplify","text":"Func.tuplify2(f : ('a, 'b) => 'c) : (('a * 'b)) => 'c\nFunc.tuplify3(f : ('a, 'b, 'c) => 'd) : 'a * 'b * 'c => 'd\nTurns a function that takes n arguments into a function that takes an n-tuple.
"},{"location":"sophia_stdlib/#untuplify","title":"untuplify","text":"Func.untuplify2(f : 'a * 'b => 'c) : ('a, 'b) => 'c\nFunc.untuplify3(f : 'a * 'b * 'c => 'd) : ('a, 'b, 'c) => 'd\nOpposite to tuplify.
"},{"location":"sophia_stdlib/#frac","title":"Frac","text":"This namespace provides operations on rational numbers. A rational number is represented as a fraction of two integers which are stored internally in the frac datatype.
The datatype consists of three constructors Neg/2, Zero/0 and Pos/2 which determine the sign of the number. Both values stored in Neg and Pos need to be strictly positive integers. However, when creating a frac you should never use the constructors explicitly. Instead of that, always use provided functions like make_frac or from_int. This helps keeping the internal representation well defined.
The described below functions take care of the normalization of the fractions \u2013 they won't grow if it is unnecessary. Please note that the size of frac can be still very big while the value is actually very close to a natural number \u2013 the division of two extremely big prime numbers will be as big as both of them. To face this issue the optimize function is provided. It will approximate the value of the fraction to fit in the given error margin and to shrink its size as much as possible.
Important note: frac must not be compared using standard <-like operators. The operator comparison is not possible to overload at this moment, nor the language provides checkers to prevent unintended usage of them. Therefore the typechecker will allow that and the results of such comparison will be unspecified. You should use lt, geq, eq etc instead.
datatype frac = Pos(int, int) | Zero | Neg(int, int)\nInternal representation of fractional numbers. First integer encodes the numerator and the second the denominator \u2013 both must be always positive, as the sign is being handled by the choice of the constructor.
"},{"location":"sophia_stdlib/#functions_3","title":"Functions","text":""},{"location":"sophia_stdlib/#make_frac","title":"make_frac","text":"Frac.make_frac(n : int, d : int) : frac
Creates a fraction out of numerator and denominator. Automatically normalizes, so make_frac(2, 4) and make_frac(1, 2) will yield same results.
Frac.num(f : frac) : int
Returns the numerator of a fraction.
"},{"location":"sophia_stdlib/#den","title":"den","text":"Frac.den(f : frac) : int
Returns the denominator of a fraction.
"},{"location":"sophia_stdlib/#to_pair","title":"to_pair","text":"Frac.to_pair(f : frac) : int * int
Turns a fraction into a pair of numerator and denominator.
"},{"location":"sophia_stdlib/#sign","title":"sign","text":"Frac.sign(f : frac) : int
Returns the signum of a fraction, -1, 0, 1 if negative, zero, positive respectively.
"},{"location":"sophia_stdlib/#to_str_3","title":"to_str","text":"Frac.to_str(f : frac) : string
Conversion to string. Does not display division by 1 or denominator if equals zero.
"},{"location":"sophia_stdlib/#simplify","title":"simplify","text":"Frac.simplify(f : frac) : frac
Reduces fraction to normal form if for some reason it is not in it.
"},{"location":"sophia_stdlib/#eq","title":"eq","text":"Frac.eq(a : frac, b : frac) : bool
Checks if a is equal to b.
Frac.neq(a : frac, b : frac) : bool
Checks if a is not equal to b.
Frac.geq(a : frac, b : frac) : bool
Checks if a is greater or equal to b.
Frac.leq(a : frac, b : frac) : bool
Checks if a is lesser or equal to b.
Frac.gt(a : frac, b : frac) : bool
Checks if a is greater than b.
Frac.lt(a : frac, b : frac) : bool
Checks if a is lesser than b.
Frac.min(a : frac, b : frac) : frac
Chooses lesser of the two fractions.
"},{"location":"sophia_stdlib/#max","title":"max","text":"Frac.max(a : frac, b : frac) : frac
Chooses greater of the two fractions.
"},{"location":"sophia_stdlib/#abs","title":"abs","text":"Frac.abs(f : frac) : frac
Absolute value.
"},{"location":"sophia_stdlib/#from_int","title":"from_int","text":"Frac.from_int(n : int) : frac
From integer conversion. Effectively make_frac(n, 1).
Frac.floor(f : frac) : int
Rounds a fraction to the nearest lesser or equal integer.
"},{"location":"sophia_stdlib/#ceil","title":"ceil","text":"Frac.ceil(f : frac) : int
Rounds a fraction to the nearest greater or equal integer.
"},{"location":"sophia_stdlib/#round_to_zero","title":"round_to_zero","text":"Frac.round_to_zero(f : frac) : int
Rounds a fraction towards zero. Effectively ceil if lesser than zero and floor if greater.
Frac.round_from_zero(f : frac) : int
Rounds a fraction from zero. Effectively ceil if greater than zero and floor if lesser.
Frac.round(f : frac) : int
Rounds a fraction to a nearest integer. If two integers are in the same distance it will choose the even one.
"},{"location":"sophia_stdlib/#add","title":"add","text":"Frac.add(a : frac, b : frac) : frac
Sum of the fractions.
"},{"location":"sophia_stdlib/#neg","title":"neg","text":"Frac.neg(a : frac) : frac
Negation of the fraction.
"},{"location":"sophia_stdlib/#sub","title":"sub","text":"Frac.sub(a : frac, b : frac) : frac
Subtraction of two fractions.
"},{"location":"sophia_stdlib/#inv","title":"inv","text":"Frac.inv(a : frac) : frac
Inverts a fraction. Throws error if a is zero.
Frac.mul(a : frac, b : frac) : frac
Multiplication of two fractions.
"},{"location":"sophia_stdlib/#div","title":"div","text":"Frac.div(a : frac, b : frac) : frac
Division of two fractions.
"},{"location":"sophia_stdlib/#int_exp","title":"int_exp","text":"Frac.int_exp(b : frac, e : int) : frac
Takes b to the power of e. The exponent can be a negative value.
Frac.optimize(f : frac, loss : frac) : frac
Shrink the internal size of a fraction as much as possible by approximating it to the point where the error would exceed the loss value.
Frac.is_sane(f : frac) : bool
For debugging. If it ever returns false in a code that doesn't call frac constructors or accept arbitrary fracs from the surface you should report it as a bug
If you expect getting calls with malformed fracs in your contract, you should use this function to verify the input.
This module contains common operations on lists like constructing, querying, traversing etc.
"},{"location":"sophia_stdlib/#is_empty","title":"is_empty","text":"List.is_empty(l : list('a)) : bool\nReturns true iff the list is equal to [].
List.first(l : list('a)) : option('a)\nReturns Some of the first element of a list or None if the list is empty.
List.tail(l : list('a)) : option(list('a))\nReturns Some of a list without its first element or None if the list is empty.
List.last(l : list('a)) : option('a)\nReturns Some of the last element of a list or None if the list is empty.
List.contains(e : 'a, l : list('a)) : bool\nl contains element e. Equivalent to List.find(x => x == e, l) != None."},{"location":"sophia_stdlib/#find","title":"find","text":"List.find(p : 'a => bool, l : list('a)) : option('a)\nFinds first element of l fulfilling predicate p as Some or None if no such element exists.
List.find_indices(p : 'a => bool, l : list('a)) : list(int)\nReturns list of all indices of elements from l that fulfill the predicate p.
List.nth(n : int, l : list('a)) : option('a)\nGets nth element of l as Some or None if l is shorter than n + 1 or n is negative.
List.get(n : int, l : list('a)) : 'a\nGets nth element of l forcefully, throwing and error if l is shorter than n + 1 or n is negative.
List.length(l : list('a)) : int\nReturns length of a list.
"},{"location":"sophia_stdlib/#from_to","title":"from_to","text":"List.from_to(a : int, b : int) : list(int)\nCreates an ascending sequence of all integer numbers between a and b (including a and b).
List.from_to_step(a : int, b : int, step : int) : list(int)\nCreates an ascending sequence of integer numbers betweeen a and b jumping by given step. Includes a and takes b only if (b - a) mod step == 0. step should be bigger than 0.
List.replace_at(n : int, e : 'a, l : list('a)) : list('a)\nReplaces nth element of l with e. Throws an error if n is negative or would cause an overflow.
List.insert_at(n : int, e : 'a, l : list('a)) : list('a)\nInserts e into l to be on position n by shifting following elements further. For instance,
insert_at(2, 9, [1,2,3,4])\n[1,2,9,3,4]."},{"location":"sophia_stdlib/#insert_by","title":"insert_by","text":"List.insert_by(cmp : (('a, 'a) => bool), x : 'a, l : list('a)) : list('a)\nAssuming that cmp represents < comparison, inserts x before the first element in the list l which is greater than it. For instance,
insert_by((a, b) => a < b, 4, [1,2,3,5,6,7])\n[1,2,3,4,5,6,7]"},{"location":"sophia_stdlib/#foldr","title":"foldr","text":"List.foldr(cons : ('a, 'b) => 'b, nil : 'b, l : list('a)) : 'b\nRight fold of a list. Assuming l = [x, y, z] will return f(x, f(y, f(z, nil))). Not tail recursive.
List.foldl(rcons : ('b, 'a) => 'b, acc : 'b, l : list('a)) : 'b\nLeft fold of a list. Assuming l = [x, y, z] will return f(f(f(acc, x), y), z). Tail recursive.
List.foreach(l : list('a), f : 'a => unit) : unit\nEvaluates f on each element of a list.
List.reverse(l : list('a)) : list('a)\nReturns a copy of l with reversed order of elements.
List.map(f : 'a => 'b, l : list('a)) : list('b)\nMaps function f over a list. For instance
map((x) => x == 0, [1, 2, 0, 3, 0])\n[false, false, true, false, true]"},{"location":"sophia_stdlib/#flat_map","title":"flat_map","text":"List.flat_map(f : 'a => list('b), l : list('a)) : list('b)\nMaps f over a list and then flattens it. For instance
flat_map((x) => [x, x * 10], [1, 2, 3])\n[1, 10, 2, 20, 3, 30]"},{"location":"sophia_stdlib/#filter","title":"filter","text":"List.filter(p : 'a => bool, l : list('a)) : list('a)\nFilters out elements of l that fulfill predicate p. For instance
filter((x) => x > 0, [-1, 1, -2, 0, 1, 2, -3])\n[1, 1, 2]"},{"location":"sophia_stdlib/#take","title":"take","text":"List.take(n : int, l : list('a)) : list('a)\nTakes n first elements of l. Fails if n is negative. If n is greater than length of a list it will return whole list.
List.drop(n : int, l : list('a)) : list('a)\nRemoves n first elements of l. Fails if n is negative. If n is greater than length of a list it will return [].
List.take_while(p : 'a => bool, l : list('a)) : list('a)\nReturns longest prefix of l in which all elements fulfill p.
List.drop_while(p : 'a => bool, l : list('a)) : list('a)\nRemoves longest prefix from l in which all elements fulfill p.
List.partition(p : 'a => bool, l : list('a)) : (list('a) * list('a))\nSeparates elements of l that fulfill p and these that do not. Elements fulfilling predicate will be in the right list. For instance
partition((x) => x > 0, [-1, 1, -2, 0, 1, 2, -3])\n([1, 1, 2], [-1, -2, 0, -3])"},{"location":"sophia_stdlib/#flatten","title":"flatten","text":"List.flatten(ll : list(list('a))) : list('a)\nFlattens a list of lists into a one list.
"},{"location":"sophia_stdlib/#all_1","title":"all","text":"List.all(p : 'a => bool, l : list('a)) : bool\nChecks if all elements of a list fulfill predicate p.
List.any(p : 'a => bool, l : list('a)) : bool\nChecks if any element of a list fulfills predicate p.
List.sum(l : list(int)) : int\nSums elements of a list. Returns 0 if the list is empty.
"},{"location":"sophia_stdlib/#product","title":"product","text":"List.product(l : list(int)) : int\nMultiplies elements of a list. Returns 1 if the list is empty.
"},{"location":"sophia_stdlib/#zip_with","title":"zip_with","text":"List.zip_with(f : ('a, 'b) => 'c, l1 : list('a), l2 : list('b)) : list('c)\n\"zips\" two lists with a function. n-th element of resulting list will be equal to f(x1, x2) where x1 and x2 are n-th elements of l1 and l2 respectively. Will cut off the tail of the longer list. For instance
zip_with((a, b) => a + b, [1,2], [1,2,3])\n[2,4]"},{"location":"sophia_stdlib/#zip","title":"zip","text":"List.zip(l1 : list('a), l2 : list('b)) : list('a * 'b)\nSpecial case of zip_with where the zipping function is (a, b) => (a, b).
List.unzip(l : list('a * 'b)) : list('a) * list('b)\nOpposite to the zip operation. Takes a list of pairs and returns pair of lists with respective elements on same indices.
List.merge(lesser_cmp : ('a, 'a) => bool, l1 : list('a), l2 : list('a)) : list('a)\nMerges two sorted lists into a single sorted list. O(length(l1) + length(l2))
"},{"location":"sophia_stdlib/#sort","title":"sort","text":"List.sort(lesser_cmp : ('a, 'a) => bool, l : list('a)) : list('a)\nSorts a list using given comparator. lesser_cmp(x, y) should return true iff x < y. If lesser_cmp is not transitive or there exists an element x such that lesser_cmp(x, x) or there exists a pair of elements x and y such that lesser_cmp(x, y) && lesser_cmp(y, x) then the result is undefined. O(length(l) * log_2(length(l))).
List.intersperse(delim : 'a, l : list('a)) : list('a)\nIntersperses elements of l with delim. Does nothing on empty lists and singletons. For instance
intersperse(0, [1, 2, 3, 4])\n[1, 0, 2, 0, 3, 0, 4]"},{"location":"sophia_stdlib/#enumerate","title":"enumerate","text":"List.enumerate(l : list('a)) : list(int * 'a)\nEquivalent to zip with [0..length(l)], but slightly faster.
Common operations on option types and lists of options.
Option.is_none(o : option('a)) : bool\nReturns true iff o == None
Option.is_some(o : option('a)) : bool\nReturns true iff o is not None.
Option.match(n : 'b, s : 'a => 'b, o : option('a)) : 'b\nBehaves like pattern matching on option using two case functions.
Option.default(def : 'a, o : option('a)) : 'a\nEscapes option wrapping by providing default value for None.
Option.force(o : option('a)) : 'a\nForcefully escapes the option wrapping assuming it is Some. Aborts on None.
Option.force_msg(o : option('a), err : string) : 'a\nForcefully escapes the option wrapping assuming it is Some. Aborts with err error message on None.
Option.contains(e : 'a, o : option('a)) : bool\ntrue if and only if o contains element equal to e. Equivalent to Option.match(false, x => x == e, o)."},{"location":"sophia_stdlib/#on_elem","title":"on_elem","text":"Option.on_elem(o : option('a), f : 'a => unit) : unit\nEvaluates f on element under Some. Does nothing on None.
Option.map(f : 'a => 'b, o : option('a)) : option('b)\nMaps element under Some. Leaves None unchanged.
Option.map2(f : ('a, 'b) => 'c, o1 : option('a), o2 : option('b)) : option('c)\nApplies arity 2 function over two options' elements. Returns Some iff both of o1 and o2 were Some, or None otherwise. For instance
map2((a, b) => a + b, Some(1), Some(2))\nSome(3) and map2((a, b) => a + b, Some(1), None)\nNone."},{"location":"sophia_stdlib/#map3","title":"map3","text":"Option.map3(f : ('a, 'b, 'c) => 'd, o1 : option('a), o2 : option('b), o3 : option('c)) : option('d)\nSame as map2 but with arity 3 function.
"},{"location":"sophia_stdlib/#app_over","title":"app_over","text":"Option.app_over(f : option ('a => 'b), o : option('a)) : option('b)\nApplies function under option over argument under option. If either of them is None the result will be None as well. For instance
app_over(Some((x) => x + 1), Some(1))\nSome(2) and app_over(Some((x) => x + 1), None)\nNone."},{"location":"sophia_stdlib/#flat_map_1","title":"flat_map","text":"Option.flat_map(f : 'a => option('b), o : option('a)) : option('b)\nPerforms monadic bind on an option. Extracts element from o (if present) and forms new option from it. For instance
flat_map((x) => Some(x + 1), Some(1))\nSome(2) and flat_map((x) => Some(x + 1), None)\nNone."},{"location":"sophia_stdlib/#to_list_1","title":"to_list","text":"Option.to_list(o : option('a)) : list('a)\nTurns o into an empty (if None) or singleton (if Some) list.
Option.filter_options(l : list(option('a))) : list('a)\nRemoves Nones from list and unpacks all remaining Somes. For instance
filter_options([Some(1), None, Some(2)])\n[1, 2]."},{"location":"sophia_stdlib/#seq_options","title":"seq_options","text":"Option.seq_options(l : list (option('a))) : option (list('a))\nTries to unpack all elements of a list from Somes. Returns None if at least element of l is None. For instance
seq_options([Some(1), Some(2)])\nSome([1, 2]), but seq_options([Some(1), Some(2), None])\nNone."},{"location":"sophia_stdlib/#choose","title":"choose","text":"Option.choose(o1 : option('a), o2 : option('a)) : option('a)\nOut of two options choose the one that is Some, or None if both are Nones.
Option.choose_first(l : list(option('a))) : option('a)\nSame as choose, but chooses from a list insted of two arguments.
"},{"location":"sophia_stdlib/#pair","title":"Pair","text":"Common operations on 2-tuples.
"},{"location":"sophia_stdlib/#fst","title":"fst","text":"Pair.fst(t : ('a * 'b)) : 'a\nFirst element projection.
"},{"location":"sophia_stdlib/#snd","title":"snd","text":"Pair.snd(t : ('a * 'b)) : 'b\nSecond element projection.
"},{"location":"sophia_stdlib/#map1","title":"map1","text":"Pair.map1(f : 'a => 'c, t : ('a * 'b)) : ('c * 'b)\nApplies function over first element.
"},{"location":"sophia_stdlib/#map2_1","title":"map2","text":"Pair.map2(f : 'b => 'c, t : ('a * 'b)) : ('a * 'c)\nApplies function over second element.
"},{"location":"sophia_stdlib/#bimap","title":"bimap","text":"Pair.bimap(f : 'a => 'c, g : 'b => 'd, t : ('a * 'b)) : ('c * 'd)\nApplies functions over respective elements.
"},{"location":"sophia_stdlib/#swap","title":"swap","text":"Pair.swap(t : ('a * 'b)) : ('b * 'a)\nSwaps elements.
"},{"location":"sophia_stdlib/#set_1","title":"Set","text":""},{"location":"sophia_stdlib/#types_4","title":"Types","text":"record set('a) = { to_map : map('a, unit) }\nSet.new() : set('a)\nReturns an empty set
"},{"location":"sophia_stdlib/#member_1","title":"member","text":"member(e : 'a, s : set('a)) : bool\nChecks if the element e is present in the set s
insert(e : 'a, s : set('a)) : set('a)\nInserts the element e in the set s
Set.delete(e : 'a, s : set('a)) : set('a)\nRemoves the element e from the set s
size(s : set('a)) : int\nReturns the number of elements in the set s
Set.to_list(s : set('a)) : list('a)\nReturns a list containing the elements of the set s
Set.from_list(l : list('a)) : set('a)\nTurns the list l into a set
Set.filter(p : 'a => bool, s : set('a)) : set('a)\nFilters out elements of s that fulfill predicate p
Set.fold(f : ('a, 'b) => 'b, acc : 'b, s : set('a)) : 'b\nFolds the function f over every element in the set s and returns the final value of the accumulator acc.
Set.subtract(s1 : set('a), s2 : set('a)) : set('a)\nReturns the elements of s1 that are not members of s2
Set.intersection(s1 : set('a), s2 : set('a)) : set('a)\nReturns the intersection of the two sets s1 and s2
Set.intersection_list(sets : list(set('a))) : set('a)\nReturns the intersection of all the sets in the given list
"},{"location":"sophia_stdlib/#union_1","title":"union","text":"Set.union(s1 : set('a), s2 : set('a)) : set('a)\nReturns the union of the two sets s1 and s2
Set.union_list(sets : list(set('a))) : set('a)\nReturns the union of all the sets in the given list
"},{"location":"sophia_stdlib/#string","title":"String","text":"Operations on the string type. A string is a UTF-8 encoded byte array.
length(s : string) : int
The length of a string.
Note: not equivalent to byte size of the string, rather List.length(String.to_list(s))
concat(s1 : string, s2 : string) : string\nConcatenates s1 and s2.
concats(ss : list(string)) : string\nConcatenates a list of strings.
"},{"location":"sophia_stdlib/#to_list_3","title":"to_list","text":"to_list(s : string) : list(char)\nConverts a string to a list of char - the code points are normalized, but composite characters are possibly converted to multiple chars. For example the string \"\ud83d\ude1ci\u0307\" is converted to [128540,105,775] - where the smiley is the first code point and the strangely dotted i becomes [105, 775].
from_list(cs : list(char)) : string\nConverts a list of characters into a normalized UTF-8 string.
"},{"location":"sophia_stdlib/#to_lower","title":"to_lower","text":"to_lower(s : string) : string\nConverts a string to lowercase.
"},{"location":"sophia_stdlib/#to_upper","title":"to_upper","text":"to_upper(s : string) : string\nConverts a string to uppercase.
"},{"location":"sophia_stdlib/#at","title":"at","text":"at(ix : int, s : string) : option(char)\nReturns the character/codepoint at (zero-based) index ix. Basically the equivalent to List.nth(ix, String.to_list(s)).
split(ix : int, s:string) : string * string\nSplits a string at (zero-based) index ix.
contains(str : string, pat : string) : option(int)\nSearches for pat in str, returning Some(ix) if pat is a substring of str starting at position ix, otherwise returns None.
tokens(str : string, pat : string) : list(string)\nSplits str into tokens, pat is the divider of tokens.
to_int(s : string) : option(int)\nConverts a decimal (\"123\", \"-253\") or a hexadecimal (\"0xa2f\", \"-0xBBB\") string into an integer. If the string doesn't contain a valid number None is returned.
sha3(s : string) : hash\nComputes the SHA3/Keccak hash of the string.
"},{"location":"sophia_stdlib/#sha256_1","title":"sha256","text":"sha256(s : string) : hash\nComputes the SHA256 hash of the string.
"},{"location":"sophia_stdlib/#blake2b_1","title":"blake2b","text":"blake2b(s : string) : hash\nComputes the Blake2B hash of the string.
"},{"location":"sophia_stdlib/#triple","title":"Triple","text":""},{"location":"sophia_stdlib/#fst_1","title":"fst","text":"Triple.fst(t : ('a * 'b * 'c)) : 'a\nFirst element projection.
"},{"location":"sophia_stdlib/#snd_1","title":"snd","text":"Triple.snd(t : ('a * 'b * 'c)) : 'b\nSecond element projection.
"},{"location":"sophia_stdlib/#thd","title":"thd","text":"Triple.thd(t : ('a * 'b * 'c)) : 'c\nThird element projection.
"},{"location":"sophia_stdlib/#map1_1","title":"map1","text":"Triple.map1(f : 'a => 'm, t : ('a * 'b * 'c)) : ('m * 'b * 'c)\nApplies function over first element.
"},{"location":"sophia_stdlib/#map2_2","title":"map2","text":"Triple.map2(f : 'b => 'm, t : ('a * 'b * 'c)) : ('a * 'm * 'c)\nApplies function over second element.
"},{"location":"sophia_stdlib/#map3_1","title":"map3","text":"Triple.map3(f : 'c => 'm, t : ('a * 'b * 'c)) : ('a * 'b * 'm)\nApplies function over third element.
"},{"location":"sophia_stdlib/#trimap","title":"trimap","text":"Triple.trimap(f : 'a => 'x, g : 'b => 'y, h : 'c => 'z, t : ('a * 'b * 'c)) : ('x * 'y * 'z)\nApplies functions over respective elements.
"},{"location":"sophia_stdlib/#swap_1","title":"swap","text":"Triple.swap(t : ('a * 'b * 'c)) : ('c * 'b * 'a)\nSwaps first and third element.
"},{"location":"sophia_stdlib/#rotr","title":"rotr","text":"Triple.rotr(t : ('a * 'b * 'c)) : ('c * 'a * 'b)\nCyclic rotation of the elements to the right.
"},{"location":"sophia_stdlib/#rotl","title":"rotl","text":"Triple.rotl(t : ('a * 'b * 'c)) : ('b * 'c * 'a)\nCyclic rotation of the elements to the left.
"},{"location":"sophia_syntax/","title":"Syntax","text":""},{"location":"sophia_syntax/#lexical-syntax","title":"Lexical syntax","text":""},{"location":"sophia_syntax/#comments","title":"Comments","text":"Single line comments start with // and block comments are enclosed in /* and */ and can be nested.
contract include let switch type record datatype if elif else function\nstateful payable true false mod public entrypoint private indexed namespace\ninterface main using as for hiding\nId = [a-z_][A-Za-z0-9_']* identifiers start with a lower case letter.Con = [A-Z][A-Za-z0-9_']* constructors start with an upper case letter.QId = (Con\\.)+Id qualified identifiers (e.g. Map.member)QCon = (Con\\.)+Con qualified constructorTVar = 'Id type variable (e.g 'a, 'b)Int = [0-9]+(_[0-9]+)*|0x[0-9A-Fa-f]+(_[0-9A-Fa-f]+)* integer literal with optional _ separatorsBytes = #[0-9A-Fa-f]+(_[0-9A-Fa-f]+)* byte array literal with optional _ separatorsString string literal enclosed in \" with escape character \\Char character literal enclosed in ' with escape character \\AccountAddress base58-encoded 32 byte account pubkey with ak_ prefixContractAddress base58-encoded 32 byte contract address with ct_ prefixOracleAddress base58-encoded 32 byte oracle address with ok_ prefixOracleQueryId base58-encoded 32 byte oracle query id with oq_ prefixValid string escape codes are
Escape ASCII\\b 8 \\t 9 \\n 10 \\v 11 \\f 12 \\r 13 \\e 27 \\xHexDigits HexDigits See the identifier encoding scheme for the details on the base58 literals.
"},{"location":"sophia_syntax/#layout-blocks","title":"Layout blocks","text":"Sophia uses Python-style layout rules to group declarations and statements. A layout block with more than one element must start on a separate line and be indented more than the currently enclosing layout block. Blocks with a single element can be written on the same line as the previous token.
Each element of the block must share the same indentation and no part of an element may be indented less than the indentation of the block. For instance
contract Layout =\nfunction foo() = 0 // no layout\nfunction bar() = // layout block starts on next line\nlet x = foo() // indented more than 2 spaces\nx\n+ 1 // the '+' is indented more than the 'x'\nIn describing the syntax below, we use the following conventions:
Expr) or terminals with some associated value (like Id).'let' or '='.|.[ square brackets ].( Parentheses ) are used for grouping.*, and one or more repetitions by a +.Block(X) denotes a layout block of Xs.Sep(X, S) is short for [X (S X)*], i.e. a possibly empty sequence of Xs separated by Ss.Sep1(X, S) is short for X (S X)*, i.e. same as Sep, but must not be empty.A Sophia file consists of a sequence of declarations in a layout block.
File ::= Block(TopDecl)\n\nTopDecl ::= ['payable'] ['main'] 'contract' Con [Implement] '=' Block(Decl)\n| 'contract' 'interface' Con [Implement] '=' Block(Decl)\n| 'namespace' Con '=' Block(Decl)\n| '@compiler' PragmaOp Version\n| 'include' String\n| Using\n\nImplement ::= ':' Sep1(Con, ',')\n\nDecl ::= 'type' Id ['(' TVar* ')'] '=' TypeAlias\n| 'record' Id ['(' TVar* ')'] '=' RecordType\n| 'datatype' Id ['(' TVar* ')'] '=' DataType\n| 'let' Id [':' Type] '=' Expr\n| (EModifier* 'entrypoint' | FModifier* 'function') Block(FunDecl)\n| Using\n\nFunDecl ::= Id ':' Type // Type signature\n| Id Args [':' Type] '=' Block(Stmt) // Definition\n| Id Args [':' Type] Block(GuardedDef) // Guarded definitions\n\nGuardedDef ::= '|' Sep1(Expr, ',') '=' Block(Stmt)\n\nUsing ::= 'using' Con ['as' Con] [UsingParts]\nUsingParts ::= 'for' '[' Sep1(Id, ',') ']'\n| 'hiding' '[' Sep1(Id, ',') ']'\n\nPragmaOp ::= '<' | '=<' | '==' | '>=' | '>'\nVersion ::= Sep1(Int, '.')\n\nEModifier ::= 'payable' | 'stateful'\nFModifier ::= 'stateful' | 'private'\n\nArgs ::= '(' Sep(Pattern, ',') ')'\nContract declarations must appear at the top-level.
For example,
contract Test =\ntype t = int\nentrypoint add (x : t, y : t) = x + y\nThere are three forms of type declarations: type aliases (declared with the type keyword), record type definitions (record) and data type definitions (datatype):
TypeAlias ::= Type\nRecordType ::= '{' Sep(FieldType, ',') '}'\nDataType ::= Sep1(ConDecl, '|')\n\nFieldType ::= Id ':' Type\nConDecl ::= Con ['(' Sep1(Type, ',') ')']\nFor example,
record point('a) = {x : 'a, y : 'a}\ndatatype shape('a) = Circle(point('a), 'a) | Rect(point('a), point('a))\ntype int_shape = shape(int)\nType ::= Domain '=>' Type // Function type\n| Type '(' Sep(Type, ',') ')' // Type application\n| '(' Type ')' // Parens\n| 'unit' | Sep(Type, '*') // Tuples\n| Id | QId | TVar\n\nDomain ::= Type // Single argument\n| '(' Sep(Type, ',') ')' // Multiple arguments\nThe function type arrow associates to the right.
Example,
'a => list('a) => (int * list('a))\nFunction bodies are blocks of statements, where a statement is one of the following
Stmt ::= 'switch' '(' Expr ')' Block(Case)\n| 'if' '(' Expr ')' Block(Stmt)\n| 'elif' '(' Expr ')' Block(Stmt)\n| 'else' Block(Stmt)\n| 'let' LetDef\n| Using\n| Expr\n\nLetDef ::= Id Args [':' Type] '=' Block(Stmt) // Function definition\n| Pattern '=' Block(Stmt) // Value definition\n\nCase ::= Pattern '=>' Block(Stmt)\n| Pattern Block(GuardedCase)\n\nGuardedCase ::= '|' Sep1(Expr, ',') '=>' Block(Stmt)\n\nPattern ::= Expr\nif statements can be followed by zero or more elif statements and an optional final else statement. For example,
let x : int = 4\nswitch(f(x))\nNone => 0\nSome(y) =>\nif(y > 10)\n\"too big\"\nelif(y < 3)\n\"too small\"\nelse\n\"just right\"\nExpr ::= '(' LamArgs ')' '=>' Block(Stmt) // Anonymous function (x) => x + 1\n| '(' BinOp ')' // Operator lambda (+)\n| 'if' '(' Expr ')' Expr 'else' Expr // If expression if(x < y) y else x\n| Expr ':' Type // Type annotation 5 : int\n| Expr BinOp Expr // Binary operator x + y\n| UnOp Expr // Unary operator ! b\n| Expr '(' Sep(Expr, ',') ')' // Application f(x, y)\n| Expr '.' Id // Projection state.x\n| Expr '[' Expr ']' // Map lookup map[key]\n| Expr '{' Sep(FieldUpdate, ',') '}' // Record or map update r{ fld[key].x = y }\n| '[' Sep(Expr, ',') ']' // List [1, 2, 3]\n| '[' Expr '|' Sep(Generator, ',') ']'\n// List comprehension [k | x <- [1], if (f(x)), let k = x+1]\n| '[' Expr '..' Expr ']' // List range [1..n]\n| '{' Sep(FieldUpdate, ',') '}' // Record or map value {x = 0, y = 1}, {[key] = val}\n| '(' Expr ')' // Parens (1 + 2) * 3\n| '(' Expr '=' Expr ')' // Assign pattern (y = x::_)\n| Id | Con | QId | QCon // Identifiers x, None, Map.member, AELib.Token\n| Int | Bytes | String | Char // Literals 123, 0xff, #00abc123, \"foo\", '%'\n| AccountAddress | ContractAddress // Chain identifiers\n| OracleAddress | OracleQueryId // Chain identifiers\n| '???' // Hole expression 1 + ???\n\nGenerator ::= Pattern '<-' Expr // Generator\n| 'if' '(' Expr ')' // Guard\n| LetDef // Definition\n\nLamArgs ::= '(' Sep(LamArg, ',') ')'\nLamArg ::= Id [':' Type]\n\nFieldUpdate ::= Path '=' Expr\nPath ::= Id // Record field\n| '[' Expr ']' // Map key\n| Path '.' Id // Nested record field\n| Path '[' Expr ']' // Nested map key\n\nBinOp ::= '||' | '&&' | '<' | '>' | '=<' | '>=' | '==' | '!='\n| '::' | '++' | '+' | '-' | '*' | '/' | 'mod' | '^'\n| '|>'\nUnOp ::= '-' | '!'\n- + * / mod ^ arithmetic operators ! && || logical operators == != < > =< >= comparison operators :: ++ list operators |> functional operators"},{"location":"sophia_syntax/#operator-precedence","title":"Operator precedence","text":"In order of highest to lowest precedence.
Operators Associativity! right ^ left * / mod left - (unary) right + - left :: ++ right < > =< >= == != none && right || right |> left"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Introduction","text":"Sophia is a functional language designed for smart contract development. It is strongly typed and has restricted mutable state.
Sophia is customized for smart contracts, which can be published to a blockchain. Thus some features of conventional languages, such as floating point arithmetic, are not present in Sophia, and some \u00e6ternity blockchain specific primitives, constructions and types have been added.
Note
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
"},{"location":"CHANGELOG/#unreleased","title":"Unreleased","text":""},{"location":"CHANGELOG/#added","title":"Added","text":""},{"location":"CHANGELOG/#changed","title":"Changed","text":""},{"location":"CHANGELOG/#removed","title":"Removed","text":""},{"location":"CHANGELOG/#fixed","title":"Fixed","text":"namespace N =\n let nc = 1\ncontract C =\n let cc = 2\ncontract Main =\n entrypoint spend(x : int) : int = x\n entrypoint f(c : Main) : int = c.spend(10)\ntypedefs field instead of type_defs to increase compatibility.EXIT opcode via exit : (string) => 'a function (behaves same as ABORT, but consumes all gas).[1, 2, 3] |> List.first |> Option.is_some // Option.is_some(List.first([1, 2, 3]))\nfunction sum(l : list(int)) : int = foldl((+), 0, l)\nfunction logical_and(x, y) = (&&)(x, y)\npp_oneline/1 has been added.record r = {} would give an error).Bitwise stdlibSet stdlibOption.force_msgusing Pair)let x::(t = y::_) = [1, 2, 3, 4] where t == [2, 3, 4])AENS.name, AENS.pointee, Chain.ttl, Chain.base_tx, Chain.ga_meta_tx, Chain.paying_for_tx) to the calldata and result decoderswitch(x)\n a::[] | a > 10 => 1\n _ => 2\nfunction\n f(a::[]) | a > 10 = 1\n f(_) = 2\nstateful modifierList.from_to_step now forbids non-positive step (this change does not alter the behavior of the previously deployed contracts)include in the Frac standard libraryChain.cloneChain.createChain.bytecode_hashvoid type that represents an empty typeCall.fee builtincontract interface keywordsmain keyword to indicate the main contract in case there are child contracts aroundList.sum and List.product no longer use List.foldlString standard library has been added. Use it by include \"String.aes\". It includes functions for turning strings into lists of characters for detailed manipulation. For example: include \"String.aes\"\ncontract C =\n entrypoint filter_all_a(s: string) : string =\n String.from_list(List.filter((c : char) => c != 'a', String.to_list(s)))\na's removed.There are also convenience functions split, concat, to_upper, to_lower, etc.
All String functions in FATEv2 operate on unicode code points. - Operations for pairing-based cryptography has been added the operations are in the standard library BLS12_381. With these operations it is possible to do Zero Knowledge-proofs, etc. The operations are for the BLS12-381 curve (as the name suggests). - Calls to functions in other contracts (i.e. remote calls) can now be protected. If a contract call fails for any reason (for instance, the remote contract crashes or runs out of gas, or the entrypoint doesn't exist or has the wrong type) the parent call also fails. To make it possible to recover from failures, contract calls takes a named argument protected : bool (default false).
If protected = true the result of the contract call is wrapped in an option, and Some(value) indicates a succesful execution and None indicates that the contract call failed. Note: any gas consumed until the failure is still charged, but all side effects in the remote contract are rolled back on failure. - A new chain operation AENS.update is supported. - New chain exploring operations AENS.lookup and Oracle.expiry to look up an AENS record and the expiry of an Oracle respectively, are added. - Transaction introspection (Auth.tx) has been added. When a Generalized account is authorized, the authorization function needs access to the transaction (and the transaction hash) for the wrapped transaction. The transaction and the transaction hash is available Auth.tx, it is only available during authentication if invoked by a normal contract call it returns None. Example:
switch(Auth.tx)\n None => abort(\"Not in Auth context\")\n Some(tx0) =>\n switch(tx0.tx)\n Chain.SpendTx(_, amount, _) => amount > 400\n Chain.ContractCallTx(_, _) => true\n _ => false\nChain.block_hash(height) is now (in FATEv2) defined for the current height - this used to be an error.mergesort and a contains function is added.protocol)Frac.aes \u2013 library for rational numberskeep_included it is possible to see which files were included during the parserun_parser that be used to evaluate any parsing rulebody, type and decl- unary operatorlet definitions are no longer supported in the toplevel of the contract function\n length : list('a) => int\n length([]) = 0\n length(x :: xs) = 1 + length(xs)\n function somes(xs : list(option('a))) : list('a) =\n [ x | Some(x) <- xs ]\n function test(m : map(int, int)) =\n let Some(x) = Map.lookup(m, 0)\n x\nAddress.to_contract - casts an address to a (any) contract type.@compiler >= 4.0.\"\\x19Ethereum Signed Message:\\n\", and similar strings.Bytes.concat and Bytes.split are added to be able to (de-)construct byte arrays.[a..b] language construct, returning the list of numbers between a and b (inclusive). Returns the empty list if a > b.init is not called from other functions.AEVM and FATE. Many of the APIs now take {backend, aevm | fate} to decide wich backend to produce artifacts for.Crypto.ecrecover_secp256k1: (hash, bytes(65)) => option(bytes(20)) and Crypto.ecverify_secp256k1 : (hash, bytes(20), bytes(65)) => bool for recovering and verifying an Ethereum address for a message hash and a signature.[x + y | x <- [1,2,3,4,5], let k = x*x, if (k > 5), y <- [k, k+1, k+2]]\n// yields [12,13,14,20,21,22,30,31,32]\npayable is introduced. Contracts, and enpoints, that shall be able to receive funds should be marked as payable. Address.is_payable(a) can be used to check if an (contract) address is payable or not.Crypto.<hash_fun> and String.<hash_fun> for byte arrays now only hash the actual byte array - not the internal ABI format.AENS.claim is updated with a NameFee field - to be able to do name auctions within contracts.Bytes.to_str for AEVM.unit instead of () and regular tuples are encoded by interspersing inner types with *, for instance int * string. Parens are not necessary. Note it only affects the types, values remain as their were before, so (1, \"a\") : int * stringAENS.transfer and AENS.revoke functions have been updated to take a name string instead of a name hash.AEVM backend complained about a missing init function when trying to generate calldata from an ACI-generated interface.Crypto.ecverify and Crypto.ecverify_secp256k1 into Crypto.verify_sig and Crypto.verify_sig_secp256k1 respectively.require : (bool, string) => (). Defined as function require(b, err) = if(!b) abort(err)\nBytes.to_str : bytes(_) => string\nBytes.to_int : bytes(_) => int\ncontract Example =\n // Exported\n entrypoint exported_fun(x) = local_fun(x)\n // Not exported\n function local_fun(x) = x\nfunction (and private function for private functions).Chain.block_hash(height) has changed, it used to be int, where 0 denoted an incorrect height. New return type is option(hash), where None represents an incorrect height.indexed is now optional for word typed (bool, int, address, ...) event arguments.'a, 'b, ... instead of '1, '2, ....state and event types (if present) now appear at the top level.contract_interface and render_aci_json.create_calldata/to_sophia_value - it can now handle negative literals.stateful annotations are now properly enforced. Functions must be marked stateful in order to update the state or spend tokens.Contract.creator, Address.is_contract, Address.is_oracle, Oracle.check and Oracle.check_query has been added to Sophia.bytes(N) has been added to generalize hash (== bytes(32)) and signature (== bytes(64)) and allow for byte arrays of arbitrary fixed length.Crypto.ecverify_secp256k1 has been added.#<hex> to address as ak_<base58check>, oracle ok_<base58check>, oracle query oq_<base58check> and remote contract ct_<base58check>.letfun (e.g. let m(f, xs) = map(f, xs)) was not working properly and has been fixed.let rec has been removed from the language, it has never worked.aeternity/aesophia_cli and has been completely removed from aesophia.Auth.tx_hash, not available in AEVM until Fortuna releaseCrypto.ecverify to the compiler.Crypto.sha3, Crypto.blake2, Crypto.sha256, String.blake2 and String.sha256 to the compiler.bits type for working with bit fields in Sophia.init function - detects programmer errors earlier.record fields - generates more understandable error messages.The ACI interface encoder and decoder.
"},{"location":"aeso_aci/#description","title":"Description","text":"This module provides an interface to generate and convert between Sophia contracts and a suitable JSON encoding of contract interface. As yet the interface is very basic.
Encoding this contract:
contract Answers =\n record state = { a : answers }\n type answers() = map(string, int)\n\n stateful function init() = { a = {} }\n private function the_answer() = 42\n function new_answer(q : string, a : int) : answers() = { [q] = a }\ngenerates the following JSON structure representing the contract interface:
{\n\"contract\": {\n\"functions\": [\n{\n\"arguments\": [],\n\"name\": \"init\",\n\"returns\": \"Answers.state\",\n\"stateful\": true\n},\n{\n\"arguments\": [\n{\n\"name\": \"q\",\n\"type\": \"string\"\n},\n{\n\"name\": \"a\",\n\"type\": \"int\"\n}\n],\n\"name\": \"new_answer\",\n\"returns\": {\n\"map\": [\n\"string\",\n\"int\"\n]\n},\n\"stateful\": false\n}\n],\n\"name\": \"Answers\",\n\"state\": {\n\"record\": [\n{\n\"name\": \"a\",\n\"type\": \"Answers.answers\"\n}\n]\n},\n\"typedefs\": [\n{\n\"name\": \"answers\",\n\"typedef\": {\n\"map\": [\n\"string\",\n\"int\"\n]\n},\n\"vars\": []\n}\n]\n}\n}\nWhen that encoding is decoded the following include definition is generated:
contract Answers =\n record state = {a : Answers.answers}\n type answers = map(string, int)\n function init : () => Answers.state\n function new_answer : (string, int) => map(string, int)\n-type aci_type() :: json | string.\n-type json() :: jsx:json_term().\n-type json_text() :: binary().\nGenerate the JSON encoding of the interface to a contract. The type definitions and non-private functions are included in the JSON string.
"},{"location":"aeso_aci/#render_aci_jsonjson-json_text-string","title":"render_aci_json(json() | json_text()) -> string().","text":"Take a JSON encoding of a contract interface and generate a contract interface that can be included in another contract.
"},{"location":"aeso_aci/#example-run","title":"Example run","text":"This is an example of using the ACI generator from an Erlang shell. The file called aci_test.aes contains the contract in the description from which we want to generate files aci_test.json which is the JSON encoding of the contract interface and aci_test.include which is the contract definition to be included inside another contract.
1> {ok,Contract} = file:read_file(\"aci_test.aes\").\n{ok,<<\"contract Answers =\\n record state = { a : answers }\\n type answers() = map(string, int)\\n\\n stateful function\"...>>}\n2> {ok,JsonACI} = aeso_aci:contract_interface(json, Contract).\n{ok,[#{contract =>\n#{functions =>\n[#{arguments => [],name => <<\"init\">>,\nreturns => <<\"Answers.state\">>,stateful => true},\n#{arguments =>\n[#{name => <<\"q\">>,type => <<\"string\">>},\n#{name => <<\"a\">>,type => <<\"int\">>}],\nname => <<\"new_answer\">>,\nreturns => #{<<\"map\">> => [<<\"string\">>,<<\"int\">>]},\nstateful => false}],\nname => <<\"Answers\">>,\nstate =>\n#{record =>\n[#{name => <<\"a\">>,type => <<\"Answers.answers\">>}]},\ntypedefs =>\n[#{name => <<\"answers\">>,\ntypedef => #{<<\"map\">> => [<<\"string\">>,<<\"int\">>]},\nvars => []}]}}]}\n3> file:write_file(\"aci_test.aci\", jsx:encode(JsonACI)).\nok\n4> {ok,InterfaceStub} = aeso_aci:render_aci_json(JsonACI).\n{ok,<<\"contract Answers =\\n record state = {a : Answers.answers}\\n type answers = map(string, int)\\n function init \"...>>}\n5> file:write_file(\"aci_test.include\", InterfaceStub).\nok\n6> jsx:prettify(jsx:encode(JsonACI)).\n<<\"[\\n {\\n \\\"contract\\\": {\\n \\\"functions\\\": [\\n {\\n \\\"arguments\\\": [],\\n \\\"name\\\": \\\"init\\\",\\n \"...>>\nThe final call to jsx:prettify(jsx:encode(JsonACI)) returns the encoding in a more easily readable form. This is what is shown in the description above.
The Sophia compiler
"},{"location":"aeso_compiler/#description","title":"Description","text":"This module provides the interface to the standard Sophia compiler. It returns the compiled module in a map which can then be loaded.
"},{"location":"aeso_compiler/#types","title":"Types","text":"contract_string() = string() | binary()\ncontract_map() = #{bytecode => binary(),\ncompiler_version => binary(),\ncontract_souce => string(),\ntype_info => type_info()}\ntype_info()\nerrorstring() = binary()\nTypes
ContractString = contract_string()\nOptions = [Option]\nCompRet = {ok,ContractMap} | {error,ErrorString}\nContractMap = contract_map()\nErrorString = errorstring()\nCompile a contract defined in a file or in a string.
The pp_ options all print to standard output the following:
pp_sophia_code - print the input Sophia code.
pp_ast - print the AST of the code
pp_types - print information about the types
pp_typed_ast - print the AST with type information at each node
pp_assembler - print the generated assembler code
The option include_child_contract_symbols includes the symbols of child contracts functions in the generated fate code. It is turned off by default to avoid making contracts bigger on chain.
By default all optimizations are turned on, to disable an optimization, it should be explicitly set to false and passed as a compiler option.
List of optimizations:
Types
ContractString = string() | binary()\nCheckRet = {ok,string(),{Types,Type | any()},Terms} | {error,Term}\nTypes = [Type]\nType = term()\n__call function."},{"location":"aeso_compiler/#version-ok-version-error-term","title":"version() -> {ok, Version} | {error, term()}","text":"Types
Version = binary()\nGet the current version of the Sophia compiler.
"},{"location":"sophia/","title":"Sophia","text":"This file has been moved here
"},{"location":"sophia_examples/","title":"Contract examples","text":""},{"location":"sophia_examples/#crowdfunding","title":"Crowdfunding","text":"/*\n * A simple crowd-funding example\n */\ncontract FundMe =\n\nrecord spend_args = { recipient : address,\namount : int }\n\nrecord state = { contributions : map(address, int),\ntotal : int,\nbeneficiary : address,\ndeadline : int,\ngoal : int }\n\nstateful function spend(args : spend_args) =\nChain.spend(args.recipient, args.amount)\n\nentrypoint init(beneficiary, deadline, goal) : state =\n{ contributions = {},\nbeneficiary = beneficiary,\ndeadline = deadline,\ntotal = 0,\ngoal = goal }\n\nfunction is_contributor(addr) =\nMap.member(addr, state.contributions)\n\nstateful entrypoint contribute() =\nif(Chain.block_height >= state.deadline)\nspend({ recipient = Call.caller, amount = Call.value }) // Refund money\nfalse\nelse\nlet amount =\nswitch(Map.lookup(Call.caller, state.contributions))\nNone => Call.value\nSome(n) => n + Call.value\nput(state{ contributions[Call.caller] = amount,\ntotal @ tot = tot + Call.value })\ntrue\n\nstateful entrypoint withdraw() =\nif(Chain.block_height < state.deadline)\nabort(\"Cannot withdraw before deadline\")\nif(Call.caller == state.beneficiary)\nwithdraw_beneficiary()\nelif(is_contributor(Call.caller))\nwithdraw_contributor()\nelse\nabort(\"Not a contributor or beneficiary\")\n\nstateful function withdraw_beneficiary() =\nrequire(state.total >= state.goal, \"Project was not funded\")\nspend({recipient = state.beneficiary,\namount = Contract.balance })\n\nstateful function withdraw_contributor() =\nif(state.total >= state.goal)\nabort(\"Project was funded\")\nlet to = Call.caller\nspend({recipient = to,\namount = state.contributions[to]})\nput(state{ contributions @ c = Map.delete(to, c) })\nThis is a list with repositories that include smart contracts written in Sophia:
The main unit of code in Sophia is the contract.
state encapsulating its local state. When creating a new contract the init entrypoint is executed and the state is initialized to its return value.The language offers some primitive functions to interact with the blockchain and contracts. Please refer to the Chain, Contract and the Call namespaces in the documentation.
"},{"location":"sophia_features/#calling-other-contracts","title":"Calling other contracts","text":"To call a function in another contract you need the address to an instance of the contract. The type of the address must be a contract type, which consists of a number of type definitions and entrypoint declarations. For instance,
// A contract type\ncontract interface VotingType =\nentrypoint vote : string => unit\nNow given contract address of type VotingType you can call the vote entrypoint of that contract:
contract VoteTwice =\nentrypoint voteTwice(v : VotingType, alt : string) =\nv.vote(alt)\nv.vote(alt)\nContract 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 the defaults are no gas limit and no tokens. Suppose there is a fee for voting:
entrypoint voteTwice(v : VotingType, fee : int, alt : string) =\nv.vote(value = fee, alt)\nv.vote(value = fee, alt)\nNamed arguments can be given in any order.
Note that reentrant calls are not permitted. In other words, when calling another contract it cannot call you back (directly or indirectly).
To construct a value of a contract type you can give a contract address literal (for instance ct_2gPXZnZdKU716QBUFKaT4VdBZituK93KLvHJB3n4EnbrHHw4Ay), or convert an account address to a contract address using Address.to_contract. Note that if the contract does not exist, or it doesn't have the entrypoint, or the type of the entrypoint does not match the stated contract type, the call fails.
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) without calling it you can write
entrypoint pay(v : VotingType, amount : int) =\nChain.spend(v.address, amount)\nIf a contract call fails for any reason (for instance, the remote contract crashes or runs out of gas, or the entrypoint doesn't exist or has the wrong type) the parent call also fails. To make it possible to recover from failures, contract calls takes a named argument protected : bool (default false).
The protected argument must be a literal boolean, and when set to true changes the type of the contract call, wrapping the result in an option type. If the call fails the result is None, otherwise it's Some(r) where r is the return value of the call.
contract interface VotingType =\nentrypoint : vote : string => unit\n\ncontract Voter =\nentrypoint tryVote(v : VotingType, alt : string) =\nswitch(v.vote(alt, protected = true) : option(unit))\nNone => \"Voting failed\"\nSome(_) => \"Voting successful\"\nAny gas that was consumed by the contract call before the failure stays consumed, which means that in order to protect against the remote contract 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 transaction still only uses up the gas spent running the contract.
Any side effects (state change, token transfers, etc.) made by a failing protected call is rolled back, just like they would be in the unprotected case.
"},{"location":"sophia_features/#contract-factories-and-child-contracts","title":"Contract factories and child contracts","text":"Since the version 6.0.0 Sophia supports deploying contracts by other contracts. This can be done in two ways:
Chain.cloneChain.createThese functions take variable number of arguments that must match the created contract's init function. Beside that they take some additional named arguments \u2013 please refer to their documentation for the details.
While Chain.clone requires only a contract interface and a living instance of a given contract on the chain, Chain.create needs a full definition of a to-create contract defined by the standard contract syntax, for example
contract IntHolder =\ntype state = int\nentrypoint init(x) = x\nentrypoint get() = state\n\nmain contract IntHolderFactory =\nstateful entrypoint new(x : int) : IntHolder =\nlet ih = Chain.create(x) : IntHolder\nih\nIn case of a presence of child contracts (IntHolder in this case), the main contract must be pointed out with the main keyword as shown in the example.
Contracts can implement one or multiple interfaces, the contract has to define every entrypoint from the implemented interface and the entrypoints in both the contract and implemented interface should have compatible types.
contract interface Animal =\n entrypoint sound : () => string\n\n contract Cat : Animal =\n entrypoint sound() = \"Cat sound\"\nContract interfaces can extend other interfaces. An extended interface has to declare all entrypoints from every parent interface. All the declarations in the extended interface must have types compatible with the declarations from the parent interface.
contract interface II =\n entrypoint f : () => unit\n\ncontract interface I : II =\n entrypoint f : () => unit\n entrypoint g : () => unit\n\ncontract C : I =\n entrypoint f() = ()\n entrypoint g() = ()\nIt is only possible to implement (or extend) an interface that has been already defined earlier in the file (or in an included file). Therefore recursive interface implementation is not allowed in Sophia.
// The following code would show an error\n\ncontract interface X : Z =\n entrypoint x : () => int\n\n contract interface Y : X =\n entrypoint x : () => int\n entrypoint y : () => int\n\n contract interface Z : Y =\n entrypoint x : () => int\n entrypoint y : () => int\n entrypoint z : () => int\n\n contract C : Z =\n entrypoint x() = 1\n entrypoint y() = 1\n entrypoint z() = 1\nWhen a contract or a contract interface implements another contract interface, the payable and stateful modifiers can be kept or changed, both in the contract and in the entrypoints, according to the following rules:
payable contract or interface can implement a payable interface or a non-payable interface.payable contract or interface can only implement a non-payable interface, and cannot implement a payable interface.payable entrypoint can implement a payable entrypoint or a non-payable entrypoint.payable entrypoint can only implement a non-payable entrypoint, and cannot implement a payable entrypoint.stateful entrypoint can implement a stateful entrypoint or a non-stateful entrypoint.stateful entrypoint can only implement a stateful entrypoint, and cannot implement a non-stateful entrypoint.Subtyping in Sophia follows common rules that take type variance into account. As described by Wikipedia,
Variance refers to how subtyping between more complex types relates to subtyping between their components.
This concept plays an important role in complex types such as tuples, datatypes and functions. Depending on the context, it can apply to positions in the structure of a type, or type parameters of generic types. There are four kinds of variances:
A type is said to be on a \"covariant\" position when it describes output or a result of some computation. Analogously, position is \"contravariant\" when it is an input, or a parameter. Intuitively, when a part of the type is produced by values of it, it is covariant. When it is consumed, it is contravariant. When a type appears to be simultaneously input and output, it is described as invariant. If a type is neither of those (that is, it's unused) it's bivariant. Furthermore, whenever a complex type appears on a contravariant position, all its covariant components become contravariant and vice versa.
Variance influences how subtyping is applied. Types on covariant positions are subtyped normally, while contravariant the opposite way. Invariant types have to be exactly the same in order for subtyping to work. Bivariant types are always compatible.
A good example of where it matters can be pictured by subtyping of function types. Let us assume there is a contract interface Animal and two contracts that implement it: Dog and Cat.
contract interface Animal =\nentrypoint age : () => int\n\ncontract Dog : Animal =\nentrypoint age() = // ...\nentrypoint woof() = \"woof\"\n\ncontract Cat : Animal =\nentrypoint age() = // ...\nentrypoint meow() = \"meow\"\nThe assumption of this exercise is that cats do not bark (because Cat does not define the woof entrypoint). If subtyping rules were applied naively, that is if we let Dog => Dog be a subtype of Animal => Animal, the following code would break:
let f : (Dog) => string = d => d.woof()\nlet g : (Animal) => string = f\nlet c : Cat = Chain.create()\ng(c) // Cat barking!\nThat is because arguments of functions are contravariant, as opposed to return the type which is covariant. Because of that, the assignment of f to g is invalid - while Dog is a subtype of Animal, Dog => string is not a subtype of Animal => string. However, Animal => string is a subtype of Dog => string. More than that, (Dog => Animal) => Dog is a subtype of (Animal => Dog) => Animal.
This has consequences on how user-defined generic types work. A type variable gains its variance from its role in the type definition as shown in the example:
datatype co('a) = Co('a) // co is covariant on 'a\ndatatype ct('a) = Ct('a => unit) // ct is contravariant on 'a\ndatatype in('a) = In('a => 'a) // in is invariant on 'a\ndatatype bi('a) = Bi // bi is bivariant on 'a\nThe following facts apply here:
co('a) is a subtype of co('b) when 'a is a subtype of 'bct('a) is a subtype of ct('b) when 'b is a subtype of 'ain('a) is a subtype of in('b) when 'a is equal to 'bbi('a) is a subtype of bi('b) alwaysThat altogether induce the following rules of subtyping in Sophia:
A function type (Args1) => Ret1 is a subtype of (Args2) => Ret2 when Ret1 is a subtype of Ret2 and each argument type from Args2 is a subtype of its counterpart in Args1.
A list type list(A) is a subtype of list(B) if A is a subtype of B.
An option type option(A) is a subtype of option(B) if A is a subtype of B.
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.
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)
When a user-defined type t('a) is covariant in 'a, then t(A) is a subtype of t(B) when A is a subtype of B.
When a user-defined type t('a) is contravariant in 'a, then t(A) is a subtype of t(B) when B is a subtype of A.
When a user-defined type t('a) is binvariant in 'a, then t(A) is a subtype of t(B) when either A is a subtype of B or when B is a subtype of A.
When a user-defined type t('a) is invariant in 'a, then t(A) can never be a subtype of t(B).
Sophia does not have arbitrary mutable state, but only a limited form of state associated with each contract instance.
state encapsulating its mutable state. The type state defaults to the unit.init function. The init function is pure and returns the initial state as its return value. If the type state is unit, the init function defaults to returning the value (). At contract creation time, the init function is executed and its result is stored as the contract state.state.put : state => unit.put function (and similar functions for transactions and events), the language is purely functional.stateful keyword (see below).To make it convenient to update parts of a deeply nested state Sophia provides special syntax for map/record updates.
"},{"location":"sophia_features/#stateful-functions","title":"Stateful functions","text":"Top-level functions and entrypoints must be annotated with the stateful keyword to be allowed to affect the state of the running contract. For instance,
stateful entrypoint set_state(s : state) =\nput(s)\nWithout the stateful annotation the compiler does not allow the call to put. A stateful annotation is required to
putChain.spendOracle.registerOracle.queryOracle.respondOracle.extendAENS.preclaimAENS.claimAENS.transferAENS.revokeAENS.updatestateful function in the current contractvalue argument.A stateful annotation is not required to
event function.value = 0, even if the called function is stateful.A concrete contract is by default not payable. Any attempt at spending to such a contract (either a Chain.spend or a normal spend transaction) will fail. If a contract shall be able to receive funds in this way it has to be declared payable:
// A payable contract\npayable contract ExampleContract =\nstateful entrypoint do_stuff() = ...\nIf in doubt, it is possible to check if an address is payable using Address.is_payable(addr).
A contract entrypoint is by default not payable. Any call to such a function (either a Remote call or a contract call transaction) that has a non-zero value will fail. Contract entrypoints that should be called with a non-zero value should be declared payable.
payable stateful entrypoint buy(to : address) =\nif(Call.value > 42)\ntransfer_item(to)\nelse\nabort(\"Value too low\")\nCode can be split into libraries using the namespace construct. Namespaces can appear at the top-level and can contain type and function definitions, but not entrypoints. Outside the namespace you can refer to the (non-private) names by qualifying them with the namespace (Namespace.name). For example,
namespace Library =\ntype number = int\nfunction inc(x : number) : number = x + 1\n\ncontract MyContract =\nentrypoint plus2(x) : Library.number =\nLibrary.inc(Library.inc(x))\nFunctions in namespaces have access to the same environment (including the Chain, Call, and Contract, builtin namespaces) as function in a contract, with the exception of state, put and Chain.event since these are dependent on the specific state and event types of the contract.
To avoid mentioning the namespace every time it is used, Sophia allows including the namespace in the current scope with the using keyword:
include \"Pair.aes\"\nusing Pair\ncontract C =\n type state = int\n entrypoint init() =\n let p = (1, 2)\n fst(p) // this is the same as Pair.fst(p)\nIt is also possible to make an alias for the namespace with the as keyword:
include \"Pair.aes\"\ncontract C =\n using Pair as P\n type state = int\n entrypoint init() =\n let p = (1, 2)\n P.fst(p) // this is the same as Pair.fst(p)\nHaving the same alias for multiple namespaces is possible and it allows referening functions that are defined in different namespaces and have different names with the same alias:
namespace Xa = function f() = 1\nnamespace Xb = function g() = 2\ncontract Cntr =\n using Xa as A\n using Xb as A\n type state = int\n entrypoint init() = A.f() + A.g()\nNote that using functions with the same name would result in an ambiguous name error:
namespace Xa = function f() = 1\nnamespace Xb = function f() = 2\ncontract Cntr =\n using Xa as A\n using Xb as A\n type state = int\n\n // the next line has an error because f is defined in both Xa and Xb\n entrypoint init() = A.f()\nImporting specific parts of a namespace or hiding these parts can also be done like this:
using Pair for [fst, snd] // this will only import fst and snd\nusing Triple hiding [fst, snd] // this will import everything except for fst and snd\nNote that it is possible to use a namespace in the top level of the file, in the contract level, namespace level, or in the function level.
"},{"location":"sophia_features/#splitting-code-over-multiple-files","title":"Splitting code over multiple files","text":"Code from another file can be included in a contract using an include statement. These must appear at the top-level (outside the main contract). The included file can contain one or more namespaces and abstract contracts. For example, if the file library.aes contains
namespace Library =\nfunction inc(x) = x + 1\nyou can use it from another file using an include:
include \"library.aes\"\ncontract MyContract =\nentrypoint plus2(x) = Library.inc(Library.inc(x))\nThis behaves as if the contents of library.aes was textually inserted into the file, except that error messages will refer to the original source locations. The language will try to include each file at most one time automatically, so even cyclic includes should be working without any special tinkering.
Sophia offers standard library which exposes some primitive operations and some higher level utilities. The builtin namespaces like Chain, Contract, Map are included by default and are supported internally by the compiler. Others like List, Frac, Option need to be manually included using the include directive. For example
include \"List.aes\"\ninclude \"Pair.aes\"\n-- Map is already there!\n\nnamespace C =\nentrypoint keys(m : map('a, 'b)) : list('a) =\nList.map(Pair.fst, (Map.to_list(m)))\nSophia has the following types:
Type Description Example int A 2-complement integer-1 address \u00e6ternity address, 32 bytes Call.origin bool A Boolean true bits A bit field Bits.none bytes(n) A byte array with n bytes #fedcba9876543210 string An array of bytes \"Foo\" list A homogeneous immutable singly linked list. [1, 2, 3] ('a, 'b) => 'c A function. Parentheses can be skipped if there is only one argument (x : int, y : int) => x + y tuple An ordered heterogeneous array (42, \"Foo\", true) record An immutable key value store with fixed key names and typed values record balance = { owner: address, value: int } map An immutable key value store with dynamic mapping of keys of one type to values of one type type accounts = map(string, address) option('a) An optional value either None or Some('a) Some(42) state A user defined type holding the contract state record state = { owner: address, magic_key: bytes(4) } event An append only list of blockchain events (or log entries) datatype event = EventX(indexed int, string) hash A 32-byte hash - equivalent to bytes(32) signature A signature - equivalent to bytes(64) 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()"},{"location":"sophia_features/#literals","title":"Literals","text":"Type Constant/Literal example(s) int -1, 2425, 4598275923475723498573485768 address ak_2gx9MEFxKvY9vMG5YnqnXWv1hCsX7rgnfvBLJS4aQurustR1rt bool true, false bits Bits.none, Bits.all bytes(8) #fedcba9876543210 string \"This is a string\" list [1, 2, 3], [(true, 24), (false, 19), (false, -42)] tuple (42, \"Foo\", true) record { owner = Call.origin, value = 100000000 } map {[\"foo\"] = 19, [\"bar\"] = 42}, {} option(int) Some(42), None state state{ owner = Call.origin, magic_key = #a298105f } event EventX(0, \"Hello\") hash #000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f signature #000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f Chain.ttl FixedTTL(1050), RelativeTTL(50) oracle('a, 'b) ok_2YNyxd6TRJPNrTcEDCe9ra59SVUdp9FR9qWC5msKZWYD9bP9z5 oracle_query('a, 'b) oq_2oRvyowJuJnEkxy58Ckkw77XfWJrmRgmGaLzhdqb67SKEL1gPY contract ct_Ez6MyeTMm17YnTnDdHTSrzMEBKmy7Uz2sXu347bTDPgVH2ifJ"},{"location":"sophia_features/#hole-expression","title":"Hole expression","text":"Hole expressions, written as ???, are expressions that are used as a placeholder. During compilation, the compiler will generate a type error indication the type of the hole expression.
include \"List.aes\"\ncontract C =\n entrypoint f() =\n List.sum(List.map(???, [1,2,3]))\nA hole expression found in the example above will generate the error Found a hole of type `(int) => int`. This says that the compiler expects a function from int to int in place of the ??? placeholder.
Constants in Sophia are contract-level bindings that can be used in either contracts or namespaces. The value of a constant can be a literal, another constant, or arithmetic operations applied to other constants. Lists, tuples, maps, and records can also be used to define a constant as long as their elements are also constants.
The following visibility rules apply to constants: * Constants defined inside a contract are private in that contract. Thus, cannot be accessed through instances of their defining contract. * Constants defined inside a namespace are public. Thus, can be used in other contracts or namespaces. * Constants cannot be defined inside a contract interface.
When a constant is shadowed, it can be accessed using its qualified name:
contract C =\n let c = 1\n entrypoint f() =\n let c = 2\n c + C.c // the result is 3\nThe name of the constant must be an id; therefore, no pattern matching is allowed when defining a constant:
contract C\n let x::y::_ = [1,2,3] // this will result in an error\nSophia integers (int) are represented by arbitrary-sized signed words and support the following arithmetic operations: - addition (x + y) - subtraction (x - y) - multiplication (x * y) - division (x / y), truncated towards zero - remainder (x mod y), satisfying y * (x / y) + x mod y == x for non-zero y - exponentiation (x ^ y)
All operations are safe with respect to overflow and underflow. The division and modulo operations throw an arithmetic error if the right-hand operand is zero.
"},{"location":"sophia_features/#bit-fields","title":"Bit fields","text":"Sophia integers do not support bit arithmetic. Instead there is a separate type bits. See the standard library documentation.
A bit field can be of arbitrary size (but it is still represented by the corresponding integer, so setting very high bits can be expensive).
"},{"location":"sophia_features/#type-aliases","title":"Type aliases","text":"Type aliases can be introduced with the type keyword and can be parameterized. For instance
type number = int\ntype string_map('a) = map(string, 'a)\nA type alias and its definition can be used interchangeably. Sophia does not support higher-kinded types, meaning that following type alias is invalid: type wrap('f, 'a) = 'f('a)
Sophia supports algebraic data types (variant types) and pattern matching. Data types are declared by giving a list of constructors with their respective arguments. For instance,
datatype one_or_both('a, 'b) = Left('a) | Right('b) | Both('a, 'b)\nElements of data types can be pattern matched against, using the switch construct:
function get_left(x : one_or_both('a, 'b)) : option('a) =\nswitch(x)\nLeft(x) => Some(x)\nRight(_) => None\nBoth(x, _) => Some(x)\nor directly in the left-hand side:
function\nget_left : one_or_both('a, 'b) => option('a)\nget_left(Left(x)) = Some(x)\nget_left(Right(_)) = None\nget_left(Both(x, _)) = Some(x)\nNOTE: Data types cannot currently be recursive.
Sophia also supports the assignment of patterns to variables:
function f(x) = switch(x)\nh1::(t = h2::_) => (h1 + h2)::t // same as `h1::h2::k => (h1 + h2)::h2::k`\n_ => x\n\nfunction g(p : int * option(int)) : int =\nlet (a, (o = Some(b))) = p // o is equal to Pair.snd(p)\nb\nGuards are boolean expressions that can be used on patterns in both switch statements and functions definitions. If a guard expression evaluates to true, then the corresponding body will be used. Otherwise, the next pattern will be checked:
function get_left_if_positive(x : one_or_both(int, 'b)) : option(int) =\nswitch(x)\nLeft(x) | x > 0 => Some(x)\nBoth(x, _) | x > 0 => Some(x)\n_ => None\nfunction\nget_left_if_positive : one_or_both(int, 'b) => option(int)\nget_left_if_positive(Left(x)) | x > 0 = Some(x)\nget_left_if_positive(Both(x, _)) | x > 0 = Some(x)\nget_left_if_positive(_) = None\nGuards cannot be stateful even when used inside a stateful function.
"},{"location":"sophia_features/#lists","title":"Lists","text":"A Sophia list is a dynamically sized, homogenous, immutable, singly linked list. A list is constructed with the syntax [1, 2, 3]. The elements of a list can be any of datatype but they must have the same type. The type of lists with elements of type 'e is written list('e). For example we can have the following lists:
[1, 33, 2, 666] : list(int)\n[(1, \"aaa\"), (10, \"jjj\"), (666, \"the beast\")] : list(int * string)\n[{[1] = \"aaa\", [10] = \"jjj\"}, {[5] = \"eee\", [666] = \"the beast\"}] : list(map(int, string))\nNew elements can be prepended to the front of a list with the :: operator. So 42 :: [1, 2, 3] returns the list [42, 1, 2, 3]. The concatenation operator ++ appends its second argument to its first and returns the resulting list. So concatenating two lists [1, 22, 33] ++ [10, 18, 55] returns the list [1, 22, 33, 10, 18, 55].
Sophia supports list comprehensions known from languages like Python, Haskell or Erlang. Example syntax:
[x + y | x <- [1,2,3,4,5], let k = x*x, if (k > 5), y <- [k, k+1, k+2]]\n// yields [12,13,14,20,21,22,30,31,32]\nLists can be constructed using the range syntax using special .. operator:
[1..4] == [1,2,3,4]\nPlease refer to the standard library for the predefined functionalities.
"},{"location":"sophia_features/#maps-and-records","title":"Maps and records","text":"A Sophia record type is given by a fixed set of fields with associated, possibly different, types. For instance
record account = { name : string,\nbalance : int,\nhistory : list(transaction) }\nMaps, on the other hand, can contain an arbitrary number of key-value bindings, but of a fixed type. The type of maps with keys of type 'k and values of type 'v is written map('k, 'v). The key type can be any type that does not contain a map or a function type.
Please refer to the standard library for the predefined functionalities.
"},{"location":"sophia_features/#constructing-maps-and-records","title":"Constructing maps and records","text":"A value of record type is constructed by giving a value for each of the fields. For the example above,
function new_account(name) =\n{name = name, balance = 0, history = []}\n function example_map() : map(string, int) =\n{[\"key1\"] = 1, [\"key2\"] = 2}\n{}."},{"location":"sophia_features/#accessing-values","title":"Accessing values","text":"Record fields access is written r.f and map lookup m[k]. For instance,
function get_balance(a : address, accounts : map(address, account)) =\naccounts[a].balance\nm[k = default]. See also Map.member and Map.lookup below."},{"location":"sophia_features/#updating-a-value","title":"Updating a value","text":"Record field updates are written r{f = v}. This creates a new record value which is the same as r, but with the value of the field f replaced by v. Similarly, m{[k] = v} constructs a map with the same values as m except that k maps to v. It makes no difference if m has a mapping for k or not.
It is possible to give a name to the old value of a field or mapping in an update: instead of acc{ balance = acc.balance + 100 } it is possible to write acc{ balance @ b = b + 100 }, binding b to acc.balance. When giving a name to a map value (m{ [k] @ x = v }), the corresponding key must be present in the map or execution fails, but a default value can be provided: m{ [k = default] @ x = v }. In this case x is bound to default if k is not in the map.
Updates can be nested:
function clear_history(a : address, accounts : map(address, account)) : map(address, account) =\naccounts{ [a].history = [] }\naccounts{ [a] @ acc = acc{ history = [] } } and thus requires a to be present in the accounts map. To have clear_history create an account if a is not in the map you can write (given a function empty_account): accounts{ [a = empty_account()].history = [] }\nInternally in the VM maps are implemented as hash maps and support fast lookup and update. Large maps can be stored in the contract state and the size of the map does not contribute to the gas costs of a contract call reading or updating it.
"},{"location":"sophia_features/#strings","title":"Strings","text":"There is a builtin type string, which can be seen as an array of bytes. Strings can be compared for equality (==, !=), used as keys in maps and records, and used in builtin functions String.length, String.concat and the hash functions described below.
Please refer to the String library documentation.
There is a builtin type char (the underlying representation being an integer), mainly used to manipulate strings via String.to_list/String.from_list.
Characters can also be introduced as character literals (`'x', '+', ...).
Please refer to the Char library documentation.
Byte arrays are fixed size arrays of 8-bit integers. They are described in hexadecimal system, for example the literal #cafe creates a two-element array of bytes ca (202) and fe (254) and thus is a value of type bytes(2).
Please refer to the Bytes library documentation.
Libraries Crypto and String provide functions to hash objects, verify signatures etc. The hash is a type alias for bytes(32).
When a Generalized account is authorized, the authorization function needs access to the transaction and the transaction hash for the wrapped transaction. (A GAMetaTx wrapping a transaction.) The transaction and the transaction hash is available in the primitive Auth.tx and Auth.tx_hash respectively, they are only available during authentication if invoked by a normal contract call they return None.
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. For a functionality documentation refer to the standard library.
"},{"location":"sophia_features/#example","title":"Example","text":"Example for an oracle answering questions of type string with answers of type int:
contract Oracles =\n\nstateful entrypoint registerOracle(acct : address,\nsign : signature, // Signed network id + oracle address + contract address\nqfee : int,\nttl : Chain.ttl) : oracle(string, int) =\nOracle.register(acct, signature = sign, qfee, ttl)\n\nentrypoint queryFee(o : oracle(string, int)) : int =\nOracle.query_fee(o)\n\npayable stateful entrypoint createQuery(o : oracle_query(string, int),\nq : string,\nqfee : int,\nqttl : Chain.ttl,\nrttl : int) : oracle_query(string, int) =\nrequire(qfee =< Call.value, \"insufficient value for qfee\")\nOracle.query(o, q, qfee, qttl, RelativeTTL(rttl))\n\nstateful entrypoint extendOracle(o : oracle(string, int),\nttl : Chain.ttl) : unit =\nOracle.extend(o, ttl)\n\nstateful entrypoint signExtendOracle(o : oracle(string, int),\nsign : signature, // Signed network id + oracle address + contract address\nttl : Chain.ttl) : unit =\nOracle.extend(o, signature = sign, ttl)\n\nstateful entrypoint respond(o : oracle(string, int),\nq : oracle_query(string, int),\nsign : signature, // Signed network id + oracle query id + contract address\nr : int) =\nOracle.respond(o, q, signature = sign, r)\n\nentrypoint getQuestion(o : oracle(string, int),\nq : oracle_query(string, int)) : string =\nOracle.get_question(o, q)\n\nentrypoint hasAnswer(o : oracle(string, int),\nq : oracle_query(string, int)) =\nswitch(Oracle.get_answer(o, q))\nNone => false\nSome(_) => true\n\nentrypoint getAnswer(o : oracle(string, int),\nq : oracle_query(string, int)) : option(int) =\nOracle.get_answer(o, q)\nWhen an Oracle literal is passed to a contract, no deep checks are performed. For extra safety Oracle.check and Oracle.check_query functions are provided.
"},{"location":"sophia_features/#aens-interface","title":"AENS interface","text":"Contracts can interact with the \u00e6ternity naming system. For this purpose the AENS library was exposed.
"},{"location":"sophia_features/#example_1","title":"Example","text":"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 name the account holder needs to create a signature sig of addr | name.hash | ct.address.
Armed with this information we can for example write a function that extends the name if it expires within 1000 blocks:
stateful entrypoint extend_if_necessary(addr : address, name : string, sig : signature) =\nswitch(AENS.lookup(name))\nNone => ()\nSome(AENS.Name(_, FixedTTL(expiry), _)) =>\nif(Chain.block_height + 1000 > expiry)\nAENS.update(addr, name, Some(RelativeTTL(50000)), None, None, signature = sig)\nAnd we can write functions that adds and removes keys from the pointers of the name:
stateful entrypoint add_key(addr : address, name : string, key : string,\npt : AENS.pointee, sig : signature) =\nswitch(AENS.lookup(name))\nNone => ()\nSome(AENS.Name(_, _, ptrs)) =>\nAENS.update(addr, name, None, None, Some(ptrs{[key] = pt}), signature = sig)\n\nstateful entrypoint delete_key(addr : address, name : string,\nkey : string, sig : signature) =\nswitch(AENS.lookup(name))\nNone => ()\nSome(AENS.Name(_, _, ptrs)) =>\nlet ptrs = Map.delete(key, ptrs)\nAENS.update(addr, name, None, None, Some(ptrs), signature = sig)\nNote: From the Iris hardfork more strict rules apply for AENS pointers, when a Sophia contract lookup or update (bad) legacy pointers, the bad keys are automatically removed so they will not appear in the pointers map.
"},{"location":"sophia_features/#events","title":"Events","text":"Sophia contracts log structured messages to an event log in the resulting blockchain transaction. The event log is quite similar to Events in Solidity. Events are further discussed in the protocol.
To use events a contract must declare a datatype event, and events are then logged using the Chain.event function:
datatype event\n= Event1(int, int, string)\n| Event2(string, address)\n\nChain.event(e : event) : unit\nThe event can have 0-3 indexed fields, and an optional payload field. A field is indexed if it fits in a 32-byte word, i.e. - bool - int - bits - address - oracle(_, _) - oracle_query(_, _) - contract types - bytes(n) for n \u2264 32, in particular hash
The payload field must be either a string or a byte array of more than 32 bytes. The fields can appear in any order.
NOTE: Indexing is not part of the core \u00e6ternity node.
Events are emitted by using the Chain.event function. The following function will emit one Event of each kind in the example.
entrypoint emit_events() : () =\nChain.event(Event1(42, 34, \"foo\"))\nChain.event(Event2(\"This is not indexed\", Contract.address))\nIt is only possible to have one (1) string parameter in the event, but it can be placed in any position (and its value will end up in the data field), i.e.
AnotherEvent(string, indexed address)\n\n...\n\nChain.event(AnotherEvent(\"This is not indexed\", Contract.address))\nTo enforce that a contract is only compiled with specific versions of the Sophia compiler, you can give one or more @compiler pragmas at the top-level (typically at the beginning) of a file. For instance, to enforce that a contract is compiled with version 4.3 of the compiler you write
@compiler >= 4.3\n@compiler < 4.4\nValid operators in compiler pragmas are <, =<, ==, >=, and >. Version numbers are given as a sequence of non-negative integers separated by dots. Trailing zeros are ignored, so 4.0.0 == 4. If a constraint is violated an error is reported and compilation fails.
Contracts can fail with an (uncatchable) exception using the built-in function
abort(reason : string) : 'a\nCalling abort causes the top-level call transaction to return an error result containing the reason string. Only the gas used up to and including the abort call is charged. This is different from termination due to a crash which consumes all available gas.
For convenience the following function is also built-in:
function require(b : bool, err : string) =\nif(!b) abort(err)\nAside from that, there is an almost equivalent function exit
exit(reason : string) : 'a\nJust like abort, it breaks the execution with the given reason. The difference however is in the gas consumption \u2014 while abort returns unused gas, a call to exit burns it all.
Some chain operations (Oracle.<operation> and AENS.<operation>) have an 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 signed varies for the different operations, but in all cases you should prepend the signature data with the network_id (ae_mainnet for the \u00e6ternity mainnet, etc.).
Sophia language offers standard library that consists of several namespaces. Some of them are already in the scope and do not need any actions to be used, while the others require some files to be included.
The out-of-the-box namespaces are:
The following ones need to be included as regular files with .aes suffix, for example
include \"List.aes\"\nThey are available without any explicit includes.
"},{"location":"sophia_stdlib/#address","title":"Address","text":""},{"location":"sophia_stdlib/#to_str","title":"to_str","text":"Address.to_str(a : address) : string\nBase58 encoded string
"},{"location":"sophia_stdlib/#is_contract","title":"is_contract","text":"Address.is_contract(a : address) : bool\nIs the address a contract
"},{"location":"sophia_stdlib/#is_oracle","title":"is_oracle","text":"Address.is_oracle(a : address) : bool\nIs the address a registered oracle
"},{"location":"sophia_stdlib/#is_payable","title":"is_payable","text":"Address.is_payable(a : address) : bool\nCan the address be spent to
"},{"location":"sophia_stdlib/#to_contract","title":"to_contract","text":"Address.to_contract(a : address) : C\nCast address to contract type C (where C is a contract)
The following functionality is available for interacting with the \u00e6ternity 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, i.e. the signature material should be prefixed by the network id.
datatype name = Name(address, Chain.ttl, map(string, AENS.pointee))\ndatatype pointee = AccountPt(address) | OraclePt(address)\n | ContractPt(address) | ChannelPt(address)\nAENS.resolve(name : string, key : string) : option('a)\nName resolution. Here name should be a registered name and key one of the attributes associated with this name (for instance \"account_pubkey\"). The return type ('a) must be resolved at compile time to an atomic type and the value is type checked against this type at run time.
AENS.lookup(name : string) : option(AENS.name)\nIf name is an active name AENS.lookup returns a name object. 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. For example:
let Some(Name(owner, FixedTTL(expiry), ptrs)) = AENS.lookup(\"example.chain\")\nAENS.preclaim(owner : address, commitment_hash : hash, <signature : signature>) : unit\nThe signature should be over network id + owner address + Contract.address (concatenated as byte arrays).
AENS.claim(owner : address, name : string, salt : int, name_fee : int, <signature : signature>) : unit\nThe signature should be over network id + owner address + name_hash + Contract.address (concatenated as byte arrays) using the private key of the owner account for signing.
AENS.transfer(owner : address, new_owner : address, name : string, <signature : signature>) : unit\nTransfers name to the new owner.
The signature should be over network id + owner address + name_hash + Contract.address (concatenated as byte arrays) using the private key of the owner account for signing.
AENS.revoke(owner : address, name : string, <signature : signature>) : unit\nRevokes the name to extend the ownership time.
The signature should be over network id + owner address + name_hash + Contract.address (concatenated as byte arrays) using the private key of the owner account for signing.
AENS.update(owner : address, name : string, expiry : option(Chain.ttl), client_ttl : option(int),\n new_ptrs : option(map(string, AENS.pointee)), <signature : signature>) : unit\nUpdates 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 block of the name is not changed.
Auth.tx : option(Chain.tx)\nWhere Chain.tx is (built-in) defined like:
namespace Chain =\n record tx = { paying_for : option(Chain.paying_for_tx)\n , ga_metas : list(Chain.ga_meta_tx)\n , actor : address\n , fee : int\n , ttl : int\n , tx : Chain.base_tx }\n\n datatype ga_meta_tx = GAMetaTx(address, int)\n datatype paying_for_tx = PayingForTx(address, int)\n datatype base_tx = SpendTx(address, int, string)\n | OracleRegisterTx | OracleQueryTx | OracleResponseTx | OracleExtendTx\n | NamePreclaimTx | NameClaimTx(hash) | NameUpdateTx(string)\n | NameRevokeTx(hash) | NameTransferTx(address, string)\n | ChannelCreateTx(address) | ChannelDepositTx(address, int) | ChannelWithdrawTx(address, int) |\n | ChannelForceProgressTx(address) | ChannelCloseMutualTx(address) | ChannelCloseSoloTx(address)\n | ChannelSlashTx(address) | ChannelSettleTx(address) | ChannelSnapshotSoloTx(address)\n | ContractCreateTx(int) | ContractCallTx(address, int)\n | GAAttachTx\nAuth.tx_hash : option(hash)\nGets the transaction hash during authentication.
"},{"location":"sophia_stdlib/#bits","title":"Bits","text":""},{"location":"sophia_stdlib/#none","title":"none","text":"Bits.none : bits\nA bit field with all bits cleared
"},{"location":"sophia_stdlib/#all","title":"all","text":"Bits.all : bits\nA bit field with all bits set
"},{"location":"sophia_stdlib/#set","title":"set","text":"Bits.set(b : bits, i : int) : bits\nSet bit i
"},{"location":"sophia_stdlib/#clear","title":"clear","text":"Bits.clear(b : bits, i : int) : bits\nClear bit i
"},{"location":"sophia_stdlib/#test","title":"test","text":"Bits.test(b : bits, i : int) : bool\nCheck if bit i is set
"},{"location":"sophia_stdlib/#sum","title":"sum","text":"Bits.sum(b : bits) : int\nCount the number of set bits
"},{"location":"sophia_stdlib/#union","title":"union","text":"Bits.union(a : bits, b : bits) : bits\nBitwise disjunction
"},{"location":"sophia_stdlib/#intersection","title":"intersection","text":"Bits.intersection(a : bits, b : bits) : bits\nBitwise conjunction
"},{"location":"sophia_stdlib/#difference","title":"difference","text":"Bits.difference(a : bits, b : bits) : bits\nEach bit is true if and only if it was 1 in a and 0 in b
Bytes.to_int(b : bytes(n)) : int\nInterprets the byte array as a big endian integer
"},{"location":"sophia_stdlib/#to_str_1","title":"to_str","text":"Bytes.to_str(b : bytes(n)) : string\nReturns the hexadecimal representation of the byte array
"},{"location":"sophia_stdlib/#concat","title":"concat","text":"Bytes.concat : (a : bytes(m), b : bytes(n)) => bytes(m + n)\nConcatenates two byte arrays
"},{"location":"sophia_stdlib/#split","title":"split","text":"Bytes.split(a : bytes(m + n)) : bytes(m) * bytes(n)\nSplits a byte array at given index
"},{"location":"sophia_stdlib/#call","title":"Call","text":"Values related to the call to the current contract
"},{"location":"sophia_stdlib/#origin","title":"origin","text":"Call.origin : address\nThe address of the account that signed the call transaction that led to this call.
"},{"location":"sophia_stdlib/#caller","title":"caller","text":"Call.caller : address\nThe address of the entity (possibly another contract) calling the contract.
"},{"location":"sophia_stdlib/#value","title":"value","text":"Call.value : int\nThe amount of coins transferred to the contract in the call.
"},{"location":"sophia_stdlib/#gas_price","title":"gas_price","text":"Call.gas_price : int\nThe gas price of the current call.
"},{"location":"sophia_stdlib/#fee","title":"fee","text":"Call.fee : int\nThe fee of the current call.
"},{"location":"sophia_stdlib/#gas_left","title":"gas_left","text":"Call.gas_left() : int\nThe amount of gas left for the current call.
"},{"location":"sophia_stdlib/#chain","title":"Chain","text":"Values and functions related to the chain itself and other entities that live on it.
"},{"location":"sophia_stdlib/#types_1","title":"Types","text":""},{"location":"sophia_stdlib/#tx_1","title":"tx","text":"record tx = { paying_for : option(Chain.paying_for_tx)\n , ga_metas : list(Chain.ga_meta_tx)\n , actor : address\n , fee : int\n , ttl : int\n , tx : Chain.base_tx }\ndatatype ga_meta_tx = GAMetaTx(address, int)\ndatatype paying_for_tx = PayingForTx(address, int)\ndatatype base_tx = SpendTx(address, int, string)\n | OracleRegisterTx | OracleQueryTx | OracleResponseTx | OracleExtendTx\n | NamePreclaimTx | NameClaimTx(hash) | NameUpdateTx(string)\n | NameRevokeTx(hash) | NameTransferTx(address, string)\n | ChannelCreateTx(address) | ChannelDepositTx(address, int) | ChannelWithdrawTx(address, int) |\n | ChannelForceProgressTx(address) | ChannelCloseMutualTx(address) | ChannelCloseSoloTx(address)\n | ChannelSlashTx(address) | ChannelSettleTx(address) | ChannelSnapshotSoloTx(address)\n | ContractCreateTx(int) | ContractCallTx(address, int)\n | GAAttachTx\nChain.balance(a : address) : int\nThe balance of account a.
Chain.block_hash(h : int) : option(bytes(32))\nThe hash of the block at height h. h has to be within 256 blocks from the current height of the chain or else the function will return None.
NOTE: In FATE VM version 1 Chain.block_height was not considered an allowed height. From FATE VM version 2 (IRIS) it will return the block hash of the current generation.
Chain.block_height : int\"\nThe height of the current block (i.e. the block in which the current call will be included).
"},{"location":"sophia_stdlib/#bytecode_hash","title":"bytecode_hash","text":"Chain.bytecode_hash : 'c => option(hash)\nReturns the hash of the contract's bytecode (or None if it is nonexistent or deployed before FATE2). The type 'c must be instantiated with a contract. The charged gas increases linearly to the size of the serialized bytecode of the deployed contract.
Chain.create(value : int, ...) => 'c\nCreates and deploys a new instance of a contract 'c. All of the unnamed arguments will be passed to the init function. The charged gas increases linearly with the size of the compiled child contract's bytecode. The source_hash on-chain entry of the newly created contract will be the SHA256 hash over concatenation of
The resulting contract's public key can be predicted and in case it happens to have some funds before its creation, its balance will be increased by the value parameter.
The value argument (default 0) is equivalent to the value in the contract creation transaction \u2013 it sets the initial value of the newly created contract charging the calling contract. Note that this won't be visible in Call.value in the init call of the new contract. It will be included in Contract.balance, however.
The type 'c must be instantiated with a contract.
Example usage:
payable contract Auction =\n record state = {supply: int, name: string}\n entrypoint init(supply, name) = {supply: supply, name: name}\n stateful payable entrypoint buy(amount) =\n require(Call.value == amount, \"amount_value_mismatch\")\n ...\n stateful entrypoint sell(amount) =\n require(amount >= 0, \"negative_amount\")\n ...\n\nmain contract Market =\n type state = list(Auction)\n entrypoint init() = []\n stateful entrypoint new(name : string) =\n let new_auction = Chain.create(0, name) : Auction\n put(new_auction::state)\nThe typechecker must be certain about the created contract's type, so it is worth writing it explicitly as shown in the example.
"},{"location":"sophia_stdlib/#clone","title":"clone","text":"Chain.clone : ( ref : 'c, gas : int, value : int, protected : bool, ...\n ) => if(protected) option('c) else 'c\nClones the contract under the mandatory named argument ref. That means a new contract of the same bytecode and the same payable parameter shall be created. NOTE: the state won't be copied and the contract will be initialized with a regular call to the init function with the remaining unnamed arguments. The resulting contract's public key can be predicted and in case it happens to have some funds before its creation, its balance will be increased by the value parameter. This operation is significantly cheaper than Chain.create as it costs a fixed amount of gas.
The gas argument (default Call.gas_left) limits the gas supply for the init call of the cloned contract.
The value argument (default 0) is equivalent to the value in the contract creation transaction \u2013 it sets the initial value of the newly created contract charging the calling contract. Note that this won't be visible in Call.value in the init call of the new contract. It will be included in Contract.balance, however.
The protected argument (default false) works identically as in remote calls. If set to true it will change the return type to option('c) and will catch all errors such as abort, out of gas and wrong arguments. Note that it can only take a boolean literal, so other expressions such as variables will be rejected by the compiler.
The type 'c must be instantiated with a contract.
Example usage:
payable contract interface Auction =\n entrypoint init : (int, string) => void\n stateful payable entrypoint buy : (int) => ()\n stateful entrypoint sell : (int) => ()\n\nmain contract Market =\n type state = list(Auction)\n entrypoint init() = []\n stateful entrypoint new_of(template : Auction, name : string) =\n switch(Chain.clone(ref=template, protected=true, 0, name))\n None => abort(\"Bad auction!\")\n Some(new_auction) =>\n put(new_auction::state)\nWhen cloning by an interface, init entrypoint declaration is required. It is a good practice to set its return type to void in order to indicate that this function is not supposed to be called and is state agnostic. Trivia: internal implementation of the init function does not actually return state, but calls put instead. Moreover, FATE prevents even handcrafted calls to init.
Chain.coinbase : address\nThe address of the account that mined the current block.
"},{"location":"sophia_stdlib/#difficulty","title":"difficulty","text":"Chain.difficulty : int\nThe difficulty of the current block.
"},{"location":"sophia_stdlib/#event","title":"event","text":"Chain.event(e : event) : unit\nEmits the event. To use this function one needs to define the event type as a datatype in the contract.
Chain.gas_limit : int\nThe gas limit of the current block.
"},{"location":"sophia_stdlib/#spend","title":"spend","text":"Chain.spend(to : address, amount : int) : unit\nSpend amount tokens to to. Will fail (and abort the contract) if contract doesn't have amount tokens to transfer, or, if to is not payable.
Chain.timestamp : int\nThe timestamp of the current block (unix time, milliseconds).
"},{"location":"sophia_stdlib/#char","title":"Char","text":""},{"location":"sophia_stdlib/#to_int_1","title":"to_int","text":"Char.to_int(c : char) : int
Char.from_int(i : int) : option(char)Returns the UTF-8 codepoint of a character\n\n\n#### from_int\n
Opposite of to_int. Returns None if the integer doesn't correspond to a single (normalized) codepoint.
Values related to the current contract
"},{"location":"sophia_stdlib/#creator","title":"creator","text":"Contract.creator : address\nAddress of the entity that signed the contract creation transaction
"},{"location":"sophia_stdlib/#address_1","title":"address","text":"Contract.address : address\nAddress of the contract account
"},{"location":"sophia_stdlib/#balance_1","title":"balance","text":"Contract.balance : int\nAmount of coins in the contract account
"},{"location":"sophia_stdlib/#crypto","title":"Crypto","text":""},{"location":"sophia_stdlib/#sha3","title":"sha3","text":"Crypto.sha3(x : 'a) : hash\nHash any object to SHA3
"},{"location":"sophia_stdlib/#sha256","title":"sha256","text":"Crypto.sha256(x : 'a) : hash\nHash any object to SHA256
"},{"location":"sophia_stdlib/#blake2b","title":"blake2b","text":"Crypto.blake2b(x : 'a) : hash\nHash any object to blake2b
"},{"location":"sophia_stdlib/#verify_sig","title":"verify_sig","text":"Crypto.verify_sig(msg : hash, pubkey : address, sig : signature) : bool\nChecks if the signature of msg was made using private key corresponding to the pubkey
Crypto.ecverify_secp256k1(msg : hash, addr : bytes(20), sig : bytes(65)) : bool\nVerifies a signature for a msg against an Ethereum style address. Note that the signature should be 65 bytes and include the recovery identifier byte V. The expected organization of the signature is (V || R || S).
Crypto.ecrecover_secp256k1(msg : hash, sig : bytes(65)) : option(bytes(20))\nRecovers the Ethereum style address from a msg hash and respective ECDSA-signature. Note that the signature should be 65 bytes and include the recovery identifier byte V. The expected organization of the signature is (V || R || S).
Crypto.verify_sig_secp256k1(msg : hash, pubkey : bytes(64), sig : bytes(64)) : bool\nVerifies a standard 64-byte ECDSA signature (R || S).
Int.to_str : int => string\nCasts integer to string using decimal representation
"},{"location":"sophia_stdlib/#map","title":"Map","text":""},{"location":"sophia_stdlib/#lookup_1","title":"lookup","text":"Map.lookup(k : 'k, m : map('k, 'v)) : option('v)
Returns the value under a key in given map as Some or None if the key is not present
Map.lookup_default(k : 'k, m : map('k, 'v), v : 'v) : 'v
Returns the value under a key in given map or the default value v if the key is not present
Map.member(k : 'k, m : map('k, 'v)) : bool
Checks if the key is present in the map
"},{"location":"sophia_stdlib/#delete","title":"delete","text":"Map.delete(k : 'k, m : map('k, 'v)) : map('k, 'v)
Removes the key from the map
"},{"location":"sophia_stdlib/#size","title":"size","text":"Map.size(m : map('k, 'v)) : int
Returns the number of elements in the map
"},{"location":"sophia_stdlib/#to_list","title":"to_list","text":"Map.to_list(m : map('k, 'v)) : list('k * 'v)
Returns a list containing pairs of keys and their respective elements.
"},{"location":"sophia_stdlib/#from_list","title":"from_list","text":"Map.from_list(m : list('k * 'v)) : map('k, 'v)
Turns a list of pairs of form (key, value) into a map
Oracle.register(<signature : bytes(64)>, acct : address, qfee : int, ttl : Chain.ttl) : oracle('a, 'b)\nRegisters new oracle answering questions of type 'a with answers of type 'b.
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 network id + account address + contract address (concatenated as byte arrays) is signed with 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.qfee is the minimum query fee to be paid by a user when asking a question of the oracle.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)).'a is the type of the question to ask.'b is the type of the oracle answers.Examples:
Oracle.register(addr0, 25, RelativeTTL(400))\n Oracle.register(addr1, 25, RelativeTTL(500), signature = sign1)\nOracle.get_question(o : oracle('a, 'b), q : oracle_query('a, 'b)) : 'a\nChecks 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\nResponds 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 the network id + oracle query id + contract address
Oracle.extend(<signature : bytes(64)>, o : oracle('a, 'b), ttl : Chain.ttl) : unit\nExtends 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.
Oracle.query_fee(o : oracle('a, 'b)) : int\nReturns the query fee of the oracle
"},{"location":"sophia_stdlib/#query","title":"query","text":"Oracle.query(o : oracle('a, 'b), q : 'a, qfee : int, qttl : Chain.ttl, rttl : Chain.ttl) : oracle_query('a, 'b)\nAsks 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.
Oracle.get_answer(o : oracle('a, 'b), q : oracle_query('a, 'b)) : option('b)\nChecks what is the optional query answer
"},{"location":"sophia_stdlib/#expiry","title":"expiry","text":"Oracle.expiry(o : oracle('a, 'b)) : int\nAsk the oracle when it expires. The result is the block height at which it will happen.
"},{"location":"sophia_stdlib/#check","title":"check","text":"Oracle.check(o : oracle('a, 'b)) : bool\nReturns true iff the oracle o exists and has correct type
Oracle.check_query(o : oracle('a, 'b), q : oracle_query('a, 'b)) : bool\nIt returns true iff the oracle query exist and has the expected type.
These need to be explicitly included (with .aes suffix)
Bitwise operations on arbitrary precision integers.
"},{"location":"sophia_stdlib/#bsr","title":"bsr","text":"Bitwise.bsr(n : int, x : int) : int\nLogical bit shift x right n positions.
Bitwise.bsl(n : int, x : int) : int\nLogical bit shift x left n positions.
Bitwise.bsli(n : int, x : int, lim : int) : int\nLogical bit shift x left n positions, limit to lim bits.
Bitwise.band(x : int, y : int) : int\nBitwise and of x and y.
Bitwise.bor(x : int, y : int) : int\nBitwise or of x and y.
Bitwise.bxor(x : int, y : int) : int\nBitwise xor of x and y.
Bitwise.bnot(x : int) : int\nBitwise not of x. Defined and implemented as bnot(x) = bxor(x, -1).
Bitwise.uband(x : int, y : int) : int\nBitwise and of non-negative numbers x and y.
Bitwise.ubor(x : int, y : int) : int\nBitwise or of non-negative x and y.
Bitwise.ubxor(x : int, y : int) : int\nBitwise xor of non-negative x and y.
Built-in (Montgomery) integer representation 32 bytes
"},{"location":"sophia_stdlib/#fp","title":"fp","text":"Built-in (Montgomery) integer representation 48 bytes
"},{"location":"sophia_stdlib/#fp2","title":"fp2","text":"record fp2 = { x1 : fp, x2 : fp }`\nrecord g1 = { x : fp, y : fp, z : fp }\nrecord g2 = { x : fp2, y : fp2, z : fp2 }\nrecord gt = { x1 : fp, x2 : fp, x3 : fp, x4 : fp, x5 : fp, x6 : fp, x7 : fp, x8 : fp, x9 : fp, x10 : fp, x11 : fp, x12 : fp }\nBLS12_381.pairing_check(xs : list(g1), ys : list(g2)) : bool\nPairing check of a list of points, xs and ys should be of equal length.
BLS12_381.int_to_fr(x : int) : fr\nConvert an integer to an fr - a 32 bytes internal (Montgomery) integer representation.
BLS12_381.int_to_fp(x : int) : fp\nConvert an integer to an fp - a 48 bytes internal (Montgomery) integer representation.
BLS12_381.fr_to_int(x : fr) : int\nConvert a fr value into an integer.
BLS12_381.fp_to_int(x : fp) : int\nConvert a fp value into an integer.
BLS12_381.mk_g1(x : int, y : int, z : int) : g1\nConstruct a g1 point from three integers.
BLS12_381.mk_g2(x1 : int, x2 : int, y1 : int, y2 : int, z1 : int, z2 : int) : g2\nConstruct a g2 point from six integers.
BLS12_381.g1_neg(p : g1) : g1\nNegate a g1 value.
BLS12_381.g1_norm(p : g1) : g1\nNormalize a g1 value.
BLS12_381.g1_valid(p : g1) : bool\nCheck that a g1 value is a group member.
BLS12_381.g1_is_zero(p : g1) : bool\nCheck if a g1 value corresponds to the zero value of the group.
BLS12_381.g1_add(p : g1, q : g1) : g1\nAdd two g1 values.
BLS12_381.g1_mul(k : fr, p : g1) : g1\nScalar multiplication for g1.
BLS12_381.g2_neg(p : g2) : g2\nNegate a g2 value.
BLS12_381.g2_norm(p : g2) : g2\nNormalize a g2 value.
BLS12_381.g2_valid(p : g2) : bool\nCheck that a g2 value is a group member.
BLS12_381.g2_is_zero(p : g2) : bool\nCheck if a g2 value corresponds to the zero value of the group.
BLS12_381.g2_add(p : g2, q : g2) : g2\nAdd two g2 values.
BLS12_381.g2_mul(k : fr, p : g2) : g2\nScalar multiplication for g2.
BLS12_381.gt_inv(p : gt) : gt\nInvert a gt value.
BLS12_381.gt_add(p : gt, q : gt) : gt\nAdd two gt values.
BLS12_381.gt_mul(p : gt, q : gt) : gt\nMultiply two gt values.
BLS12_381.gt_pow(p : gt, k : fr) : gt\nCalculate exponentiation p ^ k.
BLS12_381.gt_is_one(p : gt) : bool\nCompare a gt value to the unit value of the Gt group.
BLS12_381.pairing(p : g1, q : g2) : gt\nCompute the pairing of a g1 value and a g2 value.
BLS12_381.miller_loop(p : g1, q : g2) : gt\nDo the Miller loop stage of pairing for g1 and g2.
BLS12_381.final_exp(p : gt) : gt\nPerform the final exponentiation step of pairing for a gt value.
Functional combinators.
"},{"location":"sophia_stdlib/#id","title":"id","text":"Func.id(x : 'a) : 'a\nIdentity function. Returns its argument.
"},{"location":"sophia_stdlib/#const","title":"const","text":"Func.const(x : 'a) : 'b => 'a = (y) => x\nConstant function constructor. Given x returns a function that returns x regardless of its argument.
Func.flip(f : ('a, 'b) => 'c) : ('b, 'a) => 'c\nSwitches order of arguments of arity 2 function.
"},{"location":"sophia_stdlib/#comp","title":"comp","text":"Func.comp(f : 'b => 'c, g : 'a => 'b) : 'a => 'c\nFunction composition. comp(f, g)(x) == f(g(x)).
Func.pipe(f : 'a => 'b, g : 'b => 'c) : 'a => 'c\nFlipped function composition. pipe(f, g)(x) == g(f(x)).
Func.rapply(x : 'a, f : 'a => 'b) : 'b\nReverse application. rapply(x, f) == f(x).
Func.recur(f : ('arg => 'res, 'arg) => 'res) : 'arg => 'res\nThe Z combinator. Allows performing local recursion and having anonymous recursive lambdas. To make function A => B recursive the user needs to transform it to take two arguments instead \u2013 one of type A => B which is going to work as a self-reference, and the other one of type A which is the original argument. Therefore, transformed function should have (A => B, A) => B signature.
Example usage:
let factorial = recur((fac, n) => if(n < 2) 1 else n * fac(n - 1))\nIf the function is going to take more than one argument it will need to be either tuplified or have curried out latter arguments.
Example (factorial with custom step):
// tuplified version\nlet factorial_t(n, step) =\n let fac(rec, args) =\n let (n, step) = args\n if(n < 2) 1 else n * rec((n - step, step))\n recur(fac)((n, step))\n\n// curried version\nlet factorial_c(n, step) =\n let fac(rec, n) = (step) =>\n if(n < 2) 1 else n * rec(n - 1)(step)\n recur(fac)(n)(step)\nFunc.iter(n : int, f : 'a => 'a) : 'a => 'a\nnth composition of f with itself, for instance iter(3, f) is equivalent to (x) => f(f(f(x))).
Func.curry2(f : ('a, 'b) => 'c) : 'a => ('b => 'c)\nFunc.curry3(f : ('a, 'b, 'c) => 'd) : 'a => ('b => ('c => 'd))\nTurns a function that takes n arguments into a curried function that takes one argument and returns a function that waits for the rest in the same manner. For instance curry2((a, b) => a + b)(1)(2) == 3.
Func.uncurry2(f : 'a => ('b => 'c)) : ('a, 'b) => 'c\nFunc.uncurry3(f : 'a => ('b => ('c => 'd))) : ('a, 'b, 'c) => 'd\nOpposite to curry.
"},{"location":"sophia_stdlib/#tuplify","title":"tuplify","text":"Func.tuplify2(f : ('a, 'b) => 'c) : (('a * 'b)) => 'c\nFunc.tuplify3(f : ('a, 'b, 'c) => 'd) : 'a * 'b * 'c => 'd\nTurns a function that takes n arguments into a function that takes an n-tuple.
"},{"location":"sophia_stdlib/#untuplify","title":"untuplify","text":"Func.untuplify2(f : 'a * 'b => 'c) : ('a, 'b) => 'c\nFunc.untuplify3(f : 'a * 'b * 'c => 'd) : ('a, 'b, 'c) => 'd\nOpposite to tuplify.
"},{"location":"sophia_stdlib/#frac","title":"Frac","text":"This namespace provides operations on rational numbers. A rational number is represented as a fraction of two integers which are stored internally in the frac datatype.
The datatype consists of three constructors Neg/2, Zero/0 and Pos/2 which determine the sign of the number. Both values stored in Neg and Pos need to be strictly positive integers. However, when creating a frac you should never use the constructors explicitly. Instead of that, always use provided functions like make_frac or from_int. This helps keeping the internal representation well defined.
The described below functions take care of the normalization of the fractions \u2013 they won't grow if it is unnecessary. Please note that the size of frac can be still very big while the value is actually very close to a natural number \u2013 the division of two extremely big prime numbers will be as big as both of them. To face this issue the optimize function is provided. It will approximate the value of the fraction to fit in the given error margin and to shrink its size as much as possible.
Important note: frac must not be compared using standard <-like operators. The operator comparison is not possible to overload at this moment, nor the language provides checkers to prevent unintended usage of them. Therefore the typechecker will allow that and the results of such comparison will be unspecified. You should use lt, geq, eq etc instead.
datatype frac = Pos(int, int) | Zero | Neg(int, int)\nInternal representation of fractional numbers. First integer encodes the numerator and the second the denominator \u2013 both must be always positive, as the sign is being handled by the choice of the constructor.
"},{"location":"sophia_stdlib/#functions_3","title":"Functions","text":""},{"location":"sophia_stdlib/#make_frac","title":"make_frac","text":"Frac.make_frac(n : int, d : int) : frac
Creates a fraction out of numerator and denominator. Automatically normalizes, so make_frac(2, 4) and make_frac(1, 2) will yield same results.
Frac.num(f : frac) : int
Returns the numerator of a fraction.
"},{"location":"sophia_stdlib/#den","title":"den","text":"Frac.den(f : frac) : int
Returns the denominator of a fraction.
"},{"location":"sophia_stdlib/#to_pair","title":"to_pair","text":"Frac.to_pair(f : frac) : int * int
Turns a fraction into a pair of numerator and denominator.
"},{"location":"sophia_stdlib/#sign","title":"sign","text":"Frac.sign(f : frac) : int
Returns the signum of a fraction, -1, 0, 1 if negative, zero, positive respectively.
"},{"location":"sophia_stdlib/#to_str_3","title":"to_str","text":"Frac.to_str(f : frac) : string
Conversion to string. Does not display division by 1 or denominator if equals zero.
"},{"location":"sophia_stdlib/#simplify","title":"simplify","text":"Frac.simplify(f : frac) : frac
Reduces fraction to normal form if for some reason it is not in it.
"},{"location":"sophia_stdlib/#eq","title":"eq","text":"Frac.eq(a : frac, b : frac) : bool
Checks if a is equal to b.
Frac.neq(a : frac, b : frac) : bool
Checks if a is not equal to b.
Frac.geq(a : frac, b : frac) : bool
Checks if a is greater or equal to b.
Frac.leq(a : frac, b : frac) : bool
Checks if a is lesser or equal to b.
Frac.gt(a : frac, b : frac) : bool
Checks if a is greater than b.
Frac.lt(a : frac, b : frac) : bool
Checks if a is lesser than b.
Frac.min(a : frac, b : frac) : frac
Chooses lesser of the two fractions.
"},{"location":"sophia_stdlib/#max","title":"max","text":"Frac.max(a : frac, b : frac) : frac
Chooses greater of the two fractions.
"},{"location":"sophia_stdlib/#abs","title":"abs","text":"Frac.abs(f : frac) : frac
Absolute value.
"},{"location":"sophia_stdlib/#from_int","title":"from_int","text":"Frac.from_int(n : int) : frac
From integer conversion. Effectively make_frac(n, 1).
Frac.floor(f : frac) : int
Rounds a fraction to the nearest lesser or equal integer.
"},{"location":"sophia_stdlib/#ceil","title":"ceil","text":"Frac.ceil(f : frac) : int
Rounds a fraction to the nearest greater or equal integer.
"},{"location":"sophia_stdlib/#round_to_zero","title":"round_to_zero","text":"Frac.round_to_zero(f : frac) : int
Rounds a fraction towards zero. Effectively ceil if lesser than zero and floor if greater.
Frac.round_from_zero(f : frac) : int
Rounds a fraction from zero. Effectively ceil if greater than zero and floor if lesser.
Frac.round(f : frac) : int
Rounds a fraction to a nearest integer. If two integers are in the same distance it will choose the even one.
"},{"location":"sophia_stdlib/#add","title":"add","text":"Frac.add(a : frac, b : frac) : frac
Sum of the fractions.
"},{"location":"sophia_stdlib/#neg","title":"neg","text":"Frac.neg(a : frac) : frac
Negation of the fraction.
"},{"location":"sophia_stdlib/#sub","title":"sub","text":"Frac.sub(a : frac, b : frac) : frac
Subtraction of two fractions.
"},{"location":"sophia_stdlib/#inv","title":"inv","text":"Frac.inv(a : frac) : frac
Inverts a fraction. Throws error if a is zero.
Frac.mul(a : frac, b : frac) : frac
Multiplication of two fractions.
"},{"location":"sophia_stdlib/#div","title":"div","text":"Frac.div(a : frac, b : frac) : frac
Division of two fractions.
"},{"location":"sophia_stdlib/#int_exp","title":"int_exp","text":"Frac.int_exp(b : frac, e : int) : frac
Takes b to the power of e. The exponent can be a negative value.
Frac.optimize(f : frac, loss : frac) : frac
Shrink the internal size of a fraction as much as possible by approximating it to the point where the error would exceed the loss value.
Frac.is_sane(f : frac) : bool
For debugging. If it ever returns false in a code that doesn't call frac constructors or accept arbitrary fracs from the surface you should report it as a bug
If you expect getting calls with malformed fracs in your contract, you should use this function to verify the input.
This module contains common operations on lists like constructing, querying, traversing etc.
"},{"location":"sophia_stdlib/#is_empty","title":"is_empty","text":"List.is_empty(l : list('a)) : bool\nReturns true iff the list is equal to [].
List.first(l : list('a)) : option('a)\nReturns Some of the first element of a list or None if the list is empty.
List.tail(l : list('a)) : option(list('a))\nReturns Some of a list without its first element or None if the list is empty.
List.last(l : list('a)) : option('a)\nReturns Some of the last element of a list or None if the list is empty.
List.contains(e : 'a, l : list('a)) : bool\nl contains element e. Equivalent to List.find(x => x == e, l) != None."},{"location":"sophia_stdlib/#find","title":"find","text":"List.find(p : 'a => bool, l : list('a)) : option('a)\nFinds first element of l fulfilling predicate p as Some or None if no such element exists.
List.find_indices(p : 'a => bool, l : list('a)) : list(int)\nReturns list of all indices of elements from l that fulfill the predicate p.
List.nth(n : int, l : list('a)) : option('a)\nGets nth element of l as Some or None if l is shorter than n + 1 or n is negative.
List.get(n : int, l : list('a)) : 'a\nGets nth element of l forcefully, throwing and error if l is shorter than n + 1 or n is negative.
List.length(l : list('a)) : int\nReturns length of a list.
"},{"location":"sophia_stdlib/#from_to","title":"from_to","text":"List.from_to(a : int, b : int) : list(int)\nCreates an ascending sequence of all integer numbers between a and b (including a and b).
List.from_to_step(a : int, b : int, step : int) : list(int)\nCreates an ascending sequence of integer numbers betweeen a and b jumping by given step. Includes a and takes b only if (b - a) mod step == 0. step should be bigger than 0.
List.replace_at(n : int, e : 'a, l : list('a)) : list('a)\nReplaces nth element of l with e. Throws an error if n is negative or would cause an overflow.
List.insert_at(n : int, e : 'a, l : list('a)) : list('a)\nInserts e into l to be on position n by shifting following elements further. For instance,
insert_at(2, 9, [1,2,3,4])\n[1,2,9,3,4]."},{"location":"sophia_stdlib/#insert_by","title":"insert_by","text":"List.insert_by(cmp : (('a, 'a) => bool), x : 'a, l : list('a)) : list('a)\nAssuming that cmp represents < comparison, inserts x before the first element in the list l which is greater than it. For instance,
insert_by((a, b) => a < b, 4, [1,2,3,5,6,7])\n[1,2,3,4,5,6,7]"},{"location":"sophia_stdlib/#foldr","title":"foldr","text":"List.foldr(cons : ('a, 'b) => 'b, nil : 'b, l : list('a)) : 'b\nRight fold of a list. Assuming l = [x, y, z] will return f(x, f(y, f(z, nil))). Not tail recursive.
List.foldl(rcons : ('b, 'a) => 'b, acc : 'b, l : list('a)) : 'b\nLeft fold of a list. Assuming l = [x, y, z] will return f(f(f(acc, x), y), z). Tail recursive.
List.foreach(l : list('a), f : 'a => unit) : unit\nEvaluates f on each element of a list.
List.reverse(l : list('a)) : list('a)\nReturns a copy of l with reversed order of elements.
List.map(f : 'a => 'b, l : list('a)) : list('b)\nMaps function f over a list. For instance
map((x) => x == 0, [1, 2, 0, 3, 0])\n[false, false, true, false, true]"},{"location":"sophia_stdlib/#flat_map","title":"flat_map","text":"List.flat_map(f : 'a => list('b), l : list('a)) : list('b)\nMaps f over a list and then flattens it. For instance
flat_map((x) => [x, x * 10], [1, 2, 3])\n[1, 10, 2, 20, 3, 30]"},{"location":"sophia_stdlib/#filter","title":"filter","text":"List.filter(p : 'a => bool, l : list('a)) : list('a)\nFilters out elements of l that fulfill predicate p. For instance
filter((x) => x > 0, [-1, 1, -2, 0, 1, 2, -3])\n[1, 1, 2]"},{"location":"sophia_stdlib/#take","title":"take","text":"List.take(n : int, l : list('a)) : list('a)\nTakes n first elements of l. Fails if n is negative. If n is greater than length of a list it will return whole list.
List.drop(n : int, l : list('a)) : list('a)\nRemoves n first elements of l. Fails if n is negative. If n is greater than length of a list it will return [].
List.take_while(p : 'a => bool, l : list('a)) : list('a)\nReturns longest prefix of l in which all elements fulfill p.
List.drop_while(p : 'a => bool, l : list('a)) : list('a)\nRemoves longest prefix from l in which all elements fulfill p.
List.partition(p : 'a => bool, l : list('a)) : (list('a) * list('a))\nSeparates elements of l that fulfill p and these that do not. Elements fulfilling predicate will be in the right list. For instance
partition((x) => x > 0, [-1, 1, -2, 0, 1, 2, -3])\n([1, 1, 2], [-1, -2, 0, -3])"},{"location":"sophia_stdlib/#flatten","title":"flatten","text":"List.flatten(ll : list(list('a))) : list('a)\nFlattens a list of lists into a one list.
"},{"location":"sophia_stdlib/#all_1","title":"all","text":"List.all(p : 'a => bool, l : list('a)) : bool\nChecks if all elements of a list fulfill predicate p.
List.any(p : 'a => bool, l : list('a)) : bool\nChecks if any element of a list fulfills predicate p.
List.sum(l : list(int)) : int\nSums elements of a list. Returns 0 if the list is empty.
"},{"location":"sophia_stdlib/#product","title":"product","text":"List.product(l : list(int)) : int\nMultiplies elements of a list. Returns 1 if the list is empty.
"},{"location":"sophia_stdlib/#zip_with","title":"zip_with","text":"List.zip_with(f : ('a, 'b) => 'c, l1 : list('a), l2 : list('b)) : list('c)\n\"zips\" two lists with a function. n-th element of resulting list will be equal to f(x1, x2) where x1 and x2 are n-th elements of l1 and l2 respectively. Will cut off the tail of the longer list. For instance
zip_with((a, b) => a + b, [1,2], [1,2,3])\n[2,4]"},{"location":"sophia_stdlib/#zip","title":"zip","text":"List.zip(l1 : list('a), l2 : list('b)) : list('a * 'b)\nSpecial case of zip_with where the zipping function is (a, b) => (a, b).
List.unzip(l : list('a * 'b)) : list('a) * list('b)\nOpposite to the zip operation. Takes a list of pairs and returns pair of lists with respective elements on same indices.
List.merge(lesser_cmp : ('a, 'a) => bool, l1 : list('a), l2 : list('a)) : list('a)\nMerges two sorted lists into a single sorted list. O(length(l1) + length(l2))
"},{"location":"sophia_stdlib/#sort","title":"sort","text":"List.sort(lesser_cmp : ('a, 'a) => bool, l : list('a)) : list('a)\nSorts a list using given comparator. lesser_cmp(x, y) should return true iff x < y. If lesser_cmp is not transitive or there exists an element x such that lesser_cmp(x, x) or there exists a pair of elements x and y such that lesser_cmp(x, y) && lesser_cmp(y, x) then the result is undefined. O(length(l) * log_2(length(l))).
List.intersperse(delim : 'a, l : list('a)) : list('a)\nIntersperses elements of l with delim. Does nothing on empty lists and singletons. For instance
intersperse(0, [1, 2, 3, 4])\n[1, 0, 2, 0, 3, 0, 4]"},{"location":"sophia_stdlib/#enumerate","title":"enumerate","text":"List.enumerate(l : list('a)) : list(int * 'a)\nEquivalent to zip with [0..length(l)], but slightly faster.
Common operations on option types and lists of options.
Option.is_none(o : option('a)) : bool\nReturns true iff o == None
Option.is_some(o : option('a)) : bool\nReturns true iff o is not None.
Option.match(n : 'b, s : 'a => 'b, o : option('a)) : 'b\nBehaves like pattern matching on option using two case functions.
Option.default(def : 'a, o : option('a)) : 'a\nEscapes option wrapping by providing default value for None.
Option.force(o : option('a)) : 'a\nForcefully escapes the option wrapping assuming it is Some. Aborts on None.
Option.force_msg(o : option('a), err : string) : 'a\nForcefully escapes the option wrapping assuming it is Some. Aborts with err error message on None.
Option.contains(e : 'a, o : option('a)) : bool\ntrue if and only if o contains element equal to e. Equivalent to Option.match(false, x => x == e, o)."},{"location":"sophia_stdlib/#on_elem","title":"on_elem","text":"Option.on_elem(o : option('a), f : 'a => unit) : unit\nEvaluates f on element under Some. Does nothing on None.
Option.map(f : 'a => 'b, o : option('a)) : option('b)\nMaps element under Some. Leaves None unchanged.
Option.map2(f : ('a, 'b) => 'c, o1 : option('a), o2 : option('b)) : option('c)\nApplies arity 2 function over two options' elements. Returns Some iff both of o1 and o2 were Some, or None otherwise. For instance
map2((a, b) => a + b, Some(1), Some(2))\nSome(3) and map2((a, b) => a + b, Some(1), None)\nNone."},{"location":"sophia_stdlib/#map3","title":"map3","text":"Option.map3(f : ('a, 'b, 'c) => 'd, o1 : option('a), o2 : option('b), o3 : option('c)) : option('d)\nSame as map2 but with arity 3 function.
"},{"location":"sophia_stdlib/#app_over","title":"app_over","text":"Option.app_over(f : option ('a => 'b), o : option('a)) : option('b)\nApplies function under option over argument under option. If either of them is None the result will be None as well. For instance
app_over(Some((x) => x + 1), Some(1))\nSome(2) and app_over(Some((x) => x + 1), None)\nNone."},{"location":"sophia_stdlib/#flat_map_1","title":"flat_map","text":"Option.flat_map(f : 'a => option('b), o : option('a)) : option('b)\nPerforms monadic bind on an option. Extracts element from o (if present) and forms new option from it. For instance
flat_map((x) => Some(x + 1), Some(1))\nSome(2) and flat_map((x) => Some(x + 1), None)\nNone."},{"location":"sophia_stdlib/#to_list_1","title":"to_list","text":"Option.to_list(o : option('a)) : list('a)\nTurns o into an empty (if None) or singleton (if Some) list.
Option.filter_options(l : list(option('a))) : list('a)\nRemoves Nones from list and unpacks all remaining Somes. For instance
filter_options([Some(1), None, Some(2)])\n[1, 2]."},{"location":"sophia_stdlib/#seq_options","title":"seq_options","text":"Option.seq_options(l : list (option('a))) : option (list('a))\nTries to unpack all elements of a list from Somes. Returns None if at least element of l is None. For instance
seq_options([Some(1), Some(2)])\nSome([1, 2]), but seq_options([Some(1), Some(2), None])\nNone."},{"location":"sophia_stdlib/#choose","title":"choose","text":"Option.choose(o1 : option('a), o2 : option('a)) : option('a)\nOut of two options choose the one that is Some, or None if both are Nones.
Option.choose_first(l : list(option('a))) : option('a)\nSame as choose, but chooses from a list insted of two arguments.
"},{"location":"sophia_stdlib/#pair","title":"Pair","text":"Common operations on 2-tuples.
"},{"location":"sophia_stdlib/#fst","title":"fst","text":"Pair.fst(t : ('a * 'b)) : 'a\nFirst element projection.
"},{"location":"sophia_stdlib/#snd","title":"snd","text":"Pair.snd(t : ('a * 'b)) : 'b\nSecond element projection.
"},{"location":"sophia_stdlib/#map1","title":"map1","text":"Pair.map1(f : 'a => 'c, t : ('a * 'b)) : ('c * 'b)\nApplies function over first element.
"},{"location":"sophia_stdlib/#map2_1","title":"map2","text":"Pair.map2(f : 'b => 'c, t : ('a * 'b)) : ('a * 'c)\nApplies function over second element.
"},{"location":"sophia_stdlib/#bimap","title":"bimap","text":"Pair.bimap(f : 'a => 'c, g : 'b => 'd, t : ('a * 'b)) : ('c * 'd)\nApplies functions over respective elements.
"},{"location":"sophia_stdlib/#swap","title":"swap","text":"Pair.swap(t : ('a * 'b)) : ('b * 'a)\nSwaps elements.
"},{"location":"sophia_stdlib/#set_1","title":"Set","text":""},{"location":"sophia_stdlib/#types_4","title":"Types","text":"record set('a) = { to_map : map('a, unit) }\nSet.new() : set('a)\nReturns an empty set
"},{"location":"sophia_stdlib/#member_1","title":"member","text":"member(e : 'a, s : set('a)) : bool\nChecks if the element e is present in the set s
insert(e : 'a, s : set('a)) : set('a)\nInserts the element e in the set s
Set.delete(e : 'a, s : set('a)) : set('a)\nRemoves the element e from the set s
size(s : set('a)) : int\nReturns the number of elements in the set s
Set.to_list(s : set('a)) : list('a)\nReturns a list containing the elements of the set s
Set.from_list(l : list('a)) : set('a)\nTurns the list l into a set
Set.filter(p : 'a => bool, s : set('a)) : set('a)\nFilters out elements of s that fulfill predicate p
Set.fold(f : ('a, 'b) => 'b, acc : 'b, s : set('a)) : 'b\nFolds the function f over every element in the set s and returns the final value of the accumulator acc.
Set.subtract(s1 : set('a), s2 : set('a)) : set('a)\nReturns the elements of s1 that are not members of s2
Set.intersection(s1 : set('a), s2 : set('a)) : set('a)\nReturns the intersection of the two sets s1 and s2
Set.intersection_list(sets : list(set('a))) : set('a)\nReturns the intersection of all the sets in the given list
"},{"location":"sophia_stdlib/#union_1","title":"union","text":"Set.union(s1 : set('a), s2 : set('a)) : set('a)\nReturns the union of the two sets s1 and s2
Set.union_list(sets : list(set('a))) : set('a)\nReturns the union of all the sets in the given list
"},{"location":"sophia_stdlib/#string","title":"String","text":"Operations on the string type. A string is a UTF-8 encoded byte array.
length(s : string) : int
The length of a string.
Note: not equivalent to byte size of the string, rather List.length(String.to_list(s))
concat(s1 : string, s2 : string) : string\nConcatenates s1 and s2.
concats(ss : list(string)) : string\nConcatenates a list of strings.
"},{"location":"sophia_stdlib/#to_list_3","title":"to_list","text":"to_list(s : string) : list(char)\nConverts a string to a list of char - the code points are normalized, but composite characters are possibly converted to multiple chars. For example the string \"\ud83d\ude1ci\u0307\" is converted to [128540,105,775] - where the smiley is the first code point and the strangely dotted i becomes [105, 775].
from_list(cs : list(char)) : string\nConverts a list of characters into a normalized UTF-8 string.
"},{"location":"sophia_stdlib/#to_lower","title":"to_lower","text":"to_lower(s : string) : string\nConverts a string to lowercase.
"},{"location":"sophia_stdlib/#to_upper","title":"to_upper","text":"to_upper(s : string) : string\nConverts a string to uppercase.
"},{"location":"sophia_stdlib/#at","title":"at","text":"at(ix : int, s : string) : option(char)\nReturns the character/codepoint at (zero-based) index ix. Basically the equivalent to List.nth(ix, String.to_list(s)).
split(ix : int, s:string) : string * string\nSplits a string at (zero-based) index ix.
contains(str : string, pat : string) : option(int)\nSearches for pat in str, returning Some(ix) if pat is a substring of str starting at position ix, otherwise returns None.
tokens(str : string, pat : string) : list(string)\nSplits str into tokens, pat is the divider of tokens.
to_int(s : string) : option(int)\nConverts a decimal (\"123\", \"-253\") or a hexadecimal (\"0xa2f\", \"-0xBBB\") string into an integer. If the string doesn't contain a valid number None is returned.
sha3(s : string) : hash\nComputes the SHA3/Keccak hash of the string.
"},{"location":"sophia_stdlib/#sha256_1","title":"sha256","text":"sha256(s : string) : hash\nComputes the SHA256 hash of the string.
"},{"location":"sophia_stdlib/#blake2b_1","title":"blake2b","text":"blake2b(s : string) : hash\nComputes the Blake2B hash of the string.
"},{"location":"sophia_stdlib/#triple","title":"Triple","text":""},{"location":"sophia_stdlib/#fst_1","title":"fst","text":"Triple.fst(t : ('a * 'b * 'c)) : 'a\nFirst element projection.
"},{"location":"sophia_stdlib/#snd_1","title":"snd","text":"Triple.snd(t : ('a * 'b * 'c)) : 'b\nSecond element projection.
"},{"location":"sophia_stdlib/#thd","title":"thd","text":"Triple.thd(t : ('a * 'b * 'c)) : 'c\nThird element projection.
"},{"location":"sophia_stdlib/#map1_1","title":"map1","text":"Triple.map1(f : 'a => 'm, t : ('a * 'b * 'c)) : ('m * 'b * 'c)\nApplies function over first element.
"},{"location":"sophia_stdlib/#map2_2","title":"map2","text":"Triple.map2(f : 'b => 'm, t : ('a * 'b * 'c)) : ('a * 'm * 'c)\nApplies function over second element.
"},{"location":"sophia_stdlib/#map3_1","title":"map3","text":"Triple.map3(f : 'c => 'm, t : ('a * 'b * 'c)) : ('a * 'b * 'm)\nApplies function over third element.
"},{"location":"sophia_stdlib/#trimap","title":"trimap","text":"Triple.trimap(f : 'a => 'x, g : 'b => 'y, h : 'c => 'z, t : ('a * 'b * 'c)) : ('x * 'y * 'z)\nApplies functions over respective elements.
"},{"location":"sophia_stdlib/#swap_1","title":"swap","text":"Triple.swap(t : ('a * 'b * 'c)) : ('c * 'b * 'a)\nSwaps first and third element.
"},{"location":"sophia_stdlib/#rotr","title":"rotr","text":"Triple.rotr(t : ('a * 'b * 'c)) : ('c * 'a * 'b)\nCyclic rotation of the elements to the right.
"},{"location":"sophia_stdlib/#rotl","title":"rotl","text":"Triple.rotl(t : ('a * 'b * 'c)) : ('b * 'c * 'a)\nCyclic rotation of the elements to the left.
"},{"location":"sophia_syntax/","title":"Syntax","text":""},{"location":"sophia_syntax/#lexical-syntax","title":"Lexical syntax","text":""},{"location":"sophia_syntax/#comments","title":"Comments","text":"Single line comments start with // and block comments are enclosed in /* and */ and can be nested.
contract include let switch type record datatype if elif else function\nstateful payable true false mod public entrypoint private indexed namespace\ninterface main using as for hiding\nId = [a-z_][A-Za-z0-9_']* identifiers start with a lower case letter.Con = [A-Z][A-Za-z0-9_']* constructors start with an upper case letter.QId = (Con\\.)+Id qualified identifiers (e.g. Map.member)QCon = (Con\\.)+Con qualified constructorTVar = 'Id type variable (e.g 'a, 'b)Int = [0-9]+(_[0-9]+)*|0x[0-9A-Fa-f]+(_[0-9A-Fa-f]+)* integer literal with optional _ separatorsBytes = #[0-9A-Fa-f]+(_[0-9A-Fa-f]+)* byte array literal with optional _ separatorsString string literal enclosed in \" with escape character \\Char character literal enclosed in ' with escape character \\AccountAddress base58-encoded 32 byte account pubkey with ak_ prefixContractAddress base58-encoded 32 byte contract address with ct_ prefixOracleAddress base58-encoded 32 byte oracle address with ok_ prefixOracleQueryId base58-encoded 32 byte oracle query id with oq_ prefixValid string escape codes are
Escape ASCII\\b 8 \\t 9 \\n 10 \\v 11 \\f 12 \\r 13 \\e 27 \\xHexDigits HexDigits See the identifier encoding scheme for the details on the base58 literals.
"},{"location":"sophia_syntax/#layout-blocks","title":"Layout blocks","text":"Sophia uses Python-style layout rules to group declarations and statements. A layout block with more than one element must start on a separate line and be indented more than the currently enclosing layout block. Blocks with a single element can be written on the same line as the previous token.
Each element of the block must share the same indentation and no part of an element may be indented less than the indentation of the block. For instance
contract Layout =\nfunction foo() = 0 // no layout\nfunction bar() = // layout block starts on next line\nlet x = foo() // indented more than 2 spaces\nx\n+ 1 // the '+' is indented more than the 'x'\nIn describing the syntax below, we use the following conventions:
Expr) or terminals with some associated value (like Id).'let' or '='.|.[ square brackets ].( Parentheses ) are used for grouping.*, and one or more repetitions by a +.Block(X) denotes a layout block of Xs.Sep(X, S) is short for [X (S X)*], i.e. a possibly empty sequence of Xs separated by Ss.Sep1(X, S) is short for X (S X)*, i.e. same as Sep, but must not be empty.A Sophia file consists of a sequence of declarations in a layout block.
File ::= Block(TopDecl)\n\nTopDecl ::= ['payable'] ['main'] 'contract' Con [Implement] '=' Block(Decl)\n| 'contract' 'interface' Con [Implement] '=' Block(Decl)\n| 'namespace' Con '=' Block(Decl)\n| '@compiler' PragmaOp Version\n| 'include' String\n| Using\n\nImplement ::= ':' Sep1(Con, ',')\n\nDecl ::= 'type' Id ['(' TVar* ')'] '=' TypeAlias\n| 'record' Id ['(' TVar* ')'] '=' RecordType\n| 'datatype' Id ['(' TVar* ')'] '=' DataType\n| 'let' Id [':' Type] '=' Expr\n| (EModifier* 'entrypoint' | FModifier* 'function') Block(FunDecl)\n| Using\n\nFunDecl ::= Id ':' Type // Type signature\n| Id Args [':' Type] '=' Block(Stmt) // Definition\n| Id Args [':' Type] Block(GuardedDef) // Guarded definitions\n\nGuardedDef ::= '|' Sep1(Expr, ',') '=' Block(Stmt)\n\nUsing ::= 'using' Con ['as' Con] [UsingParts]\nUsingParts ::= 'for' '[' Sep1(Id, ',') ']'\n| 'hiding' '[' Sep1(Id, ',') ']'\n\nPragmaOp ::= '<' | '=<' | '==' | '>=' | '>'\nVersion ::= Sep1(Int, '.')\n\nEModifier ::= 'payable' | 'stateful'\nFModifier ::= 'stateful' | 'private'\n\nArgs ::= '(' Sep(Pattern, ',') ')'\nContract declarations must appear at the top-level.
For example,
contract Test =\ntype t = int\nentrypoint add (x : t, y : t) = x + y\nThere are three forms of type declarations: type aliases (declared with the type keyword), record type definitions (record) and data type definitions (datatype):
TypeAlias ::= Type\nRecordType ::= '{' Sep(FieldType, ',') '}'\nDataType ::= Sep1(ConDecl, '|')\n\nFieldType ::= Id ':' Type\nConDecl ::= Con ['(' Sep1(Type, ',') ')']\nFor example,
record point('a) = {x : 'a, y : 'a}\ndatatype shape('a) = Circle(point('a), 'a) | Rect(point('a), point('a))\ntype int_shape = shape(int)\nType ::= Domain '=>' Type // Function type\n| Type '(' Sep(Type, ',') ')' // Type application\n| '(' Type ')' // Parens\n| 'unit' | Sep(Type, '*') // Tuples\n| Id | QId | TVar\n\nDomain ::= Type // Single argument\n| '(' Sep(Type, ',') ')' // Multiple arguments\nThe function type arrow associates to the right.
Example,
'a => list('a) => (int * list('a))\nFunction bodies are blocks of statements, where a statement is one of the following
Stmt ::= 'switch' '(' Expr ')' Block(Case)\n| 'if' '(' Expr ')' Block(Stmt)\n| 'elif' '(' Expr ')' Block(Stmt)\n| 'else' Block(Stmt)\n| 'let' LetDef\n| Using\n| Expr\n\nLetDef ::= Id Args [':' Type] '=' Block(Stmt) // Function definition\n| Pattern '=' Block(Stmt) // Value definition\n\nCase ::= Pattern '=>' Block(Stmt)\n| Pattern Block(GuardedCase)\n\nGuardedCase ::= '|' Sep1(Expr, ',') '=>' Block(Stmt)\n\nPattern ::= Expr\nif statements can be followed by zero or more elif statements and an optional final else statement. For example,
let x : int = 4\nswitch(f(x))\nNone => 0\nSome(y) =>\nif(y > 10)\n\"too big\"\nelif(y < 3)\n\"too small\"\nelse\n\"just right\"\nExpr ::= '(' LamArgs ')' '=>' Block(Stmt) // Anonymous function (x) => x + 1\n| '(' BinOp ')' // Operator lambda (+)\n| 'if' '(' Expr ')' Expr 'else' Expr // If expression if(x < y) y else x\n| Expr ':' Type // Type annotation 5 : int\n| Expr BinOp Expr // Binary operator x + y\n| UnOp Expr // Unary operator ! b\n| Expr '(' Sep(Expr, ',') ')' // Application f(x, y)\n| Expr '.' Id // Projection state.x\n| Expr '[' Expr ']' // Map lookup map[key]\n| Expr '{' Sep(FieldUpdate, ',') '}' // Record or map update r{ fld[key].x = y }\n| '[' Sep(Expr, ',') ']' // List [1, 2, 3]\n| '[' Expr '|' Sep(Generator, ',') ']'\n// List comprehension [k | x <- [1], if (f(x)), let k = x+1]\n| '[' Expr '..' Expr ']' // List range [1..n]\n| '{' Sep(FieldUpdate, ',') '}' // Record or map value {x = 0, y = 1}, {[key] = val}\n| '(' Expr ')' // Parens (1 + 2) * 3\n| '(' Expr '=' Expr ')' // Assign pattern (y = x::_)\n| Id | Con | QId | QCon // Identifiers x, None, Map.member, AELib.Token\n| Int | Bytes | String | Char // Literals 123, 0xff, #00abc123, \"foo\", '%'\n| AccountAddress | ContractAddress // Chain identifiers\n| OracleAddress | OracleQueryId // Chain identifiers\n| '???' // Hole expression 1 + ???\n\nGenerator ::= Pattern '<-' Expr // Generator\n| 'if' '(' Expr ')' // Guard\n| LetDef // Definition\n\nLamArgs ::= '(' Sep(LamArg, ',') ')'\nLamArg ::= Id [':' Type]\n\nFieldUpdate ::= Path '=' Expr\nPath ::= Id // Record field\n| '[' Expr ']' // Map key\n| Path '.' Id // Nested record field\n| Path '[' Expr ']' // Nested map key\n\nBinOp ::= '||' | '&&' | '<' | '>' | '=<' | '>=' | '==' | '!='\n| '::' | '++' | '+' | '-' | '*' | '/' | 'mod' | '^'\n| '|>'\nUnOp ::= '-' | '!'\n- + * / mod ^ arithmetic operators ! && || logical operators == != < > =< >= comparison operators :: ++ list operators |> functional operators"},{"location":"sophia_syntax/#operator-precedence","title":"Operator precedence","text":"In order of highest to lowest precedence.
Operators Associativity! right ^ left * / mod left - (unary) right + - left :: ++ right < > =< >= == != none && right || right |> left"}]}
\ No newline at end of file
diff --git a/master/sitemap.xml b/master/sitemap.xml
index 9c8f64c..cdad234 100644
--- a/master/sitemap.xml
+++ b/master/sitemap.xml
@@ -2,47 +2,47 @@