Skip to content

Commit 4dae3c2

Browse files
danielattilasimondanielattilasimon
authored
Merge pull request #338 from liquity/trove-status
Proposal to extend the Status type in TroveManager to be able to tell why a Trove was closed
2 parents 0c410cc + b807d0f commit 4dae3c2

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+440
-265
lines changed

‎docs/sdk/lib-base.liquitystorederivedstate.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,5 +20,5 @@ export interface LiquityStoreDerivedState
2020
| [fees](./lib-base.liquitystorederivedstate.fees.md) | [Fees](./lib-base.fees.md) | Calculator for current fees. |
2121
| [haveUndercollateralizedTroves](./lib-base.liquitystorederivedstate.haveundercollateralizedtroves.md) | boolean | Whether there are any Troves with collateral ratio below the [minimum](./lib-base.minimum_collateral_ratio.md)<!-- -->. |
2222
| [redemptionRate](./lib-base.liquitystorederivedstate.redemptionrate.md) | [Decimal](./lib-base.decimal.md) | Current redemption rate. |
23-
| [trove](./lib-base.liquitystorederivedstate.trove.md) | [Trove](./lib-base.trove.md) | Current state of user's Trove |
23+
| [trove](./lib-base.liquitystorederivedstate.trove.md) | [UserTrove](./lib-base.usertrove.md) | Current state of user's Trove |
2424

‎docs/sdk/lib-base.liquitystorederivedstate.trove.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,5 +9,5 @@ Current state of user's Trove
99
<b>Signature:</b>
1010

1111
```typescript
12-
trove: Trove;
12+
trove: UserTrove;
1313
```

‎docs/sdk/lib-base.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
| [TransactionFailedError](./lib-base.transactionfailederror.md) | Thrown by [TransactableLiquity](./lib-base.transactableliquity.md) functions in case of transaction failure. |
1717
| [Trove](./lib-base.trove.md) | A combination of collateral and debt. |
1818
| [TroveWithPendingRedistribution](./lib-base.trovewithpendingredistribution.md) | A Trove in its state after the last direct modification. |
19+
| [UserTrove](./lib-base.usertrove.md) | A Trove that is associated with a single owner. |
1920

2021
## Interfaces
2122

@@ -73,4 +74,5 @@
7374
| [TroveClosureParams](./lib-base.troveclosureparams.md) | Parameters of a [closeTrove()](./lib-base.transactableliquity.closetrove.md) transaction. |
7475
| [TroveCreationError](./lib-base.trovecreationerror.md) | Describes why a Trove could not be created. |
7576
| [TroveCreationParams](./lib-base.trovecreationparams.md) | Parameters of an [openTrove()](./lib-base.transactableliquity.opentrove.md) transaction. |
77+
| [UserTroveStatus](./lib-base.usertrovestatus.md) | Represents whether a UserTrove is open or not, or why it was closed. |
7678

‎docs/sdk/lib-base.readableliquity.gettrove.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Get the current state of a Trove.
99
<b>Signature:</b>
1010

1111
```typescript
12-
getTrove(address?: string): Promise<Trove>;
12+
getTrove(address?: string): Promise<UserTrove>;
1313
```
1414

1515
## Parameters
@@ -20,5 +20,5 @@ getTrove(address?: string): Promise<Trove>;
2020

2121
<b>Returns:</b>
2222

23-
Promise&lt;[Trove](./lib-base.trove.md)<!-- -->&gt;
23+
Promise&lt;[UserTrove](./lib-base.usertrove.md)<!-- -->&gt;
2424

‎docs/sdk/lib-base.readableliquity.gettroves_1.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Get a slice from the list of Troves.
99
<b>Signature:</b>
1010

1111
```typescript
12-
getTroves(params: TroveListingParams): Promise<[address: string, trove: Trove][]>;
12+
getTroves(params: TroveListingParams): Promise<UserTrove[]>;
1313
```
1414

1515
## Parameters
@@ -20,7 +20,7 @@ getTroves(params: TroveListingParams): Promise<[address: string, trove: Trove][]
2020

2121
<b>Returns:</b>
2222

23-
Promise&lt;\[address: string, trove: [Trove](./lib-base.trove.md)<!-- -->\]\[\]&gt;
23+
Promise&lt;[UserTrove](./lib-base.usertrove.md)<!-- -->\[\]&gt;
2424

2525
Pairs of owner addresses and their Troves.
2626

‎docs/sdk/lib-base.trovewithpendingredistribution._constructor_.md

Lines changed: 0 additions & 23 deletions
This file was deleted.

‎docs/sdk/lib-base.trovewithpendingredistribution.applyredistribution.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
<b>Signature:</b>
88

99
```typescript
10-
applyRedistribution(totalRedistributed: Trove): Trove;
10+
applyRedistribution(totalRedistributed: Trove): UserTrove;
1111
```
1212

1313
## Parameters
@@ -18,5 +18,5 @@ applyRedistribution(totalRedistributed: Trove): Trove;
1818

1919
<b>Returns:</b>
2020

21-
[Trove](./lib-base.trove.md)
21+
[UserTrove](./lib-base.usertrove.md)
2222

‎docs/sdk/lib-base.trovewithpendingredistribution.md

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,19 +9,15 @@ A Trove in its state after the last direct modification.
99
<b>Signature:</b>
1010

1111
```typescript
12-
export declare class TroveWithPendingRedistribution extends Trove
12+
export declare class TroveWithPendingRedistribution extends UserTrove
1313
```
14-
<b>Extends:</b> [Trove](./lib-base.trove.md)
14+
<b>Extends:</b> [UserTrove](./lib-base.usertrove.md)
1515
1616
## Remarks
1717
1818
The Trove may have received collateral and debt shares from liquidations since then. Use [applyRedistribution()](./lib-base.trovewithpendingredistribution.applyredistribution.md) to calculate the Trove's most up-to-date state.
1919
20-
## Constructors
21-
22-
| Constructor | Modifiers | Description |
23-
| --- | --- | --- |
24-
| [(constructor)(collateral, debt, stake, snapshotOfTotalRedistributed)](./lib-base.trovewithpendingredistribution._constructor_.md) | | Constructs a new instance of the <code>TroveWithPendingRedistribution</code> class |
20+
The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `TroveWithPendingRedistribution` class.
2521
2622
## Methods
2723

‎docs/sdk/lib-base.usertrove.equals.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@liquity/lib-base](./lib-base.md) &gt; [UserTrove](./lib-base.usertrove.md) &gt; [equals](./lib-base.usertrove.equals.md)
4+
5+
## UserTrove.equals() method
6+
7+
<b>Signature:</b>
8+
9+
```typescript
10+
equals(that: UserTrove): boolean;
11+
```
12+
13+
## Parameters
14+
15+
| Parameter | Type | Description |
16+
| --- | --- | --- |
17+
| that | [UserTrove](./lib-base.usertrove.md) | |
18+
19+
<b>Returns:</b>
20+
21+
boolean
22+

‎docs/sdk/lib-base.usertrove.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@liquity/lib-base](./lib-base.md) &gt; [UserTrove](./lib-base.usertrove.md)
4+
5+
## UserTrove class
6+
7+
A Trove that is associated with a single owner.
8+
9+
<b>Signature:</b>
10+
11+
```typescript
12+
export declare class UserTrove extends Trove
13+
```
14+
<b>Extends:</b> [Trove](./lib-base.trove.md)
15+
16+
## Remarks
17+
18+
The SDK uses the base [Trove](./lib-base.trove.md) class as a generic container of collateral and debt, for example to represent the [total collateral and debt](./lib-base.readableliquity.gettotal.md) locked up in the protocol.
19+
20+
The `UserTrove` class extends `Trove` with extra information that's only available for Troves that are associated with a single owner (such as the owner's address, or the Trove's status).
21+
22+
The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `UserTrove` class.
23+
24+
## Properties
25+
26+
| Property | Modifiers | Type | Description |
27+
| --- | --- | --- | --- |
28+
| [ownerAddress](./lib-base.usertrove.owneraddress.md) | | string | Address that owns this Trove. |
29+
| [status](./lib-base.usertrove.status.md) | | [UserTroveStatus](./lib-base.usertrovestatus.md) | Provides more information when the UserTrove is empty. |
30+
31+
## Methods
32+
33+
| Method | Modifiers | Description |
34+
| --- | --- | --- |
35+
| [equals(that)](./lib-base.usertrove.equals.md) | | |
36+

‎docs/sdk/lib-base.usertrove.owneraddress.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@liquity/lib-base](./lib-base.md) &gt; [UserTrove](./lib-base.usertrove.md) &gt; [ownerAddress](./lib-base.usertrove.owneraddress.md)
4+
5+
## UserTrove.ownerAddress property
6+
7+
Address that owns this Trove.
8+
9+
<b>Signature:</b>
10+
11+
```typescript
12+
readonly ownerAddress: string;
13+
```

‎docs/sdk/lib-base.usertrove.status.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@liquity/lib-base](./lib-base.md) &gt; [UserTrove](./lib-base.usertrove.md) &gt; [status](./lib-base.usertrove.status.md)
4+
5+
## UserTrove.status property
6+
7+
Provides more information when the UserTrove is empty.
8+
9+
<b>Signature:</b>
10+
11+
```typescript
12+
readonly status: UserTroveStatus;
13+
```

‎docs/sdk/lib-base.usertrovestatus.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@liquity/lib-base](./lib-base.md) &gt; [UserTroveStatus](./lib-base.usertrovestatus.md)
4+
5+
## UserTroveStatus type
6+
7+
Represents whether a UserTrove is open or not, or why it was closed.
8+
9+
<b>Signature:</b>
10+
11+
```typescript
12+
export declare type UserTroveStatus = "nonExistent" | "open" | "closedByOwner" | "closedByLiquidation" | "closedByRedemption";
13+
```

‎docs/sdk/lib-ethers.ethersliquity.gettrove.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Get the current state of a Trove.
99
<b>Signature:</b>
1010

1111
```typescript
12-
getTrove(address?: string, overrides?: EthersCallOverrides): Promise<Trove>;
12+
getTrove(address?: string, overrides?: EthersCallOverrides): Promise<UserTrove>;
1313
```
1414

1515
## Parameters
@@ -21,5 +21,5 @@ getTrove(address?: string, overrides?: EthersCallOverrides): Promise<Trove>;
2121

2222
<b>Returns:</b>
2323

24-
Promise&lt;[Trove](./lib-base.trove.md)<!-- -->&gt;
24+
Promise&lt;[UserTrove](./lib-base.usertrove.md)<!-- -->&gt;
2525

‎docs/sdk/lib-ethers.ethersliquity.gettroves_1.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Get a slice from the list of Troves.
99
<b>Signature:</b>
1010

1111
```typescript
12-
getTroves(params: TroveListingParams, overrides?: EthersCallOverrides): Promise<[address: string, trove: Trove][]>;
12+
getTroves(params: TroveListingParams, overrides?: EthersCallOverrides): Promise<UserTrove[]>;
1313
```
1414

1515
## Parameters
@@ -21,7 +21,7 @@ getTroves(params: TroveListingParams, overrides?: EthersCallOverrides): Promise<
2121

2222
<b>Returns:</b>
2323

24-
Promise&lt;\[address: string, trove: [Trove](./lib-base.trove.md)<!-- -->\]\[\]&gt;
24+
Promise&lt;[UserTrove](./lib-base.usertrove.md)<!-- -->\[\]&gt;
2525

2626
Pairs of owner addresses and their Troves.
2727

‎docs/sdk/lib-ethers.readableethersliquity.gettrove.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Get the current state of a Trove.
99
<b>Signature:</b>
1010

1111
```typescript
12-
getTrove(address?: string, overrides?: EthersCallOverrides): Promise<Trove>;
12+
getTrove(address?: string, overrides?: EthersCallOverrides): Promise<UserTrove>;
1313
```
1414

1515
## Parameters
@@ -21,5 +21,5 @@ getTrove(address?: string, overrides?: EthersCallOverrides): Promise<Trove>;
2121

2222
<b>Returns:</b>
2323

24-
Promise&lt;[Trove](./lib-base.trove.md)<!-- -->&gt;
24+
Promise&lt;[UserTrove](./lib-base.usertrove.md)<!-- -->&gt;
2525

‎docs/sdk/lib-ethers.readableethersliquity.gettroves_1.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Get a slice from the list of Troves.
99
<b>Signature:</b>
1010

1111
```typescript
12-
getTroves(params: TroveListingParams, overrides?: EthersCallOverrides): Promise<[address: string, trove: Trove][]>;
12+
getTroves(params: TroveListingParams, overrides?: EthersCallOverrides): Promise<UserTrove[]>;
1313
```
1414

1515
## Parameters
@@ -21,7 +21,7 @@ getTroves(params: TroveListingParams, overrides?: EthersCallOverrides): Promise<
2121

2222
<b>Returns:</b>
2323

24-
Promise&lt;\[address: string, trove: [Trove](./lib-base.trove.md)<!-- -->\]\[\]&gt;
24+
Promise&lt;[UserTrove](./lib-base.usertrove.md)<!-- -->\[\]&gt;
2525

2626
Pairs of owner addresses and their Troves.
2727

‎packages/contracts/contracts/BorrowerOperations.sol

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -73,10 +73,6 @@ contract BorrowerOperations is LiquityBase, Ownable, CheckContract, IBorrowerOpe
7373
enum BorrowerOperation {
7474
openTrove,
7575
closeTrove,
76-
addColl,
77-
withdrawColl,
78-
withdrawLUSD,
79-
repayLUSD,
8076
adjustTrove
8177
}
8278

‎packages/contracts/contracts/TroveManager.sol

Lines changed: 19 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,13 @@ contract TroveManager is LiquityBase, Ownable, CheckContract, ITroveManager {
6060
// The timestamp of the latest fee operation (redemption or new LUSD issuance)
6161
uint public lastFeeOperationTime;
6262

63-
enum Status { nonExistent, active, closed }
63+
enum Status {
64+
nonExistent,
65+
active,
66+
closedByOwner,
67+
closedByLiquidation,
68+
closedByRedemption
69+
}
6470

6571
// Store the necessary data for a trove
6672
struct Trove {
@@ -332,7 +338,7 @@ contract TroveManager is LiquityBase, Ownable, CheckContract, ITroveManager {
332338
singleLiquidation.debtToRedistribute,
333339
singleLiquidation.collToRedistribute) = _getOffsetAndRedistributionVals(singleLiquidation.entireTroveDebt, collToLiquidate, _LUSDInStabPool);
334340

335-
_closeTrove(_borrower);
341+
_closeTrove(_borrower, Status.closedByLiquidation);
336342
emit TroveLiquidated(_borrower, singleLiquidation.entireTroveDebt, singleLiquidation.entireTroveColl, TroveManagerOperation.liquidateInNormalMode);
337343
emit TroveUpdated(_borrower, 0, 0, 0, TroveManagerOperation.liquidateInNormalMode);
338344
return singleLiquidation;
@@ -372,7 +378,7 @@ contract TroveManager is LiquityBase, Ownable, CheckContract, ITroveManager {
372378
singleLiquidation.debtToRedistribute = singleLiquidation.entireTroveDebt;
373379
singleLiquidation.collToRedistribute = vars.collToLiquidate;
374380

375-
_closeTrove(_borrower);
381+
_closeTrove(_borrower, Status.closedByLiquidation);
376382
emit TroveLiquidated(_borrower, singleLiquidation.entireTroveDebt, singleLiquidation.entireTroveColl, TroveManagerOperation.liquidateInRecoveryMode);
377383
emit TroveUpdated(_borrower, 0, 0, 0, TroveManagerOperation.liquidateInRecoveryMode);
378384

@@ -386,7 +392,7 @@ contract TroveManager is LiquityBase, Ownable, CheckContract, ITroveManager {
386392
singleLiquidation.debtToRedistribute,
387393
singleLiquidation.collToRedistribute) = _getOffsetAndRedistributionVals(singleLiquidation.entireTroveDebt, vars.collToLiquidate, _LUSDInStabPool);
388394

389-
_closeTrove(_borrower);
395+
_closeTrove(_borrower, Status.closedByLiquidation);
390396
emit TroveLiquidated(_borrower, singleLiquidation.entireTroveDebt, singleLiquidation.entireTroveColl, TroveManagerOperation.liquidateInRecoveryMode);
391397
emit TroveUpdated(_borrower, 0, 0, 0, TroveManagerOperation.liquidateInRecoveryMode);
392398
/*
@@ -402,7 +408,7 @@ contract TroveManager is LiquityBase, Ownable, CheckContract, ITroveManager {
402408
_removeStake(_borrower);
403409
singleLiquidation = _getCappedOffsetVals(singleLiquidation.entireTroveDebt, singleLiquidation.entireTroveColl, _price);
404410

405-
_closeTrove(_borrower);
411+
_closeTrove(_borrower, Status.closedByLiquidation);
406412
if (singleLiquidation.collSurplus > 0) {
407413
collSurplusPool.accountSurplus(_borrower, singleLiquidation.collSurplus);
408414
}
@@ -822,7 +828,7 @@ contract TroveManager is LiquityBase, Ownable, CheckContract, ITroveManager {
822828
if (newDebt == LUSD_GAS_COMPENSATION) {
823829
// No debt left in the Trove (except for the gas compensation), therefore the trove gets closed
824830
_removeStake(_borrower);
825-
_closeTrove(_borrower);
831+
_closeTrove(_borrower, Status.closedByRedemption);
826832
_redeemCloseTrove(_contractsCache, _borrower, LUSD_GAS_COMPENSATION, newColl);
827833
emit TroveUpdated(_borrower, 0, 0, 0, TroveManagerOperation.redeemCollateral);
828834

@@ -1223,14 +1229,16 @@ contract TroveManager is LiquityBase, Ownable, CheckContract, ITroveManager {
12231229

12241230
function closeTrove(address _borrower) external override {
12251231
_requireCallerIsBorrowerOperations();
1226-
return _closeTrove(_borrower);
1232+
return _closeTrove(_borrower, Status.closedByOwner);
12271233
}
12281234

1229-
function _closeTrove(address _borrower) internal {
1235+
function _closeTrove(address _borrower, Status closedStatus) internal {
1236+
assert(closedStatus != Status.nonExistent && closedStatus != Status.active);
1237+
12301238
uint TroveOwnersArrayLength = TroveOwners.length;
12311239
_requireMoreThanOneTroveInSystem(TroveOwnersArrayLength);
12321240

1233-
Troves[_borrower].status = Status.closed;
1241+
Troves[_borrower].status = closedStatus;
12341242
Troves[_borrower].coll = 0;
12351243
Troves[_borrower].debt = 0;
12361244

@@ -1286,8 +1294,9 @@ contract TroveManager is LiquityBase, Ownable, CheckContract, ITroveManager {
12861294
* [A B C D E] => [A E C D], and updates E's Trove struct to point to its new array index.
12871295
*/
12881296
function _removeTroveOwner(address _borrower, uint TroveOwnersArrayLength) internal {
1297+
Status troveStatus = Troves[_borrower].status;
12891298
// It’s set in caller function `_closeTrove`
1290-
assert(Troves[_borrower].status == Status.closed);
1299+
assert(troveStatus != Status.nonExistent && troveStatus != Status.active);
12911300

12921301
uint128 index = Troves[_borrower].arrayIndex;
12931302
uint length = TroveOwnersArrayLength;

0 commit comments

Comments
 (0)