# Loans positions & total positions

positions 记录某个用户的某个抵押品的债仓, 对应链上存储：`loans.positions`
total positions 记录某个抵押品的总债仓，对应链上存储：`loans.totalPositions`

## 状态变化的关键事件

### 1. `loans.PositionUpdated{owner, collateral_type, collateral_adjustment, debit_adjustment}`

+ 改变 positions: 用户`owner`的`collateral_type`债仓发生变化，抵押品数量变化为`collateral_adjustment`, 债务unit变化为`debit_adjustment`
+ 改变 total positions: `collateral_type` 的总债仓发生上面相应的变化

## positions相关操作历史的统计（与状态变化的统计独立开来）

### 1.债仓调整
判断条件：出现 `loans.PositionUpdated{owner, collateral_type, collateral_adjustment, debit_adjustment}` 事件, 但不同时存在对应 `owner` 和 `collateral_type` 的 `cdpEngine.LiquidateUnsafeCDP` 事件 或 `cdpEngine.CloseCDPInDebitByDEX` 事件

可以判断为 `owner ` 对 `collateral_type ` 的调整操作

### 2. 债仓调整（close by cdp）
判断条件： 出现 `cdpEngine.CloseCDPInDebitByDEX{collateral_type, owner, sold_collateral_amount, refund_collateral_amount, debit_value}` 事件

相关次要事件：同时会出现对应 `owner` 和 `collateral_type` 的 `loans.PositionUpdated` 和 `loans.ConfiscateCollateralAndDebit` 事件

可以判断为 `owner ` 通过Dex 来关掉 `collateral_type ` 债仓， `sold_collateral_amount` 为卖出的抵押物数量， `refund_collateral_amount` 为拿回的抵押物数量， `debit_value` 为卖出抵押物抵消的全部债务价值(aUSD)

### 3. 债仓清算
判断条件：出现 `cdpEngine.LiquidateUnsafeCDP {collateral_type, owner, collateral_amount, bad_debt_value, target_amount` 事件

相关次要事件：同时会出现对应 `owner` 和 `collateral_type` 的 `loans.PositionUpdated` 和 `loans.ConfiscateCollateralAndDebit` 事件

表示 `owner` 和 `collateral_type` 的债仓被清算， `collateral_amount ` 为被清算债仓的抵押品数量， `bad_debt_value ` 为被清算债仓的债务价值(aUSD), `target_amount ` 为债务价值+罚金数量(aUSD)。

清算时，用户可能拿到一些 `collateral_type` 的退款，这种情况下会同时出现 `tokens.Transfer(currency_id == collateral_type， from == CDP_TREAUSY_ACCOUNT, to == collateral_type, , amount)` 或者 `tokens.Transfer(from == CDP_TREAUSY_ACCOUNT, to == collateral_type, amount)` 事件（后者表示抵押物是ACA/KAR的情况）， amount 即为退回给 `owner` 的抵押品数量

### 4. 债仓转移
忽略，前端没有开放这个操作的统计，且链上也几乎没有发生过

# balance & total supply

balance 记录某个账户的某种currency的余额 （余额分为 free 和 reserved）, 对应链上存储：`tokens.accounts` (非ACA/KAR, 非 ERC20 资产)和 `system.accounts.data` （ACA/KAR） 中的 free 和 reserved
total supply 记录某种currency的总量， 对应链上存储：`tokens.totalIssuance` (非ACA/KAR, 非 ERC20 资产)和 `balances.totalIssuance` （ACA/KAR）

## 状态变化的关键事件

### 1. `tokens.Transfer {currency_id, from, to, amount}`
+ 改变 balance:
1. 用户`from `的`currency_id `资产的balance 中 free 减少 `amount`
2. 用户`to`的`currency_id `资产的balance 中 free 增加 `amount`

### 2. `tokens.Deposited { currency_id, who, amount}`
+ 改变 balance: 用户`who `的`currency_id `资产的balance 中 free 增加 `amount`
+ 改变 total supply: `currency_id `资产的总发行量 增加 `amount`

### 3. `tokens.Withdrawn { currency_id, who, amount}`
+ 改变 balance: 用户`who `的`currency_id `资产的balance 中 free 减少 `amount`
+ 改变 total supply: `currency_id `资产的总发行量 减少 `amount`

### 4. `tokens.Reserved { currency_id, who, amount}`
+ 改变 balance: 用户`who `的`currency_id `资产的balance 中 free 减少 `amount`, 同时 reserved 增加 `amount`

### 5. `tokens.Unreserved { currency_id, who, amount}`
+ 改变 balance: 用户`who `的`currency_id `资产的balance 中 free 增加 `amount`, 同时 reserved 减少 `amount`

### 6. `tokens.BalanceSet {currency_id, who, free, reserved}`
+ 改变 balance: 用户`who `的 `currency_id `资产的balance 中 free 被重置为 `free`, reserved 被重置为 `reserved `

### 7. `tokens.TotalIssuanceSet {currency_id, amount}`
+ 改变 total supply: `currency_id `资产的总发行量被 重置为 `amount`

### 8. `tokens.Slashed {currency_id, free_amount, reserved_amount}`
+ 改变 balance: 用户`who `的 `currency_id `资产的balance中 free 减少 `free_amount `, reserved 减少 `reserved_amount `
+ 改变 total supply: `currency_id `资产的总发行量 减少 (`free_amount ` + `reserved_amount`)

### 9. `tokens.ReserveRepatriated {currency_id, from, to, amount, status}`
+ 改变 balance:
1. 用户 `to ` 的 `currency_id`资产的balance 中 reserved 增加 `amount `
2. 用户 `from` 的 `currency_id`资产的balance 中 ， 如果 `stats` == `BalanceStatus::Free` , free 减少 `amount` ； 如果是 `stats` == `BalanceStatus::Reserved` ， 则是 reserved 减少 `amount`

### 10. `balances.Deposit {who, amount}`
+ 改变 balance: 用户 `who` 的 ACA/KAR 资产的 balance 中， free 增加 `amount`
+ 改变 total supply: ACA/KAR 资产的总发行量 增加 `amount`

### 11. `balances.Withdraw {who, amount}`
+ 改变 balance: 用户 `who` 的 ACA/KAR 资产的 balance 中， free 减少 `amount`
+ 改变 total supply: ACA/KAR 资产的总发行量 减少 `amount`

### 12. `balances.Transfer {from, to, amount}`
+ 改变 balance:
1. 用户`from `的 ACA/KAR 资产的balance 中 free 减少 `amount`
2. 用户`to`的 ACA/KAR 资产的balance 中 free 增加 `amount`

### 13. `balances.BalanceSet { who, free, reserved}`
+ 改变 balance: 用户`who `的 ACA/KAR 资产的balance 中 free 被重置为 `free`, reserved 被重置为 `reserved `

### 14. `balances.Reserved {who, amount}`
+ 改变 balance: 用户`who `的ACA/KAR资产的balance 中 free 减少 `amount`, 同时 reserved 增加 `amount`

### 15. `balances.Unreserved {who, amount}`
+ 改变 balance: 用户`who `的ACA/KAR资产的balance 中 free 增加 `amount`, 同时 reserved 减少 `amount`

### 16. `balances.ReserveRepatriated {from, to, amount, destination_status}`
+ 改变 balance:
1. 用户 `from` 的 ACA/KAR资产的balance 中 reserved 减少 `amount `
2. 用户 `to` 的 ACA/KAR 资产的balance 中 ， 如果 `destination_status ` == `Status::Free` , free 增加 `amount`； 如果是 `destination_status ` == `Status::Reserved` ， 则是 reserved 增加 `amount`

> 注意，这里和tokens.ReserveRepatriated 的行为不同

### 17. `balances. DustLost {account, amount}`
+ 改变 balance: 用户`who `的ACA/KAR资产的balance 中 free 和 reserved 重置为 0 （实际上 原来的free + reserved 刚好等于 `amount`）
+ 改变 total supply: ACA/KAR 资产的总发行量 减少 `amount`