From c51ea4444600729d064e49ca1c55100865bc8b6a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rapha=C3=ABl=20Cauderlier?=
 <raphael.cauderlier@nomadic-labs.com>
Date: Mon, 30 Jan 2023 11:30:56 +0100
Subject: [PATCH 1/4] Proto/Token: rename "source" into "giver"

There is a risk of confusion between the notion of transaction
source (the account signing and/or sending a transaction) and the
notion of token transfer source (the account being debited). Most of
the time this is not a problem because the accounts coincide but
sometimes it is good to explicit the distinction.
---
 .../lib_protocol/alpha_context.mli            |  18 +-
 src/proto_alpha/lib_protocol/fees_storage.mli |  12 +-
 .../test/integration/test_token.ml            | 198 +++++++++---------
 src/proto_alpha/lib_protocol/token.ml         |  40 ++--
 src/proto_alpha/lib_protocol/token.mli        |  42 ++--
 5 files changed, 155 insertions(+), 155 deletions(-)

diff --git a/src/proto_alpha/lib_protocol/alpha_context.mli b/src/proto_alpha/lib_protocol/alpha_context.mli
index a215cb1b20b3..cf78a84e381b 100644
--- a/src/proto_alpha/lib_protocol/alpha_context.mli
+++ b/src/proto_alpha/lib_protocol/alpha_context.mli
@@ -5250,7 +5250,7 @@ module Token : sig
     | `Block_fees
     | `Frozen_bonds of Contract.t * Bond_id.t ]
 
-  type source =
+  type giver =
     [ `Invoice
     | `Bootstrap
     | `Initial_commitments
@@ -5281,14 +5281,14 @@ module Token : sig
   val transfer_n :
     ?origin:Receipt.update_origin ->
     context ->
-    ([< source] * Tez.t) list ->
+    ([< giver] * Tez.t) list ->
     [< sink] ->
     (context * Receipt.balance_updates) tzresult Lwt.t
 
   val transfer :
     ?origin:Receipt.update_origin ->
     context ->
-    [< source] ->
+    [< giver] ->
     [< sink] ->
     Tez.t ->
     (context * Receipt.balance_updates) tzresult Lwt.t
@@ -5305,14 +5305,14 @@ module Fees : sig
     ?origin:Receipt.update_origin ->
     context ->
     storage_limit:Z.t ->
-    payer:Token.source ->
+    payer:Token.giver ->
     Z.t ->
     (context * Z.t * Receipt.balance_updates) tzresult Lwt.t
 
   val burn_storage_increase_fees :
     ?origin:Receipt_repr.update_origin ->
     context ->
-    payer:Token.source ->
+    payer:Token.giver ->
     Z.t ->
     (context * Receipt.balance_updates) tzresult Lwt.t
 
@@ -5320,21 +5320,21 @@ module Fees : sig
     ?origin:Receipt.update_origin ->
     context ->
     storage_limit:Z.t ->
-    payer:Token.source ->
+    payer:Token.giver ->
     (context * Z.t * Receipt.balance_updates) tzresult Lwt.t
 
   val burn_tx_rollup_origination_fees :
     ?origin:Receipt.update_origin ->
     context ->
     storage_limit:Z.t ->
-    payer:Token.source ->
+    payer:Token.giver ->
     (context * Z.t * Receipt.balance_updates) tzresult Lwt.t
 
   val burn_sc_rollup_origination_fees :
     ?origin:Receipt.update_origin ->
     context ->
     storage_limit:Z.t ->
-    payer:Token.source ->
+    payer:Token.giver ->
     Z.t ->
     (context * Z.t * Receipt.balance_updates) tzresult Lwt.t
 
@@ -5342,7 +5342,7 @@ module Fees : sig
     ?origin:Receipt.update_origin ->
     context ->
     storage_limit:Z.t ->
-    payer:Token.source ->
+    payer:Token.giver ->
     Z.t ->
     (context * Z.t * Receipt.balance_updates) tzresult Lwt.t
 
diff --git a/src/proto_alpha/lib_protocol/fees_storage.mli b/src/proto_alpha/lib_protocol/fees_storage.mli
index 78a13395d977..87044b04c81a 100644
--- a/src/proto_alpha/lib_protocol/fees_storage.mli
+++ b/src/proto_alpha/lib_protocol/fees_storage.mli
@@ -67,7 +67,7 @@ val burn_storage_fees :
   ?origin:Receipt_repr.update_origin ->
   Raw_context.t ->
   storage_limit:Z.t ->
-  payer:Token.source ->
+  payer:Token.giver ->
   Z.t ->
   (Raw_context.t * Z.t * Receipt_repr.balance_updates) tzresult Lwt.t
 
@@ -82,7 +82,7 @@ val burn_storage_fees :
 val burn_storage_increase_fees :
   ?origin:Receipt_repr.update_origin ->
   Raw_context.t ->
-  payer:Token.source ->
+  payer:Token.giver ->
   Z.t ->
   (Raw_context.t * Receipt_repr.balance_updates) tzresult Lwt.t
 
@@ -92,7 +92,7 @@ val burn_origination_fees :
   ?origin:Receipt_repr.update_origin ->
   Raw_context.t ->
   storage_limit:Z.t ->
-  payer:Token.source ->
+  payer:Token.giver ->
   (Raw_context.t * Z.t * Receipt_repr.balance_updates) tzresult Lwt.t
 
 (** Calls [burn_storage_fees] with the parameter [consumed] mapped to the
@@ -101,7 +101,7 @@ val burn_tx_rollup_origination_fees :
   ?origin:Receipt_repr.update_origin ->
   Raw_context.t ->
   storage_limit:Z.t ->
-  payer:Token.source ->
+  payer:Token.giver ->
   (Raw_context.t * Z.t * Receipt_repr.balance_updates) tzresult Lwt.t
 
 (** [burn_sc_rollup_origination_fees ~origin ctxt ~storage_limit ~payer consumed]
@@ -110,7 +110,7 @@ val burn_sc_rollup_origination_fees :
   ?origin:Receipt_repr.update_origin ->
   Raw_context.t ->
   storage_limit:Z.t ->
-  payer:Token.source ->
+  payer:Token.giver ->
   Z.t ->
   (Raw_context.t * Z.t * Receipt_repr.balance_updates) tzresult Lwt.t
 
@@ -120,6 +120,6 @@ val burn_zk_rollup_origination_fees :
   ?origin:Receipt_repr.update_origin ->
   Raw_context.t ->
   storage_limit:Z.t ->
-  payer:Token.source ->
+  payer:Token.giver ->
   Z.t ->
   (Raw_context.t * Z.t * Receipt_repr.balance_updates) tzresult Lwt.t
diff --git a/src/proto_alpha/lib_protocol/test/integration/test_token.ml b/src/proto_alpha/lib_protocol/test/integration/test_token.ml
index 89d9389517ca..f8edc38a41ea 100644
--- a/src/proto_alpha/lib_protocol/test/integration/test_token.ml
+++ b/src/proto_alpha/lib_protocol/test/integration/test_token.ml
@@ -57,18 +57,18 @@ let test_simple_balances () =
   let open Lwt_result_wrap_syntax in
   Random.init 0 ;
   create_context () >>=? fun (ctxt, pkh) ->
-  let src = `Contract (Contract.Implicit pkh) in
+  let giver = `Contract (Contract.Implicit pkh) in
   let pkh, _pk, _sk = Signature.generate_key () in
   let dest = `Contract (Contract.Implicit pkh) in
   let amount = Tez.one in
-  wrap (Token.transfer ctxt src dest amount) >>=? fun (ctxt', _) ->
-  wrap (Token.balance ctxt src) >>=? fun (ctxt, bal_src) ->
-  wrap (Token.balance ctxt' src) >>=? fun (ctxt', bal_src') ->
+  wrap (Token.transfer ctxt giver dest amount) >>=? fun (ctxt', _) ->
+  wrap (Token.balance ctxt giver) >>=? fun (ctxt, bal_giver) ->
+  wrap (Token.balance ctxt' giver) >>=? fun (ctxt', bal_giver') ->
   wrap (Token.balance ctxt dest) >>=? fun (_, bal_dest) ->
   wrap (Token.balance ctxt' dest) >>=? fun (_, bal_dest') ->
-  bal_src' +? amount >>?= fun add_bal_src'_amount ->
+  bal_giver' +? amount >>?= fun add_bal_giver'_amount ->
   bal_dest +? amount >>?= fun add_bal_dest_amount ->
-  Assert.equal_tez ~loc:__LOC__ bal_src add_bal_src'_amount >>=? fun () ->
+  Assert.equal_tez ~loc:__LOC__ bal_giver add_bal_giver'_amount >>=? fun () ->
   Assert.equal_tez ~loc:__LOC__ bal_dest' add_bal_dest_amount
 
 (** Check balance updates for a simple transfer from [bootstrap] to new
@@ -77,19 +77,19 @@ let test_simple_balance_updates () =
   let open Lwt_result_wrap_syntax in
   Random.init 0 ;
   create_context () >>=? fun (ctxt, pkh) ->
-  let src = Contract.Implicit pkh in
+  let giver = Contract.Implicit pkh in
   let pkh, _pk, _sk = Signature.generate_key () in
   let dest = Contract.Implicit pkh in
   let amount = Tez.one in
-  wrap (Token.transfer ctxt (`Contract src) (`Contract dest) amount)
+  wrap (Token.transfer ctxt (`Contract giver) (`Contract dest) amount)
   >>=? fun (_, bal_updates) ->
   Alcotest.(
     check
       bool
-      "Missing balance update for source contract."
+      "Missing balance update for giver contract."
       (List.mem
          ~equal:( = )
-         Receipt.(Contract src, Debited amount, Block_application)
+         Receipt.(Contract giver, Debited amount, Block_application)
          bal_updates)
       true) ;
   Alcotest.(
@@ -304,21 +304,21 @@ let test_transferring_to_sink () =
   test_transferring_to_burned ctxt >>=? fun () ->
   test_transferring_to_frozen_bonds ctxt
 
-let check_src_balances ctxt ctxt' src amount =
+let check_giver_balances ctxt ctxt' giver amount =
   let open Lwt_result_wrap_syntax in
-  wrap (Token.balance ctxt src) >>=? fun (_, bal_src) ->
-  wrap (Token.balance ctxt' src) >>=? fun (_, bal_src') ->
-  bal_src' +? amount >>?= fun add_bal_src'_amount ->
-  Assert.equal_tez ~loc:__LOC__ bal_src add_bal_src'_amount
+  wrap (Token.balance ctxt giver) >>=? fun (_, bal_giver) ->
+  wrap (Token.balance ctxt' giver) >>=? fun (_, bal_giver') ->
+  bal_giver' +? amount >>?= fun add_bal_giver'_amount ->
+  Assert.equal_tez ~loc:__LOC__ bal_giver add_bal_giver'_amount
 
-let test_transferring_from_unbounded_source ctxt src expected_bupds =
+let test_transferring_from_infinite_source ctxt giver expected_bupds =
   let open Lwt_result_wrap_syntax in
   (* Transferring zero must not return balance updates. *)
-  wrap (Token.transfer ctxt src `Burned Tez.zero) >>=? fun (_, bupds) ->
+  wrap (Token.transfer ctxt giver `Burned Tez.zero) >>=? fun (_, bupds) ->
   Assert.equal_bool ~loc:__LOC__ (bupds = []) true >>=? fun () ->
   (* Test transferring a non null amount. *)
   let amount = random_amount () in
-  wrap (Token.transfer ctxt src `Burned amount) >>=? fun (_, bupds) ->
+  wrap (Token.transfer ctxt giver `Burned amount) >>=? fun (_, bupds) ->
   let expected_bupds =
     expected_bupds amount
     @ Receipt.[(Burned, Credited amount, Block_application)]
@@ -334,14 +334,14 @@ let balance_no_fail ctxt account =
   if allocated then wrap (Token.balance ctxt account)
   else return (ctxt, Tez.zero)
 
-let test_transferring_from_bounded_source ctxt src amount expected_bupds =
+let test_transferring_from_container ctxt giver amount expected_bupds =
   let open Lwt_result_wrap_syntax in
-  balance_no_fail ctxt src >>=? fun (ctxt, balance) ->
+  balance_no_fail ctxt giver >>=? fun (ctxt, balance) ->
   Assert.equal_tez ~loc:__LOC__ balance Tez.zero >>=? fun () ->
   (* Test transferring from an empty account. *)
-  wrap (Token.transfer ctxt src `Burned Tez.one) >>= fun res ->
+  wrap (Token.transfer ctxt giver `Burned Tez.one) >>= fun res ->
   let error_title =
-    match src with
+    match giver with
     | `Contract _ -> "Balance too low"
     | `Delegate_balance _ | `Frozen_deposits _ | `Frozen_bonds _ ->
         "Storage error (fatal internal error)"
@@ -349,36 +349,36 @@ let test_transferring_from_bounded_source ctxt src amount expected_bupds =
   in
   Assert.proto_error_with_info ~loc:__LOC__ res error_title >>=? fun () ->
   (* Transferring zero must be a noop, and must not return balance updates. *)
-  wrap (Token.transfer ctxt src `Burned Tez.zero) >>=? fun (ctxt', bupds) ->
+  wrap (Token.transfer ctxt giver `Burned Tez.zero) >>=? fun (ctxt', bupds) ->
   Assert.equal_bool ~loc:__LOC__ (ctxt == ctxt' && bupds = []) true
   >>=? fun () ->
   (* Force the allocation of [dest] if need be. *)
-  force_allocation_if_need_be ctxt src >>=? fun ctxt ->
+  force_allocation_if_need_be ctxt giver >>=? fun ctxt ->
   (* Test transferring everything. *)
-  wrap (Token.transfer ctxt `Minted src amount) >>=? fun (ctxt, _) ->
-  wrap (Token.transfer ctxt src `Burned amount) >>=? fun (ctxt', bupds) ->
-  check_src_balances ctxt ctxt' src amount >>=? fun () ->
+  wrap (Token.transfer ctxt `Minted giver amount) >>=? fun (ctxt, _) ->
+  wrap (Token.transfer ctxt giver `Burned amount) >>=? fun (ctxt', bupds) ->
+  check_giver_balances ctxt ctxt' giver amount >>=? fun () ->
   let expected_bupds =
     expected_bupds @ Receipt.[(Burned, Credited amount, Block_application)]
   in
   Assert.equal_bool ~loc:__LOC__ (bupds = expected_bupds) true >>=? fun () ->
   (* Test transferring a smaller amount. *)
-  wrap (Token.transfer ctxt `Minted src amount) >>=? fun (ctxt, _) ->
-  (match src with
+  wrap (Token.transfer ctxt `Minted giver amount) >>=? fun (ctxt, _) ->
+  (match giver with
   | `Frozen_bonds _ ->
-      wrap (Token.transfer ctxt src `Burned amount) >>= fun res ->
+      wrap (Token.transfer ctxt giver `Burned amount) >>= fun res ->
       let error_title = "Partial spending of frozen bonds" in
       Assert.proto_error_with_info ~loc:__LOC__ res error_title
   | _ ->
-      wrap (Token.transfer ctxt src `Burned amount) >>=? fun (ctxt', bupds) ->
-      check_src_balances ctxt ctxt' src amount >>=? fun () ->
+      wrap (Token.transfer ctxt giver `Burned amount) >>=? fun (ctxt', bupds) ->
+      check_giver_balances ctxt ctxt' giver amount >>=? fun () ->
       Assert.equal_bool ~loc:__LOC__ (bupds = expected_bupds) true)
   >>=? fun () ->
   (* Test transferring more than available. *)
-  wrap (Token.balance ctxt src) >>=? fun (ctxt, balance) ->
-  wrap (Token.transfer ctxt src `Burned (balance +! Tez.one)) >>= fun res ->
+  wrap (Token.balance ctxt giver) >>=? fun (ctxt, balance) ->
+  wrap (Token.transfer ctxt giver `Burned (balance +! Tez.one)) >>= fun res ->
   let error_title =
-    match src with
+    match giver with
     | `Contract _ -> "Balance too low"
     | `Frozen_bonds _ -> "Partial spending of frozen bonds"
     | _ -> "Underflowing tez subtraction"
@@ -387,18 +387,18 @@ let test_transferring_from_bounded_source ctxt src amount expected_bupds =
 
 let test_transferring_from_contract ctxt =
   let pkh, _pk, _sk = Signature.generate_key () in
-  let src = Contract.Implicit pkh in
+  let giver = Contract.Implicit pkh in
   let amount = random_amount () in
-  test_transferring_from_bounded_source
+  test_transferring_from_container
     ctxt
-    (`Contract src)
+    (`Contract giver)
     amount
-    [(Contract src, Debited amount, Block_application)]
+    [(Contract giver, Debited amount, Block_application)]
 
 let test_transferring_from_collected_commitments ctxt =
   let amount = random_amount () in
   let bpkh = Blinded_public_key_hash.zero in
-  test_transferring_from_bounded_source
+  test_transferring_from_container
     ctxt
     (`Collected_commitments bpkh)
     amount
@@ -407,17 +407,17 @@ let test_transferring_from_collected_commitments ctxt =
 let test_transferring_from_delegate_balance ctxt =
   let pkh, _pk, _sk = Signature.generate_key () in
   let amount = random_amount () in
-  let src = Contract.Implicit pkh in
-  test_transferring_from_bounded_source
+  let giver = Contract.Implicit pkh in
+  test_transferring_from_container
     ctxt
     (`Delegate_balance pkh)
     amount
-    [(Contract src, Debited amount, Block_application)]
+    [(Contract giver, Debited amount, Block_application)]
 
 let test_transferring_from_frozen_deposits ctxt =
   let pkh, _pk, _sk = Signature.generate_key () in
   let amount = random_amount () in
-  test_transferring_from_bounded_source
+  test_transferring_from_container
     ctxt
     (`Frozen_deposits pkh)
     amount
@@ -425,7 +425,7 @@ let test_transferring_from_frozen_deposits ctxt =
 
 let test_transferring_from_collected_fees ctxt =
   let amount = random_amount () in
-  test_transferring_from_bounded_source
+  test_transferring_from_container
     ctxt
     `Block_fees
     amount
@@ -437,46 +437,46 @@ let test_transferring_from_frozen_bonds ctxt =
   let sc_rollup = sc_rollup () in
   let bond_id = Bond_id.Sc_rollup_bond_id sc_rollup in
   let amount = random_amount () in
-  test_transferring_from_bounded_source
+  test_transferring_from_container
     ctxt
     (`Frozen_bonds (contract, bond_id))
     amount
     [(Frozen_bonds (contract, bond_id), Debited amount, Block_application)]
 
-let test_transferring_from_source () =
+let test_transferring_from_giver () =
   Random.init 0 ;
   create_context () >>=? fun (ctxt, _) ->
-  test_transferring_from_unbounded_source ctxt `Invoice (fun am ->
+  test_transferring_from_infinite_source ctxt `Invoice (fun am ->
       [(Invoice, Debited am, Block_application)])
   >>=? fun () ->
-  test_transferring_from_unbounded_source ctxt `Bootstrap (fun am ->
+  test_transferring_from_infinite_source ctxt `Bootstrap (fun am ->
       [(Bootstrap, Debited am, Block_application)])
   >>=? fun () ->
-  test_transferring_from_unbounded_source ctxt `Initial_commitments (fun am ->
+  test_transferring_from_infinite_source ctxt `Initial_commitments (fun am ->
       [(Initial_commitments, Debited am, Block_application)])
   >>=? fun () ->
-  test_transferring_from_unbounded_source ctxt `Revelation_rewards (fun am ->
+  test_transferring_from_infinite_source ctxt `Revelation_rewards (fun am ->
       [(Nonce_revelation_rewards, Debited am, Block_application)])
   >>=? fun () ->
-  test_transferring_from_unbounded_source
+  test_transferring_from_infinite_source
     ctxt
     `Double_signing_evidence_rewards
     (fun am ->
       [(Double_signing_evidence_rewards, Debited am, Block_application)])
   >>=? fun () ->
-  test_transferring_from_unbounded_source ctxt `Endorsing_rewards (fun am ->
+  test_transferring_from_infinite_source ctxt `Endorsing_rewards (fun am ->
       [(Endorsing_rewards, Debited am, Block_application)])
   >>=? fun () ->
-  test_transferring_from_unbounded_source ctxt `Baking_rewards (fun am ->
+  test_transferring_from_infinite_source ctxt `Baking_rewards (fun am ->
       [(Baking_rewards, Debited am, Block_application)])
   >>=? fun () ->
-  test_transferring_from_unbounded_source ctxt `Baking_bonuses (fun am ->
+  test_transferring_from_infinite_source ctxt `Baking_bonuses (fun am ->
       [(Baking_bonuses, Debited am, Block_application)])
   >>=? fun () ->
-  test_transferring_from_unbounded_source ctxt `Minted (fun am ->
+  test_transferring_from_infinite_source ctxt `Minted (fun am ->
       [(Minted, Debited am, Block_application)])
   >>=? fun () ->
-  test_transferring_from_unbounded_source
+  test_transferring_from_infinite_source
     ctxt
     `Liquidity_baking_subsidies
     (fun am -> [(Liquidity_baking_subsidies, Debited am, Block_application)])
@@ -538,7 +538,7 @@ let build_test_cases () =
   let bond_id2 = Bond_id.Sc_rollup_bond_id sc_rollup2 in
   let user1ic = Contract.Implicit user1 in
   let baker2ic = Contract.Implicit baker2 in
-  let src_list =
+  let giver_list =
     [
       (`Invoice, random_amount ());
       (`Bootstrap, random_amount ());
@@ -572,54 +572,54 @@ let build_test_cases () =
       `Burned;
     ]
   in
-  return (ctxt, List.product src_list dest_list)
+  return (ctxt, List.product giver_list dest_list)
 
-let check_src_balances ctxt ctxt' src amount =
-  match cast_to_container_type src with
+let check_giver_balances ctxt ctxt' giver amount =
+  match cast_to_container_type giver with
   | None -> return_unit
-  | Some src -> check_src_balances ctxt ctxt' src amount
+  | Some giver -> check_giver_balances ctxt ctxt' giver amount
 
 let check_sink_balances ctxt ctxt' dest amount =
   match cast_to_container_type dest with
   | None -> return_unit
   | Some dest -> check_sink_balances ctxt ctxt' dest amount
 
-let rec check_balances ctxt ctxt' src dest amount =
+let rec check_balances ctxt ctxt' giver dest amount =
   let open Lwt_result_wrap_syntax in
-  match (cast_to_container_type src, cast_to_container_type dest) with
+  match (cast_to_container_type giver, cast_to_container_type dest) with
   | None, None -> return_unit
   | ( Some (`Delegate_balance d),
       Some (`Contract (Contract.Implicit c) as contract) )
   | ( Some (`Contract (Contract.Implicit c) as contract),
       Some (`Delegate_balance d) )
     when d = c ->
-      (* src and dest are in fact referring to the same contract *)
+      (* giver and dest are in fact referring to the same contract *)
       check_balances ctxt ctxt' contract contract amount
-  | Some src, Some dest when src = dest ->
-      (* src and dest are the same contract *)
+  | Some giver, Some dest when giver = dest ->
+      (* giver and dest are the same contract *)
       wrap (Token.balance ctxt dest) >>=? fun (_, bal_dest) ->
       wrap (Token.balance ctxt' dest) >>=? fun (_, bal_dest') ->
       Assert.equal_tez ~loc:__LOC__ bal_dest bal_dest'
-  | Some src, None -> check_src_balances ctxt ctxt' src amount
+  | Some giver, None -> check_giver_balances ctxt ctxt' giver amount
   | None, Some dest -> check_sink_balances ctxt ctxt' dest amount
-  | Some src, Some dest ->
-      check_src_balances ctxt ctxt' src amount >>=? fun () ->
+  | Some giver, Some dest ->
+      check_giver_balances ctxt ctxt' giver amount >>=? fun () ->
       check_sink_balances ctxt ctxt' dest amount
 
-let test_all_combinations_of_sources_and_sinks () =
+let test_all_combinations_of_givers_and_sinks () =
   let open Lwt_result_wrap_syntax in
   Random.init 0 ;
   build_test_cases () >>=? fun (ctxt, cases) ->
   List.iter_es
-    (fun ((src, amount), dest) ->
-      (match cast_to_container_type src with
+    (fun ((giver, amount), dest) ->
+      (match cast_to_container_type giver with
       | None -> return ctxt
-      | Some src ->
-          wrap (Token.transfer ctxt `Minted src amount) >>=? fun (ctxt, _) ->
+      | Some giver ->
+          wrap (Token.transfer ctxt `Minted giver amount) >>=? fun (ctxt, _) ->
           return ctxt)
       >>=? fun ctxt ->
-      wrap (Token.transfer ctxt src dest amount) >>=? fun (ctxt', _) ->
-      check_balances ctxt ctxt' src dest amount)
+      wrap (Token.transfer ctxt giver dest amount) >>=? fun (ctxt', _) ->
+      check_balances ctxt ctxt' giver dest amount)
     cases
 
 (** [coalesce (account, Credited am1, origin) (account, Credited am2, origin)
@@ -662,16 +662,16 @@ let check_balances_are_consistent ctxt1 ctxt2 elt =
       return_unit
 
 (** Test that [transfer_n] is equivalent to n debits followed by n credits. *)
-let test_transfer_n ctxt src dest =
+let test_transfer_n ctxt giver dest =
   (* Run transfer_n. *)
-  Token.transfer_n ctxt src dest >>=? fun (ctxt1, bal_updates1) ->
-  (* Debit all sources. *)
+  Token.transfer_n ctxt giver dest >>=? fun (ctxt1, bal_updates1) ->
+  (* Debit all givers. *)
   List.fold_left_es
-    (fun (ctxt, bal_updates) (src, am) ->
-      Token.transfer ctxt src `Burned am >>=? fun (ctxt, debit_logs) ->
+    (fun (ctxt, bal_updates) (giver, am) ->
+      Token.transfer ctxt giver `Burned am >>=? fun (ctxt, debit_logs) ->
       return (ctxt, bal_updates @ debit_logs))
     (ctxt, [])
-    src
+    giver
   >>=? fun (ctxt, debit_logs) ->
   (* remove burning balance updates *)
   let debit_logs =
@@ -679,13 +679,13 @@ let test_transfer_n ctxt src dest =
       (fun b -> match b with Receipt.Burned, _, _ -> false | _ -> true)
       debit_logs
   in
-  (* Credit the sink for each source. *)
+  (* Credit the sink for each giver. *)
   List.fold_left_es
     (fun (ctxt, bal_updates) (_, am) ->
       Token.transfer ctxt `Minted dest am >>=? fun (ctxt, credit_logs) ->
       return (ctxt, bal_updates @ credit_logs))
     (ctxt, [])
-    src
+    giver
   >>=? fun (ctxt2, credit_logs) ->
   (* remove minting balance updates *)
   let credit_logs =
@@ -701,10 +701,10 @@ let test_transfer_n ctxt src dest =
   in
   assert (bal_updates1 = debit_logs @ credit_logs) ;
   (* Check balances are the same in ctxt1 and ctxt2. *)
-  List.(iter_es (check_balances_are_consistent ctxt1 ctxt2) (map fst src))
+  List.(iter_es (check_balances_are_consistent ctxt1 ctxt2) (map fst giver))
   >>=? fun () -> check_balances_are_consistent ctxt1 ctxt2 dest
 
-let test_transfer_n_with_empty_source () =
+let test_transfer_n_with_no_giver () =
   let open Lwt_result_wrap_syntax in
   Random.init 0 ;
   create_context () >>=? fun (ctxt, pkh) ->
@@ -712,7 +712,7 @@ let test_transfer_n_with_empty_source () =
   let dest = `Delegate_balance pkh in
   wrap (test_transfer_n ctxt [] dest)
 
-let test_transfer_n_with_non_empty_source () =
+let test_transfer_n_with_several_givers () =
   let open Lwt_result_wrap_syntax in
   Random.init 0 ;
   create_context () >>=? fun (ctxt, pkh) ->
@@ -734,15 +734,15 @@ let test_transfer_n_with_non_empty_source () =
   wrap (Token.transfer ctxt origin user3c amount) >>=? fun (ctxt, _) ->
   wrap (Token.transfer ctxt origin user4c (random_amount ()))
   >>=? fun (ctxt, _) ->
-  let sources =
+  let givers =
     [
       (user2c, random_amount ());
       (user3c, random_amount ());
       (user4c, random_amount ());
     ]
   in
-  wrap (test_transfer_n ctxt sources user1c) >>=? fun () ->
-  wrap (test_transfer_n ctxt ((user1c, random_amount ()) :: sources) user1c)
+  wrap (test_transfer_n ctxt givers user1c) >>=? fun () ->
+  wrap (test_transfer_n ctxt ((user1c, random_amount ()) :: givers) user1c)
 
 let tests =
   Tztest.
@@ -752,19 +752,19 @@ let tests =
       tztest "transfer - test allocated" `Quick test_allocated;
       tztest "transfer - test transfer to sink" `Quick test_transferring_to_sink;
       tztest
-        "transfer - test transfer from source"
+        "transfer - test transfer from giver"
         `Quick
-        test_transferring_from_source;
+        test_transferring_from_giver;
       tztest
-        "transfer - test all (sources x sinks)"
+        "transfer - test all (givers x sinks)"
         `Quick
-        test_all_combinations_of_sources_and_sinks;
+        test_all_combinations_of_givers_and_sinks;
       tztest
-        "transfer - test from empty sources to a destination"
+        "transfer - test from no giver to a destination"
         `Quick
-        test_transfer_n_with_empty_source;
+        test_transfer_n_with_no_giver;
       tztest
-        "transfer - test from n sources to a destination"
+        "transfer - test from n givers to a destination"
         `Quick
-        test_transfer_n_with_non_empty_source;
+        test_transfer_n_with_several_givers;
     ]
diff --git a/src/proto_alpha/lib_protocol/token.ml b/src/proto_alpha/lib_protocol/token.ml
index 072cb8e262a4..40ace57c7f11 100644
--- a/src/proto_alpha/lib_protocol/token.ml
+++ b/src/proto_alpha/lib_protocol/token.ml
@@ -45,7 +45,7 @@ type infinite_source =
   | `Tx_rollup_rejection_rewards
   | `Sc_rollup_refutation_rewards ]
 
-type source = [infinite_source | container]
+type giver = [infinite_source | container]
 
 type infinite_sink =
   [ `Storage_fees
@@ -158,9 +158,9 @@ let credit ctxt dest amount origin =
           >>=? fun ctxt -> return (ctxt, Frozen_bonds (contract, bond_id))))
   >|=? fun (ctxt, balance) -> (ctxt, (balance, Credited amount, origin))
 
-let spend ctxt src amount origin =
+let spend ctxt giver amount origin =
   let open Receipt_repr in
-  (match src with
+  (match giver with
   | #infinite_source as infinite_source ->
       let src =
         match infinite_source with
@@ -180,9 +180,9 @@ let spend ctxt src amount origin =
       return (ctxt, src)
   | #container as container -> (
       match container with
-      | `Contract src ->
-          Contract_storage.spend_only_call_from_token ctxt src amount
-          >|=? fun ctxt -> (ctxt, Contract src)
+      | `Contract giver ->
+          Contract_storage.spend_only_call_from_token ctxt giver amount
+          >|=? fun ctxt -> (ctxt, Contract giver)
       | `Collected_commitments bpkh ->
           Commitment_storage.decrease_commitment_only_call_from_token
             ctxt
@@ -214,21 +214,21 @@ let spend ctxt src amount origin =
           >>=? fun ctxt -> return (ctxt, Frozen_bonds (contract, bond_id))))
   >|=? fun (ctxt, balance) -> (ctxt, (balance, Debited amount, origin))
 
-let transfer_n ?(origin = Receipt_repr.Block_application) ctxt src dest =
-  let sources = List.filter (fun (_, am) -> Tez_repr.(am <> zero)) src in
-  match sources with
+let transfer_n ?(origin = Receipt_repr.Block_application) ctxt givers dest =
+  let givers = List.filter (fun (_, am) -> Tez_repr.(am <> zero)) givers in
+  match givers with
   | [] ->
       (* Avoid accessing context data when there is nothing to transfer. *)
       return (ctxt, [])
   | _ :: _ ->
-      (* Withdraw from sources. *)
+      (* Withdraw from givers. *)
       List.fold_left_es
-        (fun (ctxt, total, debit_logs) (source, amount) ->
-          spend ctxt source amount origin >>=? fun (ctxt, debit_log) ->
+        (fun (ctxt, total, debit_logs) (giver, amount) ->
+          spend ctxt giver amount origin >>=? fun (ctxt, debit_log) ->
           Tez_repr.(amount +? total) >>?= fun total ->
           return (ctxt, total, debit_log :: debit_logs))
         (ctxt, Tez_repr.zero, [])
-        sources
+        givers
       >>=? fun (ctxt, amount, debit_logs) ->
       credit ctxt dest amount origin >>=? fun (ctxt, credit_log) ->
       (* Deallocate implicit contracts with no stake. This must be done after
@@ -236,18 +236,18 @@ let transfer_n ?(origin = Receipt_repr.Block_application) ctxt src dest =
          balance from (`Contract c) to (`Frozen_bonds (c,_)) would leave the
          contract c unallocated. *)
       List.fold_left_es
-        (fun ctxt (source, _amount) ->
-          match source with
+        (fun ctxt (giver, _amount) ->
+          match giver with
           | `Contract contract | `Frozen_bonds (contract, _) ->
               Contract_storage.ensure_deallocated_if_empty ctxt contract
-          | #source -> return ctxt)
+          | #giver -> return ctxt)
         ctxt
-        sources
+        givers
       >|=? fun ctxt ->
       (* Make sure the order of balance updates is : debit logs in the order of
-         of the parameter [src], and then the credit log. *)
+         of the parameter [givers], and then the credit log. *)
       let balance_updates = List.rev (credit_log :: debit_logs) in
       (ctxt, balance_updates)
 
-let transfer ?(origin = Receipt_repr.Block_application) ctxt src dest amount =
-  transfer_n ~origin ctxt [(src, amount)] dest
+let transfer ?(origin = Receipt_repr.Block_application) ctxt giver dest amount =
+  transfer_n ~origin ctxt [(giver, amount)] dest
diff --git a/src/proto_alpha/lib_protocol/token.mli b/src/proto_alpha/lib_protocol/token.mli
index 0e6595f90b8b..f075d7c2fe56 100644
--- a/src/proto_alpha/lib_protocol/token.mli
+++ b/src/proto_alpha/lib_protocol/token.mli
@@ -24,15 +24,15 @@
 (*****************************************************************************)
 
 (** The aim of this module is to manage operations involving tokens such as
-    minting, transferring, and burning. Every constructor of the types [source],
+    minting, transferring, and burning. Every constructor of the types [giver],
     [container], or [sink] represents a kind of account that holds a given (or
     possibly infinite) amount of tokens.
 
-    Tokens can be transferred from a [source] to a [sink]. To uniformly handle
-    all cases, special constructors of sources and sinks may be used. For
-    example, the source [`Minted] is used to express a transfer of minted tokens
+    Tokens can be transferred from a [giver] to a [sink]. To uniformly handle
+    all cases, special constructors of givers and sinks may be used. For
+    example, the giver [`Minted] is used to express a transfer of minted tokens
     to a destination, and the sink [`Burned] is used to express the action of
-    burning a given amount of tokens taken from a source. Thanks to uniformity,
+    burning a given amount of tokens taken from a giver. Thanks to uniformity,
     it is easier to track transfers of tokens throughout the protocol by running
     [grep -R "Token.transfer" src/proto_alpha].
 
@@ -98,9 +98,9 @@ type infinite_source =
   | `Sc_rollup_refutation_rewards
     (** Sc_rollup refutation rewards (slashing redistribution) *) ]
 
-(** [source] is the type of token providers. Token providers that are not
+(** [giver] is the type of token providers. Token providers that are not
     containers are considered to have infinite capacity. *)
-type source = [infinite_source | container]
+type giver = [infinite_source | container]
 
 type infinite_sink =
   [ `Storage_fees  (** Fees burnt to compensate storage usage *)
@@ -134,32 +134,32 @@ val allocated :
 val balance :
   Raw_context.t -> container -> (Raw_context.t * Tez_repr.t) tzresult Lwt.t
 
-(** [transfer_n ?origin ctxt sources dest] transfers [amount] Tez from [src] to
-    [dest] for each [(src, amount)] pair in [sources], and returns a new
+(** [transfer_n ?origin ctxt givers dest] transfers [amount] Tez from [giver] to
+    [dest] for each [(giver, amount)] pair in [givers], and returns a new
     context, and the list of corresponding balance updates. The function behaves
-    as though [transfer src dest amount] was invoked for each pair
-    [(src, amount)] in [sources], however a single balance update is generated
+    as though [transfer giver dest amount] was invoked for each pair
+    [(giver, amount)] in [givers], however a single balance update is generated
     for the total amount transferred to [dest].
-    When [sources] is an empty list, the function does nothing to the context,
+    When [givers] is an empty list, the function does nothing to the context,
     and returns an empty list of balance updates. *)
 val transfer_n :
   ?origin:Receipt_repr.update_origin ->
   Raw_context.t ->
-  ([< source] * Tez_repr.t) list ->
+  ([< giver] * Tez_repr.t) list ->
   [< sink] ->
   (Raw_context.t * Receipt_repr.balance_updates) tzresult Lwt.t
 
-(** [transfer ?origin ctxt src dest amount] transfers [amount] Tez from source
-    [src] to destination [dest], and returns a new context, and the list of
+(** [transfer ?origin ctxt giver dest amount] transfers [amount] Tez from giver
+    [giver] to destination [dest], and returns a new context, and the list of
     corresponding balance updates tagged with [origin]. By default, [~origin] is
     set to [Receipt_repr.Block_application].
-    Returns {!Storage_Error Missing_key} if [src] refers to a contract that is
+    Returns {!Storage_Error Missing_key} if [giver] refers to a contract that is
     not allocated.
-    Returns a [Balance_too_low] error if [src] refers to a contract whose
+    Returns a [Balance_too_low] error if [giver] refers to a contract whose
     balance is less than [amount].
-    Returns a [Subtraction_underflow] error if [src] refers to a source that is
-    not a contract and whose balance is less than [amount].
-    Returns a [Empty_implicit_delegated_contract] error if [src] is an
+    Returns a [Subtraction_underflow] error if [giver] is
+    not a contract and its balance is less than [amount].
+    Returns a [Empty_implicit_delegated_contract] error if [giver] is an
     implicit contract that delegates to a different contract, and whose balance
     is equal to [amount].
     Returns a [Non_existing_contract] error if
@@ -173,7 +173,7 @@ val transfer_n :
 val transfer :
   ?origin:Receipt_repr.update_origin ->
   Raw_context.t ->
-  [< source] ->
+  [< giver] ->
   [< sink] ->
   Tez_repr.t ->
   (Raw_context.t * Receipt_repr.balance_updates) tzresult Lwt.t
-- 
GitLab


From 4a8769a50f72acf0bdce85a1f0a949cd3f570dd0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rapha=C3=ABl=20Cauderlier?=
 <raphael.cauderlier@nomadic-labs.com>
Date: Mon, 30 Jan 2023 11:46:28 +0100
Subject: [PATCH 2/4] Proto/Token: fix a typo

---
 src/proto_alpha/lib_protocol/token.mli | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/proto_alpha/lib_protocol/token.mli b/src/proto_alpha/lib_protocol/token.mli
index f075d7c2fe56..c6a213d3d5bb 100644
--- a/src/proto_alpha/lib_protocol/token.mli
+++ b/src/proto_alpha/lib_protocol/token.mli
@@ -76,7 +76,7 @@ type container =
     (** Frozen tokens of a contract for bond deposits (currently used by rollups) *)
   ]
 
-(** [infinite_source] defines types of tokens provides which are considered to be
+(** [infinite_source] defines types of tokens providers which are considered to be
  ** of infinite capacity. *)
 type infinite_source =
   [ `Invoice
-- 
GitLab


From 90b02f5a9edc30c3fe895e4a94217d38b11908ea Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rapha=C3=ABl=20Cauderlier?=
 <raphael.cauderlier@nomadic-labs.com>
Date: Mon, 30 Jan 2023 12:03:59 +0100
Subject: [PATCH 3/4] Proto/Token: rename "sink" and "destination" into
 "receiver"

This is just for consistency with the previous "source" -> "giver" renaming.
---
 .../lib_protocol/alpha_context.mli            |   6 +-
 .../test/integration/test_token.ml            | 191 +++++++++---------
 src/proto_alpha/lib_protocol/token.ml         |  25 +--
 src/proto_alpha/lib_protocol/token.mli        |  36 ++--
 4 files changed, 134 insertions(+), 124 deletions(-)

diff --git a/src/proto_alpha/lib_protocol/alpha_context.mli b/src/proto_alpha/lib_protocol/alpha_context.mli
index cf78a84e381b..d36f8f6312cd 100644
--- a/src/proto_alpha/lib_protocol/alpha_context.mli
+++ b/src/proto_alpha/lib_protocol/alpha_context.mli
@@ -5265,7 +5265,7 @@ module Token : sig
     | `Sc_rollup_refutation_rewards
     | container ]
 
-  type sink =
+  type receiver =
     [ `Storage_fees
     | `Double_signing_punishments
     | `Lost_endorsing_rewards of public_key_hash * bool * bool
@@ -5282,14 +5282,14 @@ module Token : sig
     ?origin:Receipt.update_origin ->
     context ->
     ([< giver] * Tez.t) list ->
-    [< sink] ->
+    [< receiver] ->
     (context * Receipt.balance_updates) tzresult Lwt.t
 
   val transfer :
     ?origin:Receipt.update_origin ->
     context ->
     [< giver] ->
-    [< sink] ->
+    [< receiver] ->
     Tez.t ->
     (context * Receipt.balance_updates) tzresult Lwt.t
 end
diff --git a/src/proto_alpha/lib_protocol/test/integration/test_token.ml b/src/proto_alpha/lib_protocol/test/integration/test_token.ml
index f8edc38a41ea..edf122f6c957 100644
--- a/src/proto_alpha/lib_protocol/test/integration/test_token.ml
+++ b/src/proto_alpha/lib_protocol/test/integration/test_token.ml
@@ -59,17 +59,17 @@ let test_simple_balances () =
   create_context () >>=? fun (ctxt, pkh) ->
   let giver = `Contract (Contract.Implicit pkh) in
   let pkh, _pk, _sk = Signature.generate_key () in
-  let dest = `Contract (Contract.Implicit pkh) in
+  let receiver = `Contract (Contract.Implicit pkh) in
   let amount = Tez.one in
-  wrap (Token.transfer ctxt giver dest amount) >>=? fun (ctxt', _) ->
+  wrap (Token.transfer ctxt giver receiver amount) >>=? fun (ctxt', _) ->
   wrap (Token.balance ctxt giver) >>=? fun (ctxt, bal_giver) ->
   wrap (Token.balance ctxt' giver) >>=? fun (ctxt', bal_giver') ->
-  wrap (Token.balance ctxt dest) >>=? fun (_, bal_dest) ->
-  wrap (Token.balance ctxt' dest) >>=? fun (_, bal_dest') ->
+  wrap (Token.balance ctxt receiver) >>=? fun (_, bal_receiver) ->
+  wrap (Token.balance ctxt' receiver) >>=? fun (_, bal_receiver') ->
   bal_giver' +? amount >>?= fun add_bal_giver'_amount ->
-  bal_dest +? amount >>?= fun add_bal_dest_amount ->
+  bal_receiver +? amount >>?= fun add_bal_receiver_amount ->
   Assert.equal_tez ~loc:__LOC__ bal_giver add_bal_giver'_amount >>=? fun () ->
-  Assert.equal_tez ~loc:__LOC__ bal_dest' add_bal_dest_amount
+  Assert.equal_tez ~loc:__LOC__ bal_receiver' add_bal_receiver_amount
 
 (** Check balance updates for a simple transfer from [bootstrap] to new
     [Implicit]. *)
@@ -79,9 +79,9 @@ let test_simple_balance_updates () =
   create_context () >>=? fun (ctxt, pkh) ->
   let giver = Contract.Implicit pkh in
   let pkh, _pk, _sk = Signature.generate_key () in
-  let dest = Contract.Implicit pkh in
+  let receiver = Contract.Implicit pkh in
   let amount = Tez.one in
-  wrap (Token.transfer ctxt (`Contract giver) (`Contract dest) amount)
+  wrap (Token.transfer ctxt (`Contract giver) (`Contract receiver) amount)
   >>=? fun (_, bal_updates) ->
   Alcotest.(
     check
@@ -95,60 +95,65 @@ let test_simple_balance_updates () =
   Alcotest.(
     check
       bool
-      "Missing balance update for destination contract."
+      "Missing balance update for receiver contract."
       (List.mem
          ~equal:( = )
-         Receipt.(Contract dest, Credited amount, Block_application)
+         Receipt.(Contract receiver, Credited amount, Block_application)
          bal_updates)
       true) ;
   return_unit
 
-let test_allocated_and_deallocated ctxt dest initial_status status_when_empty =
+let test_allocated_and_deallocated ctxt receiver initial_status
+    status_when_empty =
   let open Lwt_result_wrap_syntax in
-  wrap (Token.allocated ctxt dest) >>=? fun (ctxt, allocated) ->
+  wrap (Token.allocated ctxt receiver) >>=? fun (ctxt, allocated) ->
   Assert.equal_bool ~loc:__LOC__ allocated initial_status >>=? fun () ->
   let amount = Tez.one in
-  wrap (Token.transfer ctxt `Minted dest amount) >>=? fun (ctxt', _) ->
-  wrap (Token.allocated ctxt' dest) >>=? fun (ctxt', allocated) ->
+  wrap (Token.transfer ctxt `Minted receiver amount) >>=? fun (ctxt', _) ->
+  wrap (Token.allocated ctxt' receiver) >>=? fun (ctxt', allocated) ->
   Assert.equal_bool ~loc:__LOC__ allocated true >>=? fun () ->
-  wrap (Token.balance ctxt' dest) >>=? fun (ctxt', bal_dest') ->
-  wrap (Token.transfer ctxt' dest `Burned bal_dest') >>=? fun (ctxt', _) ->
-  wrap (Token.allocated ctxt' dest) >>=? fun (_, allocated) ->
+  wrap (Token.balance ctxt' receiver) >>=? fun (ctxt', bal_receiver') ->
+  wrap (Token.transfer ctxt' receiver `Burned bal_receiver')
+  >>=? fun (ctxt', _) ->
+  wrap (Token.allocated ctxt' receiver) >>=? fun (_, allocated) ->
   Assert.equal_bool ~loc:__LOC__ allocated status_when_empty >>=? fun () ->
   return_unit
 
-let test_allocated_and_deallocated_when_empty ctxt dest =
-  test_allocated_and_deallocated ctxt dest false false
+let test_allocated_and_deallocated_when_empty ctxt receiver =
+  test_allocated_and_deallocated ctxt receiver false false
 
-let test_allocated_and_still_allocated_when_empty ctxt dest initial_status =
-  test_allocated_and_deallocated ctxt dest initial_status true
+let test_allocated_and_still_allocated_when_empty ctxt receiver initial_status =
+  test_allocated_and_deallocated ctxt receiver initial_status true
 
 let test_allocated () =
   Random.init 0 ;
   create_context () >>=? fun (ctxt, pkh) ->
-  let dest = `Delegate_balance pkh in
-  test_allocated_and_still_allocated_when_empty ctxt dest true >>=? fun () ->
+  let receiver = `Delegate_balance pkh in
+  test_allocated_and_still_allocated_when_empty ctxt receiver true
+  >>=? fun () ->
   let pkh, _pk, _sk = Signature.generate_key () in
-  let dest = `Contract (Contract.Implicit pkh) in
-  test_allocated_and_deallocated_when_empty ctxt dest >>=? fun () ->
-  let dest = `Collected_commitments Blinded_public_key_hash.zero in
-  test_allocated_and_deallocated_when_empty ctxt dest >>=? fun () ->
-  let dest = `Frozen_deposits pkh in
-  test_allocated_and_still_allocated_when_empty ctxt dest false >>=? fun () ->
-  let dest = `Block_fees in
-  test_allocated_and_still_allocated_when_empty ctxt dest true >>=? fun () ->
-  let dest =
+  let receiver = `Contract (Contract.Implicit pkh) in
+  test_allocated_and_deallocated_when_empty ctxt receiver >>=? fun () ->
+  let receiver = `Collected_commitments Blinded_public_key_hash.zero in
+  test_allocated_and_deallocated_when_empty ctxt receiver >>=? fun () ->
+  let receiver = `Frozen_deposits pkh in
+  test_allocated_and_still_allocated_when_empty ctxt receiver false
+  >>=? fun () ->
+  let receiver = `Block_fees in
+  test_allocated_and_still_allocated_when_empty ctxt receiver true
+  >>=? fun () ->
+  let receiver =
     let bond_id = Bond_id.Sc_rollup_bond_id (sc_rollup ()) in
     `Frozen_bonds (Contract.Implicit pkh, bond_id)
   in
-  test_allocated_and_deallocated_when_empty ctxt dest
+  test_allocated_and_deallocated_when_empty ctxt receiver
 
-let check_sink_balances ctxt ctxt' dest amount =
+let check_receiver_balances ctxt ctxt' receiver amount =
   let open Lwt_result_wrap_syntax in
-  wrap (Token.balance ctxt dest) >>=? fun (_, bal_dest) ->
-  wrap (Token.balance ctxt' dest) >>=? fun (_, bal_dest') ->
-  bal_dest +? amount >>?= fun add_bal_dest_amount ->
-  Assert.equal_tez ~loc:__LOC__ bal_dest' add_bal_dest_amount
+  wrap (Token.balance ctxt receiver) >>=? fun (_, bal_receiver) ->
+  wrap (Token.balance ctxt' receiver) >>=? fun (_, bal_receiver') ->
+  bal_receiver +? amount >>?= fun add_bal_receiver_amount ->
+  Assert.equal_tez ~loc:__LOC__ bal_receiver' add_bal_receiver_amount
 
 (* Accounts of the form (`DelegateBalance pkh) are not allocated when they
    receive funds for the first time. To force allocation, we transfer to
@@ -161,42 +166,43 @@ let force_allocation_if_need_be ctxt account =
       wrap (Token.transfer ctxt `Minted account Tez.one_mutez) >|=? fst
   | _ -> return ctxt
 
-let test_transferring_to_sink ctxt sink amount expected_bupds =
+let test_transferring_to_receiver ctxt receiver amount expected_bupds =
   let open Lwt_result_wrap_syntax in
   (* Transferring zero must be a noop, and must not return balance updates. *)
-  wrap (Token.transfer ctxt `Minted sink Tez.zero) >>=? fun (ctxt', bupds) ->
+  wrap (Token.transfer ctxt `Minted receiver Tez.zero)
+  >>=? fun (ctxt', bupds) ->
   Assert.equal_bool ~loc:__LOC__ (ctxt == ctxt' && bupds = []) true
   >>=? fun () ->
-  (* Force the allocation of [dest] if need be. *)
-  force_allocation_if_need_be ctxt sink >>=? fun ctxt ->
+  (* Force the allocation of [receiver] if need be. *)
+  force_allocation_if_need_be ctxt receiver >>=? fun ctxt ->
   (* Test transferring a non null amount. *)
-  wrap (Token.transfer ctxt `Minted sink amount) >>=? fun (ctxt', bupds) ->
-  check_sink_balances ctxt ctxt' sink amount >>=? fun () ->
+  wrap (Token.transfer ctxt `Minted receiver amount) >>=? fun (ctxt', bupds) ->
+  check_receiver_balances ctxt ctxt' receiver amount >>=? fun () ->
   let expected_bupds =
     Receipt.(Minted, Debited amount, Block_application) :: expected_bupds
   in
   Alcotest.(
     check bool "Balance updates do not match." (bupds = expected_bupds) true) ;
   (* Test transferring to go beyond capacity. *)
-  wrap (Token.balance ctxt' sink) >>=? fun (ctxt', bal) ->
+  wrap (Token.balance ctxt' receiver) >>=? fun (ctxt', bal) ->
   let amount = Tez.of_mutez_exn Int64.max_int -! bal +! Tez.one_mutez in
-  wrap (Token.transfer ctxt' `Minted sink amount) >>= fun res ->
+  wrap (Token.transfer ctxt' `Minted receiver amount) >>= fun res ->
   Assert.proto_error_with_info ~loc:__LOC__ res "Overflowing tez addition"
 
 let test_transferring_to_contract ctxt =
   let pkh, _pk, _sk = Signature.generate_key () in
-  let dest = Contract.Implicit pkh in
+  let receiver = Contract.Implicit pkh in
   let amount = random_amount () in
-  test_transferring_to_sink
+  test_transferring_to_receiver
     ctxt
-    (`Contract dest)
+    (`Contract receiver)
     amount
-    [(Contract dest, Credited amount, Block_application)]
+    [(Contract receiver, Credited amount, Block_application)]
 
 let test_transferring_to_collected_commitments ctxt =
   let amount = random_amount () in
   let bpkh = Blinded_public_key_hash.zero in
-  test_transferring_to_sink
+  test_transferring_to_receiver
     ctxt
     (`Collected_commitments bpkh)
     amount
@@ -204,18 +210,18 @@ let test_transferring_to_collected_commitments ctxt =
 
 let test_transferring_to_delegate_balance ctxt =
   let pkh, _pk, _sk = Signature.generate_key () in
-  let dest = Contract.Implicit pkh in
+  let receiver = Contract.Implicit pkh in
   let amount = random_amount () in
-  test_transferring_to_sink
+  test_transferring_to_receiver
     ctxt
     (`Delegate_balance pkh)
     amount
-    [(Contract dest, Credited amount, Block_application)]
+    [(Contract receiver, Credited amount, Block_application)]
 
 let test_transferring_to_frozen_deposits ctxt =
   let pkh, _pk, _sk = Signature.generate_key () in
   let amount = random_amount () in
-  test_transferring_to_sink
+  test_transferring_to_receiver
     ctxt
     (`Frozen_deposits pkh)
     amount
@@ -223,7 +229,7 @@ let test_transferring_to_frozen_deposits ctxt =
 
 let test_transferring_to_collected_fees ctxt =
   let amount = random_amount () in
-  test_transferring_to_sink
+  test_transferring_to_receiver
     ctxt
     `Block_fees
     amount
@@ -287,13 +293,13 @@ let test_transferring_to_frozen_bonds ctxt =
   let sc_rollup = sc_rollup () in
   let bond_id = Bond_id.Sc_rollup_bond_id sc_rollup in
   let amount = random_amount () in
-  test_transferring_to_sink
+  test_transferring_to_receiver
     ctxt
     (`Frozen_bonds (contract, bond_id))
     amount
     [(Frozen_bonds (contract, bond_id), Credited amount, Block_application)]
 
-let test_transferring_to_sink () =
+let test_transferring_to_receiver () =
   Random.init 0 ;
   create_context () >>=? fun (ctxt, _) ->
   test_transferring_to_contract ctxt >>=? fun () ->
@@ -352,7 +358,7 @@ let test_transferring_from_container ctxt giver amount expected_bupds =
   wrap (Token.transfer ctxt giver `Burned Tez.zero) >>=? fun (ctxt', bupds) ->
   Assert.equal_bool ~loc:__LOC__ (ctxt == ctxt' && bupds = []) true
   >>=? fun () ->
-  (* Force the allocation of [dest] if need be. *)
+  (* Force the allocation of [giver] if need be. *)
   force_allocation_if_need_be ctxt giver >>=? fun ctxt ->
   (* Test transferring everything. *)
   wrap (Token.transfer ctxt `Minted giver amount) >>=? fun (ctxt, _) ->
@@ -557,7 +563,7 @@ let build_test_cases () =
       (`Frozen_bonds (baker2ic, bond_id2), random_amount ());
     ]
   in
-  let dest_list =
+  let receiver_list =
     [
       `Collected_commitments Blinded_public_key_hash.zero;
       `Delegate_balance baker1;
@@ -572,54 +578,54 @@ let build_test_cases () =
       `Burned;
     ]
   in
-  return (ctxt, List.product giver_list dest_list)
+  return (ctxt, List.product giver_list receiver_list)
 
 let check_giver_balances ctxt ctxt' giver amount =
   match cast_to_container_type giver with
   | None -> return_unit
   | Some giver -> check_giver_balances ctxt ctxt' giver amount
 
-let check_sink_balances ctxt ctxt' dest amount =
-  match cast_to_container_type dest with
+let check_receiver_balances ctxt ctxt' receiver amount =
+  match cast_to_container_type receiver with
   | None -> return_unit
-  | Some dest -> check_sink_balances ctxt ctxt' dest amount
+  | Some receiver -> check_receiver_balances ctxt ctxt' receiver amount
 
-let rec check_balances ctxt ctxt' giver dest amount =
+let rec check_balances ctxt ctxt' giver receiver amount =
   let open Lwt_result_wrap_syntax in
-  match (cast_to_container_type giver, cast_to_container_type dest) with
+  match (cast_to_container_type giver, cast_to_container_type receiver) with
   | None, None -> return_unit
   | ( Some (`Delegate_balance d),
       Some (`Contract (Contract.Implicit c) as contract) )
   | ( Some (`Contract (Contract.Implicit c) as contract),
       Some (`Delegate_balance d) )
     when d = c ->
-      (* giver and dest are in fact referring to the same contract *)
+      (* giver and receiver are in fact referring to the same contract *)
       check_balances ctxt ctxt' contract contract amount
-  | Some giver, Some dest when giver = dest ->
-      (* giver and dest are the same contract *)
-      wrap (Token.balance ctxt dest) >>=? fun (_, bal_dest) ->
-      wrap (Token.balance ctxt' dest) >>=? fun (_, bal_dest') ->
-      Assert.equal_tez ~loc:__LOC__ bal_dest bal_dest'
+  | Some giver, Some receiver when giver = receiver ->
+      (* giver and receiver are the same contract *)
+      wrap (Token.balance ctxt receiver) >>=? fun (_, bal_receiver) ->
+      wrap (Token.balance ctxt' receiver) >>=? fun (_, bal_receiver') ->
+      Assert.equal_tez ~loc:__LOC__ bal_receiver bal_receiver'
   | Some giver, None -> check_giver_balances ctxt ctxt' giver amount
-  | None, Some dest -> check_sink_balances ctxt ctxt' dest amount
-  | Some giver, Some dest ->
+  | None, Some receiver -> check_receiver_balances ctxt ctxt' receiver amount
+  | Some giver, Some receiver ->
       check_giver_balances ctxt ctxt' giver amount >>=? fun () ->
-      check_sink_balances ctxt ctxt' dest amount
+      check_receiver_balances ctxt ctxt' receiver amount
 
-let test_all_combinations_of_givers_and_sinks () =
+let test_all_combinations_of_givers_and_receivers () =
   let open Lwt_result_wrap_syntax in
   Random.init 0 ;
   build_test_cases () >>=? fun (ctxt, cases) ->
   List.iter_es
-    (fun ((giver, amount), dest) ->
+    (fun ((giver, amount), receiver) ->
       (match cast_to_container_type giver with
       | None -> return ctxt
       | Some giver ->
           wrap (Token.transfer ctxt `Minted giver amount) >>=? fun (ctxt, _) ->
           return ctxt)
       >>=? fun ctxt ->
-      wrap (Token.transfer ctxt giver dest amount) >>=? fun (ctxt', _) ->
-      check_balances ctxt ctxt' giver dest amount)
+      wrap (Token.transfer ctxt giver receiver amount) >>=? fun (ctxt', _) ->
+      check_balances ctxt ctxt' giver receiver amount)
     cases
 
 (** [coalesce (account, Credited am1, origin) (account, Credited am2, origin)
@@ -662,9 +668,9 @@ let check_balances_are_consistent ctxt1 ctxt2 elt =
       return_unit
 
 (** Test that [transfer_n] is equivalent to n debits followed by n credits. *)
-let test_transfer_n ctxt giver dest =
+let test_transfer_n ctxt giver receiver =
   (* Run transfer_n. *)
-  Token.transfer_n ctxt giver dest >>=? fun (ctxt1, bal_updates1) ->
+  Token.transfer_n ctxt giver receiver >>=? fun (ctxt1, bal_updates1) ->
   (* Debit all givers. *)
   List.fold_left_es
     (fun (ctxt, bal_updates) (giver, am) ->
@@ -679,10 +685,10 @@ let test_transfer_n ctxt giver dest =
       (fun b -> match b with Receipt.Burned, _, _ -> false | _ -> true)
       debit_logs
   in
-  (* Credit the sink for each giver. *)
+  (* Credit the receiver for each giver. *)
   List.fold_left_es
     (fun (ctxt, bal_updates) (_, am) ->
-      Token.transfer ctxt `Minted dest am >>=? fun (ctxt, credit_logs) ->
+      Token.transfer ctxt `Minted receiver am >>=? fun (ctxt, credit_logs) ->
       return (ctxt, bal_updates @ credit_logs))
     (ctxt, [])
     giver
@@ -702,15 +708,15 @@ let test_transfer_n ctxt giver dest =
   assert (bal_updates1 = debit_logs @ credit_logs) ;
   (* Check balances are the same in ctxt1 and ctxt2. *)
   List.(iter_es (check_balances_are_consistent ctxt1 ctxt2) (map fst giver))
-  >>=? fun () -> check_balances_are_consistent ctxt1 ctxt2 dest
+  >>=? fun () -> check_balances_are_consistent ctxt1 ctxt2 receiver
 
 let test_transfer_n_with_no_giver () =
   let open Lwt_result_wrap_syntax in
   Random.init 0 ;
   create_context () >>=? fun (ctxt, pkh) ->
   wrap (test_transfer_n ctxt [] `Block_fees) >>=? fun () ->
-  let dest = `Delegate_balance pkh in
-  wrap (test_transfer_n ctxt [] dest)
+  let receiver = `Delegate_balance pkh in
+  wrap (test_transfer_n ctxt [] receiver)
 
 let test_transfer_n_with_several_givers () =
   let open Lwt_result_wrap_syntax in
@@ -750,21 +756,24 @@ let tests =
       tztest "transfer - balances" `Quick test_simple_balances;
       tztest "transfer - balance updates" `Quick test_simple_balance_updates;
       tztest "transfer - test allocated" `Quick test_allocated;
-      tztest "transfer - test transfer to sink" `Quick test_transferring_to_sink;
+      tztest
+        "transfer - test transfer to receiver"
+        `Quick
+        test_transferring_to_receiver;
       tztest
         "transfer - test transfer from giver"
         `Quick
         test_transferring_from_giver;
       tztest
-        "transfer - test all (givers x sinks)"
+        "transfer - test all (givers x receivers)"
         `Quick
-        test_all_combinations_of_givers_and_sinks;
+        test_all_combinations_of_givers_and_receivers;
       tztest
-        "transfer - test from no giver to a destination"
+        "transfer - test from no giver to a receiver"
         `Quick
         test_transfer_n_with_no_giver;
       tztest
-        "transfer - test from n givers to a destination"
+        "transfer - test from n givers to a receiver"
         `Quick
         test_transfer_n_with_several_givers;
     ]
diff --git a/src/proto_alpha/lib_protocol/token.ml b/src/proto_alpha/lib_protocol/token.ml
index 40ace57c7f11..d1c4d97667cb 100644
--- a/src/proto_alpha/lib_protocol/token.ml
+++ b/src/proto_alpha/lib_protocol/token.ml
@@ -55,7 +55,7 @@ type infinite_sink =
   | `Sc_rollup_refutation_punishments
   | `Burned ]
 
-type sink = [infinite_sink | container]
+type receiver = [infinite_sink | container]
 
 let allocated ctxt stored =
   match stored with
@@ -104,9 +104,9 @@ let balance ctxt stored =
       >|=? fun (ctxt, balance_opt) ->
       (ctxt, Option.value ~default:Tez_repr.zero balance_opt)
 
-let credit ctxt dest amount origin =
+let credit ctxt receiver amount origin =
   let open Receipt_repr in
-  (match dest with
+  (match receiver with
   | #infinite_sink as infinite_sink ->
       let sink =
         match infinite_sink with
@@ -120,9 +120,9 @@ let credit ctxt dest amount origin =
       return (ctxt, sink)
   | #container as container -> (
       match container with
-      | `Contract dest ->
-          Contract_storage.credit_only_call_from_token ctxt dest amount
-          >|=? fun ctxt -> (ctxt, Contract dest)
+      | `Contract receiver ->
+          Contract_storage.credit_only_call_from_token ctxt receiver amount
+          >|=? fun ctxt -> (ctxt, Contract receiver)
       | `Collected_commitments bpkh ->
           Commitment_storage.increase_commitment_only_call_from_token
             ctxt
@@ -136,8 +136,8 @@ let credit ctxt dest amount origin =
             contract
             amount
           >|=? fun ctxt -> (ctxt, Contract contract)
-      | `Frozen_deposits delegate as dest ->
-          allocated ctxt dest >>=? fun (ctxt, allocated) ->
+      | `Frozen_deposits delegate as receiver ->
+          allocated ctxt receiver >>=? fun (ctxt, allocated) ->
           (if not allocated then Frozen_deposits_storage.init ctxt delegate
           else return ctxt)
           >>=? fun ctxt ->
@@ -214,7 +214,7 @@ let spend ctxt giver amount origin =
           >>=? fun ctxt -> return (ctxt, Frozen_bonds (contract, bond_id))))
   >|=? fun (ctxt, balance) -> (ctxt, (balance, Debited amount, origin))
 
-let transfer_n ?(origin = Receipt_repr.Block_application) ctxt givers dest =
+let transfer_n ?(origin = Receipt_repr.Block_application) ctxt givers receiver =
   let givers = List.filter (fun (_, am) -> Tez_repr.(am <> zero)) givers in
   match givers with
   | [] ->
@@ -230,7 +230,7 @@ let transfer_n ?(origin = Receipt_repr.Block_application) ctxt givers dest =
         (ctxt, Tez_repr.zero, [])
         givers
       >>=? fun (ctxt, amount, debit_logs) ->
-      credit ctxt dest amount origin >>=? fun (ctxt, credit_log) ->
+      credit ctxt receiver amount origin >>=? fun (ctxt, credit_log) ->
       (* Deallocate implicit contracts with no stake. This must be done after
          spending and crediting. If done in between then a transfer of all the
          balance from (`Contract c) to (`Frozen_bonds (c,_)) would leave the
@@ -249,5 +249,6 @@ let transfer_n ?(origin = Receipt_repr.Block_application) ctxt givers dest =
       let balance_updates = List.rev (credit_log :: debit_logs) in
       (ctxt, balance_updates)
 
-let transfer ?(origin = Receipt_repr.Block_application) ctxt giver dest amount =
-  transfer_n ~origin ctxt [(giver, amount)] dest
+let transfer ?(origin = Receipt_repr.Block_application) ctxt giver receiver
+    amount =
+  transfer_n ~origin ctxt [(giver, amount)] receiver
diff --git a/src/proto_alpha/lib_protocol/token.mli b/src/proto_alpha/lib_protocol/token.mli
index c6a213d3d5bb..a2a639e7d876 100644
--- a/src/proto_alpha/lib_protocol/token.mli
+++ b/src/proto_alpha/lib_protocol/token.mli
@@ -25,13 +25,13 @@
 
 (** The aim of this module is to manage operations involving tokens such as
     minting, transferring, and burning. Every constructor of the types [giver],
-    [container], or [sink] represents a kind of account that holds a given (or
+    [container], or [receiver] represents a kind of account that holds a given (or
     possibly infinite) amount of tokens.
 
-    Tokens can be transferred from a [giver] to a [sink]. To uniformly handle
-    all cases, special constructors of givers and sinks may be used. For
+    Tokens can be transferred from a [giver] to a [receiver]. To uniformly handle
+    all cases, special constructors of givers and receivers may be used. For
     example, the giver [`Minted] is used to express a transfer of minted tokens
-    to a destination, and the sink [`Burned] is used to express the action of
+    to a receiver, and the receiver [`Burned] is used to express the action of
     burning a given amount of tokens taken from a giver. Thanks to uniformity,
     it is easier to track transfers of tokens throughout the protocol by running
     [grep -R "Token.transfer" src/proto_alpha].
@@ -112,9 +112,9 @@ type infinite_sink =
   | `Sc_rollup_refutation_punishments  (** Smart rollups refutation slashing *)
   | `Burned  (** Generic sink mainly for test purpose *) ]
 
-(** [sink] is the type of token receivers. Token receivers that are not
+(** [receiver] is the type of token receivers. Token receivers that are not
     containers are considered to have infinite capacity. *)
-type sink = [infinite_sink | container]
+type receiver = [infinite_sink | container]
 
 (** [allocated ctxt container] returns a new context because of possible access
     to carbonated data, and a boolean that is [true] when
@@ -134,23 +134,23 @@ val allocated :
 val balance :
   Raw_context.t -> container -> (Raw_context.t * Tez_repr.t) tzresult Lwt.t
 
-(** [transfer_n ?origin ctxt givers dest] transfers [amount] Tez from [giver] to
-    [dest] for each [(giver, amount)] pair in [givers], and returns a new
+(** [transfer_n ?origin ctxt givers receiver] transfers [amount] Tez from [giver] to
+    [receiver] for each [(giver, amount)] pair in [givers], and returns a new
     context, and the list of corresponding balance updates. The function behaves
-    as though [transfer giver dest amount] was invoked for each pair
+    as though [transfer giver receiver amount] was invoked for each pair
     [(giver, amount)] in [givers], however a single balance update is generated
-    for the total amount transferred to [dest].
+    for the total amount transferred to [receiver].
     When [givers] is an empty list, the function does nothing to the context,
     and returns an empty list of balance updates. *)
 val transfer_n :
   ?origin:Receipt_repr.update_origin ->
   Raw_context.t ->
   ([< giver] * Tez_repr.t) list ->
-  [< sink] ->
+  [< receiver] ->
   (Raw_context.t * Receipt_repr.balance_updates) tzresult Lwt.t
 
-(** [transfer ?origin ctxt giver dest amount] transfers [amount] Tez from giver
-    [giver] to destination [dest], and returns a new context, and the list of
+(** [transfer ?origin ctxt giver receiver amount] transfers [amount] Tez from giver
+    [giver] to receiver [receiver], and returns a new context, and the list of
     corresponding balance updates tagged with [origin]. By default, [~origin] is
     set to [Receipt_repr.Block_application].
     Returns {!Storage_Error Missing_key} if [giver] refers to a contract that is
@@ -163,17 +163,17 @@ val transfer_n :
     implicit contract that delegates to a different contract, and whose balance
     is equal to [amount].
     Returns a [Non_existing_contract] error if
-    [dest] refers to an originated contract that is not allocated.
+    [receiver] refers to an originated contract that is not allocated.
     Returns a [Non_existing_contract] error if [amount <> Tez_repr.zero], and
-    [dest] refers to an originated contract that is not allocated.
-    Returns a [Addition_overflow] error if [dest] refers to a sink whose balance
+    [receiver] refers to an originated contract that is not allocated.
+    Returns a [Addition_overflow] error if [receiver] refers to a receiver whose balance
     is greater than [Int64.max - amount].
-    Returns a [Wrong_level] error if [src] or [dest] refer to a level that is
+    Returns a [Wrong_level] error if [src] or [receiver] refer to a level that is
     not the current level. *)
 val transfer :
   ?origin:Receipt_repr.update_origin ->
   Raw_context.t ->
   [< giver] ->
-  [< sink] ->
+  [< receiver] ->
   Tez_repr.t ->
   (Raw_context.t * Receipt_repr.balance_updates) tzresult Lwt.t
-- 
GitLab


From 51c56530c0d18ec243f680e1f739a9b6de15bf8b Mon Sep 17 00:00:00 2001
From: Boubacar Sall <boubacar@nomadic-labs.com>
Date: Wed, 8 Feb 2023 20:56:39 +0000
Subject: [PATCH 4/4] Proto/Token/Doc: add some forgotten arguments

---
 src/proto_alpha/lib_protocol/token.mli | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/proto_alpha/lib_protocol/token.mli b/src/proto_alpha/lib_protocol/token.mli
index a2a639e7d876..3b75692e1cf7 100644
--- a/src/proto_alpha/lib_protocol/token.mli
+++ b/src/proto_alpha/lib_protocol/token.mli
@@ -137,7 +137,7 @@ val balance :
 (** [transfer_n ?origin ctxt givers receiver] transfers [amount] Tez from [giver] to
     [receiver] for each [(giver, amount)] pair in [givers], and returns a new
     context, and the list of corresponding balance updates. The function behaves
-    as though [transfer giver receiver amount] was invoked for each pair
+    as though [transfer ?origin ctxt giver receiver amount] was invoked for each pair
     [(giver, amount)] in [givers], however a single balance update is generated
     for the total amount transferred to [receiver].
     When [givers] is an empty list, the function does nothing to the context,
-- 
GitLab