-
Notifications
You must be signed in to change notification settings - Fork 5
/
JBMultiTerminal.sol
1918 lines (1703 loc) · 85.3 KB
/
JBMultiTerminal.sol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
// SPDX-License-Identifier: MIT
pragma solidity 0.8.23;
import {JBPermissionIds} from "@bananapus/permission-ids/src/JBPermissionIds.sol";
import {ERC2771Context} from "@openzeppelin/contracts/metatx/ERC2771Context.sol";
import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {IERC20Metadata} from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
import {Address} from "@openzeppelin/contracts/utils/Address.sol";
import {Context} from "@openzeppelin/contracts/utils/Context.sol";
import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
import {mulDiv} from "@prb/math/src/Common.sol";
import {IAllowanceTransfer} from "@uniswap/permit2/src/interfaces/IAllowanceTransfer.sol";
import {IPermit2} from "@uniswap/permit2/src/interfaces/IPermit2.sol";
import {JBPermissioned} from "./abstract/JBPermissioned.sol";
import {IJBController} from "./interfaces/IJBController.sol";
import {IJBDirectory} from "./interfaces/IJBDirectory.sol";
import {IJBFeelessAddresses} from "./interfaces/IJBFeelessAddresses.sol";
import {IJBFeeTerminal} from "./interfaces/IJBFeeTerminal.sol";
import {IJBMultiTerminal} from "./interfaces/IJBMultiTerminal.sol";
import {IJBPayoutTerminal} from "./interfaces/IJBPayoutTerminal.sol";
import {IJBPermissioned} from "./interfaces/IJBPermissioned.sol";
import {IJBPermissions} from "./interfaces/IJBPermissions.sol";
import {IJBPermitTerminal} from "./interfaces/IJBPermitTerminal.sol";
import {IJBProjects} from "./interfaces/IJBProjects.sol";
import {IJBRedeemTerminal} from "./interfaces/IJBRedeemTerminal.sol";
import {IJBRulesets} from "./interfaces/IJBRulesets.sol";
import {IJBSplitHook} from "./interfaces/IJBSplitHook.sol";
import {IJBSplits} from "./interfaces/IJBSplits.sol";
import {IJBTerminal} from "./interfaces/IJBTerminal.sol";
import {IJBTerminalStore} from "./interfaces/IJBTerminalStore.sol";
import {JBConstants} from "./libraries/JBConstants.sol";
import {JBFees} from "./libraries/JBFees.sol";
import {JBMetadataResolver} from "./libraries/JBMetadataResolver.sol";
import {JBRulesetMetadataResolver} from "./libraries/JBRulesetMetadataResolver.sol";
import {JBAccountingContext} from "./structs/JBAccountingContext.sol";
import {JBAfterPayRecordedContext} from "./structs/JBAfterPayRecordedContext.sol";
import {JBAfterRedeemRecordedContext} from "./structs/JBAfterRedeemRecordedContext.sol";
import {JBFee} from "./structs/JBFee.sol";
import {JBPayHookSpecification} from "./structs/JBPayHookSpecification.sol";
import {JBRedeemHookSpecification} from "./structs/JBRedeemHookSpecification.sol";
import {JBRuleset} from "./structs/JBRuleset.sol";
import {JBSingleAllowance} from "./structs/JBSingleAllowance.sol";
import {JBSplit} from "./structs/JBSplit.sol";
import {JBSplitHookContext} from "./structs/JBSplitHookContext.sol";
import {JBTokenAmount} from "./structs/JBTokenAmount.sol";
/// @notice `JBMultiTerminal` manages native/ERC-20 payments, redemptions, and surplus allowance usage for any number of
/// projects. Terminals are the entry point for operations involving inflows and outflows of funds.
contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
// A library that parses the packed ruleset metadata into a friendlier format.
using JBRulesetMetadataResolver for JBRuleset;
// A library that adds default safety checks to ERC20 functionality.
using SafeERC20 for IERC20;
//*********************************************************************//
// --------------------------- custom errors ------------------------- //
//*********************************************************************//
error JBMultiTerminal_AccountingContextAlreadySet(address token);
error JBMultiTerminal_AddingAccountingContextNotAllowed();
error JBMultiTerminal_FeeTerminalNotFound();
error JBMultiTerminal_NoMsgValueAllowed(uint256 value);
error JBMultiTerminal_OverflowAlert(uint256 value, uint256 limit);
error JBMultiTerminal_PermitAllowanceNotEnough(uint256 amount, uint256 allowance);
error JBMultiTerminal_RecipientProjectTerminalNotFound(uint256 projectId, address token);
error JBMultiTerminal_SplitHookInvalid(IJBSplitHook hook);
error JBMultiTerminal_TerminalTokensIncompatible();
error JBMultiTerminal_TokenNotAccepted(address token);
error JBMultiTerminal_UnderMinReturnedTokens(uint256 count, uint256 min);
error JBMultiTerminal_UnderMinTokensPaidOut(uint256 amount, uint256 min);
error JBMultiTerminal_UnderMinTokensReclaimed(uint256 amount, uint256 min);
error JBMultiTerminal_ZeroAccountingContextDecimals();
error JBMultiTerminal_ZeroAccountingContextCurrency();
//*********************************************************************//
// ------------------------- public constants ------------------------ //
//*********************************************************************//
/// @notice This terminal's fee (as a fraction out of `JBConstants.MAX_FEE`).
/// @dev Fees are charged on payouts to addresses and surplus allowance usage, as well as redemptions while the
/// redemption rate is less than 100%.
uint256 public constant override FEE = 25; // 2.5%
//*********************************************************************//
// ------------------------ internal constants ----------------------- //
//*********************************************************************//
/// @notice Project ID #1 receives fees. It should be the first project launched during the deployment process.
uint256 internal constant _FEE_BENEFICIARY_PROJECT_ID = 1;
/// @notice The number of seconds fees can be held for.
uint256 internal constant _FEE_HOLDING_SECONDS = 2_419_200; // 28 days
//*********************************************************************//
// ---------------- public immutable stored properties --------------- //
//*********************************************************************//
/// @notice The directory of terminals and controllers for PROJECTS.
IJBDirectory public immutable override DIRECTORY;
/// @notice The contract that stores addresses that shouldn't incur fees when being paid towards or from.
IJBFeelessAddresses public immutable override FEELESS_ADDRESSES;
/// @notice The permit2 utility.
IPermit2 public immutable override PERMIT2;
/// @notice Mints ERC-721s that represent project ownership and transfers.
IJBProjects public immutable override PROJECTS;
/// @notice The contract storing and managing project rulesets.
IJBRulesets public immutable override RULESETS;
/// @notice The contract that stores splits for each project.
IJBSplits public immutable override SPLITS;
/// @notice The contract that stores and manages the terminal's data.
IJBTerminalStore public immutable override STORE;
//*********************************************************************//
// --------------------- internal stored properties ------------------ //
//*********************************************************************//
/// @notice Context describing how a token is accounted for by a project.
/// @custom:param projectId The ID of the project that the token accounting context applies to.
/// @custom:param token The address of the token being accounted for.
mapping(uint256 projectId => mapping(address token => JBAccountingContext)) internal _accountingContextForTokenOf;
/// @notice A list of tokens accepted by each project.
/// @custom:param projectId The ID of the project to get a list of accepted tokens for.
mapping(uint256 projectId => JBAccountingContext[]) internal _accountingContextsOf;
/// @notice Fees that are being held for each project.
/// @dev Projects can temporarily hold fees and unlock them later by adding funds to the project's balance.
/// @dev Held fees can be processed at any time by this terminal's owner.
/// @custom:param projectId The ID of the project that is holding fees.
/// @custom:param token The token that the fees are held in.
mapping(uint256 projectId => mapping(address token => JBFee[])) internal _heldFeesOf;
//*********************************************************************//
// -------------------------- constructor ---------------------------- //
//*********************************************************************//
/// @param feelessAddresses A contract that stores addresses that shouldn't incur fees when being paid towards or
/// from.
/// @param permissions A contract storing permissions.
/// @param projects A contract which mints ERC-721s that represent project ownership and transfers.
/// @param splits A contract that stores splits for each project.
/// @param store A contract that stores the terminal's data.
/// @param permit2 A permit2 utility.
/// @param trustedForwarder A trusted forwarder of transactions to this contract.
constructor(
IJBFeelessAddresses feelessAddresses,
IJBPermissions permissions,
IJBProjects projects,
IJBSplits splits,
IJBTerminalStore store,
IPermit2 permit2,
address trustedForwarder
)
JBPermissioned(permissions)
ERC2771Context(trustedForwarder)
{
DIRECTORY = store.DIRECTORY();
FEELESS_ADDRESSES = feelessAddresses;
PROJECTS = projects;
RULESETS = store.RULESETS();
SPLITS = splits;
STORE = store;
PERMIT2 = permit2;
}
//*********************************************************************//
// ------------------------- external views -------------------------- //
//*********************************************************************//
/// @notice A project's accounting context for a token.
/// @dev See the `JBAccountingContext` struct for more information.
/// @param projectId The ID of the project to get token accounting context of.
/// @param token The token to check the accounting context of.
/// @return The token's accounting context for the token.
function accountingContextForTokenOf(
uint256 projectId,
address token
)
external
view
override
returns (JBAccountingContext memory)
{
return _accountingContextForTokenOf[projectId][token];
}
/// @notice The tokens accepted by a project.
/// @param projectId The ID of the project to get the accepted tokens of.
/// @return tokenContexts The accounting contexts of the accepted tokens.
function accountingContextsOf(uint256 projectId) external view override returns (JBAccountingContext[] memory) {
return _accountingContextsOf[projectId];
}
/// @notice Gets the total current surplus amount in this terminal for a project, in terms of a given currency.
/// @dev This total surplus only includes tokens that the project accepts (as returned by
/// `accountingContextsOf(...)`).
/// @param projectId The ID of the project to get the current total surplus of.
/// @param decimals The number of decimals to include in the fixed point returned value.
/// @param currency The currency to express the returned value in terms of.
/// @return The current surplus amount the project has in this terminal, in terms of `currency` and with the
/// specified number of decimals.
function currentSurplusOf(
uint256 projectId,
uint256 decimals,
uint256 currency
)
external
view
override
returns (uint256)
{
return STORE.currentSurplusOf(address(this), projectId, _accountingContextsOf[projectId], decimals, currency);
}
/// @notice Fees that are being held for a project.
/// @dev Projects can temporarily hold fees and unlock them later by adding funds to the project's balance.
/// @dev Held fees can be processed at any time by this terminal's owner.
/// @param projectId The ID of the project that is holding fees.
/// @param token The token that the fees are held in.
function heldFeesOf(uint256 projectId, address token) external view override returns (JBFee[] memory) {
return _heldFeesOf[projectId][token];
}
//*********************************************************************//
// -------------------------- public views --------------------------- //
//*********************************************************************//
/// @notice Indicates whether this contract adheres to the specified interface.
/// @dev See {IERC165-supportsInterface}.
/// @param interfaceId The ID of the interface to check for adherence to.
/// @return A flag indicating if the provided interface ID is supported.
function supportsInterface(bytes4 interfaceId) public pure override returns (bool) {
return interfaceId == type(IJBMultiTerminal).interfaceId || interfaceId == type(IJBPermissioned).interfaceId
|| interfaceId == type(IJBTerminal).interfaceId || interfaceId == type(IJBRedeemTerminal).interfaceId
|| interfaceId == type(IJBPayoutTerminal).interfaceId || interfaceId == type(IJBPermitTerminal).interfaceId
|| interfaceId == type(IJBMultiTerminal).interfaceId || interfaceId == type(IJBFeeTerminal).interfaceId
|| interfaceId == type(IERC165).interfaceId;
}
//*********************************************************************//
// -------------------------- internal views ------------------------- //
//*********************************************************************//
/// @notice Checks this terminal's balance of a specific token.
/// @param token The address of the token to get this terminal's balance of.
/// @return This terminal's balance.
function _balanceOf(address token) internal view returns (uint256) {
// If the `token` is native, get the native token balance.
return token == JBConstants.NATIVE_TOKEN ? address(this).balance : IERC20(token).balanceOf(address(this));
}
/// @dev `ERC-2771` specifies the context as being a single address (20 bytes).
function _contextSuffixLength() internal view override(ERC2771Context, Context) returns (uint256) {
return super._contextSuffixLength();
}
/// @notice Returns the current controller of a project.
/// @param projectId The ID of the project to get the controller of.
/// @return controller The project's controller.
function _controllerOf(uint256 projectId) internal view returns (IJBController) {
return IJBController(address(DIRECTORY.controllerOf(projectId)));
}
/// @notice Returns a flag indicating if interacting with an address should not incur fees.
/// @param addr The address to check.
/// @return A flag indicating if the address should not incur fees.
function _isFeeless(address addr) internal view returns (bool) {
return FEELESS_ADDRESSES.isFeeless(addr);
}
/// @notice The calldata. Preferred to use over `msg.data`.
/// @return calldata The `msg.data` of this call.
function _msgData() internal view override(ERC2771Context, Context) returns (bytes calldata) {
return ERC2771Context._msgData();
}
/// @notice The message's sender. Preferred to use over `msg.sender`.
/// @return sender The address which sent this call.
function _msgSender() internal view override(ERC2771Context, Context) returns (address sender) {
return ERC2771Context._msgSender();
}
/// @notice Returns the value that should be forwarded with transactions, determined by whether or not a token is
/// the native token.
/// @param token The token being sent.
/// @param amount The amount of the token being sent
/// @return value The value to attach to the transaction being sent.
function _payValueOf(address token, uint256 amount) internal pure returns (uint256) {
return token == JBConstants.NATIVE_TOKEN ? amount : 0;
}
//*********************************************************************//
// ---------------------- external transactions ---------------------- //
//*********************************************************************//
/// @notice Adds accounting contexts for a project to this terminal so the project can begin accepting the tokens in
/// those contexts.
/// @dev Only a project's owner, an operator with the `ADD_ACCOUNTING_CONTEXTS` permission from that owner, or a
/// project's controller can add accounting contexts for the project.
/// @param projectId The ID of the project having to add accounting contexts for.
/// @param accountingContexts The accounting contexts to add.
function addAccountingContextsFor(
uint256 projectId,
JBAccountingContext[] calldata accountingContexts
)
external
override
{
// Enforce permissions.
_requirePermissionAllowingOverrideFrom({
account: PROJECTS.ownerOf(projectId),
projectId: projectId,
permissionId: JBPermissionIds.ADD_ACCOUNTING_CONTEXTS,
alsoGrantAccessIf: _msgSender() == address(_controllerOf(projectId))
});
// Get a reference to the project's current ruleset.
JBRuleset memory ruleset = RULESETS.currentOf(projectId);
// Make sure that if there's a ruleset, it allows adding accounting contexts.
if (ruleset.id != 0 && !ruleset.allowAddAccountingContext()) {
revert JBMultiTerminal_AddingAccountingContextNotAllowed();
}
// Start accepting each token.
for (uint256 i; i < accountingContexts.length; i++) {
// Set the accounting context being iterated on.
JBAccountingContext memory accountingContext = accountingContexts[i];
// Get a storage reference to the currency accounting context for the token.
JBAccountingContext storage storedAccountingContext =
_accountingContextForTokenOf[projectId][accountingContext.token];
// Make sure the token accounting context isn't already set.
if (storedAccountingContext.token != address(0)) {
revert JBMultiTerminal_AccountingContextAlreadySet(storedAccountingContext.token);
}
// Keep track of a flag indiciating if we know the provided decimals are incorrect.
bool knownInvalidDecimals;
// Check if the token is the native token and has the correct decimals
if (accountingContext.token == JBConstants.NATIVE_TOKEN && accountingContext.decimals != 18) {
knownInvalidDecimals = true;
} else if (accountingContext.token != JBConstants.NATIVE_TOKEN) {
// slither-disable-next-line calls-loop
try IERC165(accountingContext.token).supportsInterface(type(IERC20Metadata).interfaceId) returns (
bool doesSupport
) {
// slither-disable-next-line calls-loop
if (doesSupport && accountingContext.decimals != IERC20Metadata(accountingContext.token).decimals())
{
knownInvalidDecimals = true;
}
} catch {}
}
// Make sure the decimals are correct.
if (knownInvalidDecimals) {
revert JBMultiTerminal_ZeroAccountingContextDecimals();
}
// Make sure the currency is non-zero.
if (accountingContext.currency == 0) revert JBMultiTerminal_ZeroAccountingContextCurrency();
// Define the context from the config.
storedAccountingContext.token = accountingContext.token;
storedAccountingContext.decimals = accountingContext.decimals;
storedAccountingContext.currency = accountingContext.currency;
// Add the token to the list of accepted tokens of the project.
_accountingContextsOf[projectId].push(storedAccountingContext);
emit SetAccountingContext({projectId: projectId, context: storedAccountingContext, caller: _msgSender()});
}
}
/// @notice Adds funds to a project's balance without minting tokens.
/// @dev Adding to balance can unlock held fees if `shouldUnlockHeldFees` is true.
/// @param projectId The ID of the project to add funds to the balance of.
/// @param amount The amount of tokens to add to the balance, as a fixed point number with the same number of
/// decimals as this terminal. If this is a native token terminal, this is ignored and `msg.value` is used instead.
/// @param token The token being added to the balance.
/// @param shouldReturnHeldFees A flag indicating if held fees should be returned based on the amount being added.
/// @param memo A memo to pass along to the emitted event.
/// @param metadata Extra data to pass along to the emitted event.
function addToBalanceOf(
uint256 projectId,
address token,
uint256 amount,
bool shouldReturnHeldFees,
string calldata memo,
bytes calldata metadata
)
external
payable
override
{
// Add to balance.
_addToBalanceOf({
projectId: projectId,
token: token,
amount: _acceptFundsFor(projectId, token, amount, metadata),
shouldReturnHeldFees: shouldReturnHeldFees,
memo: memo,
metadata: metadata
});
}
/// @notice Executes a payout to a split.
/// @dev Only accepts calls from this terminal itself.
/// @param split The split to pay.
/// @param projectId The ID of the project the split belongs to.
/// @param token The address of the token being paid to the split.
/// @param amount The total amount being paid to the split, as a fixed point number with the same number of
/// decimals as this terminal.
/// @return netPayoutAmount The amount sent to the split after subtracting fees.
function executePayout(
JBSplit calldata split,
uint256 projectId,
address token,
uint256 amount,
address originalMessageSender
)
external
returns (uint256 netPayoutAmount)
{
// NOTICE: May only be called by this terminal itself.
require(msg.sender == address(this));
// By default, the net payout amount is the full amount. This will be adjusted if fees are taken.
netPayoutAmount = amount;
// If there's a split hook set, transfer to its `process` function.
if (split.hook != IJBSplitHook(address(0))) {
// Make sure that the address supports the split hook interface.
if (!split.hook.supportsInterface(type(IJBSplitHook).interfaceId)) {
revert JBMultiTerminal_SplitHookInvalid(split.hook);
}
// This payout is eligible for a fee since the funds are leaving this contract and the split hook isn't a
// feeless address.
if (!_isFeeless(address(split.hook))) {
netPayoutAmount -= JBFees.feeAmountIn(amount, FEE);
}
// Create the context to send to the split hook.
JBSplitHookContext memory context = JBSplitHookContext({
token: token,
amount: netPayoutAmount,
decimals: _accountingContextForTokenOf[projectId][token].decimals,
projectId: projectId,
groupId: uint256(uint160(token)),
split: split
});
// Trigger any inherited pre-transfer logic.
_beforeTransferTo({to: address(split.hook), token: token, amount: netPayoutAmount});
// Get a reference to the amount being paid in `msg.value`.
uint256 payValue = _payValueOf(token, netPayoutAmount);
// If this terminal's token is the native token, send it in `msg.value`.
split.hook.processSplitWith{value: payValue}(context);
// Otherwise, if a project is specified, make a payment to it.
} else if (split.projectId != 0) {
// Get a reference to the terminal being used.
IJBTerminal terminal = DIRECTORY.primaryTerminalOf(split.projectId, token);
// The project must have a terminal to send funds to.
if (terminal == IJBTerminal(address(0))) {
revert JBMultiTerminal_RecipientProjectTerminalNotFound(split.projectId, token);
}
// This payout is eligible for a fee if the funds are leaving this contract and the receiving terminal isn't
// a feelss address.
if (terminal != this && !_isFeeless(address(terminal))) {
netPayoutAmount -= JBFees.feeAmountIn(amount, FEE);
}
// Trigger any inherited pre-transfer logic.
// slither-disable-next-line reentrancy-events
if (terminal != this) _beforeTransferTo({to: address(terminal), token: token, amount: netPayoutAmount});
// Send the `projectId` in the metadata as a referral.
bytes memory metadata = bytes(abi.encodePacked(projectId));
// Add to balance if preferred.
if (split.preferAddToBalance) {
_efficientAddToBalance({
terminal: terminal,
projectId: split.projectId,
token: token,
amount: netPayoutAmount,
metadata: metadata
});
} else {
// Keep a reference to the beneficiary of the payment.
address beneficiary = split.beneficiary != address(0) ? split.beneficiary : originalMessageSender;
_efficientPay({
terminal: terminal,
projectId: split.projectId,
token: token,
amount: netPayoutAmount,
beneficiary: beneficiary,
metadata: metadata
});
}
} else {
// If there's a beneficiary, send the funds directly to the beneficiary.
// If there isn't a beneficiary, send the funds to the `_msgSender()`.
address payable recipient =
split.beneficiary != address(0) ? split.beneficiary : payable(originalMessageSender);
// This payout is eligible for a fee since the funds are leaving this contract and the recipient isn't a
// feeless address.
if (!_isFeeless(recipient)) {
netPayoutAmount -= JBFees.feeAmountIn(amount, FEE);
}
// If there's a beneficiary, send the funds directly to the beneficiary. Otherwise send to the
// `_msgSender()`.
_transferFrom({from: address(this), to: recipient, token: token, amount: netPayoutAmount});
}
}
/// @notice Process a specified amount of fees for a project.
/// @dev Only accepts calls from this terminal itself.
/// @param projectId The ID of the project paying the fee.
/// @param token The token the fee is being paid in.
/// @param amount The fee amount, as a fixed point number with 18 decimals.
/// @param beneficiary The address to mint tokens to (from the project which receives fees), and pass along to the
/// ruleset's data hook and pay hook if applicable.
/// @param feeTerminal The terminal that'll receive the fees.
function executeProcessFee(
uint256 projectId,
address token,
uint256 amount,
address beneficiary,
IJBTerminal feeTerminal
)
external
{
// NOTICE: May only be called by this terminal itself.
require(msg.sender == address(this));
if (address(feeTerminal) == address(0)) {
revert JBMultiTerminal_FeeTerminalNotFound();
}
// Trigger any inherited pre-transfer logic if funds will be transferred.
if (address(feeTerminal) != address(this)) {
// slither-disable-next-line reentrancy-events
_beforeTransferTo({to: address(feeTerminal), token: token, amount: amount});
}
// Send the projectId in the metadata.
bytes memory metadata = bytes(abi.encodePacked(projectId));
_efficientPay({
terminal: feeTerminal,
projectId: _FEE_BENEFICIARY_PROJECT_ID,
token: token,
amount: amount,
beneficiary: beneficiary,
metadata: metadata
});
}
/// @notice Migrate a project's funds and operations to a new terminal that accepts the same token type.
/// @dev Only a project's owner or an operator with the `MIGRATE_TERMINAL` permission from that owner can migrate
/// the project's terminal.
/// @param projectId The ID of the project being migrated.
/// @param token The address of the token being migrated.
/// @param to The terminal contract being migrated to, which will receive the project's funds and operations.
/// @return balance The amount of funds that were migrated, as a fixed point number with the same amount of decimals
/// as this terminal.
function migrateBalanceOf(
uint256 projectId,
address token,
IJBTerminal to
)
external
override
returns (uint256 balance)
{
// Enforce permissions.
_requirePermissionFrom({
account: PROJECTS.ownerOf(projectId),
projectId: projectId,
permissionId: JBPermissionIds.MIGRATE_TERMINAL
});
// The terminal being migrated to must accept the same token as this terminal.
if (to.accountingContextForTokenOf(projectId, token).currency == 0) {
revert JBMultiTerminal_TerminalTokensIncompatible();
}
// Record the migration in the store.
// slither-disable-next-line reentrancy-events
balance = STORE.recordTerminalMigration(projectId, token);
emit MigrateTerminal({projectId: projectId, token: token, to: to, amount: balance, caller: _msgSender()});
// Transfer the balance if needed.
if (balance != 0) {
// Trigger any inherited pre-transfer logic.
// slither-disable-next-line reentrancy-events
_beforeTransferTo({to: address(to), token: token, amount: balance});
// If this terminal's token is the native token, send it in `msg.value`.
uint256 payValue = _payValueOf(token, balance);
// Withdraw the balance to transfer to the new terminal;
// slither-disable-next-line reentrancy-events
to.addToBalanceOf{value: payValue}({
projectId: projectId,
token: token,
amount: balance,
shouldReturnHeldFees: false,
memo: "",
metadata: bytes("")
});
}
// Process any held fees.
_processHeldFeesOf({projectId: projectId, token: token, forced: true});
}
/// @notice Pay a project with tokens.
/// @param projectId The ID of the project being paid.
/// @param amount The amount of terminal tokens being received, as a fixed point number with the same number of
/// decimals as this terminal. If this terminal's token is native, this is ignored and `msg.value` is used in its
/// place.
/// @param token The token being paid.
/// @param beneficiary The address to mint tokens to, and pass along to the ruleset's data hook and pay hook if
/// applicable.
/// @param minReturnedTokens The minimum number of project tokens expected in return for this payment, as a fixed
/// point number with the same number of decimals as this terminal. If the amount of tokens minted for the
/// beneficiary would be less than this amount, the payment is reverted.
/// @param memo A memo to pass along to the emitted event.
/// @param metadata Bytes to pass along to the emitted event, as well as the data hook and pay hook if applicable.
/// @return beneficiaryTokenCount The number of tokens minted to the beneficiary, as a fixed point number with 18
/// decimals.
function pay(
uint256 projectId,
address token,
uint256 amount,
address beneficiary,
uint256 minReturnedTokens,
string calldata memo,
bytes calldata metadata
)
external
payable
override
returns (uint256 beneficiaryTokenCount)
{
// Pay the project.
beneficiaryTokenCount = _pay({
projectId: projectId,
token: token,
amount: _acceptFundsFor(projectId, token, amount, metadata),
payer: _msgSender(),
beneficiary: beneficiary,
memo: memo,
metadata: metadata
});
// The token count for the beneficiary must be greater than or equal to the specified minimum.
if (beneficiaryTokenCount < minReturnedTokens) {
revert JBMultiTerminal_UnderMinReturnedTokens(beneficiaryTokenCount, minReturnedTokens);
}
}
/// @notice Process any fees that are being held for the project.
/// @param projectId The ID of the project to process held fees for.
/// @param token The token to process held fees for.
function processHeldFeesOf(uint256 projectId, address token) external override {
_processHeldFeesOf({projectId: projectId, token: token, forced: false});
}
/// @notice Holders can redeem a project's tokens to reclaim some of that project's surplus tokens, or to trigger
/// rules determined by the current ruleset's data hook and redeem hook.
/// @dev Only a token's holder or an operator with the `REDEEM_TOKENS` permission from that holder can redeem those
/// tokens.
/// @param holder The account whose tokens are being redeemed.
/// @param projectId The ID of the project the project tokens belong to.
/// @param tokenToReclaim The token being reclaimed.
/// @param redeemCount The number of project tokens to redeem, as a fixed point number with 18 decimals.
/// @param minTokensReclaimed The minimum number of terminal tokens expected in return, as a fixed point number with
/// the same number of decimals as this terminal. If the amount of tokens minted for the beneficiary would be less
/// than this amount, the redemption is reverted.
/// @param beneficiary The address to send the reclaimed terminal tokens to, and to pass along to the ruleset's
/// data hook and redeem hook if applicable.
/// @param metadata Bytes to send along to the emitted event, as well as the data hook and redeem hook if
/// applicable.
/// @return reclaimAmount The amount of terminal tokens that the project tokens were redeemed for, as a fixed point
/// number with 18 decimals.
function redeemTokensOf(
address holder,
uint256 projectId,
address tokenToReclaim,
uint256 redeemCount,
uint256 minTokensReclaimed,
address payable beneficiary,
bytes calldata metadata
)
external
override
returns (uint256 reclaimAmount)
{
// Enforce permissions.
_requirePermissionFrom({account: holder, projectId: projectId, permissionId: JBPermissionIds.REDEEM_TOKENS});
reclaimAmount = _redeemTokensOf(holder, projectId, tokenToReclaim, redeemCount, beneficiary, metadata);
// The amount being reclaimed must be at least as much as was expected.
if (reclaimAmount < minTokensReclaimed) {
revert JBMultiTerminal_UnderMinTokensReclaimed(reclaimAmount, minTokensReclaimed);
}
}
/// @notice Sends payouts to a project's current payout split group, according to its ruleset, up to its current
/// payout limit.
/// @dev If the percentages of the splits in the project's payout split group do not add up to 100%, the remainder
/// is sent to the project's owner.
/// @dev Anyone can send payouts on a project's behalf. Projects can include a wildcard split (a split with no
/// `hook`, `projectId`, or `beneficiary`) to send funds to the `_msgSender()` which calls this function. This can
/// be used to incentivize calling this function.
/// @dev payouts sent to addresses which aren't feeless incur the protocol fee.
/// @dev Payouts a projects don't incur fees if its terminal is feeless.
/// @param projectId The ID of the project having its payouts sent.
/// @param token The token being sent.
/// @param amount The total number of terminal tokens to send, as a fixed point number with same number of decimals
/// as this terminal.
/// @param currency The expected currency of the payouts being sent. Must match the currency of one of the
/// project's current ruleset's payout limits.
/// @param minTokensPaidOut The minimum number of terminal tokens that the `amount` should be worth (if expressed
/// in terms of this terminal's currency), as a fixed point number with the same number of decimals as this
/// terminal. If the amount of tokens paid out would be less than this amount, the send is reverted.
/// @return amountPaidOut The total amount paid out.
function sendPayoutsOf(
uint256 projectId,
address token,
uint256 amount,
uint256 currency,
uint256 minTokensPaidOut
)
external
override
returns (uint256 amountPaidOut)
{
amountPaidOut = _sendPayoutsOf(projectId, token, amount, currency);
// The amount being paid out must be at least as much as was expected.
if (amountPaidOut < minTokensPaidOut) {
revert JBMultiTerminal_UnderMinTokensPaidOut(amountPaidOut, minTokensPaidOut);
}
}
/// @notice Allows a project to pay out funds from its surplus up to the current surplus allowance.
/// @dev Only a project's owner or an operator with the `USE_ALLOWANCE` permission from that owner can use the
/// surplus allowance.
/// @dev Incurs the protocol fee unless the caller is a feeless address.
/// @param projectId The ID of the project to use the surplus allowance of.
/// @param token The token being paid out from the surplus.
/// @param amount The amount of terminal tokens to use from the project's current surplus allowance, as a fixed
/// point number with the same amount of decimals as this terminal.
/// @param currency The expected currency of the amount being paid out. Must match the currency of one of the
/// project's current ruleset's surplus allowances.
/// @param minTokensPaidOut The minimum number of terminal tokens that should be used from the surplus allowance
/// (including fees), as a fixed point number with 18 decimals. If the amount of surplus used would be less than
/// this amount, the transaction is reverted.
/// @param beneficiary The address to send the surplus funds to.
/// @param feeBeneficiary The address to send the tokens resulting from paying the fee.
/// @param memo A memo to pass along to the emitted event.
/// @return netAmountPaidOut The number of tokens that were sent to the beneficiary, as a fixed point number with
/// the same amount of decimals as the terminal.
function useAllowanceOf(
uint256 projectId,
address token,
uint256 amount,
uint256 currency,
uint256 minTokensPaidOut,
address payable beneficiary,
address payable feeBeneficiary,
string calldata memo
)
external
override
returns (uint256 netAmountPaidOut)
{
// Enforce permissions.
_requirePermissionFrom({
account: PROJECTS.ownerOf(projectId),
projectId: projectId,
permissionId: JBPermissionIds.USE_ALLOWANCE
});
netAmountPaidOut = _useAllowanceOf(projectId, token, amount, currency, beneficiary, feeBeneficiary, memo);
// The amount being withdrawn must be at least as much as was expected.
if (netAmountPaidOut < minTokensPaidOut) {
revert JBMultiTerminal_UnderMinTokensPaidOut(netAmountPaidOut, minTokensPaidOut);
}
}
//*********************************************************************//
// ------------------------ internal functions ----------------------- //
//*********************************************************************//
/// @notice Accepts an incoming token.
/// @param projectId The ID of the project that the transfer is being accepted for.
/// @param token The token being accepted.
/// @param amount The number of tokens being accepted.
/// @param metadata The metadata in which permit2 context is provided.
/// @return amount The number of tokens which have been accepted.
function _acceptFundsFor(
uint256 projectId,
address token,
uint256 amount,
bytes calldata metadata
)
internal
returns (uint256)
{
// Make sure the project has an accounting context for the token being paid.
if (_accountingContextForTokenOf[projectId][token].token == address(0)) {
revert JBMultiTerminal_TokenNotAccepted(token);
}
// If the terminal's token is the native token, override `amount` with `msg.value`.
if (token == JBConstants.NATIVE_TOKEN) return msg.value;
// If the terminal's token is not native, revert if there is a non-zero `msg.value`.
if (msg.value != 0) revert JBMultiTerminal_NoMsgValueAllowed(msg.value);
// Unpack the allowance to use, if any, given by the frontend.
(bool exists, bytes memory parsedMetadata) =
JBMetadataResolver.getDataFor({id: JBMetadataResolver.getId("permit2"), metadata: metadata});
// Check if the metadata contains permit data.
if (exists) {
// Keep a reference to the allowance context parsed from the metadata.
(JBSingleAllowance memory allowance) = abi.decode(parsedMetadata, (JBSingleAllowance));
// Make sure the permit allowance is enough for this payment. If not we revert early.
if (amount > allowance.amount) {
revert JBMultiTerminal_PermitAllowanceNotEnough(amount, allowance.amount);
}
// Keep a reference to the permit rules.
IAllowanceTransfer.PermitSingle memory permitSingle = IAllowanceTransfer.PermitSingle({
details: IAllowanceTransfer.PermitDetails({
token: token,
amount: allowance.amount,
expiration: allowance.expiration,
nonce: allowance.nonce
}),
spender: address(this),
sigDeadline: allowance.sigDeadline
});
// Set the allowance to `spend` tokens for the user.
try PERMIT2.permit({owner: _msgSender(), permitSingle: permitSingle, signature: allowance.signature}) {}
catch (bytes memory) {}
}
// Get a reference to the balance before receiving tokens.
uint256 balanceBefore = _balanceOf(token);
// Transfer tokens to this terminal from the msg sender.
_transferFrom({from: _msgSender(), to: payable(address(this)), token: token, amount: amount});
// The amount should reflect the change in balance.
return _balanceOf(token) - balanceBefore;
}
/// @notice Adds funds to a project's balance without minting tokens.
/// @param projectId The ID of the project to add funds to the balance of.
/// @param token The address of the token being added to the project's balance.
/// @param amount The amount of tokens to add as a fixed point number with the same number of decimals as this
/// terminal. If this is a native token terminal, this is ignored and `msg.value` is used instead.
/// @param shouldReturnHeldFees A flag indicating if held fees should be returned based on the amount being added.
/// @param memo A memo to pass along to the emitted event.
/// @param metadata Extra data to pass along to the emitted event.
function _addToBalanceOf(
uint256 projectId,
address token,
uint256 amount,
bool shouldReturnHeldFees,
string memory memo,
bytes memory metadata
)
internal
{
// Return held fees if desired. This mechanism means projects don't pay fees multiple times when funds go out of
// and back into the protocol.
uint256 returnedFees = shouldReturnHeldFees ? _returnHeldFees(projectId, token, amount) : 0;
emit AddToBalance({
projectId: projectId,
amount: amount,
returnedFees: returnedFees,
memo: memo,
metadata: metadata,
caller: _msgSender()
});
// Record the added funds with any returned fees.
STORE.recordAddedBalanceFor({projectId: projectId, token: token, amount: amount + returnedFees});
}
/// @notice Logic to be triggered before transferring tokens from this terminal.
/// @param to The address the transfer is going to.
/// @param token The token being transferred.
/// @param amount The number of tokens being transferred, as a fixed point number with the same number of decimals
/// as this terminal.
function _beforeTransferTo(address to, address token, uint256 amount) internal {
// If the token is the native token, no allowance needed.
if (token == JBConstants.NATIVE_TOKEN) return;
IERC20(token).safeIncreaseAllowance(to, amount);
}
/// @notice Fund a project either by calling this terminal's internal `addToBalance` function or by calling the
/// recipient
/// terminal's `addToBalance` function.
/// @param terminal The terminal on which the project is expecting to receive funds.
/// @param projectId The ID of the project being funded.
/// @param token The token being used.
/// @param amount The amount being funded, as a fixed point number with the amount of decimals that the terminal's
/// accounting context specifies.
/// @param metadata Additional metadata to include with the payment.
function _efficientAddToBalance(
IJBTerminal terminal,
uint256 projectId,
address token,
uint256 amount,
bytes memory metadata
)
internal
{
// Call the internal method if this terminal is being used.
if (terminal == IJBTerminal(address(this))) {
_addToBalanceOf({
projectId: projectId,
token: token,
amount: amount,
shouldReturnHeldFees: false,
memo: "",
metadata: metadata
});
} else {
// Get a reference to the amount being added to balance through `msg.value`.
uint256 payValue = _payValueOf(token, amount);
// Add to balance.
// If this terminal's token is the native token, send it in `msg.value`.
terminal.addToBalanceOf{value: payValue}({
projectId: projectId,
token: token,
amount: amount,
shouldReturnHeldFees: false,
memo: "",
metadata: metadata
});
}
}
/// @notice Pay a project either by calling this terminal's internal `pay` function or by calling the recipient
/// terminal's `pay` function.
/// @param terminal The terminal on which the project is expecting to receive payments.
/// @param projectId The ID of the project being paid.
/// @param token The token being paid in.
/// @param amount The amount being paid, as a fixed point number with the amount of decimals that the terminal's
/// accounting context specifies.
/// @param beneficiary The address to receive any platform tokens minted.
/// @param metadata Additional metadata to include with the payment.
function _efficientPay(
IJBTerminal terminal,
uint256 projectId,
address token,
uint256 amount,
address beneficiary,
bytes memory metadata
)
internal
{