diff --git a/gitlab-pages/docs/reference/current.md b/gitlab-pages/docs/reference/current.md new file mode 100644 index 000000000..c9f1945d8 --- /dev/null +++ b/gitlab-pages/docs/reference/current.md @@ -0,0 +1,319 @@ +--- +id: current-reference +title: Current - Things relating to the current execution context +--- + +## Current.balance() : tez + +Get the balance for the contract. + + + + +```pascaligo +function main (const p : unit; const s: tez) : list(operation) * tez is + ((nil : list(operation)), balance) +``` + +```cameligo +let main (p, s : unit * tez) = + ([] : operation list), balance +``` + +```reasonligo +let main = ((p,s): (unit, tez)) => ([]: list(operation), balance); +``` + + + +## Current.time() : timestamp + +Returns the current time as a [unix timestamp](https://en.wikipedia.org/wiki/Unix_time). + +In LIGO, timestamps are type compatible in operations with `int`(s). This lets you set e.g. time constraints for your smart contracts like this: + +### Examples + +#### 24 hours from now + + +```pascaligo group=b +const today: timestamp = now; +const one_day: int = 86400; +const in_24_hrs: timestamp = today + one_day; +const some_date: timestamp = ("2000-01-01T10:10:10Z" : timestamp); +const one_day_later: timestamp = some_date + one_day; +``` + + +```cameligo group=b +let today: timestamp = Current.time +let one_day: int = 86400 +let in_24_hrs: timestamp = today + one_day +let some_date: timestamp = ("2000-01-01t10:10:10Z" : timestamp) +let one_day_later: timestamp = some_date + one_day +``` + + +```reasonligo group=b +let today: timestamp = Current.time; +let one_day: int = 86400; +let in_24_hrs: timestamp = today + one_day; +let some_date: timestamp = ("2000-01-01t10:10:10Z" : timestamp); +let one_day_later: timestamp = some_date + one_day; +``` + + + +#### 24 hours ago + + +```pascaligo group=c +const today: timestamp = now; +const one_day: int = 86400; +const in_24_hrs: timestamp = today - one_day; +``` + + +```cameligo group=c +let today: timestamp = Current.time +let one_day: int = 86400 +let in_24_hrs: timestamp = today - one_day +``` + + +```reasonligo group=c +let today: timestamp = Current.time; +let one_day: int = 86400; +let in_24_hrs: timestamp = today - one_day; +``` + + + +#### Comparing timestamps + +You can also compare timestamps using the same comparison operators as for numbers: + + + +```pascaligo group=c +const not_tommorow: bool = (now = in_24_hrs) +``` + + +```cameligo group=c +let not_tomorrow: bool = (Current.time = in_24_hrs) +``` + + +```reasonligo group=c +let not_tomorrow: bool = (Current.time == in_24_hrs); +``` + + + + +## Current.amount() : tez + +Get the amount of tez provided by the sender to complete this transaction. + + + + +```pascaligo +function check (const p: unit) : int is + begin + var result : int := 0; + if amount = 100tz then + result := 42 + else + result := 0 + end with result +``` + + +```cameligo +let check_ (p: unit) : int = if Current.amount = 100tz then 42 else 0 +``` + + +```reasonligo +let check_ = (p: unit) : int => + if (Current.amount == 100tz) { + 42; + } + else { + 0; + }; +``` + + + +## Current.sender() : address + +Get the address that initiated the current transaction. + + + + +```pascaligo +function main (const p: unit) : address is sender +``` + + +```cameligo +let main (p: unit) : address = Current.sender +``` + + +```reasonligo +let main = (p: unit) : address => Current.sender; +``` + + + +## Current.address(c: a' contract) : address + +Get the address associated with a `contract`. + + + + +```pascaligo +function main (const p : key_hash) : address is block { + const c : contract(unit) = implicit_account(p) ; +} with address(c) +``` + + +```cameligo +let main (p : key_hash) = + let c : unit contract = Current.implicit_account p in + Current.address c +``` + + +```reasonligo +let main = (p : key_hash) : address => { + let c : contract(unit) = Current.implicit_account(p) ; + Current.address(c) ; +}; +``` + + + +## Current.self_address() : address + +Get the address of the currently running contract. + + + + +```pascaligo +function main (const p: unit) : address is self_address +``` + + +```cameligo +let main (p: unit) : address = Current.self_address +``` + + +```reasonligo +let main = (p: unit): address => Current.self_address; +``` + + + +## Current.implicit_account(p: key_hash) : a' contract + +Get the default contract associated with an on-chain keypair. This contract +doesn't execute code, instead it exists to receive money on behalf of a keys +owner. + + + + +```pascaligo +function main (const kh: key_hash) : contract(unit) is implicit_account(kh) +``` + + +```cameligo +let main (kh: key_hash) : unit contract = Current.implicit_account kh +``` + + +```reasonligo +let main = (kh: key_hash): contract(unit) => Current.implicit_account(kh); +``` + + + +## Current.source() : address + +Get the _originator_ of the current transaction. That is, if a chain of transactions +led to the current execution get the address that began the chain. Not to be confused +with `Current.sender`, which gives the address of the contract or user which directly +caused the current transaction. + +> ⚠️ +> There are a few caveats you should keep in mind before using `SOURCE` over `SENDER`: +> +> 1. SOURCE will never be a contract, so if you want to allow contracts (multisigs etc) to operate your contract, you need to use SENDER +> 2. https://vessenes.com/tx-origin-and-ethereum-oh-my/ -- in general it is somewhat unsafe to assume that SOURCE understands everything that's going to happen in a transaction. If SOURCE transfers to a malicious (or sufficiently attackable) contract, that contract might potentially transfer to yours, without SOURCE's consent. So if you are using SOURCE for authentication, you risk being confused. A good historical example of this is bakers paying out delegation rewards. Naive bakers did (and probably still do) just use tezos-client to transfer to whatever KT1 delegates they had, even if those KT1 were malicious scripts. + + + + +```pascaligo +function main (const p: unit) : address is source +``` + + +```cameligo +let main (p: unit) : address = Current.source +``` + + +```reasonligo +let main = (p: unit) : address => Current.source; +``` + + + +## Current.failwith(error_message: string) : a' + +Cause the contract to fail with an error message. + +> ⚠ Using this currently requires a type annotation on the failwith to unify it +> with the type of whatever other code branch it's on. + + + + +```pascaligo +function main (const p : int; const s : unit) : list(operation) * unit is + block { + if p > 10 then failwith("fail") else skip; + } + with ((nil : list(operation)), s) +``` + + +```cameligo +let main (p,s: unit * unit) = + if true then failwith "This contract always fails" else () +``` + + +```reasonligo +let main = ((p,s): (unit, unit)) => + if (true) { + failwith("This contract always fails"); + } else { + (); + }; +``` + + diff --git a/src/test/contracts/amount.ligo b/src/test/contracts/amount.ligo new file mode 100644 index 000000000..8d4961be8 --- /dev/null +++ b/src/test/contracts/amount.ligo @@ -0,0 +1,8 @@ +function check (const p: unit) : int is + begin + var result : int := 0; + if amount = 100tz then + result := 42 + else + result := 0 + end with result diff --git a/src/test/contracts/amount.mligo b/src/test/contracts/amount.mligo index 995f165fe..8e31e2d0c 100644 --- a/src/test/contracts/amount.mligo +++ b/src/test/contracts/amount.mligo @@ -1 +1 @@ -let check = if Current.amount > 100tz then 42 else 0 \ No newline at end of file +let check_ (p: unit) : int = if Current.amount = 100tz then 42 else 0 diff --git a/src/test/contracts/amount.religo b/src/test/contracts/amount.religo new file mode 100644 index 000000000..9d19491b8 --- /dev/null +++ b/src/test/contracts/amount.religo @@ -0,0 +1,7 @@ +let check_ = (p: unit) : int => + if (Current.amount == 100tz) { + 42; + } + else { + 0; + }; diff --git a/src/test/integration_tests.ml b/src/test/integration_tests.ml index 6238fb836..b8270e005 100644 --- a/src/test/integration_tests.ml +++ b/src/test/integration_tests.ml @@ -1820,6 +1820,41 @@ let balance_constant_religo () : unit result = let expected = e_tuple [e_list []; e_mutez 4000000000000] in expect_eq program "main" input expected +let amount () : unit result = + let%bind program = type_file "./contracts/amount.ligo" in + let input = e_unit () in + let expected = e_int 42 in + let amount = + match Memory_proto_alpha.Protocol.Alpha_context.Tez.of_string "100" with + | Some t -> t + | None -> Memory_proto_alpha.Protocol.Alpha_context.Tez.one + in + let options = Proto_alpha_utils.Memory_proto_alpha.make_options ~amount () in + expect_eq ~options program "check" input expected + +let amount_mligo () : unit result = + let%bind program = mtype_file "./contracts/amount.mligo" in + let input = e_unit () in + let expected = e_int 42 in + let amount = + match Memory_proto_alpha.Protocol.Alpha_context.Tez.of_string "100" with + | Some t -> t + | None -> Memory_proto_alpha.Protocol.Alpha_context.Tez.one + in + let options = Proto_alpha_utils.Memory_proto_alpha.make_options ~amount () in + expect_eq ~options program "check_" input expected + +let amount_religo () : unit result = + let%bind program = retype_file "./contracts/amount.religo" in + let input = e_unit () in + let expected = e_int 42 in + let amount = + match Memory_proto_alpha.Protocol.Alpha_context.Tez.of_string "100" with + | Some t -> t + | None -> Memory_proto_alpha.Protocol.Alpha_context.Tez.one + in + let options = Proto_alpha_utils.Memory_proto_alpha.make_options ~amount () in + expect_eq ~options program "check_" input expected let addr_test program = let open Proto_alpha_utils.Memory_proto_alpha in @@ -2398,6 +2433,9 @@ let main = test_suite "Integration (End to End)" [ test "balance constant" balance_constant ; test "balance constant (mligo)" balance_constant_mligo ; test "balance constant (religo)" balance_constant_religo ; + test "amount" amount ; + test "amount (mligo)" amount_mligo ; + test "amount (religo)" amount_religo ; test "address" address ; test "address (mligo)" address_mligo ; test "address (religo)" address_religo ; diff --git a/src/test/md_file_tests.ml b/src/test/md_file_tests.ml index 15e7e1767..c728a929d 100644 --- a/src/test/md_file_tests.ml +++ b/src/test/md_file_tests.ml @@ -128,6 +128,7 @@ let md_files = [ "/gitlab-pages/docs/reference/big_map.md"; "/gitlab-pages/docs/reference/string.md"; "/gitlab-pages/docs/reference/crypto.md"; + "/gitlab-pages/docs/reference/current.md"; ] let md_root = "../../gitlab-pages/docs/language-basics/"