Embed solidity code, interfaces in documentation

doc/texinfo/accountsindex.sol.texi

@@ -0,0 +1,18 @@
+@subsection Accounts Index
+
+Account address membership list.
+
+Records time when account was added.
+
+Addresses may be @emph{added}, @emph{removed}, aswell as @emph{deactivated} and @emph{activated}. Deactivated accounts still count towards the @code{entryCount}.
+
+The @code{entry} method is used to iterate the account list. The order of which accounts are returned is not guaranteed. Any returned value matching @code{address(0x00)} should be skipped, and not counted towards @code{entryCount}.
+
+@table @dfn
+@item ERC165 Interface identifier
+@include ../../build/AccountsIndex.interface
+@item Solidity interface definition
+@include ../../build/contract_AccountsIndex.texi
+@item Reference implementation
+@uref{git://holbrook.no/eth-accounts-index.git,}
+@end table

doc/texinfo/burner.sol.texi

@@ -0,0 +1,14 @@
+@subsection Burner
+
+Attached to @code{ERC20} and @code{ERC721} tokens that may be @emph{burned}.
+
+Implements the @code{burn(...)} part of @code{ERC5679} for interoperability.
+
+@table @dfn
+@item ERC165 Interface identifier
+@include ../../build/Burner.interface
+@item Solidity interface definition
+@include ../../build/contract_Burner.texi
+@item Example implementation
+@uref{https://git.grassecon.net/cicnet/erc20-demurrage-token.git}
+@end table

doc/texinfo/declarator.sol.texi

@@ -0,0 +1,20 @@
+@subsection Declarator
+
+Permissionless store of signed claims made by an address about other addresses, or addresses about themselves.
+
+It is used to declare or respond to certifications of vouchers, NFT, voucher members.
+
+Addresses may be Externally Owned Accounts or smart contracts.
+
+Claims may be made with or without topics. A missing topic is synonymous with a topic valud of @code{bytes32(0x00)}.
+
+Any number of claims can be made about an address under any number of topics. All claims must be stored, and returned in the order which they were added.
+
+@table @dfn
+@item ERC165 Interface identifier
+@include ../../build/Declarator.interface
+@item Solidity interface definition
+@include ../../build/contract_Declarator.texi
+@item Reference implementation
+@uref{git://holbrook.no/eth-address-index.git,}
+@end table

doc/texinfo/expire.sol.texi

@@ -0,0 +1,13 @@
+@subsection Expire
+
+Defines a token contract that may not be used after a certain time.
+
+A contract defining an expiry @emph{must not} allow changing the expiration time to a time in the past.
+
+
+@table @dfn
+@item ERC165 Interface identifier
+@include ../../build/Expire.interface
+@item Solidity interface definition
+@include ../../build/contract_Expire.texi
+@end table

doc/texinfo/faucet.sol.texi

@@ -0,0 +1,39 @@
+@subsection Faucet
+
+Used for dispensing tokens to any address.
+
+It can be used for gas tokens and @emph{ERC20} alike.
+
+The interface is the same whether the faucet is dispensing from existing balance or minting new tokens.
+
+The value dispersed @emph{must} be the same for all addresses.
+
+In general, four criteria are expected to exist in any combination for limiting access to the faucet:
+
+@table @dfn
+@item Time
+A recipient may only use the faucet again after some time has passed.
+@item Balance threshold
+A recipient may only use the faucet after its balance is below a certain amount.
+@item Membership
+A recipient may only use the faucet if it has been added to an access control list.
+@item Capacity
+The contract has sufficient token funds to dispense the current defined amount to dispense.
+@end table
+
+The @emph{check(address)} contract call @emph{must} evaluate all four criteria, and @emph{must} return @code{false} if any of the criteria are not met.
+
+
+@table @dfn
+@item ERC165 Interface identifier
+@include ../../build/Faucet.interface
+@item Solidity interface definition
+@include ../../build/contract_Faucet.texi
+@item Reference implementations
+@itemize
+@item
+@uref{git://holbrook.no/erc20-faucet.git,}
+@item
+@uref{git://holbrook.no/eth-faucet.git,}
+@end itemize
+@end table

doc/texinfo/locator.sol.texi

@@ -0,0 +1,58 @@
+@subsection Locator
+
+This interface supports @code{ERC721 Metadata}, in particular the @code{tokenURI(uint256)} call.
+
+Off-chain resources in the CIC network @emph{must} be defined in terms of content addressed strings.
+
+It @emph{must} be possible to refer to all off-chain resources directly by the content address.
+
+Furthermore, it @emph{should} be possible to refer to a resource by a fully-qualified location on the web or an overlay network (e.g. tor).
+
+@table @dfn
+@item ERC165 Interface identifier
+@include ../../build/Locator.interface
+@item Solidity interface definition
+@include ../../build/contract_Locator.texi
+@end table
+
+
+@subsubsection Expressing locators in terms of numetic token id
+
+Given the numeric token id @code{1234567890987654321}, and a base url @code{https://contentgateway.grassecon.net}, the result of the methods may be as follows:
+
+@table @code
+@item toURI(000000000000000000000000000000000000000000000000112210f4b16c1cb1)
+-> @code{https://contentgateway.grassecon.net/000000000000000000000000000000000000000000000000112210f4b16c1cb1}
+@item toURL(000000000000000000000000000000000000000000000000112210f4b16c1cb1)
+-> @code{https://contentgateway.grassecon.net/000000000000000000000000000000000000000000000000112210f4b16c1cb1}
+@item tokenURI(1234567890987654321)
+-> @code{https://contentgateway.grassecon.net/000000000000000000000000000000000000000000000000112210f4b16c1cb1}
+@end table
+
+
+@subsubsection Expressing locators in terms of a digest
+
+Given the data @code{foo}, the digest algorithm @code{sha256} and a base url @code{https://contentgateway.grassecon.net}, the result of the methods may be as follows:
+
+@table @code
+@item toURI(sha256(foo))
+-> @code{"sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"}
+@item toURL(sha256(foo))
+-> @code{"https://contentgateway.grassecon.net/2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"}
+@item tokenURI(toUint(sha256(foo)))
+-> @code{"https://contentgateway.grassecon.net/2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"}
+@end table
+
+
+@subsubsection Locator without URL
+
+Given the data @code{foo}, the digest algorithm @code{sha256} and no base url, the result of the methods may be as follows:
+
+@table @code
+@item toURI(sha256(foo))
+-> @code{"sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"}
+@item toURL(sha256(foo))
+-> @code{""}
+@item tokenURI(toUint(sha256(foo)))
+-> @code{"sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"}
+@end table

doc/texinfo/minter.sol.texi

@@ -0,0 +1,14 @@
+@subsection Minter
+
+Attached to @code{ERC20} and @code{ERC721} tokens that may be minted.
+
+Implements the @code{mint(...)} and @code{safeMint(...)} parts of @code{ERC5679} for interoperability.
+
+@table @dfn
+@item ERC165 Interface identifier
+@include ../../build/Minter.interface
+@item Solidity interface definition
+@include ../../build/contract_Minter.texi
+@item Example implementation
+@uref{https://git.grassecon.net/cicnet/erc20-demurrage-token.git}
+@end table

doc/texinfo/msg.sol.texi

@@ -0,0 +1,15 @@
+@subsection Msg
+
+Enables a reference "message" to describe the contract using an off-chain resource.
+
+The reference may or may not be mutable.
+
+The interface complements @code{Locator} and @code{MultiHash} to generate locators for how to resolve the reference.
+
+
+@table @dfn
+@item ERC165 Interface identifier
+@include ../../build/Msg.interface
+@item Solidity interface definition
+@include ../../build/contract_Msg.texi
+@end table

doc/texinfo/multihash.sol.texi

@@ -0,0 +1,25 @@
+@subsection Multihash
+
+A complement to @code{Locator}, enabling validation and generation for multihashes that have been registered to the contract. 
+
+
+@table @dfn
+@item ERC165 Interface identifier
+@include ../../build/MultiHash.interface
+@item Solidity interface definition
+@include ../../build/contract_MultiHash.texi
+@end table
+
+
+@subsubsection Using @code{Multihash} with @code{Locator}
+
+Given the data @code{foo}, the digest algorithm @code{sha256} (multihash prefix @code{1220}) and a base url @code{https://contentgateway.grassecon.net}, the result of the methods may be as follows:
+
+@table @code
+@item toURI(sha256(foo))
+-> @code{"sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"}
+@item toURL(sha256(foo))
+-> @code{"https://contentgateway.grassecon.net/12202c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"}
+@item tokenURI(toUint(sha256(foo)))
+-> @code{"https://contentgateway.grassecon.net/12202c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"}
+@end table

doc/texinfo/old.texi

@@ -0,0 +1,59 @@
+@subsection Auxiliary contracts
+
+All other Smart Contracts in the network other than CICRegistry are essentially optional, and each applies @emph{at least one} the interfaces defined in the @code{cic-contracts} repository.
+
+
+@subsection Contract interfaces
+
+All contracts interfaces also implement the @strong{EIP165} Standard Interface Detection.
+
+
+@subsubsection Registry
+
+A key-value store, which resolves arbitrary 32-byte pointers to Ethereum addresses. Typically, this is used to resolve an address from a well-known identifier, either as a UTF-8 value or a 256-bit hash.
+
+It also provides numerical index access to all registered values in order of insertion.
+
+
+@subsubsection Registry Client
+
+A subset of the @code{Registry} interface, which defines only the non-transactional methods of the contract. The @code{Registry Client} interface is implemented by the @code{CICRegistry} contract.
+
+
+@subsubsection Faucet
+
+Enables disbursement of a set amount of tokens to a requesting address.
+
+Allows privileged accounts to adjust the amount of tokens to disburse.
+
+Can be implemented as a periodic or a one-time service per account.
+
+
+@subsubsection Transfer approval
+
+Enables a third-party approval to spend an ERC20 token allowance.
+
+This is useful in the case of a custodial key store, where a transaction has been initiated by another entity than the owner of the key.
+
+The contract allows the third-party address to either allow or reject the transfer.
+
+
+@subsubsection Declarator
+
+Stores one or more 32-byte entries as a description of an Ethereum address, @emph{signed} by another Ethereum address.
+
+This can be used to @emph{describe} network resources, be it tokens, contracts or user accounts. Examples of uses are KYC documentation proofs for users, token metadata used for display, or fraud alerts.
+
+Entries are stored by the transacting address that adds address/description pairs. In other words, any address may have different "opinions" registered about it, depending on which signing address it is queried in the context of. This, in turn, allows the quering entity to compile its own "opinion" of an address by combining data from signatures it trusts.
+
+Entries typically are text strings or content hashes. 
+
+
+@subsubsection Address Index
+
+A simple append-only list of addresses. Used to check whether an address is part of a particular group.
+
+
+@subsubsection DEX Index
+
+Methods required to convert between tokens.

doc/texinfo/overview.texi

@@ -2,75 +2,59 @@
 @chapter Smart contract interfaces
 
 
-@section Smart Contracts in the CIC Network
 
-@subsection Technology
+@section Technology
 
-The long-term aim of the CIC network is to be agnostic of consensus engines. However, since we have to start @emph{somewhere}, the current state of development only deals with Smart Contracts on the (Ethereum Virtual Machine (EVM).
+CIC smart contracts are implemented using the @emph{solidity} programming language for the (Ethereum Virtual Machine (EVM).
 
 
-@subsection The registry contract
+@section Inherited ERC definitions
 
-The CICRegistry contract defines the entry-point to the entire CIC network. All other CIC network resources can be discovered through this contract.
+@subsection Direct use
 
-Its implementation is contained in the @file{cic-registry} repository. Details about it are documented further in that section.
+The following well-known solidity interfaces are used directly.
 
-@subsection Auxiliary contracts
-
-All other Smart Contracts in the network other than CICRegistry are essentially optional, and each applies @emph{at least one} the interfaces defined in the @code{cic-contracts} repository.
+@itemize @bullet
+@item
+@uref{https://eips.ethereum.org/EIPS/eip-20, ERC20 - Token Standard}
+@item
+@uref{https://eips.ethereum.org/EIPS/eip-165, ERC165 - Standard Interface Detection}
+@item
+@uref{https://eips.ethereum.org/EIPS/eip-173, ERC173 - Contract Ownership Standard}
+@item
+@uref{https://eips.ethereum.org/EIPS/eip-721, ERC721 - Non-Fungible Token Standard}
+@end itemize
 
 
-@subsection Contract interfaces
+@subsection Extended ERC definitions
 
-All contracts interfaces also implement the @strong{EIP165} Standard Interface Detection.
+@itemize @dfn
+@item
+@uref{https://eips.ethereum.org/EIPS/eip-5679, ERC5679 - Token Minting and Burning} (See @code{Minter}, @code{Burner})
+@end itemize
 
 
-@subsubsection Registry
+@section Native implementations
 
-A key-value store, which resolves arbitrary 32-byte pointers to Ethereum addresses. Typically, this is used to resolve an address from a well-known identifier, either as a UTF-8 value or a 256-bit hash.
+@include accountsindex.sol.texi
 
-It also provides numerical index access to all registered values in order of insertion.
+@include burner.sol.texi
 
+@include declarator.sol.texi
 
-@subsubsection Registry Client
+@include expire.sol.texi
 
-A subset of the @code{Registry} interface, which defines only the non-transactional methods of the contract. The @code{Registry Client} interface is implemented by the @code{CICRegistry} contract.
+@include faucet.sol.texi
 
+@include locator.sol.texi
 
-@subsubsection Faucet
+@include minter.sol.texi
 
-Enables disbursement of a set amount of tokens to a requesting address.
+@include msg.sol.texi
 
-Allows privileged accounts to adjust the amount of tokens to disburse.
+@include multihash.sol.texi
 
-Can be implemented as a periodic or a one-time service per account.
+@include registry.sol.texi
 
+@include writer.sol.texi
 
-@subsubsection Transfer approval
-
-Enables a third-party approval to spend an ERC20 token allowance.
-
-This is useful in the case of a custodial key store, where a transaction has been initiated by another entity than the owner of the key.
-
-The contract allows the third-party address to either allow or reject the transfer.
-
-
-@subsubsection Declarator
-
-Stores one or more 32-byte entries as a description of an Ethereum address, @emph{signed} by another Ethereum address.
-
-This can be used to @emph{describe} network resources, be it tokens, contracts or user accounts. Examples of uses are KYC documentation proofs for users, token metadata used for display, or fraud alerts.
-
-Entries are stored by the transacting address that adds address/description pairs. In other words, any address may have different "opinions" registered about it, depending on which signing address it is queried in the context of. This, in turn, allows the quering entity to compile its own "opinion" of an address by combining data from signatures it trusts.
-
-Entries typically are text strings or content hashes. 
-
-
-@subsubsection Address Index
-
-A simple append-only list of addresses. Used to check whether an address is part of a particular group.
-
-
-@subsubsection DEX Index
-
-Methods required to convert between tokens.

doc/texinfo/registry.sol.texi

@@ -0,0 +1,23 @@
+@subsection Registry
+
+The Registry interface is a key-value store resolving well-known contract identifier names to contract addresses.
+
+It currently has two distinct uses in the CIC context:
+
+@enumerate
+@item
+Entry-point to discover all relevant contracts of CIC networks.
+@item
+Unique (ERC20) token symbol resolver.
+@end enumerate
+
+@table @dfn
+@item ERC165 Interface identifier
+@include ../../build/RegistryClient.interface
+@item Solidity interface definition
+@include ../../build/contract_RegistryClient.texi
+@item Reference implementation
+@uref{git://holbrook.no/eth-contract-registry.git,}
+@item Token index implementation
+@uref{git://holbrook.no/eth-contract-registry.git,}
+@end table

doc/texinfo/writer.sol.texi

@@ -0,0 +1,25 @@
+@subsection Writer
+
+A complement to ERC173, which allows definition of a class of super-users for a contract.
+
+Typically, a super-user address may perform @emph{more} actions than a "normal" address, aswell as @emph{some} actions normally limited to the @emph{contract owner}.
+
+Typically, only the @emph{contract owner} can add or remove a super-user.
+
+Some use-case examples of super-user actions include:
+
+@itemize
+@item
+Mint new tokens.
+@item
+Change the amount dispensed by the faucet.
+@item
+Edit access control lists.
+@end itemize
+
+@table @dfn
+@item ERC165 Interface identifier
+@include ../../build/Writer.interface
+@item Solidity interface definition
+@include ../../build/contract_Writer.texi
+@end table