-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathprint.html
More file actions
1443 lines (1401 loc) · 147 KB
/
print.html
File metadata and controls
1443 lines (1401 loc) · 147 KB
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
<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>ZAI docs</title>
<meta name="robots" content="noindex" />
<!-- Custom HTML head -->
<!-- Fonts -->
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
href="https://fonts.googleapis.com/css2?family=Open+Sans:wght@300;400;500;600;700;800&family=Rubik:ital,wght@0,400;0,700;0,800;1,600&display=swap"
rel="stylesheet"
/>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="shortcut icon" href="favicon.png">
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/general.css">
<link rel="stylesheet" href="css/chrome.css">
<link rel="stylesheet" href="css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
</head>
<body>
<!-- Provide site root to javascript -->
<script type="text/javascript">
var path_to_root = "";
var default_theme = "ayu";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
<span class="logo" ></span>
<ol class="chapter"><li class="chapter-item expanded "><a href="index.html"><strong aria-hidden="true">1.</strong> Home</a></li><li class="chapter-item expanded affix "><li class="part-title">Documentation</li><li class="chapter-item expanded "><a href="detailed/intro/index.html"><strong aria-hidden="true">2.</strong> ❱ Getting Started</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="detailed/intro/hai.html"><strong aria-hidden="true">2.1.</strong> Introduction to ZAI</a></li><li class="chapter-item expanded "><a href="detailed/intro/protocol.html"><strong aria-hidden="true">2.2.</strong> Azos Protocol 101</a></li></ol></li><li class="chapter-item expanded "><a href="detailed/modules/index.html"><strong aria-hidden="true">3.</strong> ❱ Core Modules</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="detailed/modules/safe_engine.html"><strong aria-hidden="true">3.1.</strong> SAFE Engine</a></li><li class="chapter-item expanded "><a href="detailed/modules/acc_engine.html"><strong aria-hidden="true">3.2.</strong> Accounting Engine</a></li><li class="chapter-item expanded "><a href="detailed/modules/liq_engine.html"><strong aria-hidden="true">3.3.</strong> Liquidation Engine</a></li><li class="chapter-item expanded "><a href="detailed/modules/oracle_relayer.html"><strong aria-hidden="true">3.4.</strong> Oracle Relayer</a></li><li class="chapter-item expanded "><a href="detailed/modules/tax_collector.html"><strong aria-hidden="true">3.5.</strong> Tax Collector</a></li><li class="chapter-item expanded "><a href="detailed/modules/pid_controller.html"><strong aria-hidden="true">3.6.</strong> PID Controller</a></li><li class="chapter-item expanded "><a href="detailed/modules/sf_treasury.html"><strong aria-hidden="true">3.7.</strong> Stability Fee Treasury</a></li></ol></li><li class="chapter-item expanded "><a href="detailed/auctions/index.html"><strong aria-hidden="true">4.</strong> ❱ Auction Houses</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="detailed/auctions/cah.html"><strong aria-hidden="true">4.1.</strong> Collateral Auction House</a></li><li class="chapter-item expanded "><a href="detailed/auctions/dah.html"><strong aria-hidden="true">4.2.</strong> Debt Auction House</a></li><li class="chapter-item expanded "><a href="detailed/auctions/sah.html"><strong aria-hidden="true">4.3.</strong> Surplus Auction House</a></li></ol></li><li class="chapter-item expanded "><a href="detailed/settlement/index.html"><strong aria-hidden="true">5.</strong> ❱ Settlement</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="detailed/settlement/global_settlement.html"><strong aria-hidden="true">5.1.</strong> Global Settlement</a></li><li class="chapter-item expanded "><a href="detailed/settlement/ps_sah.html"><strong aria-hidden="true">5.2.</strong> Post Settlement Surplus Auction House</a></li><li class="chapter-item expanded "><a href="detailed/settlement/ps_surplus_actioneer.html"><strong aria-hidden="true">5.3.</strong> Settlement Surplus Actioneer</a></li></ol></li><li class="chapter-item expanded "><a href="detailed/tokens/index.html"><strong aria-hidden="true">6.</strong> ❱ Tokens & Utils</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="detailed/tokens/system_coin.html"><strong aria-hidden="true">6.1.</strong> System Coin</a></li><li class="chapter-item expanded "><a href="detailed/tokens/protocol_token.html"><strong aria-hidden="true">6.2.</strong> Protocol Token</a></li><li class="chapter-item expanded "><a href="detailed/tokens/join_adapter.html"><strong aria-hidden="true">6.3.</strong> Join Adapters</a></li></ol></li><li class="chapter-item expanded "><a href="detailed/utils/index.html"><strong aria-hidden="true">7.</strong> ❱ Contract Utils</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="detailed/utils/authorizable.html"><strong aria-hidden="true">7.1.</strong> Authorizable</a></li><li class="chapter-item expanded "><a href="detailed/utils/modifiable.html"><strong aria-hidden="true">7.2.</strong> Modifiable</a></li><li class="chapter-item expanded "><a href="detailed/utils/disableable.html"><strong aria-hidden="true">7.3.</strong> Disableable</a></li><li class="chapter-item expanded "><a href="detailed/utils/factory/index.html"><strong aria-hidden="true">7.4.</strong> ❱ Factories</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="detailed/utils/factory/factory_child.html"><strong aria-hidden="true">7.4.1.</strong> Factory Child</a></li><li class="chapter-item expanded "><a href="detailed/utils/factory/authorizable_child.html"><strong aria-hidden="true">7.4.2.</strong> Authorizable Child</a></li><li class="chapter-item expanded "><a href="detailed/utils/factory/disableable_child.html"><strong aria-hidden="true">7.4.3.</strong> Disableable Child</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="detailed/proxies/index.html"><strong aria-hidden="true">8.</strong> ❱ Proxy Utils</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="detailed/proxies/hai_proxy.html"><strong aria-hidden="true">8.1.</strong> ZAI Proxy</a></li><li class="chapter-item expanded "><a href="detailed/proxies/hai_proxy_factory.html"><strong aria-hidden="true">8.2.</strong> Proxy Factory</a></li><li class="chapter-item expanded "><a href="detailed/proxies/hai_safe_manager.html"><strong aria-hidden="true">8.3.</strong> SAFE Manager</a></li><li class="chapter-item expanded "><a href="detailed/proxies/actions/index.html"><strong aria-hidden="true">8.4.</strong> ❱ Actions</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="detailed/proxies/actions/basic_actions.html"><strong aria-hidden="true">8.4.1.</strong> Basic Actions</a></li><li class="chapter-item expanded "><a href="detailed/proxies/actions/rewarded_actions.html"><strong aria-hidden="true">8.4.2.</strong> Rewarded Actions</a></li><li class="chapter-item expanded "><a href="detailed/proxies/actions/bidding_actions.html"><strong aria-hidden="true">8.4.3.</strong> Bidding Actions</a></li><li class="chapter-item expanded "><a href="detailed/proxies/actions/settlement_actions.html"><strong aria-hidden="true">8.4.4.</strong> Settlement Actions</a></li></ol></li></ol></li><li class="chapter-item expanded "><li class="part-title">Technical Documentation</li></ol>
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky bordered">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle"></button>
<button id="theme-toggle-light" class="icon-button" type="button" title="Enable light theme" aria-label="Enable light theme">
<i class="fa fa-sun-o"></i>
</button>
<button id="theme-toggle-dark" class="icon-button" type="button" title="Enable dark theme" aria-label="Enable dark theme">
<i class="fa fa-moon-o"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title"></h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h1 id="zai"><a class="header" href="#zai">ZAI</a></h1>
<p>This repository contains the core documentation for the Azos Platform and ZAI, a GEB fork. GEB is the abbreviation of <a href="https://en.wikipedia.org/wiki/G%C3%B6del,_Escher,_Bach">Gödel, Escher and Bach</a> as well as the name of an <a href="https://en.wikipedia.org/wiki/Geb">Egyptian god</a>.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="-getting-started"><a class="header" href="#-getting-started">❱ Getting Started</a></h1>
<p>Welcome to the "Getting Started" guide for the Azos Protocol. If you're new to the system or looking for a concise introduction, you've come to the right place. This section is designed to provide you with a straightforward overview of the essential concepts and steps needed to interact with the Azos ecosystem. Whether you're planning to mint stablecoins, or understand the intricacies of our smart contracts, this guide will equip you with the basic knowledge to take your first steps. Let's dive in!</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="introduction-to-zai"><a class="header" href="#introduction-to-zai">Introduction to ZAI</a></h1>
<h2 id="introduction-to-zai-a-framework-for-stablecoin-systems"><a class="header" href="#introduction-to-zai-a-framework-for-stablecoin-systems">Introduction to ZAI: A Framework for Stablecoin Systems</a></h2>
<p>ZAI serves as a framework for creating systems capable of issuing stablecoins. These stablecoins not only act as a reliable source of collateral for other DeFi protocols—when compared to assets like ETH or BTC—but also function as a store of value, complete with an integrated funding rate.</p>
<p>For a comprehensive understanding of the ZAI framework, this documentation aims to detail each of its components. We strongly recommend reviewing Reflexer's original <a href="https://github.com/reflexer-labs/whitepapers/blob/master/English/rai-english.pdf">whitepaper</a> as a precursor to this documentation.</p>
<h4 id="core-differentiators-of-zai-from-geb"><a class="header" href="#core-differentiators-of-zai-from-geb">Core Differentiators of ZAI from GEB</a></h4>
<p>ZAI is an enhanced fork of <a href="https://github.com/reflexer-labs/geb">GEB</a>, but it comes with several key distinctions:</p>
<ul>
<li><strong>Advanced System Parameter Controls</strong>: ZAI features refined mechanisms for managing system parameters, offering superior flexibility and control.</li>
<li><strong>Enhanced Deployment and Upgradeability</strong>: The framework allows for streamlined deployment and upgrades, simplifying system maintenance.</li>
<li><strong>Robust Testing and Simulation Suite</strong>: ZAI includes an upgraded testing and simulation environment, aiding in the identification and mitigation of system risks.</li>
<li><strong>Emphasis on Multi-Collateral Operations</strong>: ZAI is designed with a focus on handling multiple types of collateral, broadening its application scope.</li>
<li><strong>Inclusion of Factories for Common Contract Types</strong>: The framework comes with pre-built factories for commonly used contract types, reducing the operations needed for collateral setup.</li>
<li><strong>Standardized Methods and Contract Utilities</strong>: ZAI standardizes the way contracts and methods are utilized, making it easier for developers to generate changes across the system.</li>
<li><strong>Revamped Contract Interactions</strong>: The framework restructures the way contracts communicate with each other, leading to more efficient and reliable operations.</li>
</ul>
<p>By incorporating these features, ZAI aims to provide a more advanced, reliable, and user-friendly stablecoin system.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="azos-protocol-101"><a class="header" href="#azos-protocol-101">Azos Protocol 101</a></h1>
<h2 id="zai-framework-mechanics"><a class="header" href="#zai-framework-mechanics">ZAI Framework Mechanics</a></h2>
<h3 id="what-is-zai"><a class="header" href="#what-is-zai">What is ZAI?</a></h3>
<ul>
<li><strong>Low-Cost</strong>: The ZAI protocol is deployed on the Optimism network, offering significantly low gas fees for transactions.</li>
<li><strong>Dollar-Denominated</strong>: Both the system coin and the collaterals are denominated in US Dollar.</li>
<li><strong>Collateral-Backed</strong>: A diverse basket of collateral types backs the minting of the system coin.</li>
<li><strong>Control-Pegged</strong>: A PID controller dynamically adjusts the funding rate to balance value transfer between minters (debtors) and holders (creditors).</li>
<li><strong>Settleable</strong>: The system can undergo a Global Settlement, during which all debts are squared and ZAI holders can redeem tokens for a share of the collateral pool, regardless of whether they have outstanding debts.</li>
</ul>
<h3 id="glossary"><a class="header" href="#glossary">Glossary</a></h3>
<h4 id="units-of-measurement"><a class="header" href="#units-of-measurement">Units of Measurement</a></h4>
<ul>
<li><code>WEI</code>: The base unit for raw ERC20 amounts.</li>
<li><code>WAD</code>: A unit with <strong>18 decimal places</strong>, used for representing balances.</li>
<li><code>RAY</code>: A unit with <strong>27 decimal places</strong>, utilized for rate computations.</li>
<li><code>RAD</code>: A unit with <strong>45 decimal places</strong>, employed for calculating owed amounts.
<blockquote>
<p><strong>Note</strong>: The <a href="detailed/intro//src/libraries/Math.sol/library.Math.html">Math Library</a> handles all unit multiplications and divisions.</p>
</blockquote>
</li>
</ul>
<h4 id="tokens"><a class="header" href="#tokens">Tokens</a></h4>
<ul>
<li><code>systemCoin</code>: The ERC20 stablecoin issued by ZAI.</li>
<li><code>protocolToken</code>: The ERC20 governance token, used for system parameter voting and participating in debt/surplus auctions.</li>
<li><code>collateral</code>: Any ERC20 token that serves as collateral, enhancing the corresponding <code>cType</code> balance.</li>
</ul>
<h4 id="key-concepts"><a class="header" href="#key-concepts">Key Concepts</a></h4>
<ul>
<li><code>cType</code>: Represents a unique identifier for a collateral type within the ZAI system.</li>
<li><code>COIN</code>: An internal balance of system coins convertible to <code>systemCoin</code> on a <code>1:1</code> basis.</li>
<li><code>DEBT</code>: An internal ledger entry representing unbacked debt, erasable with <code>COIN</code> on a <code>1:1</code> basis.</li>
<li><code>SAFE</code>: A vault-like contract holding collateral and generating <code>COINs</code>, which may also accrue <code>DEBT</code>.
<ul>
<li><code>lockedCollateral</code>: The collateral amount held within a <code>SAFE</code>.</li>
<li><code>generatedDebt</code>: The debt incurred by a <code>SAFE</code> during the <code>COIN</code> generation process. Note that it does <strong>NOT</strong> correlate directly to the amount of <code>COINs</code> generated.</li>
<li><strong>Liquidation</strong>: A process triggered for under-collateralized SAFEs, wherein their <code>generatedDebt</code> is moved to the system's <code>DEBT</code> and collateral is seized for auction to cancel out the <code>DEBT</code>.</li>
</ul>
</li>
<li><code>redemptionPrice</code>: The internal price at which system coins can be exchanged for collateral.</li>
<li><code>targetPrice</code>: A reference price utilized to adjust the <code>redemptionPrice</code>, often aligned with market price.</li>
<li><code>redemptionRate</code>: Governs how the <code>redemptionPrice</code> changes over time, essentially functioning as the system's funding rate.</li>
<li><code>stabilityFee</code>: A separate interest rate, unconnected to the <code>redemptionRate</code>, applied to user debts and collected by the system.</li>
<li><code>accumulatedRate</code>: Reflects the compounded <code>stabilityFee</code> applied to a <code>cType</code>, determining the relationship between <code>generatedDebt</code> and the <code>COINs</code> produced.</li>
</ul>
<p>This guide aims to provide a comprehensive understanding of ZAI's framework and its intricacies. Armed with this knowledge, you'll be better equipped to interact with the protocol effectively.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="-core-modules"><a class="header" href="#-core-modules">❱ Core Modules</a></h1>
<p>Welcome to the core contracts that make up the Azos Protocol. This is your go-to resource for understanding the architecture and components that underpin the ZAI system. From collateral management and stablecoin issuance to governance and global settlement, these contracts are the building blocks that ensure the protocol's stability, scalability, and security.</p>
<p>Whether you're a developer, a system administrator, or just an enthusiast interested in the mechanics of the Azos Protocol, this index provides detailed information on each core contract and its role within the system. Explore how they interact, understand their functionalities, and learn how they contribute to the robust framework that makes ZAI a leader in decentralized finance.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="safe-engine"><a class="header" href="#safe-engine">SAFE Engine</a></h1>
<p>See <a href="detailed/modules//src/contracts/SAFEEngine.sol/contract.SAFEEngine.html">SAFEEngine.sol</a> for more details.</p>
<h2 id="1-introduction"><a class="header" href="#1-introduction">1. Introduction</a></h2>
<p>The SAFE Engine serves as the central component of the ZAI framework, managing data on user-owned SAFEs (Simplified Agreement for Future Equity) and the interest rates for different forms of collateral. It performs the following functions:</p>
<ul>
<li>Monitoring the debt generated at the system level, by a specific collateral type, or by individual SAFEs.</li>
<li>Facilitating the internal movement of coins, collateral, or debt between accounts.</li>
<li>Seizing collateral from SAFEs, usually during liquidation events.</li>
<li>Managing account permissions.</li>
<li>Implementing debt caps on a global scale, as well as for each type of collateral and individual SAFE.</li>
</ul>
<p>Users have the ability to alter the status of their SAFEs via the SAFE Engine, provided that the collateralization ratio remains above the designated minimum threshold.</p>
<blockquote>
<p><strong>Notice</strong>: The SAFE Engine relies on <a href="detailed/modules/../tokens/join_adapter.html">join adapter contracts</a> to hold the balance of ERC20 tokens of the system. Transfers within the system are handled entirely by the SAFE Engine, which does not handle any ERC20 tokens directly.</p>
</blockquote>
<h2 id="2-contract-details"><a class="header" href="#2-contract-details">2. Contract Details</a></h2>
<h3 id="key-methods"><a class="header" href="#key-methods">Key Methods:</a></h3>
<p><strong>Permissioned</strong></p>
<ul>
<li><code>transferCollateral</code>: Transfers collateral from one account to another.</li>
<li><code>transferInternalCoins</code>: Transfers coins from one account to another.</li>
<li><code>transferSAFECollateralAndDebt</code>: Transfers collateral and debt from one SAFE to another.</li>
<li><code>modifySAFECollateralization</code>: Locks/Releases collateral in a SAFE, and/or generates/repays a SAFE's debt.</li>
</ul>
<p><strong>Authorized</strong></p>
<ul>
<li><code>updateCollateralPrice</code>: Updates the prices of a collateral type.</li>
<li><code>updateAccumulatedRate</code>: Updates the accumulated rate of a collateral type.</li>
<li><code>modifyCollateralBalance</code>: Modifies the collateral balance of an account.</li>
<li><code>confiscateSAFECollateralAndDebt</code>: Confiscates collateral and debt from a SAFE.</li>
<li><code>disableContract</code>: Locks the SAFEs, accumulated rates, and collateral prices from being modified.</li>
</ul>
<h3 id="required-authorities"><a class="header" href="#required-authorities">Required Authorities:</a></h3>
<ul>
<li><strong>Oracle Relayer</strong>: needs authorization to call <code>updateCollateralPrice</code>.</li>
<li><strong>Tax Collector</strong>: needs authorization to call <code>updateAccumulatedRate</code>.</li>
<li><strong>Liquidation Engine</strong>: needs authorization to call <code>confiscateSAFECollateralAndDebt</code>.</li>
<li><strong>Coin Join</strong>: needs authorization to call <code>transferInternalCoins</code>.</li>
<li><strong>Collateral Join</strong>: needs authorization to call <code>modifyCollateralBalance</code>.</li>
<li><strong>Global Settlement</strong>: needs authorization to call <code>disableContract</code>.</li>
</ul>
<h3 id="contract-parameters"><a class="header" href="#contract-parameters">Contract Parameters:</a></h3>
<p><strong>Global</strong></p>
<ul>
<li><code>globalDebtCeiling</code>: The max amount of debt that can be generated by the system.</li>
<li><code>safeDebtCeiling</code>: The max amount of debt that can be generated by a SAFE.</li>
</ul>
<p><strong>Per Collateral Type</strong></p>
<ul>
<li><code>debtCeiling</code>: The max amount of debt that can be generated globally by the collateral type.</li>
<li><code>debtFloor</code>: The min amount of debt that can be generated by a SAFE of that collateral type.</li>
</ul>
<h3 id="contract-data"><a class="header" href="#contract-data">Contract Data:</a></h3>
<p><strong>Global</strong></p>
<ul>
<li><code>globalDebt</code>: The amount of debt that was generated by the system.</li>
<li><code>globalUnbackedDebt</code>: The amount of debt that was generated by the system and is not backed by collateral.</li>
</ul>
<p><strong>Per Collateral Type</strong></p>
<ul>
<li><code>debtAmount</code>: The amount of debt that was generated by the collateral type.</li>
<li><code>lockedAmount</code>: The amount of collateral that is locked in all SAFEs using the collateral type.</li>
<li><code>accumulatedRate</code>: A value that represents the accumulated interest rate.</li>
<li><code>safetyPrice</code>: The price of the collateral type (vs ZAI) at which the SAFE is considered unsafe.</li>
<li><code>liquidationPrice</code>: The price of the collateral type (vs ZAI) at which the SAFE is considered liquidatable.</li>
</ul>
<blockquote>
<p>A user action should never be able to modify the SAFE collateralization resulting in an unsafe state. When an update the <code>safetyPrice</code> leaves the SAFE in an unsafe state, the user may only add collateral and/or repay debt in order to restore the SAFE's collateralization to a safe state.</p>
<p><strong>Notice</strong>: The <code>lockedAmount</code> is a storage variable used to visibilize the total amount of collateral that backs the <code>debtAmount</code>. However, this value can be artificially increased, by creating a SAFE without debt and locking collateral in it: on the event of Global Settlement, this user would be allowed to withdraw all of his collateral and it would not be accounted for the redemptions.</p>
</blockquote>
<h2 id="3-key-mechanisms--concepts"><a class="header" href="#3-key-mechanisms--concepts">3. Key Mechanisms & Concepts</a></h2>
<h3 id="accounts-vs-safes"><a class="header" href="#accounts-vs-safes">ACCOUNTs vs SAFEs</a></h3>
<p>The SAFE Engine handles 2 different types of entities:</p>
<ul>
<li>ACCOUNTs:
<ul>
<li>May have coins and collateral (non confiscatable) balance</li>
<li>May have SAFEs (one for each collateral type)</li>
<li>May have authorized accounts to modify their balance (or SAFEs)</li>
<li>May have in some cases (unbacked) debt (confiscatable)</li>
</ul>
</li>
<li>SAFEs:
<ul>
<li>Defined by the account's address (owner) and a collateral type</li>
<li>May only have locked collateral and generated debt</li>
<li>May be modified by the owner account, or by authorized accounts</li>
</ul>
</li>
</ul>
<blockquote>
<p><strong>Notice</strong>: The protocol may be able to confiscate collateral from SAFEs, but not from ACCOUNTs, all debt generated to ACCOUNTs has is considered unbacked. Core contracts of the protocol may have debt, and they should try to settle it by destroying COINs in their balance.</p>
</blockquote>
<h3 id="the-collaterals--safes-accountances"><a class="header" href="#the-collaterals--safes-accountances">The Collaterals & SAFEs Accountances</a></h3>
<p>A SAFE consists of the following information:</p>
<ul>
<li><code>account</code>: The address of the owner.</li>
<li><code>collateralType</code>: The collateral type identifier.</li>
<li><code>generatedDebt</code>: The amount of debt that was generated.</li>
<li><code>lockedCollateral</code>: The amount of collateral that is locked in.</li>
</ul>
<p>The SAFE Engine also tracks per collateral type the following information:</p>
<ul>
<li><code>accumulatedRate</code>: A value that represents the accumulated interest rate.</li>
<li><code>safetyPrice</code>: The price of the collateral type (vs ZAI) at which the SAFE is considered unsafe.</li>
<li><code>liquidationPrice</code>: The price of the collateral type (vs ZAI) at which the SAFE is considered liquidatable</li>
</ul>
<p>A SAFE is considered healthy when the following condition is met:</p>
<pre><code>lockedCollateral * safetyPrice >= generatedDebt * accumulatedRate
</code></pre>
<h3 id="coin-debt-and-zai-dynamics"><a class="header" href="#coin-debt-and-zai-dynamics">COIN, DEBT, and ZAI Dynamics</a></h3>
<p>In this system, COINs and DEBT function similarly to matter and antimatter, created and annulled in pairs. The ZAI token acts as the ERC20 counterpart of a COIN when it's outside the system, maintaining a redeemable 1:1 ratio. The system enables users to lock COINs to mint ZAI or burn ZAI to unlock COINs, making them operable within the framework.</p>
<p>DEBT, when unsecured, can be nullified using COINs on a 1:1 basis. However, within SAFEs, the relationship between <code>generatedDebt</code> and generated COINs diverges from the 1:1 ratio.</p>
<h3 id="interest-accumulation"><a class="header" href="#interest-accumulation">Interest Accumulation</a></h3>
<p>The "accumulated rate" represents the constantly accumulating interest or fees on the outstanding ZAI-generated debt. Calculated over time, it's based on the amount of ZAI minted and the applicable stability fee rate. This ensures that the debt owed by users evolves due to the ongoing addition of the stability fee. Whenever a user mints or repays ZAI, the formula for <code>generatedDebt</code> is:</p>
<pre><code>coinAmount = generatedDebt * accumulatedRate
</code></pre>
<p>Here, <code>coinAmount</code> is the number of coins the user wishes to mint or burn, and <code>accumulatedRate</code> is the relevant collateral's accumulated interest rate. The <code>coinAmount</code> could also be a negative figure, indicating debt dissolution.</p>
<blockquote>
<p><strong>Example</strong>: Assume a 10% annual interest rate on collateral TKN.</p>
<p>Initially, the <code>accumulatedRate</code> is 1. When Alice mints 100 ZAI tokens (COINs) from the SAFE Engine, her resulting debt is <code>100 * 1 = 100</code>.</p>
<p>After one year, Alice repays her 100 debt. Now, the <code>accumulatedRate</code> stands at 1.1, requiring Alice to repay <code>100 * 1.1 = 110</code> ZAI tokens.</p>
<p>Concurrently, Bob mints 100 ZAI, resulting in a (<code>100 / 1.1</code>) <code>90.9</code> debt.</p>
<p>By year two, the <code>accumulatedRate</code> becomes 1.21. To repay his debt, Bob needs <code>90.9 * 1.21 = 110</code> ZAI tokens, identical to Alice's amount.</p>
<p><strong>Note</strong>: Negative interest rates could technically be implemented using the same mechanics.</p>
</blockquote>
<p>Whenever the system refreshes the <code>accumulatedRate</code>, it leads to a surplus of COINs that get allocated to an unspecified address. This surplus emerges from the <code>updateAccumulatedRate</code> function, invoked by the Tax Collector. Importantly, these additional COINs are not directly extracted from any SAFE; instead, they manifest as a simultaneous debt increment for all SAFEs holding the taxed collateral type.</p>
<h3 id="transfer-collateral-and-coins-events"><a class="header" href="#transfer-collateral-and-coins-events">Transfer Collateral and Coins events</a></h3>
<p>Since the transfer of collateral and coins is handled by the SAFE Engine, the events <code>TransferCollateral</code> and <code>TransferInternalCoins</code> are emitted by the SAFE Engine, and not by the ERC20 contracts. The events emitted by the SAFE Engine try to follow the same structure as the ERC20 events, but with the addition of the collateral type identifier in the <code>TransferCollateral</code> event.</p>
<p><strong>Generating Debt and minting ZAI</strong>:</p>
<ul>
<li>Lock collateral in a SAFE:
<ul>
<li>Deposit TKN: <code>TransferCollateral(TKN, source, ACCOUNT, amount)</code></li>
<li>Lock TKN:
<ul>
<li><code>TransferCollateral(TKN, ACCOUNT, 0, amount)</code></li>
<li><code>TransferCollateral(TKN, 0, SAFE, amount)</code></li>
</ul>
</li>
<li>Generate DEBT: <code>TransferInternalCoins(0, ACCOUNT, amount)</code></li>
<li>Mint ZAI:
<ul>
<li><code>TransferInternalCoins(ACCOUNT, COIN_JOIN, amount)</code></li>
<li><code>ERC20.Transfer(0, destination, amount)</code></li>
</ul>
</li>
</ul>
</li>
</ul>
<h2 id="4-gotchas"><a class="header" href="#4-gotchas">4. Gotchas</a></h2>
<h3 id="permissioned-vs-authorized"><a class="header" href="#permissioned-vs-authorized">Permissioned vs Authorized</a></h3>
<p>Authorized accounts are addresses allowed to call SAFE Engine <code>isAuthorized</code> methods. While a SAFE can add approval to an account, which gives permission to the account to modify the SAFE's state (on <code>isSAFEAllowed</code> methods), this account is not authorized to call SAFE Engine authorized methods (<code>isAuthorized</code>).</p>
<h3 id="safe-state-vs-coin-and-debt"><a class="header" href="#safe-state-vs-coin-and-debt">SAFE State vs COIN and DEBT</a></h3>
<p>The <code>generatedDebt</code> and <code>lockedCollateral</code> of a SAFE is measured in WAD units, while the COINs and DEBT (that gets limited, for example, by the debt ceilings) are measured in RAD units.</p>
<blockquote>
<p><strong>Notice</strong>: The reason for this is that the resultant <code>COIN|DEBT</code> is calculated by:</p>
<pre><code>generatedDebt[WAD] * accumulatedRate[RAY] = COIN|DEBT[RAD]
</code></pre>
</blockquote>
<h3 id="collateral-balance-vs-locked-collateral"><a class="header" href="#collateral-balance-vs-locked-collateral">Collateral Balance vs Locked Collateral</a></h3>
<p>As stated before, an ACCOUNT can have collateral balance, and an account's SAFE can have locked collateral. The difference between these two is that the collateral balance is the amount of collateral that the user has available to use (transfer or withdraw), and the locked collateral is the amount of collateral that the user has locked in a SAFE, that the user would need to modify the SAFE collateralization in order to use.</p>
<h3 id="unbacked-debt-and-debt-settlement"><a class="header" href="#unbacked-debt-and-debt-settlement">Unbacked Debt and Debt Settlement</a></h3>
<p>Unbacked debt, or debt that is accounted to an ACCOUNT (not a SAFE with locked collateral) is only generated to contracts of the protocol. This debt can only be settled by having an equal an equal amount of COINs in the ACCOUNT's balance, and calling <code>settleDebt</code> with the amount of DEBT/COINs to destroy.</p>
<p>This debt is only generated when a SAFE gets liquidated, a portion of the SAFE's collateral is transferred to the Collateral Auction House, the SAFE's debt is transferred to the Accounting Engine (unbacked). The Auction House will the transfer COINs to the Accounting Engine in order for the debt to be settled.</p>
<h3 id="confiscation-of-collateral-and-debt"><a class="header" href="#confiscation-of-collateral-and-debt">Confiscation of Collateral and Debt</a></h3>
<p>An authorized account may call <code>confiscateSAFECollateralAndDebt</code> to confiscate the locked collateral and/or debt of a SAFE. This method does not perform any checks on the SAFE's state. The flow of value is inversed when it happens during liquidations, than when the system is under global settlement. This means that this method is always authorized to arbitrarily modify the SAFE's state (and the DEBT balance of an account), even after the system was shutdown.</p>
<!-- TODO: mv to proxy section
### Proxy Accounts (SAFE Manager)
In orther to facilitate the management of SAFEs, the protocol incorporates a SAFE Manager contract allowing a same user to control multiple SAFEs with the same collateral type. This interaction is done through an ownable proxy contract, and a SAFE Handler.
- The user's Proxy
- has an account in the SAFE Engine (can hold collateral and coins).
- can create a new SAFE (deploying a new SAFE Handler) identified by an #ID (autoincremental).
- is the owner (in the SAFE Manager) of the SAFE that's identified by the SAFE Handler.
- The SAFE Handler
- account that authorizes the SAFE Manager (in the SAFE Engine) to modify the SAFE in its behalf.
- has no other functionality.
- To deposit/withdraw collateral, the tokens are transferred from/to the user's Proxy account to/from the SAFE Handler's SAFE.
- To generate/repay debt, the coins are transferred from/to the user's Proxy account to/from the SAFE Handler's SAFE.
**Notice**: Regular users may find that their `coinBalance` (in their proxy address) is usually `0` (or close to), as proxy interactions are designed to always use the `coinBalance` to mint ZAI and transfer the ERC20 to the user's address.
-->
<h2 id="5-failure-modes"><a class="header" href="#5-failure-modes">5. Failure Modes</a></h2>
<h3 id="parameters-misconfiguration"><a class="header" href="#parameters-misconfiguration">Parameters misconfiguration</a></h3>
<ul>
<li>Low <code>globalDebtCeiling</code> may limit user borrowing.</li>
<li>High <code>globalDebtCeiling</code> risks debt overload.</li>
<li>Low <code>safeDebtCeiling</code> hampers individual borrowing.</li>
<li><code>safeDebtCeiling</code> above <code>globalDebtCeiling</code> is likely moot.</li>
<li>Low <code>cType.debtCeiling</code> curbs borrowing for specific collateral.</li>
<li><code>cType.debtCeiling</code> above <code>globalDebtCeiling</code> is typically irrelevant.</li>
<li>Low <code>cType.debtFloor</code> raises liquidation risks.</li>
<li>High <code>cType.debtFloor</code> deters small borrowers.</li>
</ul>
<h3 id="liquidation-mechanics"><a class="header" href="#liquidation-mechanics">Liquidation mechanics</a></h3>
<p>Despite the fact that the SAFE Engine holds the latest collateral prices and SAFE state, the liquidation of a SAFE is handled by the Liquidation Engine. The Liquidation Engine is authorized to call <code>confiscateSAFECollateralAndDebt</code>, which doesn't perform healthy checks, and allows it to modify the SAFE's state in an arbitrary way. If the Liquidation Engine (or any authorized address) is misconfigured, it may result in the liquidation of SAFEs that are not unsafe, or malicious modifications to any SAFE's state.</p>
<h3 id="accumulated-rate-and-collateral-prices"><a class="header" href="#accumulated-rate-and-collateral-prices">Accumulated Rate and Collateral Prices</a></h3>
<p>Both the <code>updateAccumulatedRate</code> and <code>updateCollateralPrice</code> are authorized methods that perform no further checks in the validity of the parameters passed. If the Oracle Relayer or the Tax Collector (or any other authorized address) are misconfigured, it may result in the <code>accumulatedRate</code> or <code>safetyPrice</code> being set to an arbitrary value.</p>
<p>If the <code>accumulatedRate</code> for a given collateral type is set to <code>0</code>, the collateral type may be bricked beyond repair, as the <code>accumulatedRate</code> is iteratively calculated by multiplying the previous value to a multiplier.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="accounting-engine"><a class="header" href="#accounting-engine">Accounting Engine</a></h1>
<p>See <a href="detailed/modules//src/contracts/AccountingEngine.sol/contract.AccountingEngine.html">AccountingEngine.sol</a> for more details.</p>
<h2 id="1-introduction-1"><a class="header" href="#1-introduction-1">1. Introduction</a></h2>
<p>The Accounting Engine serves as the system's financial management hub, overseeing tasks such as:</p>
<ul>
<li>Tracking system surplus and deficit.</li>
<li>Managing system debt through auctions.</li>
<li>Dealing with system surplus via auctions or transfers.</li>
<li>Accepting COINs (for instance, from auctions) and using them to offset DEBT.</li>
</ul>
<h2 id="2-contract-details-1"><a class="header" href="#2-contract-details-1">2. Contract Details</a></h2>
<h3 id="key-methods-1"><a class="header" href="#key-methods-1">Key Methods:</a></h3>
<p><strong>Public</strong></p>
<ul>
<li><code>popDebtFromQueue</code>: Removes a certain amount of debt from the time-sensitive queue after the <code>popDebtDelay</code> duration has elapsed, for either settlement or auction.</li>
<li><code>settleDebt</code>: Utilizes coin balance to settle debt.</li>
<li><code>cancelAuctionedDebtWithSurplus</code>: Utilizes coins to settle debt that's in the queue.</li>
<li><code>auctionDebt</code>: Triggers an auction to liquidate portions of unsettled debt.</li>
<li><code>auctionSurplus</code>: Triggers an auction to liquidate surplus once all debt has been settled.</li>
<li><code>transferExtraSurplus</code>: Allocates (instead of auctioning it) excess surplus following debt settlement.</li>
<li><code>transferPostSettlementSurplus</code>: Allocates all remaining surplus when a Global Settlement event occurs.</li>
</ul>
<p><strong>Authorized</strong></p>
<ul>
<li><code>pushDebtToQueue</code>: Adds a specified amount of debt to a time-sensitive queue.</li>
<li><code>disableContract</code>: Deactivates both Debt and Surplus Auction Houses, clears as much debt as possible, and transfers (after <code>disableCooldown</code> delay) any leftover surplus to a designated drain address.</li>
</ul>
<h3 id="required-authorities-1"><a class="header" href="#required-authorities-1">Required Authorities:</a></h3>
<ul>
<li><strong>LiquidationEngine</strong>: needs authorization to call <code>pushDebtToQueue</code>.</li>
<li><strong>Debt Auction House</strong>: needs authorization to call <code>cancelAuctionedDebtWithSurplus</code>.</li>
<li><strong>Surplus Auction House</strong>: needs approval to modify the contract's state in the SAFE Engine.</li>
<li><strong>Global Settlement</strong>: needs authorization to call <code>disableContract</code>.</li>
</ul>
<h3 id="contract-parameters-1"><a class="header" href="#contract-parameters-1">Contract Parameters:</a></h3>
<p><strong>Global</strong></p>
<ul>
<li><strong>SAFE Engine</strong>: Holds the coin and debt balance, is called to settle debt.</li>
<li><strong>Surplus Auction House</strong>: Is called to start surplus auctions.</li>
<li><strong>Debt Auction House</strong>: Is called to start debt auctions.</li>
<li><code>postSettlementSurplusDrain</code>: Address to which surplus is sent following Global Settlement.</li>
<li><code>surplusIsTransferred</code>: Whether the surplus should be either auctioned off or transferred.</li>
<li><code>surplusDelay</code>: Time lag before the surplus becomes eligible for either auction or transfer.</li>
<li><code>popDebtDelay</code>: Time interval after which debt can be popped from the time-sensitive queue.</li>
<li><code>disableCooldown</code>: The waiting period following Global Settlement, after which any remaining surplus should be transferred.</li>
<li><code>surplusAmount</code>: Amount of surplus eligible for auction or transfer during each operation.</li>
<li><code>surplusBuffer</code>: Minimum surplus reserve to be maintained in the contract following an auction or transfer.</li>
<li><code>debtAuctionMintedTokens</code>: Initial quantity of Protocol Tokens offered for minting in debt auctions.</li>
<li><code>debtAuctionBidSize</code>: Chunk of debt that can be offered in each individual debt auction.</li>
</ul>
<h2 id="3-key-mechanisms--concepts-1"><a class="header" href="#3-key-mechanisms--concepts-1">3. Key Mechanisms & Concepts</a></h2>
<h3 id="queued-debt-on-auction-debt--unqueued-unauctioned-debt"><a class="header" href="#queued-debt-on-auction-debt--unqueued-unauctioned-debt">Queued Debt, On Auction Debt & Unqueued Unauctioned Debt</a></h3>
<p>Within the SAFE Engine's scope, the Accounting Engine maintains a single debt balance associated with the contract address. This balance is the summation of three components: the queued debt, representing debt in line for auctioning; the unqueued debt, which is currently being auctioned; and the remaining debt not undergoing auction at the moment.</p>
<p>The unqueued-unauctioned debt can be calculated as follows:</p>
<pre><code>unqueuedUnauctionedDebt = debtBalance - queuedDebt - onAuctionDebt
</code></pre>
<p>Once the <code>unqueuedUnauctionedDebt</code> debt reaches the specified <code>debtAuctionBidSize</code> threshold and the cooldown period elapses, a debt auction is initiated. During this process, the overall debt of the contract remains unchanged, but the <code>onAuctionDebt</code> metric increases as the debt enters the auction phase. Simultaneously, the calculation for <code>unqueuedUnauctionedDebt</code> decreases as the debt undergoing auction is accounted for.</p>
<h2 id="4-gotchas-1"><a class="header" href="#4-gotchas-1">4. Gotchas</a></h2>
<h3 id="unqueued-unauctioned-debt-underflow"><a class="header" href="#unqueued-unauctioned-debt-underflow">Unqueued Unauctioned Debt underflow</a></h3>
<p>The <code>queuedDebt</code> is modified through the <code>pushDebtToQueue</code> (authorized) and <code>popDebtFromQueue</code> (public) methods. They don't exclusively mirror the <code>debtBalance</code> recorded in the SAFE Engine. If an authorized contract uses <code>pushDebtToQueue</code> without transferring debt to the Accounting Engine, it could lead to an underflow issue (if <code>queuedDebt</code> exceeds <code>debtBalance</code>). This situation could potentially disrupt the contract's ability to auction debt as the <code>unqueuedUnauctionedDebt</code> calculation might underflow and revert.</p>
<h2 id="5-failure-modes-1"><a class="header" href="#5-failure-modes-1">5. Failure Modes</a></h2>
<h3 id="parameters-misconfiguration-1"><a class="header" href="#parameters-misconfiguration-1">Parameters misconfiguration</a></h3>
<ul>
<li>High <code>surplusDelay</code> slows surplus actions.</li>
<li>Low <code>surplusDelay</code> rushes surplus auctions.</li>
<li>High <code>popDebtDelay</code> delays debt auctions.</li>
<li>Low <code>popDebtDelay</code> risks double debt coverage.</li>
<li>High <code>surplusAmount</code> risks unfilled surplus auctions.</li>
<li>Low <code>surplusAmount</code> hampers surplus actions.</li>
<li>High <code>surplusBuffer</code> blocks surplus auctions.</li>
<li>Low <code>surplusBuffer</code> risks uncovered new debt.</li>
<li>High <code>debtAuctionMintedTokens</code> dilutes protocol tokens.</li>
<li>Low <code>debtAuctionMintedTokens</code> risks failed debt auctions.</li>
<li>High <code>debtAuctionBidSize</code> risks unfilled debt auctions.</li>
<li>Low <code>debtAuctionBidSize</code> slows debt auctions.</li>
<li>Low <code>shutdownCooldown</code> risks premature surplus moves.</li>
<li>High <code>shutdownCooldown</code> delays post-shutdown surplus actions.</li>
</ul>
<h3 id="post-settlement-surplus-drain-misconfiguration"><a class="header" href="#post-settlement-surplus-drain-misconfiguration">Post Settlement Surplus Drain misconfiguration</a></h3>
<p>The <code>postSettlementSurplusDrain</code> address should be configured after the system is deployed. It's permissible to leave it unset, but doing so comes with implications: if Global Settlement is activated while this address is not specified, any surplus remaining after the settlement won't be drained. Instead, this surplus can only be used for debt elimination. It's worth noting that once Global Settlement is triggered, the address for <code>postSettlementSurplusDrain</code> becomes immutable and can't be changed.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="liquidation-engine"><a class="header" href="#liquidation-engine">Liquidation Engine</a></h1>
<p>See <a href="detailed/modules//src/contracts/LiquidationEngine.sol/contract.LiquidationEngine.html">LiquidationEngine.sol</a> for more details.</p>
<h2 id="1-introduction-2"><a class="header" href="#1-introduction-2">1. Introduction</a></h2>
<p>The Liquidation Engine is the component responsible for managing the liquidation processes of SAFEs. Its primary duties include:</p>
<ul>
<li>Determining the liquidation status of a SAFE.</li>
<li>Initiating a SAFE Saviour action to enhance the SAFE's financial health, if applicable.</li>
<li>Assessing the amount of collateral required to be confiscated from a SAFE to offset its debt.</li>
<li>Activating the process to seize collateral from a SAFE.</li>
<li>Initiating collateral auctions.</li>
</ul>
<h2 id="2-contract-details-2"><a class="header" href="#2-contract-details-2">2. Contract Details</a></h2>
<h3 id="key-functions"><a class="header" href="#key-functions">Key Functions:</a></h3>
<p><strong>Public</strong></p>
<ul>
<li><code>liquidateSAFE</code>: Evaluates the condition of a SAFE and commences the liquidation process if the SAFE is eligible for liquidation (and if SAFE Saviour intervention fails).</li>
</ul>
<p><strong>Permissioned</strong></p>
<ul>
<li><code>protectSAFE</code>: Selects a SAFE Saviour to defend a SAFE against liquidation.</li>
</ul>
<p><strong>Authorized</strong></p>
<ul>
<li><code>connectSAFESaviour</code>: Permits a SAFE Saviour contract to associate with a SAFE for the purpose of preventing its liquidation.</li>
<li><code>disconnectSAFESaviour</code>: Revokes permission for a SAFE Saviour contract to be linked to SAFEs.</li>
<li><code>removeCoinsFromAuction</code>: Adjusts the accounted amount of coins that are currently under auction.</li>
</ul>
<h3 id="required-authorities-2"><a class="header" href="#required-authorities-2">Required Authorities:</a></h3>
<ul>
<li><strong>Collateral Auction Houses</strong>: need authorization to call <code>removeCoinsFromAuction</code>.</li>
<li><strong>Global Settlement</strong>: needs authorization to call <code>disableContract</code> (and block further liquidations).</li>
</ul>
<h3 id="contract-parameters-2"><a class="header" href="#contract-parameters-2">Contract Parameters:</a></h3>
<p><strong>Global</strong></p>
<ul>
<li><strong>SAFE Engine</strong>: Holds the SAFE state, is called to confiscate the SAFE collateral and debt.</li>
<li><strong>Accounting Engine</strong>: The confiscated debt is transferred to the Accounting Engine balance, and pushed to its queue to be auctioned.</li>
<li><code>onAuctionSystemCoinLimit</code>: Maximum amount of system coins that can be simultaneously auctioned.</li>
</ul>
<p><strong>Per Collateral Type</strong></p>
<ul>
<li><strong>Collateral Auction House</strong>: Is called to start collateral auctions.</li>
<li><code>liquidationPenalty</code>: Penalty applied to the debt of the SAFE that is being liquidated. This penalty represents an excess in the amount of debt that the collateral auction needs to cover.</li>
<li><code>liquidationQuantity</code>: Max amount of debt that can be liquidated in each liquidation.</li>
</ul>
<h2 id="3-key-mechanisms--concepts-2"><a class="header" href="#3-key-mechanisms--concepts-2">3. Key Mechanisms & Concepts</a></h2>
<h3 id="liquidation-penalty"><a class="header" href="#liquidation-penalty">Liquidation Penalty</a></h3>
<p>If a SAFE is subject to liquidation carrying a specific debt amount, the Liquidation Engine initiates a collateral auction. The target debt to be covered in the auction is determined by the following equation:</p>
<pre><code>debtToAuction = debtToCover * liquidationPenalty
</code></pre>
<blockquote>
<p><strong>Example</strong>: Alice has a SAFE with 1000 TKN locked and a 500 COINs debt. The TKN price drops, and Alice's SAFE gets liquidated. The liquidation penalty is <code>1.1</code>, so the collateral auction will auction off Alice's 1000 TKNs, to try to cover 550 COINs of debt.</p>
</blockquote>
<h3 id="liquidation-quantity"><a class="header" href="#liquidation-quantity">Liquidation Quantity</a></h3>
<p>The quantity of collateral and debt seized from a SAFE during liquidation is decided based on the following criteria:</p>
<ul>
<li>If the SAFE's debt is smaller than <code>liquidationQuantity</code>, the SAFE undergoes full liquidation.</li>
<li>If the SAFE's debt surpasses <code>liquidationQuantity</code>, the SAFE is only partially liquidated, and residual debt remains.</li>
<li>If the SAFE's outstanding debt crosses the <code>onAuctionSystemCoinLimit</code>, partial liquidation occurs, and any remaining debt stays in the SAFE.</li>
<li>In cases of partial liquidation, a corresponding slice of collateral is seized, leaving the remaining collateral intact within the SAFE.</li>
</ul>
<h3 id="safe-saviours"><a class="header" href="#safe-saviours">SAFE Saviours</a></h3>
<p>These are smart contracts authorized to intervene on a user's behalf to improve the SAFE's financial condition and prevent liquidation. To become operational, SAFE Saviour contracts must receive authorization and must be chosen by each individual user.</p>
<h2 id="4-gotchas-2"><a class="header" href="#4-gotchas-2">4. Gotchas</a></h2>
<h3 id="system-coin-limit"><a class="header" href="#system-coin-limit">System Coin Limit</a></h3>
<p>This parameter establishes a shared upper limit for the total quantity of coins—equivalent to debt—that can be simultaneously auctioned for all kinds of collateral. Once this collective cap is reached, no additional debt auctions can occur, regardless of the type of collateral in question.</p>
<p>Reaching this ceiling can set off a chain reaction of consequences. For example, if a specific collateral type is unusually volatile and maxes out the debt limit through numerous auctions, it could essentially monopolize the available auction capacity, preventing other types of collateral from being auctioned. Furthermore, reaching this ceiling can freeze all new collateral auctions, affecting the liquidity and stability of the system until remedial actions are taken.</p>
<p>Therefore, it's vital for both users and system administrators to closely monitor how near the system is to hitting the <code>onAuctionSystemCoinLimit</code>. Breaching this limit could disrupt a wide range of operations.</p>
<blockquote>
<p><strong>Notice</strong>: The <code>onAuctionSystemCoinLimit</code> is a number with RAD precision.</p>
</blockquote>
<h2 id="5-failure-modes-2"><a class="header" href="#5-failure-modes-2">5. Failure Modes</a></h2>
<h3 id="parameters-misconfiguration-2"><a class="header" href="#parameters-misconfiguration-2">Parameters misconfiguration:</a></h3>
<ul>
<li>High <code>onAuctionSystemCoinLimit</code> risks mass collateral liquidation.</li>
<li>Low <code>onAuctionSystemCoinLimit</code> slows SAFE liquidations.</li>
<li>High <code>liquidationPenalty</code> amplifies user losses.</li>
<li>Low <code>liquidationPenalty</code> encourages overleveraging.</li>
<li>High <code>liquidationQuantity</code> favors full SAFE liquidations.</li>
<li>Low <code>liquidationQuantity</code> makes small auctions gas-inefficient.</li>
</ul>
<div style="break-before: page; page-break-before: always;"></div><h1 id="oracle-relayer"><a class="header" href="#oracle-relayer">Oracle Relayer</a></h1>
<p>See <a href="detailed/modules//src/contracts/OracleRelayer.sol/contract.OracleRelayer.html">OracleRelayer.sol</a> for more details.</p>
<h2 id="1-introduction-3"><a class="header" href="#1-introduction-3">1. Introduction</a></h2>
<p>The Oracle Relayer is the module that handles the quoting mechanism of the system. It is responsible for the following:</p>
<ul>
<li>Storing the oracles addresses for each collateral type.</li>
<li>Fetching and updating the price of the collateral types.</li>
<li>Updating the redemption price, given the redemption rate.</li>
</ul>
<h2 id="2-contract-details-3"><a class="header" href="#2-contract-details-3">2. Contract Details</a></h2>
<h3 id="key-methods-2"><a class="header" href="#key-methods-2">Key Methods:</a></h3>
<p><strong>Public</strong></p>
<ul>
<li><code>marketPrice</code>: Gets the market price of the system coin.</li>
<li><code>redemptionPrice</code>: Gets and updates the redemption price.</li>
<li><code>calcRedemptionPrice</code>: View method that calculates (but does not update) the current redemption price.</li>
<li><code>updateCollateralPrice</code>: Fetchs the price of a collateral type, updates the redemption price, calculates the safety and liquidation prices, and updates them in the SAFE Engine.</li>
</ul>
<p><strong>Authorized</strong></p>
<ul>
<li><code>updateRedemptionRate</code>: Updates the redemption rate.</li>
</ul>
<h3 id="required-authorities-3"><a class="header" href="#required-authorities-3">Required Authorities:</a></h3>
<ul>
<li><strong>PID Rate Setter</strong>: needs authorization to call <code>updateRedemptionRate</code>.</li>
</ul>
<h3 id="contract-parameters-3"><a class="header" href="#contract-parameters-3">Contract Parameters:</a></h3>
<p><strong>Global</strong></p>
<ul>
<li><strong>SAFE Engine</strong>: Is called to update the collateral prices on it.</li>
<li><strong>System Coin Oracle</strong>: Is queried to fetch the market price of the system coin.</li>
<li><code>redemptionRateLowerBound</code>: Lower bound of the redemption rate.</li>
<li><code>redemptionRateUpperBound</code>: Upper bound of the redemption rate.</li>
</ul>
<p><strong>Per Collateral Type</strong></p>
<ul>
<li><strong>Oracle</strong>: Is queried to fetch the price of the collateral type.</li>
<li><code>safetyCRatio</code>: Ratio applied to the collateral price to define the safety price.</li>
<li><code>liquidationCRatio</code>: Ratio applied to the collateral price to define the liquidation price.</li>
</ul>
<h2 id="3-key-mechanisms--concepts-3"><a class="header" href="#3-key-mechanisms--concepts-3">3. Key Mechanisms & Concepts</a></h2>
<h3 id="quoting-mechanism"><a class="header" href="#quoting-mechanism">Quoting Mechanism</a></h3>
<p>Each collateral type needs to have an associated oracle that quotes the collateral in terms of the denomination currency (in ZAI, US Dollars). The System Coin Oracle needs to be also denominated in the same currency.</p>
<p>The Oracle Relayer handles the quoting mechanism, in which collateral types are quoted in terms of ZAI, applying a variable rate to ZAI price. The collateral price is calculated as follows:</p>
<pre><code>collateralPrice = oraclePrice / redemptionPrice
</code></pre>
<h3 id="c-ratios"><a class="header" href="#c-ratios">C Ratios</a></h3>
<p>Safety and liquidation prices are calculated by applying a ratio to the collateral price. The safety price is calculated as follows:</p>
<pre><code>safetyPrice = collateralPrice * safetyCRatio
liquidationPrice = collateralPrice * liquidationCRatio
</code></pre>
<p>The safety price is the price at which the SAFE is considered safe, a user may modify the SAFE collateralization as long as the resulting state is above the safety price.</p>
<p>The liquidation price is the price at which the SAFE is considered liquidatable, and the SAFE may be liquidated.</p>
<h2 id="4-gotchas-3"><a class="header" href="#4-gotchas-3">4. Gotchas</a></h2>
<h2 id="5-failure-modes-3"><a class="header" href="#5-failure-modes-3">5. Failure Modes</a></h2>
<h3 id="parameters-misconfiguration-3"><a class="header" href="#parameters-misconfiguration-3">Parameters misconfiguration:</a></h3>
<ul>
<li>High <code>safetyCRatio</code> limits SAFE modifications.</li>
<li><code>safetyCRatio</code> near <code>liquidationCRatio</code> makes it redundant.</li>
<li>High <code>liquidationCRatio</code> may cause needless liquidations.</li>
<li>Low <code>liquidationCRatio</code> encourages overleveraging.</li>
</ul>
<div style="break-before: page; page-break-before: always;"></div><h1 id="tax-collector"><a class="header" href="#tax-collector">Tax Collector</a></h1>
<p>See <a href="detailed/modules//src/contracts/TaxCollector.sol/contract.TaxCollector.html">TaxCollector.sol</a> for more details.</p>
<h2 id="1-introduction-4"><a class="header" href="#1-introduction-4">1. Introduction</a></h2>
<p>The Tax Collector is the module that handles the collection of taxes. It is responsible for the following:</p>
<ul>
<li>Storing the interest rate for each collateral type.</li>
<li>Storing the tax revenue receivers.</li>
<li>Calculating and distributing the tax revenue.</li>
</ul>
<h2 id="2-contract-details-4"><a class="header" href="#2-contract-details-4">2. Contract Details</a></h2>
<h3 id="key-methods-3"><a class="header" href="#key-methods-3">Key Methods:</a></h3>
<p><strong>Public</strong></p>
<ul>
<li><code>taxSingle</code>: Calculates and distributes the tax revenue for a single collateral type.</li>
<li><code>taxMany</code>: Calculates and distributes the tax revenue for a set of collateral types.</li>
</ul>
<h3 id="contract-parameters-4"><a class="header" href="#contract-parameters-4">Contract Parameters:</a></h3>
<p><strong>Global</strong></p>
<ul>
<li><strong>SAFE Engine</strong>: Is called to update the accumulated rate for each collateral type.</li>
<li><strong>Primary Tax Receiver</strong>: Receives tax revenue for all collateral types.</li>
<li><code>globalStabilityFee</code>: Global stability fee applied to all collateral types.</li>
<li><code>maxStabilityFeeRange</code>: Maximum range for the stability fee to differ from 1 (no fee).</li>
</ul>
<p><strong>Per Collateral Type</strong></p>
<ul>
<li><strong>Secondary Tax Receivers</strong>: Addresses (and tax percentage) that receive revenue for the collateral type total stability fees.</li>
<li><code>stabilityFee</code>: Stability fee applied only to the collateral type.</li>
</ul>
<h2 id="3-key-mechanisms--concepts-4"><a class="header" href="#3-key-mechanisms--concepts-4">3. Key Mechanisms & Concepts</a></h2>
<h3 id="primary-and-secondary-tax-receivers"><a class="header" href="#primary-and-secondary-tax-receivers">Primary and Secondary Tax Receivers</a></h3>
<p>The contract holds 2 types of tax receivers:</p>
<ul>
<li><strong>Primary Tax Receiver</strong>: Is a shared address across all the collateral types. It receives the remaining tax revenue after the secondary tax receivers have been paid.</li>
<li><strong>Secondary Tax Receivers</strong>: Is a set of addresses per collateral type, that can be set to receive a fixed percentage amount of the tax revenue of the collateral type.</li>
</ul>
<h3 id="global-and-per-collateral-stability-fees"><a class="header" href="#global-and-per-collateral-stability-fees">Global and Per Collateral Stability Fees</a></h3>
<p>The tax (or Stability Fee) can be configured in 2 ways:</p>
<ul>
<li><strong>Global Stability Fee</strong>: Shared across all the collateral types.</li>
<li><strong>Per Collateral Stability Fee</strong>: Set for each collateral type.</li>
</ul>
<p>The final stability fee computed for a collateral type is the multiplication of both fees. To avoid retroactivity, the tax collecting routine first reads the previously stored stability fee, and then calculates and stores the new one.</p>
<h2 id="4-gotchas-4"><a class="header" href="#4-gotchas-4">4. Gotchas</a></h2>
<h2 id="5-failure-modes-4"><a class="header" href="#5-failure-modes-4">5. Failure Modes</a></h2>
<h3 id="parameters-misconfiguration-4"><a class="header" href="#parameters-misconfiguration-4">Parameters misconfiguration:</a></h3>
<ul>
<li><code>maxStabilityFeeRange</code> too high may result in a bad calculation of the stability fee, resulting in broken collateral types (as their accumulated rate will be too low/high).</li>
<li><code>maxStabilityFeeRange</code> too low may result in a bounded value for the stability fee, bounding the final stability fee to a value very similar to 1 (no stability fee).</li>
<li><code>maxSecondaryTaxReceivers</code> too low may result in not being able to add a secondary tax receiver to a collateral type.</li>
<li>Stability fees (<code>global * perCollateral</code>) too high may result in users not interested in generating debt.</li>
<li>Stability fees too low may result in the protocol not being able to generate enough revenue to cover the system expenses.</li>
</ul>
<div style="break-before: page; page-break-before: always;"></div><h1 id="pid-controller"><a class="header" href="#pid-controller">PID Controller</a></h1>
<p>See <a href="detailed/modules//src/contracts/PIDController.sol/contract.PIDController.html">PIDController.sol</a> and <a href="detailed/modules//src/contracts/PIDRateSetter.sol/contract.PIDRateSetter.html">PIDRateSetter.sol</a> for more details.</p>
<h2 id="1-introduction-5"><a class="header" href="#1-introduction-5">1. Introduction</a></h2>
<p>The PID Controller is a smart contract that fine-tunes the system's redemption rate by analyzing the <code>deviation</code>, which is the discrepancy between the market and redemption prices. It performs the following tasks:</p>
<ul>
<li>Computes and stores the system's proportional and integral deviations.</li>
<li>Applies a decay factor to the integral deviation.</li>
<li>Adjusts the redemption rate by applying proportional and integral gains to the deviation.</li>
</ul>
<p>The PID Rate Setter schedules and triggers the PID Controller's redemption rate adjustments.</p>
<h2 id="2-contract-details-5"><a class="header" href="#2-contract-details-5">2. Contract Details</a></h2>
<h3 id="21-pid-controller"><a class="header" href="#21-pid-controller">2.1 PID Controller</a></h3>
<h3 id="key-methods-4"><a class="header" href="#key-methods-4">Key Methods:</a></h3>
<p><strong>Authorized</strong></p>
<ul>
<li><code>computeRate</code>: Computes the new redemption rate, applying the proportional and integral gains to the deviation (can only be called by the PID Rate Setter contract).</li>
</ul>
<h3 id="contract-parameters-5"><a class="header" href="#contract-parameters-5">Contract Parameters:</a></h3>
<ul>
<li><strong>Seed Proposer</strong>: Authorized address for initiating redemption rate updates.</li>
<li><code>integralPeriodSize</code>: Minimum duration required to calculate integral deviation.</li>
<li><code>perSecondCumulativeLeak</code>: Decay constant for the integral deviation.</li>
<li><code>noiseBarrier</code>: Lowest deviation percentage considered for redemption rate adjustment.</li>
<li><code>feedbackOutputUpperBound</code>: Maximum limit for the redemption rate.</li>
<li><code>feedbackOutputLowerBound</code>: Minimum limit for the redemption rate.</li>
<li><code>proportionalGain</code>: Gain factor for proportional deviation.</li>
<li><code>integralGain</code>: Gain factor for integral deviation.</li>
</ul>
<h3 id="22-pid-rate-setter"><a class="header" href="#22-pid-rate-setter">2.2 PID Rate Setter</a></h3>
<h3 id="key-methods-5"><a class="header" href="#key-methods-5">Key Methods:</a></h3>
<p><strong>Public</strong></p>
<ul>
<li><code>updateRate</code>: Retrieves market and redemption prices from the Oracle Relayer and prompts the PID Controller to compute the new redemption rate.</li>
</ul>
<h3 id="contract-parameters-6"><a class="header" href="#contract-parameters-6">Contract Parameters:</a></h3>
<ul>
<li><code>updateRateDelay</code>: Time gap between successive redemption rate adjustments.</li>
</ul>
<h2 id="3-key-mechanisms--concepts-5"><a class="header" href="#3-key-mechanisms--concepts-5">3. Key Mechanisms & Concepts</a></h2>
<h3 id="deviation-metrics"><a class="header" href="#deviation-metrics">Deviation Metrics</a></h3>
<p>The PID Controller monitors the gap between market and redemption prices and stores both the proportional and integral deviations. Whenever the deviation changes, its integral component is decayed to mitigate the impact of historical deviations on future rates.</p>
<h4 id="proportional-deviation-pterm"><a class="header" href="#proportional-deviation-pterm">Proportional Deviation (<code>pTerm</code>)</a></h4>
<p>It is computed as:</p>
<pre><code>pTerm = (redemptionPrice - marketPrice) / redemptionPrice
</code></pre>
<h4 id="integral-deviation-iterm"><a class="header" href="#integral-deviation-iterm">Integral Deviation (<code>iTerm</code>)</a></h4>
<p>It is calculated iteratively:</p>
<pre><code>iTerm_n = (iTerm_(n-1) * decayFactor) + ((pTerm_n - pTerm_(n-1)) / 2)
</code></pre>
<h3 id="gain-parameters"><a class="header" href="#gain-parameters">Gain Parameters</a></h3>
<p>The system owner can configure the gain parameters for proportional (<code>pGain</code>) and integral (<code>iGain</code>) deviations. The redemption rate is then adjusted as follows:</p>
<pre><code>redemptionRate = 1 + (pTerm * pGain + iTerm * iGain)
</code></pre>
<p><strong>Notice</strong>: All of pTerm, iTerm, pGain, iGain can be negative, so the redemption rate can be lesser than 1 (decrease the rate). Yet the redemption rate can never be 0 or negative.</p>
<h2 id="4-gotchas-5"><a class="header" href="#4-gotchas-5">4. Gotchas</a></h2>
<h2 id="5-failure-modes-5"><a class="header" href="#5-failure-modes-5">5. Failure Modes</a></h2>
<ul>
<li>Invalid <code>seedProposer</code> risks stale redemption rate.</li>
<li>High <code>noiseBarrier</code> hampers redemption rate adjustment.</li>
<li>High <code>integralPeriodSize</code> lowers PID responsiveness.</li>
<li>Over-the-top <code>feedbackOutputUpperBound</code> is likely disregarded.</li>
<li>Null <code>feedbackOutputUpperBound</code> constrains positive control range.</li>
<li>Excessive <code>feedbackOutputLowerBound</code> may be overlooked.</li>
<li>Null <code>feedbackOutputLowerBound</code> limits negative control range.</li>
<li>High <code>perSecondCumulativeLeak</code> quickens integral decay.</li>
<li>Low <code>perSecondCumulativeLeak</code> amplifies integral's historical effect.</li>
<li>High <code>kp</code> makes controller jittery to current deviations.</li>
<li>High <code>ki</code> overemphasizes historical deviations.</li>
</ul>
<div style="break-before: page; page-break-before: always;"></div><h1 id="stability-fee-treasury"><a class="header" href="#stability-fee-treasury">Stability Fee Treasury</a></h1>
<p>See <a href="detailed/modules//src/contracts/StabilityFeeTreasury.sol/contract.StabilityFeeTreasury.html">StabilityFeeTreasury.sol</a> for more details.</p>
<h2 id="1-introduction-6"><a class="header" href="#1-introduction-6">1. Introduction</a></h2>
<p>The Stability Fee Treasury functions as a specialized contract designed for managing protocol fees that are not factored into the system's surplus or deficit calculations. Unlike locked funds, the funds within this contract remain liquid and can be flexibly utilized by the system owner. Its key responsibilities encompass:</p>
<ul>
<li>Facilitating the disbursement of rewards for maintenance tasks.</li>
<li>Utilizing funds to address unbacked debt.</li>
<li>Managing diverse payments initiated by the system owner.</li>
<li>Replenishing the system's surplus/deficit sheets when the treasury surpasses its predefined capacity.</li>
</ul>
<h2 id="2-contract-details-6"><a class="header" href="#2-contract-details-6">2. Contract Details</a></h2>
<h3 id="key-methods-6"><a class="header" href="#key-methods-6">Key Methods:</a></h3>
<p><strong>Public</strong></p>
<ul>
<li><code>settleDebt</code>: This function efficiently allocates available funds to cover unbacked debt within the treasury's accounting.</li>
<li><code>transferSurplusFunds</code>: This operation addresses outstanding debt to the maximum extent achievable and transfers any excess funds beyond the capacity back to the system's surplus/deficit sheets.</li>
</ul>
<p><strong>Permissioned</strong></p>
<ul>
<li><code>takeFunds</code>: Enables the authorized withdrawal of funds from a consenting address to the treasury.</li>
<li><code>pullFunds</code>: Allows an address with sufficient allowance to withdraw funds from the treasury.</li>
</ul>
<p><strong>Authorized</strong></p>
<ul>
<li><code>setTotalAllowance</code>: Grant an address the permission to withdraw funds from the treasury up to a specified limit.</li>
<li><code>setPerHourAllowance</code>: Assign a per-hour withdrawal limit to an address, allowing them to pull funds from the treasury within this constraint.</li>
<li><code>giveFunds</code>: Move funds from the treasury to a designated address.</li>
<li><code>disableContract</code>: Swiftly transfer all available funds from the contract to a predetermined drainage address.</li>
</ul>
<h3 id="required-authorities-4"><a class="header" href="#required-authorities-4">Required Authorities:</a></h3>
<ul>
<li><strong>Global Settlement</strong>: needs authorization to call <code>disableContract</code>.</li>
</ul>
<h3 id="contract-parameters-7"><a class="header" href="#contract-parameters-7">Contract Parameters:</a></h3>
<ul>
<li><strong>SAFEEngine</strong>: Query and settle the treasury's coin and debt balance.</li>
<li><strong>Extra Surplus Receiver</strong>: Who receives the funds that are above the treasury's capacity (usually Accounting Engine).</li>
<li><strong>CoinJoin</strong>: Used to join ERC20 ZAI into the system.</li>
<li><code>treasuryCapacity</code>: Maximum amount of funds that the treasury can hold (before transferring to the extra surplus receiver).</li>
<li><code>pullFundsMinThreshold</code>: Minimum amount of funds that the treasury must hold to be able to pull funds from it.</li>
<li><code>surplusTransferDelay</code>: Minimum delay between transfers of funds to the extra surplus receiver.</li>
</ul>
<h2 id="3-key-mechanisms--concepts-6"><a class="header" href="#3-key-mechanisms--concepts-6">3. Key Mechanisms & Concepts</a></h2>
<h2 id="4-gotchas-6"><a class="header" href="#4-gotchas-6">4. Gotchas</a></h2>
<h2 id="5-failure-modes-6"><a class="header" href="#5-failure-modes-6">5. Failure Modes</a></h2>
<div style="break-before: page; page-break-before: always;"></div><h1 id="-auction-houses"><a class="header" href="#-auction-houses">❱ Auction Houses</a></h1>
<h2 id="introduction"><a class="header" href="#introduction">Introduction</a></h2>
<p>Auction Houses are core smart contracts in the Azos Protocol that manage debt, surplus, and collateral through automated auctions. Whether you're an active participant or simply interested in ZAI's stability mechanisms, understanding these components is crucial.</p>
<h3 id="types-of-auction-houses"><a class="header" href="#types-of-auction-houses">Types of Auction Houses</a></h3>
<ol>
<li><strong>Collateral Auction House</strong>: Facilitates the sale of confiscated collateral from liquidated SAFEs, aiming to cover associated debts.</li>
<li><strong>Debt Auction House</strong>: Auctions off the system's debt, offering to mint Protocol Tokens as rewards for debt settlement.</li>
<li><strong>Surplus Auction House</strong>: Manages system surplus, conducting auctions (Protocol Tokens buybacks) to distribute excess funds.</li>
</ol>
<p>Understanding these mechanisms is essential for navigating the Azos Protocol's automated balance and risk management features.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="collateral-auction-house"><a class="header" href="#collateral-auction-house">Collateral Auction House</a></h1>
<p>See <a href="detailed/auctions//src/contracts/CollateralAuctionHouse.sol/contract.CollateralAuctionHouse.html">CollateralAuctionHouse.sol</a> for more details.</p>
<h2 id="1-introduction-7"><a class="header" href="#1-introduction-7">1. Introduction</a></h2>
<p>The Collateral Auction House plays a crucial role in maintaining the stability of the Azos Protocol by handling the auction of collateral seized from undercollateralized SAFEs. The primary objective is to convert this confiscated collateral into system coins, which are then forwarded to the Accounting Engine for debt destruction.</p>
<p>The Collateral Auction House utilizes an increasing discount model. This encourages early bidding by incrementally increasing the discount applied to the collateral over time. The rationale behind this is to expedite the auction process and ensure that debts are covered as swiftly as possible.</p>
<h2 id="2-contract-details-7"><a class="header" href="#2-contract-details-7">2. Contract Details</a></h2>
<h3 id="key-methods-7"><a class="header" href="#key-methods-7">Key Methods:</a></h3>
<p><strong>Public</strong></p>
<ul>
<li><code>buyCollateral</code>: Enables holders of the system coin to participate in auctions by purchasing available collateral.</li>
</ul>
<p><strong>Authorized</strong></p>
<ul>
<li><code>startAuction</code>: Initiates a new collateral auction for the contract's specific collateral type.</li>
<li><code>terminateAuctionPrematurely</code>: Allows for the early termination of an ongoing auction, with any remaining collateral allocated to the caller's address.</li>
</ul>
<h3 id="contract-parameters-8"><a class="header" href="#contract-parameters-8">Contract Parameters</a></h3>
<ul>
<li><strong>Liquidation Engine Address</strong>: Specifies the address of the Liquidation Engine, the module responsible for handling the on-auction system coin limit.</li>
<li><strong>Oracle Relayer Address</strong>: Specifies the address of the Oracle Relayer, responsible for providing up-to-date price information.</li>
<li><code>minimumBid</code>: Sets the minimum system coin bid required to participate in collateral auctions.</li>
<li><code>minDiscount</code>: Defines the initial discount rate at which auctions commence.</li>
<li><code>maxDiscount</code>: Sets the upper limit for the discount rate that auctions can achieve.</li>
<li><code>perSecondDiscountUpdateRate</code>: Determines the rate at which the discount increases for each second the auction is live.</li>
</ul>
<h2 id="3-key-mechanisms--concepts-7"><a class="header" href="#3-key-mechanisms--concepts-7">3. Key Mechanisms & Concepts</a></h2>
<h3 id="collateral-price-feed-and-discount-model"><a class="header" href="#collateral-price-feed-and-discount-model">Collateral Price Feed and Discount Model</a></h3>
<p>The Collateral Auction House relies on the system's collateral price feed to determine the current market price of the collateral in terms of system coins. Upon establishing this baseline, the contract employs a dynamic discount model to calculate the auction price of the collateral. Here's how the discount model works:</p>
<ul>
<li>
<p><strong>Initial Discount</strong>: Each auction kicks off with a predefined minimum discount. This discount is set by the <code>minDiscount</code> parameter.</p>
</li>
<li>
<p><strong>Per-Second Discount Rate</strong>: The contract features a rate at which the discount increases on a per-second basis. This rate is determined by the <code>perSecondDiscountUpdateRate</code> parameter.</p>
</li>
<li>
<p><strong>Maximum Discount Cap</strong>: Once the auction reaches the maximum allowable discount, as defined by the <code>maxDiscount</code> parameter, the auction remains at this discount level until either all the collateral is bought or the auction is prematurely terminated.</p>
</li>
</ul>
<p>This approach ensures that the auction starts incentivizing early bids but also allows for adjustments over time, ultimately facilitating efficient price discovery and collateral liquidation.</p>
<h2 id="4-gotchas-7"><a class="header" href="#4-gotchas-7">4. Gotchas</a></h2>
<h2 id="5-failure-modes-7"><a class="header" href="#5-failure-modes-7">5. Failure Modes</a></h2>
<div style="break-before: page; page-break-before: always;"></div><h1 id="debt-auction-house"><a class="header" href="#debt-auction-house">Debt Auction House</a></h1>
<p>See <a href="detailed/auctions//src/contracts/DebtAuctionHouse.sol/contract.DebtAuctionHouse.html">DebtAuctionHouse.sol</a> for more details.</p>
<h2 id="1-introduction-8"><a class="header" href="#1-introduction-8">1. Introduction</a></h2>
<p>The Debt Auction House contract plays a crucial role in the protocol by managing and auctioning off bad debt. To achieve this, the contract mints protocol tokens, which are auctioned off to users in exchange for system coins. These system coins are then used to annihilate the corresponding bad debt from the system.</p>
<p>The Debt Auction House utilizes a descending bidding model. In this model, a predetermined amount of debt is up for auction. Participants bid by specifying how many protocol tokens they are willing to accept in exchange for taking on this debt. As the auction progresses, the number of protocol tokens a bidder is willing to accept decreases, leading to a more favorable exchange rate for the protocol.</p>
<p>This system ensures that bad debts are efficiently cleared from the protocol, while also incentivizing participants to compete for the most favorable exchange rates.</p>
<h2 id="2-contract-details-8"><a class="header" href="#2-contract-details-8">2. Contract Details</a></h2>
<h3 id="key-methods-8"><a class="header" href="#key-methods-8">Key Methods:</a></h3>
<p><strong>Public</strong></p>
<ul>
<li><code>restartAuction</code>: Allows for the resumption of an expired auction that has received no bids. This restarts the auction and increases the initial quantity of protocol tokens to be minted as an incentive for participation.</li>
<li><code>decreaseSoldAmount</code>: Enables users to participate in the auction by bidding. System coins are transferred during this operation.</li>
<li><code>settleAuction</code>: Finalizes an auction, distributing the protocol tokens to the winning bidder.</li>
<li><code>terminateAuctionPrematurely</code>: Ends an auction before its scheduled completion. This method creates an unbacked debt entry in the Accounting Engine and returns the system coins to the highest bidder. Note that this action can only be performed when the contract is disabled.</li>
</ul>
<p><strong>Authorized</strong></p>
<ul>
<li><code>startAuction</code>: Initiates a new debt auction.</li>
</ul>
<h3 id="contract-parameters-9"><a class="header" href="#contract-parameters-9">Contract Parameters:</a></h3>
<ul>
<li><strong>Accounting Engine</strong>: The address of the Accounting Engine contract that handles the system's financial records.</li>
</ul>
<p>These methods and parameters provide a comprehensive control structure for managing bad debt through auctions, balancing both protocol and user interests.</p>
<h2 id="3-key-mechanisms--concepts-8"><a class="header" href="#3-key-mechanisms--concepts-8">3. Key Mechanisms & Concepts</a></h2>
<h2 id="4-gotchas-8"><a class="header" href="#4-gotchas-8">4. Gotchas</a></h2>
<h2 id="5-failure-modes-8"><a class="header" href="#5-failure-modes-8">5. Failure Modes</a></h2>
<div style="break-before: page; page-break-before: always;"></div><h1 id="surplus-auction-house"><a class="header" href="#surplus-auction-house">Surplus Auction House</a></h1>
<p>For more details, refer to the <a href="detailed/auctions//src/contracts/SurplusAuctionHouse.sol/contract.SurplusAuctionHouse.html">SurplusAuctionHouse.sol</a> contract.</p>
<h2 id="1-introduction-9"><a class="header" href="#1-introduction-9">1. Introduction</a></h2>
<p>The Surplus Auction House is tasked with auctioning the system's surplus coins in exchange for protocol tokens. A fraction of these protocol tokens is burnt to create a deflationary effect, while the rest is transferred to a specified target address. The auction employs an ascending bidding model: a fixed number of system coins are up for auction, and participants bid by offering increasingly higher amounts of protocol tokens.</p>
<h2 id="2-contract-details-9"><a class="header" href="#2-contract-details-9">2. Contract Details</a></h2>
<h3 id="key-methods-9"><a class="header" href="#key-methods-9">Key Methods:</a></h3>
<p><strong>Public</strong></p>
<ul>
<li><code>increaseBidSize</code>: Enables users to participate in the auction by offering higher amounts of protocol tokens, which are transferred during this operation.</li>
<li><code>restartAuction</code>: Resets an expired auction that has not received any bids, making it available for new bids.</li>
<li><code>settleAuction</code>: Finalizes the auction, transferring the system coins to the winning bidder.</li>
<li><code>terminateAuctionPrematurely</code>: Aborts an auction before its scheduled completion. This action returns the protocol tokens to the highest bidder but is only possible when the contract is deactivated.</li>
</ul>
<p><strong>Authorized</strong></p>
<ul>
<li><code>startAuction</code>: Initiates a new surplus auction.</li>
</ul>
<h2 id="3-key-mechanisms--concepts-9"><a class="header" href="#3-key-mechanisms--concepts-9">3. Key Mechanisms & Concepts</a></h2>
<h2 id="4-gotchas-9"><a class="header" href="#4-gotchas-9">4. Gotchas</a></h2>
<h2 id="5-failure-modes-9"><a class="header" href="#5-failure-modes-9">5. Failure Modes</a></h2>
<div style="break-before: page; page-break-before: always;"></div><h1 id="-settlement"><a class="header" href="#-settlement">❱ Settlement</a></h1>
<p>The Settlement Module serves as a critical component in the lifecycle of the ZAI protocol, governing its shutdown and the subsequent redemption of ZAI tokens for underlying collateral. It activates in circumstances that necessitate the halting of the system—such as critical bugs, governance decisions, or market anomalies—to ensure a smooth and orderly unwinding of positions. The module's primary objective is to provide a transparent and fair mechanism for redeeming ZAI tokens, thereby ensuring the protocol's integrity even in its termination phase.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="global-settlement"><a class="header" href="#global-settlement">Global Settlement</a></h1>
<p>See <a href="detailed/settlement//src/contracts/settlement/GlobalSettlement.sol/contract.GlobalSettlement.html">GlobalSettlement.sol</a> for more details.</p>
<h2 id="1-introduction-10"><a class="header" href="#1-introduction-10">1. Introduction</a></h2>
<p>The Global Settlement contract serves as the emergency brake and ultimate wind-down mechanism for the system. Its responsibilities include:</p>
<ul>
<li><strong>Triggering the System Shutdown</strong>: Initiating the process to safely halt all operations.</li>
<li><strong>Processing SAFEs</strong>: Settling all Secure, Automated, Flexible, and Efficient (SAFE) accounts to determine each collateral's deficits and surplus.</li>
<li><strong>Terminating Auctions</strong>: Bringing all ongoing auctions to a premature end, ensuring that assets are no longer tied up.</li>
<li><strong>Calculating Redemption Price</strong>: Determining the value at which system coin holders can redeem their coins for backing collateral.</li>
<li><strong>Redemption</strong>: Enabling system coin holders to exchange their coins for the appropriate collateral, completing the shutdown process.</li>
</ul>
<p>This contract is crucial for ensuring that, in the event of a system shutdown, all parties can walk away with assets that are rightfully theirs, thus maintaining a fair and secure environment.</p>
<h2 id="2-contract-details-10"><a class="header" href="#2-contract-details-10">2. Contract Details</a></h2>
<h3 id="key-methods-10"><a class="header" href="#key-methods-10">Key Methods:</a></h3>
<p><strong>Public</strong></p>
<ul>
<li><code>freezeCollateralType</code>: Captures the current market price of a specified collateral type and freezes it within the contract. This is crucial for ensuring accurate valuations during the shutdown process.</li>
<li><code>fastTrackAuction</code>: Allows for the immediate termination of ongoing collateral auctions. This function ensures that assets are returned to their rightful owners as quickly as possible during a shutdown.</li>
<li><code>processSAFE</code>: This method is responsible for settling the debts associated with SAFEs and determining any collateral deficit that exists. This ensures that all assets and liabilities are properly accounted for.</li>
<li><code>freeCollateral</code>: Post-processing of SAFEs, this function enables SAFE owners to withdraw any remaining collateral. This ensures that users recover their tied-up assets.</li>
<li><code>setOutstandingCoinSupply</code>: Sets the global coin supply (which also accounts for the system's debt). This is important for calculating how much collateral can be redeemed for each system coin.</li>
<li><code>calculateCashPrice</code>: Determines the price at which system coin holders can redeem their coins for backing collateral. This provides clarity and fairness in the redemption process.</li>
<li><code>prepareCoinsForRedeeming</code>: Allows system coin holders to deposit their coins into the contract in preparation for redemption. This sets the stage for users to reclaim their backing collateral.</li>
<li><code>redeemCollateral</code>: Executes the redemption process, transferring the appropriate amount of collateral to system coin holders who have previously deposited their coins for redemption. This is the final step in the shutdown and asset recovery process.</li>
</ul>
<p><strong>Authorized</strong></p>
<ul>
<li><code>shutdownSystem</code>: This function triggers the system shutdown, initiating all the processes mentioned above. This function can only be executed by an authorized entity.</li>
</ul>
<p>These methods collectively enable a structured and secure way to halt system operations, settle accounts, and distribute assets in the event of a system shutdown.</p>
<h3 id="contract-parameters-10"><a class="header" href="#contract-parameters-10">Contract Parameters:</a></h3>
<ul>
<li><strong>Oracle Relayer</strong>: The address used to fetch the redemption price and the collaterals price.</li>
<li><strong>Liquidation Engine</strong>: The address used to fetch the collateral auction houses from each collateral type.</li>
<li><strong>Coin Join</strong>: The Coin Join contract (to disable).</li>
<li><strong>Collateral Join Factory</strong>: The Collateral Join Factory contract (to disable).</li>
<li><strong>Collateral Auction House Factory</strong>: The Collateral Auction House Factory contract (to disable).</li>
<li><strong>Stability Fee Treasury</strong>: The Stability Fee Treasury contract, that needs to be disabled before the Accounting Engine to transfer its funds to it.</li>
<li><strong>Accounting Engine</strong>: The Accounting Engine contract, that tries after disablement to settle as much debt as possible, and transfer the remaining surplus to the post settlement drain account.</li>
<li><code>shutdownCooldown</code>: The amount of time that must pass after the system shutdown is triggered before the outstanding coin supply can be calculated.</li>
</ul>
<h2 id="3-key-mechanisms--concepts-10"><a class="header" href="#3-key-mechanisms--concepts-10">3. Key Mechanisms & Concepts</a></h2>
<h3 id="system-shutdown"><a class="header" href="#system-shutdown">System Shutdown</a></h3>
<p>The system shutdown is triggered by calling the <code>shutdownSystem</code> method, that triggers the <code>disableContract</code> method on the disableable contracts (see <a href="detailed/settlement//src/contracts/utils/Disableable.sol/contract.Disableable.html">Disableable.sol</a>). Disableable contracts implement the following tools:</p>
<ul>
<li><code>contractEnabled</code>: A boolean flag that indicates whether the contract is enabled or disabled.</li>
<li><code>_onContractDisable</code> method: A routine that is triggered when the contract is disabled.</li>
<li><code>whenEnabled / whenDisabled</code> modifiers: Modifiers that can be used to restrict the execution of a method to when the contract is enabled or disabled.</li>
</ul>
<h3 id="collateral-redemption-price-calculation"><a class="header" href="#collateral-redemption-price-calculation">Collateral Redemption Price Calculation</a></h3>
<p>The <code>calculateCashPrice</code> method plays a critical role in the Global Settlement contract by determining the rate at which each system coin can be redeemed for its underlying collateral. The method employs a complex formula to arrive at this price, ensuring an equitable distribution of collateral assets based on various dynamic factors.</p>
<p>The formula used to calculate the collateral redemption price (<code>collateralCashPrice</code>) is as follows:</p>
<pre><code>collateralCashPrice =
(
collateralDebt * accumulatedRate / collateralPrice
- collateralShortfall
) / outstandingCoinSupply
</code></pre>
<p><strong>Where</strong>:</p>
<ul>
<li><code>collateralDebt</code>: Represents the aggregate debt associated with a specific collateral type, generated by SAFEs.</li>
<li><code>accumulatedRate</code>: The total accrued rate (like interest or tax rate) applied to the specific collateral type over time.</li>
<li><code>collateralPrice</code>: The most recent market price for the specific collateral type, usually fetched from a trusted oracle.</li>
<li><code>outstandingCoinSupply</code>: The total circulation of system coins, essentially the aggregate debt of the system.</li>
<li><code>collateralShortfall</code>: Quantifies the deficit in terms of system coins for the collateral type.
<blockquote>
<p>If SAFEs for a particular collateral type are under-collateralized, this value will capture the shortfall. Conversely, if SAFEs are over-collateralized, owners are entitled to withdraw the surplus.</p>
</blockquote>
</li>
</ul>
<h4 id="redemption-mechanism"><a class="header" href="#redemption-mechanism">Redemption Mechanism:</a></h4>
<p>Once the <code>collateralCashPrice</code> is calculated, users can redeem their system coins for the backing collateral using the following formula:</p>
<pre><code>redeemableCollateral = coinAmount * collateralCashPrice
</code></pre>
<p>This ensures that each coin is redeemable for a fair portion of collateral, aiming to clear out both coins and collateral from the system by the end of the Global Settlement process.</p>
<blockquote>
<p><strong>Notice</strong>: The design of this formula is such that by the end of the redemption process, the system should ideally have neither excess coins nor remaining collateral. It provides a balanced mechanism for winding down system operations and returning assets to participants.</p>
</blockquote>
<h2 id="4-gotchas-10"><a class="header" href="#4-gotchas-10">4. Gotchas</a></h2>
<h2 id="5-failure-modes-10"><a class="header" href="#5-failure-modes-10">5. Failure Modes</a></h2>
<h3 id="parameters-misconfiguration-5"><a class="header" href="#parameters-misconfiguration-5">Parameters Misconfiguration</a></h3>
<ul>