Trait implementation

sip/sip-002-smart-contract-language.md

@@ -98,48 +98,85 @@ any type.
 ## Inter-Contract Calls
 
 A smart contract may call functions from other smart contracts using a
-`(contract-call!)` function. This function accepts a function name and
-the smart contract's _identifier_ as input.  A smart contract's
-identifier is a hash of the smart contract's definition, represented
-as a Stacks address with a specific "smart contract" version byte. The
-smart contract identifier is a _principal_.
+`(contract-call?)` function.
 
-For example, to call the function `register-name` in a smart contract,
-you would use:
+This function returns a Response type result-- the return value of the called smart
+contract function. Note that if a called smart contract returns an
+`err` type, it is guaranteed to not alter any smart contract state
+whatsoever. Of course, any transaction fees paid for the execution
+of that function will not be returned.
+
+We distinguish 2 different types of `contract-call?`:
+
+* Static dispatch: the callee is a known, invariant contract available
+on-chain when the caller contract is being deployed. In this case, the
+callee's principal is provided as first argument, followed by the name
+of the method and its arguments:
 
 ```scheme
-(contract-call!
-    'SC3H92H297DX3YDPFHZGH90G8Z4NPH4VE8E83YWAQ
-    'register-name
+(contract-call?
+    'SC3H92H297DX3YDPFHZGH90G8Z4NPH4VE8E83YWAQ.registrar
+    register-name
     name-to-register)
 ```
 
-This function returns a boolean-- the return value of the called smart
-contract function. Note that if a called smart contract returns an
-`err` type, it is guaranteed to not alter any smart contract state
-whatsoever. Of course, any transaction fees paid for the execution
-of that function will not be returned.
+This approach must always be preferred, when adequate.
+It makes static analysis easier, and eliminates the
+potential for reentrancy bugs when the contracts are
+being published (versus when being used).
+
+* Dynamic dispatch: the callee is passed as an argument, and typed
+as a trait reference (<A>).
+
+```scheme
+(define-public (swap (token-a <can-transfer-tokens>)
+                     (amount-a uint)
+                     (owner-a principal)
+                     (token-b <can-transfer-tokens>)
+                     (amount-b uint)
+                     (owner-b principal)))
+     (begin
+         (unwrap! (contract-call? token-a transfer-from? owner-a owner-b amount-a))
+         (unwrap! (contract-call? token-b transfer-from? owner-b owner-a amount-b))))
+```
+
+Traits can either be locally defined:
+
+```scheme
+(define-trait can-transfer-tokens (
+    (transfer-from? (principal principal uint) (response uint)))
+```
+
+Or imported from an existing contract:
+
+```scheme
+(use-trait can-transfer-tokens
+    'SC3H92H297DX3YDPFHZGH90G8Z4NPH4VE8E83YWAQ.contract-defining-trait.can-transfer-tokens)
+```
+
+Looking at trait conformance, callee contracts have two different paths.
+They can either be "compatible" with a trait by defining methods
+matching some of the methods defined in a trait, or explicitely declare
+conformance using the `impl-trait` statement:
+
+```scheme
+(impl-trait 'SC3H92H297DX3YDPFHZGH90G8Z4NPH4VE8E83YWAQ.contract-defining-trait.can-transfer-tokens)
+```
+
+Explicit conformance should be prefered when adequate.
+It acts as a safeguard by helping the static analysis system to detect
+deviations in method signatures before contract deployment.
 
 The following limitations are imposed on contract calls:
 
-1. No dynamic dispatch. At the time of the smart contract creation,
-   any contracts being called must be specified. Future designs may
-   enable this by allowing contract principals to be supplied as
-   function arguments, however, on initial release, we believe
-   dynamic invocation to be too dangerous to support.
-2. Called smart contracts _must_ exist at the time of creation.
-3. No cycles may exist in the call graph of a smart contract. This
+1. On static dispatches, callee smart contracts _must_ exist at the time of creation.
+2. No cycles may exist in the call graph of a smart contract. This
    prevents recursion (and re-entrancy bugs). Such structures can
    be detected with static analysis of the call graph, and will be
    rejected by the network.
-
-The language described here only allows for eager binding of smart
-contract function calls-- this makes static analysis easier, and
-eliminates the potential for reentrancy bugs. A key benefit of the
-static analyzability of this smart contracting language is that _all_
-functions that can possibly be called from a given transaction can be
-known _a priori_ so that a user can be warned about all side effects
-before signing a transaction.
+3. `contract-call?` are for inter-contract calls only. Situations
+   where the caller is also the callee will result in abortion of
+   the ongoing transaction.
 
 ## Principals and Owner Verification
 
@@ -166,7 +203,7 @@ priori which functions a given smart contract will ever call.
 
 Another global variable, `contract-caller`, _does_ change during
 inter-contract calls. In particular, `contract-caller` is the contract
-principal corresponding to the most recent invocation of `contract-call!`.
+principal corresponding to the most recent invocation of `contract-call?`.
 In the case of a "top-level" invocation, this variable is equal to `tx-sender`.
 
 Assets in the smart contracting language and blockchain are
@@ -322,7 +359,7 @@ Example:
  12234) -> returns owner principal of name represent by integer 12234
 ```
 
-Just as with the `(contract-call!)` function, the map name and contract
+Just as with the `(contract-call?)` function, the map name and contract
 principal arguments must be constants, specified at the time of
 publishing.
 

src/clarity.rs

@@ -125,9 +125,9 @@ fn advance_cli_chain_tip(path: &String) -> (BlockHeaderHash, BlockHeaderHash) {
 
     friendly_expect(tx.execute("CREATE TABLE IF NOT EXISTS cli_chain_tips(id INTEGER PRIMARY KEY AUTOINCREMENT, block_hash TEXT UNIQUE NOT NULL);", NO_PARAMS),
                     &format!("FATAL: failed to create 'cli_chain_tips' table"));
-   
+
     let parent_block_hash = get_cli_chain_tip(&tx);
-    
+
     let random_bytes = rand::thread_rng().gen::<[u8; 32]>();
     let next_block_hash  = friendly_expect_opt(BlockHeaderHash::from_bytes(&random_bytes),
                                               "Failed to generate random block header.");

src/vm/analysis/analysis_db.rs

@@ -1,10 +1,12 @@
-use std::collections::HashMap;
+use std::collections::{HashMap, BTreeMap, BTreeSet};
 
-use vm::types::{TypeSignature, FunctionType, QualifiedContractIdentifier};
+use vm::types::{TypeSignature, FunctionType, QualifiedContractIdentifier, TraitIdentifier};
+use vm::types::signatures::FunctionSignature;
 use vm::database::{ClaritySerializable, ClarityDeserializable,
                    RollbackWrapper, MarfedKV, ClarityBackingStore};
 use vm::analysis::errors::{CheckError, CheckErrors, CheckResult};
 use vm::analysis::type_checker::{ContractAnalysis};
+use vm::representations::{ClarityName};
 
 pub struct AnalysisDatabase <'a> {
     store: RollbackWrapper <'a>
@@ -67,7 +69,7 @@ impl <'a> AnalysisDatabase <'a> {
         self.store.prepare_for_contract_metadata(contract_identifier, Sha512Trunc256Sum([0; 32]));
     }
 
-    fn load_contract(&mut self, contract_identifier: &QualifiedContractIdentifier) -> Option<ContractAnalysis> {
+    pub fn load_contract(&mut self, contract_identifier: &QualifiedContractIdentifier) -> Option<ContractAnalysis> {
         self.store.get_metadata(contract_identifier, AnalysisDatabase::storage_key())
             // treat NoSuchContract error thrown by get_metadata as an Option::None --
             //    the analysis will propagate that as a CheckError anyways.
@@ -80,6 +82,7 @@ impl <'a> AnalysisDatabase <'a> {
         if self.store.has_metadata_entry(contract_identifier, key) {
             return Err(CheckErrors::ContractAlreadyExists(contract_identifier.to_string()).into())
         }
+
         self.store.insert_metadata(contract_identifier, key, &contract.serialize());
         Ok(())
     }
@@ -98,6 +101,19 @@ impl <'a> AnalysisDatabase <'a> {
            .cloned())
     }
 
+    pub fn get_defined_trait(&mut self, contract_identifier: &QualifiedContractIdentifier, trait_name: &str) -> CheckResult<Option<BTreeMap<ClarityName, FunctionSignature>>> {
+        let contract = self.load_contract(contract_identifier)
+            .ok_or(CheckErrors::NoSuchContract(contract_identifier.to_string()))?;
+        Ok(contract.get_defined_trait(trait_name)
+           .cloned())
+    }
+
+    pub fn get_implemented_traits(&mut self, contract_identifier: &QualifiedContractIdentifier) -> CheckResult<BTreeSet<TraitIdentifier>> {
+        let contract = self.load_contract(contract_identifier)
+            .ok_or(CheckErrors::NoSuchContract(contract_identifier.to_string()))?;
+        Ok(contract.implemented_traits)
+    }
+
     pub fn get_map_type(&mut self, contract_identifier: &QualifiedContractIdentifier, map_name: &str) -> CheckResult<(TypeSignature, TypeSignature)> {
         let contract = self.load_contract(contract_identifier)
             .ok_or(CheckErrors::NoSuchContract(contract_identifier.to_string()))?;

src/vm/analysis/contract_interface_builder/mod.rs

@@ -15,7 +15,8 @@ pub fn build_contract_interface(contract_analysis: &ContractAnalysis) -> Contrac
         map_types,
         fungible_tokens,
         non_fungible_tokens,
-        top_level_expression_sorting: _,
+        defined_traits: _,
+        implemented_traits: _,
         expressions: _,
         contract_identifier: _,
         type_map: _,
@@ -88,6 +89,7 @@ pub enum ContractInterfaceAtomType {
         type_f: Box<ContractInterfaceAtomType>, 
         length: u32, 
     },
+    trait_reference,
 }
 
 #[derive(Debug, Serialize)]
@@ -127,6 +129,7 @@ impl ContractInterfaceAtomType {
             UIntType => ContractInterfaceAtomType::uint128,
             BoolType => ContractInterfaceAtomType::bool,
             PrincipalType => ContractInterfaceAtomType::principal,
+            TraitReferenceType(_) => ContractInterfaceAtomType::trait_reference,
             BufferType(len) => ContractInterfaceAtomType::buffer { length: len.into() },
             TupleType(sig) => Self::from_tuple_type(sig),
             ListType(list_data) => {

src/vm/analysis/errors.rs

@@ -129,6 +129,17 @@ pub enum CheckErrors {
     IllegalOrUnknownFunctionApplication(String),
     UnknownFunction(String),
 
+    // traits
+    TraitReferenceUnknown(String),
+    TraitMethodUnknown(String, String),
+    ExpectedTraitIdentifier,
+    ImportTraitBadSignature,
+    TraitReferenceNotAllowed,
+    BadTraitImplementation(String, String),
+    DefineTraitBadSignature,
+    UnexpectedTraitOrFieldReference,
+    TraitBasedContractCallInReadOnly,
+
     WriteAttemptedInReadOnly,
     AtBlockClosureMustBeReadOnly
 }
@@ -312,13 +323,22 @@ impl DiagnosableError for CheckErrors {
             CheckErrors::TooManyExpressions => format!("reached limit of expressions"),
             CheckErrors::IllegalOrUnknownFunctionApplication(function_name) => format!("use of illegal / unresolved function '{}", function_name),
             CheckErrors::UnknownFunction(function_name) => format!("use of unresolved function '{}'", function_name),
+            CheckErrors::TraitBasedContractCallInReadOnly => format!("use of trait based contract calls are not allowed in read-only context"),
             CheckErrors::WriteAttemptedInReadOnly => format!("expecting read-only statements, detected a writing operation"),
             CheckErrors::AtBlockClosureMustBeReadOnly => format!("(at-block ...) closures expect read-only statements, but detected a writing operation"),
             CheckErrors::BadTokenName => format!("expecting an token name as an argument"),
             CheckErrors::DefineFTBadSignature => format!("(define-token ...) expects a token name as an argument"),
             CheckErrors::DefineNFTBadSignature => format!("(define-asset ...) expects an asset name and an asset identifier type signature as arguments"),
             CheckErrors::NoSuchNFT(asset_name) => format!("tried to use asset function with a undefined asset ('{}')", asset_name),
             CheckErrors::NoSuchFT(asset_name) => format!("tried to use token function with a undefined token ('{}')", asset_name),
+            CheckErrors::TraitReferenceUnknown(trait_name) => format!("use of undeclared trait <{}>", trait_name),
+            CheckErrors::TraitMethodUnknown(trait_name, func_name) => format!("method '{}' unspecified in trait <{}>", func_name, trait_name),
+            CheckErrors::ImportTraitBadSignature => format!("(use-trait ...) expects a trait name and a trait identifier"),
+            CheckErrors::BadTraitImplementation(trait_name, func_name) => format!("invalid signature for method '{}' regarding trait's specification <{}>", func_name, trait_name),
+            CheckErrors::ExpectedTraitIdentifier => format!("expecting expression of type trait identifier"),
+            CheckErrors::UnexpectedTraitOrFieldReference => format!("unexpected use of trait reference or field"),
+            CheckErrors::DefineTraitBadSignature => format!("invalid trait definition"),
+            CheckErrors::TraitReferenceNotAllowed => format!("trait references can not be stored"),
             CheckErrors::TypeAlreadyAnnotatedFailure | CheckErrors::CheckerImplementationFailure => {
                 format!("internal error - please file an issue on github.com/blockstack/blockstack-core")
             },
@@ -329,6 +349,7 @@ impl DiagnosableError for CheckErrors {
         match &self {
             CheckErrors::BadSyntaxBinding => Some(format!("binding syntax example: ((supply int) (ttl int))")),
             CheckErrors::BadLetSyntax => Some(format!("'let' syntax example: (let ((supply 1000) (ttl 60)) <next-expression>)")),
+            CheckErrors::TraitReferenceUnknown(_) => Some(format!("traits should be either defined, with define-trait, or imported, with use-trait.")),
             CheckErrors::NoSuchBlockInfoProperty(_) => Some(format!("properties available: time, header-hash, burnchain-header-hash, vrf-seed")),
             _ => None
         }

src/vm/analysis/mod.rs

@@ -1,6 +1,6 @@
 pub mod types;
 pub mod errors;
-pub mod definition_sorter;
+pub mod trait_checker;
 pub mod type_checker;
 pub mod read_only_checker;
 pub mod analysis_db;
@@ -13,8 +13,8 @@ use vm::types::{TypeSignature, QualifiedContractIdentifier};
 pub use self::errors::{CheckResult, CheckError, CheckErrors};
 pub use self::analysis_db::{AnalysisDatabase};
 
-use self::definition_sorter::DefinitionSorter;
 use self::read_only_checker::ReadOnlyChecker;
+use self::trait_checker::TraitChecker;
 use self::type_checker::TypeChecker;
 
 #[cfg(test)]
@@ -49,9 +49,9 @@ pub fn run_analysis(contract_identifier: &QualifiedContractIdentifier,
 
     analysis_db.execute(|db| {
         let mut contract_analysis = ContractAnalysis::new(contract_identifier.clone(), expressions.to_vec());
-        DefinitionSorter::run_pass(&mut contract_analysis, db)?;
         ReadOnlyChecker::run_pass(&mut contract_analysis, db)?;
         TypeChecker::run_pass(&mut contract_analysis, db)?;
+        TraitChecker::run_pass(&mut contract_analysis, db)?;
         if save_contract {
             db.insert_contract(&contract_identifier, &contract_analysis)?;
         }

src/vm/analysis/read_only_checker/mod.rs

@@ -1,5 +1,5 @@
 use vm::representations::{SymbolicExpressionType, SymbolicExpression, ClarityName};
-use vm::representations::SymbolicExpressionType::{AtomValue, Atom, List, LiteralValue};
+use vm::representations::SymbolicExpressionType::{AtomValue, Atom, List, LiteralValue, TraitReference, Field};
 use vm::types::{TypeSignature, TupleTypeSignature, Value, PrincipalData, parse_name_type_pairs};
 use vm::functions::NativeFunctions;
 use vm::functions::define::DefineFunctionsParsed;
@@ -41,7 +41,7 @@ impl <'a, 'b> ReadOnlyChecker <'a, 'b> {
 
     pub fn run(& mut self, contract_analysis: &mut ContractAnalysis) -> CheckResult<()> {
 
-        for exp in contract_analysis.expressions_iter() {
+        for exp in contract_analysis.expressions.iter() {
             let mut result = self.check_reads_only_valid(&exp);
             if let Err(ref mut error) = result {
                 if !error.has_expression() {
@@ -95,6 +95,9 @@ impl <'a, 'b> ReadOnlyChecker <'a, 'b> {
                 Map { .. } | NonFungibleToken { .. } | UnboundedFungibleToken { .. } => {
                     // No arguments to (define-map ...) or (define-non-fungible-token) or fungible tokens without max supplies are eval'ed.
                 },
+                Trait { .. } | UseTrait { .. } | ImplTrait { .. } => {
+                    // No arguments to (use-trait ...), (define-trait ...). or (impl-trait) are eval'ed.
+                },
             }
         } else {
             self.check_read_only(expr)?;
@@ -108,10 +111,7 @@ impl <'a, 'b> ReadOnlyChecker <'a, 'b> {
     /// Note that because of (1), this function _cannot_ short-circuit on read-only.
     fn check_read_only(&mut self, expr: &SymbolicExpression) -> CheckResult<bool> {
         match expr.expr {
-            AtomValue(_) | LiteralValue(_) => {
-                Ok(true)
-            },
-            Atom(_) => {
+            AtomValue(_) | LiteralValue(_) | Atom(_) | TraitReference(_, _) | Field(_) => {
                 Ok(true)
             },
             List(ref expression) => {
@@ -259,15 +259,23 @@ impl <'a, 'b> ReadOnlyChecker <'a, 'b> {
             },
             ContractCall => {
                 check_arguments_at_least(2, args)?;
-                let contract_identifier = match args[0].expr {
-                    SymbolicExpressionType::LiteralValue(Value::Principal(PrincipalData::Contract(ref contract_identifier))) => contract_identifier,
-                    _ => return Err(CheckError::new(CheckErrors::ContractCallExpectName))
-                };
 
                 let function_name = args[1].match_atom()
                     .ok_or(CheckErrors::ContractCallExpectName)?;
 
-                let is_function_read_only = self.db.get_read_only_function_type(&contract_identifier, function_name)?.is_some();
+                let is_function_read_only = match &args[0].expr {
+                    SymbolicExpressionType::LiteralValue(Value::Principal(PrincipalData::Contract(ref contract_identifier))) => {
+                        self.db.get_read_only_function_type(&contract_identifier, function_name)?.is_some()
+                    },
+                    SymbolicExpressionType::Atom(_trait_reference) => {
+                        // Dynamic dispatch from a readonly-function can only be guaranteed at runtime,
+                        // which would defeat granting a static readonly stamp. 
+                        // As such dynamic dispatch is currently forbidden.
+                        false
+                    },
+                    _ => return Err(CheckError::new(CheckErrors::ContractCallExpectName))
+                };
+
                 self.check_all_read_only(&args[2..])
                     .map(|args_read_only| args_read_only && is_function_read_only)
             }