# Charged Particles Contract

## Get Contract Info

> ***Get Info about the Contract, its Settings, and its State.***

### getStateAddress

```d
function getStateAddress() 
    external 
    view 
    virtual 
    override 
    returns (address stateAddress);
```

Gets the address of the Charged-State contract, which can be used for setting and retrieving additional information about a Particle (NFT) contract. E.g. time locks on particle mass (principal) or charge (interest).

| Parameter/Return Value | Description                       |
| ---------------------- | --------------------------------- |
| settingsAddress        | address of Charged State contract |

### getSettingsAddress

```d
function getSettingsAddress() 
    external
    view
    virtual
    override 
    returns (address settingsAddress);
```

Gets the address of the ChargedSettings contract, which can be used for setting and retrieving the settings of the ChargedParticles contract. E.g. Creator annuity.

When Custom Contracts are registered, only the "owner" or operator of the Contract is allowed to register them and define custom rules for how their tokens are "Charged". Otherwise, any token can be "Charged" according to the default rules of Charged Particles.

| Parameter/Return Value | Description                          |
| ---------------------- | ------------------------------------ |
| settingsAddress        | address of Charged Settings contract |

### onERC721Received

Part of the ERC721 standard. Required for any contract that receives ERC-721 tokens. See [Open Zeppelin](https://docs.openzeppelin.com/contracts/3.x/api/token/erc721#IERC721Receiver) for more detail.

```d
function onERC721Received(
  address, 
  address,
  uint256, 
  bytes calldata
) external virtual override returns (bytes4);
```

## Get Particle balances

> ***Get Particle Mass (principal) and Charge (interest) balances.***

### baseParticleMass

Gets the amount of Mass (principal) for a Particle for a single asset token. E.g. Returns the amount of USDC deposited into a Particle less earned interest.

```d
function baseParticleMass(
  address contractAddress, 
  uint256 tokenId, 
  string walletManagerId,
  address assetToken
) external virtual override managerEnabled(walletManagerId) returns (uint256);
```

| Parameter/Return Value | Description                                       |
| ---------------------- | ------------------------------------------------- |
| contractAddress        | Charged Particles contract address                |
| tokenId                | id of Particle                                    |
| walletManagerId        | id of Wallet Manager for yield source             |
| assetToken             | address of token to get mass of e.g. DAI          |
| return                 | Amount of underlying Assets held within the Token |

### currentParticleCharge

Gets the amount of Interest that the Particle has generated representing the Charge (interest) of the Particle.

```d
function currentParticleCharge(
  address contractAddress,
  uint256 tokenId,
  string walletManagerId, 
  address assetToken
) external virtual override managerEnabled(walletManagerId) (uint256);
```

| Parameter/Return Value | Description                                                     |
| ---------------------- | --------------------------------------------------------------- |
| contractAddress        | contract address for Particle                                   |
| tokenId                | id of Particle                                                  |
| walletManagerId        | id of Wallet Manager for yield source (e.g. Aave)               |
| assetToken             | address of asset token to check (e.g. DAI)                      |
| return                 | The amount of interest the Token has generated (in asset token) |

### currentParticleKinetics

Gets the amount of LP Tokens that the Particle has generated representing the Kinetics of the Particle.

Kinetics represent additional tokens that a lending protocol provides users in addition to the interest-bearing asset. For example, when a user deposits into Compound, they receive a [cToken](https://compound.finance/docs/ctokens) representing their interest-bearing position, as well as [COMP tokens](https://compound.finance/docs/governance#comp). COMP tokens are the Kinetics in this example.

```d
function currentParticleKinetics(
  address contractAddress,
  uint256 tokenId,
  string walletManagerId,
  address assetToken
) external virtual override managerEnabled(walletManagerId) (uint256);
```

| Parameter/Return Value | Description                                        |
| ---------------------- | -------------------------------------------------- |
| contractAddress        | contract address for Particle                      |
| tokenId                | id of Particle                                     |
| walletManagerId        | id of BasketManager to check the token balance of  |
| return                 | total amount of LP tokens that have been generated |

### currentParticleCovalentBonds

Gets the total amount of ERC721 Tokens that the Particle holds.

```d
function currentParticleCovalentBonds(
  address contractAddress,
  uint256 tokenId,
  string basketManagerId
) external view virtual override basketEnabled(basketManagerId) returns (uint256);
```

| Parameter/Return Value | Description                                        |
| ---------------------- | -------------------------------------------------- |
| contractAddress        | contract address for Particle                      |
| tokenId                | id of Particle                                     |
| basektManagerId        | id of BasketManager to check the token balance of  |
| return                 | total amount of ERC721 tokens held within particle |

## Charge & Discharge Particles

> ***Deposit Principal and Withdraw Interest from Particles.***

### energizeParticle

Fund Particle with Asset Token. Must be called by the account providing the Asset. Account must Approve Charged Particles contract as Operator of Asset.

```d
function energizeParticle(
  address contractAddress,
  uint256 tokenId,
  string walletManagerId,
  address assetToken,
  uint256 assetAmount,
  address referrer
) external virtual override managerEnabled(walletManagerId nonReentrant returns (uint256 yieldTokensAmount);
```

| Parameter/Return Value | Description                                                                      |
| ---------------------- | -------------------------------------------------------------------------------- |
| contractAddress        | contract address for Particle                                                    |
| tokenId                | id of Particle                                                                   |
| walletManagerId        | id of Wallet Manager for token                                                   |
| assetToken             | address of asset-token being used (e.g. DAI)                                     |
| referrer               | referrer \*used for an internal feature that has yet to be implemented -- ignore |
| assetAmount            | amount of asset token to energize token with                                     |
| yieldTokensAmount      | amount of yield-bearing tokens added to escrow for the token                     |

### dischargeParticle

Allows the owner or operator of the Particle to collect or transfer the Charge (interest) generated from the token without removing the Mass (principal) of the underlying asset held within the token.

```d
function dischargeParticle(
  address receiver,
  address contractAddress,
  uint256 tokenId,
  string walletManagerId,
  address assetToken
) external virtual override managerEnabled(walletManagerId) nonReentrant returns (uint256 creatorAmount, uint256 receiverAmount);`
```

| Parameter/Return Value | Description                                                  |
| ---------------------- | ------------------------------------------------------------ |
| receiver               | address to receive discharged asset                          |
| contractAddress        | contract address for Particle                                |
| tokenId                | id of Particle                                               |
| walletManagerId        | wallet manager of assets to discharge from token (e.g. Aave) |
| assetToken             | address of asset-token being discharged (e.g. DAI)           |
| creatorAmount          | amount of asset token to discharge for creator               |
| receiverAmount         | amount of asset token to discharge for receiver              |

### dischargeParticleAmount

Allows the owner or operator of the Particle to collect or transfer a specific amount of the interest generated from the token without removing the Mass (principal) of the underlying asset held within the token.

```d
function dischargeParticleAmount(
  address receiver,
  address contractAddress,
  uint256 tokenId,
  string calldata walletManagerId,
  address assetToken,
  uint256 assetAmount
) external virtual override managerEnabled(walletManagerId) nonReentrant returns (uint256 creatorAmount, uint256 receiverAmount);
```

| Parameter/Return Value | Description                                                  |
| ---------------------- | ------------------------------------------------------------ |
| receiver               | address to receive discharged asset                          |
| contractAddress        | contract address for Particle                                |
| tokenId                | id of Particle                                               |
| walletManagerId        | wallet manager of assets to discharge from token (e.g. Aave) |
| assetToken             | address of asset-token being discharged (e.g. DAI)           |
| assetAmount            | specific amount of asset token to discharge                  |
| creatorAmount          | amount of asset token to discharge for creator               |
| receiverAmount         | amount of asset token to discharge for receiver              |

### dischargeParticleForCreator

Allows the Creator of the Particle to collect or transfer a their portion of the Charge (interest) generated from the token without removing the underlying Mass (principal) held within the token.

```d
function dischargeParticleForCreator(
  address receiver,
  address contractAddress,
  uint256 tokenId,
  string walletManagerId,
  address assetToken,
  uint256 assetAmount
)  external virtual override managerEnabled(walletMangerId) nonReentrant returns (uint256 receiverAmount);
```

| Parameter/Return Value | Description                                                  |
| ---------------------- | ------------------------------------------------------------ |
| receiver               | address to receive discharged asset                          |
| contractAddress        | contract address for Particle                                |
| tokenId                | id of Particle                                               |
| walletManagerId        | wallet manager of assets to discharge from token (e.g. Aave) |
| assetToken             | address of asset-token being discharged (e.g. DAI)           |
| assetAmount            | specific amount of asset token to discharge                  |
| receiverAmount         | amount of asset token to discharge for receiver              |

## Release Particles

> ***Withdraw principal from particles.***

### releaseParticle

Releases the Full amount of Mass + Charge (principal + interest) held within the Particle by LP of the Assets.

```d
function releaseParticle(
  address receiver,
  address contractAddress,
  uint256 tokenId,
  string walletManagerId,
  address assetToken
) external virtual override managerEnabled(walletMangerId) nonReentrant returns (uint256 creatorAmount, uint256 receiverAmount)
```

| Parameter/Return Value | Description                                                              |
| ---------------------- | ------------------------------------------------------------------------ |
| receiver               | address to receive released asset tokens                                 |
| contractAddress        | contract address for Particle                                            |
| tokenId                | id of Particle                                                           |
| walletManagerId        | wallet manager of assets to discharge from token (e.g. Aave)             |
| assetToken             | address of asset-token being released (e.g. DAI)                         |
| creatorAmount          | amount of asset token released to creator                                |
| receiverAmount         | amount of asset token to released to receiver (includes principalAmount) |

### releaseParticleAmount

Releases a partial amount of Mass + Charge (principal + interest) held within the Particle by LP of the Assets.

```d
function releaseParticleAmount(
  address receiver,
  address contractAddress,
  uint256 tokenId,
  string walletManagerId,
  address assetToken,
  uint256 assetAmount
) external virtual override managerEnabled(walletMangerId) nonReentrant returns (uint256 creatorAmount, uint256 receiverAmount)
```

| Parameter/Return Value | Description                                                              |
| ---------------------- | ------------------------------------------------------------------------ |
| receiver               | address to receive released asset tokens                                 |
| contractAddress        | contract address for Particle                                            |
| tokenId                | id of Particle                                                           |
| walletManagerId        | wallet manager of assets to discharge from token (e.g. Aave)             |
| assetToken             | address of asset-token being released (e.g. DAI)                         |
| assetAmount            | the specific amount of asset token to release from the Particle          |
| creatorAmount          | amount of asset token released to creator                                |
| receiverAmount         | amount of asset token to released to receiver (includes principalAmount) |

## Covalent Bonding

> ***Deposit & Withdraw ERC721s from a Particle.***

### covalentBond

Deposit other NFT Assets into a Particle. Must be called by the account providing the Asset. Account must Approve THIS contract as Operator of Asset.

```d
function covalentBond(
  address contractAddress,
  uint256 tokenId,
  string basketManagerId,
  address nftTokenAddress,
  uint256 nftTokenId
) external virtual override basketEnabled(basketManagerId) nonReentrant returns (bool success)
```

| Parameter/Return Value | Description                                       |
| ---------------------- | ------------------------------------------------- |
| contractAddress        | contract address for Particle                     |
| tokenId                | id of Particle                                    |
| basketManagerId        | the basket to deposit the NFT into                |
| nftTokenAddress        | the address of the NFT token being deposited      |
| nftTokenId             | the id of the NFT token being deposited           |
| return                 | true or false depending on success of transaction |

### breakCovalentBond

Release NFT Assets from the Particle.

```d
function breakCovalentBond(
  address receiver,
  address contractAddress,
  uint256 tokenId,
  string calldata basketManagerId,
  address nftTokenAddress,
  uint256 nftTokenId
) external virtual override basketEnabled(basketManagerId) nonReentrant returns (bool success)
```

| Parameter/Return Value | Description                                       |
| ---------------------- | ------------------------------------------------- |
| receiver               | the address to receive the released NFTs          |
| contractAddress        | contract address for Particle                     |
| tokenId                | id of Particle                                    |
| basketManagerId        | the basket to deposit the NFT into                |
| nftTokenAddress        | the address of the NFT token being released       |
| nftTokenId             | the id of the NFT token being released            |
| return                 | true or false depending on success of transaction |

## Other

### Events

**UniverseSet**

```erlang
event UniverseSet(address indexed universeAddress);
```

**ChargedStateSet**

```erlang
event ChargedStateSet(address indexed chargedState);
```

**ChargedSettingsSet**

```erlang
event ChargedSettingsSet(address indexed chargedSettings);
```

**LeptonTokenSet**

```erlang
event LeptonTokenSet(address indexed leptonToken);
```

### Wallet / Basket Manager IDs:

| **Manager**                           | **Manager ID** |
| ------------------------------------- | -------------- |
| Generic ERC20s (non-interest-earning) | 'generic'      |
| ERC721s & ERC1155s                    | 'generic'      |
| Aave ERC20s (interest-earning)        | 'aave'         |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.charged.fi/charged-particles-protocol/developing-on-the-protocol/smart-contracts/v1/smart-contracts-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.