> For the complete documentation index, see [llms.txt](https://docs.mercurydata.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mercurydata.app/retroshades/get-started/writing-and-emitting-retroshades.md).

# Writing and Emitting Retroshades

As promised, this section is very short, because there's little to know about Retroshades: it's all Soroban code!

The only concept that you need to keep in mind is that the retroshade logic within your contract is not metered on chain, and you are not paying any extra fees by adding Retroshade logic to your code. In fact, you can write retroshades for contracts that are already deployed and you don't need to perform any kind of action on-chain.

The contracts compiled with the mercury feature can be directly deployed to Mercury's retroshade network and work out of the box.

## Defining Retroshades

Defining retroshades means defining rust structures. Keep in mind that:

* The fields will be translated to database columns. So if you have data that you want to be able to efficiently query, include them as top-level field, rather than in a nested structure.
* The types are transformed to their corresponding native database type.
* The `contract_id` (string) and `transaction` (transaction hash) fields are injected automatically on every event, alongside `_mercury_event_id`. Do not define them in your struct, otherwise it will cause a conflict.

```rust
#[cfg(feature = "mercury")]
mod retroshade {
    use retroshade_sdk::Retroshade;
    use soroban_sdk::{contracttype, Address, Symbol};

    #[derive(Retroshade)]
    #[contracttype]
    pub struct LiquidityEvent {
        pub from: Address,
        pub kind: Symbol,
        pub amount: i128,
        pub at_fee_per_share_universal: i128,
        pub at_fee_per_share_particular: i128,
        pub at_shares: i128,
        pub new_shares_minted: i128,
        pub ledger: u32,
        pub timestamp: u64,
    }
}
```

## Emitting Retroshades

Emitting a retroshade is as simple as declaring the retroshade structure and emit it in your target code block:

```rust
#[cfg(feature = "mercury")]
retroshade::LiquidityEvent {
    from,
    amount,
    at_fee_per_share_particular,
    at_fee_per_share_universal,
    at_shares,
    new_shares_minted: amount,
    kind: symbol_short!("deposit"),
    ledger: env.ledger().sequence(),
    timestamp: env.ledger().timestamp(),
}
.emit(&env);
```

Keep in mind that you can add additional soroban code under the mercury flag to retrieve the data you need!

```rust
#[cfg(feature = "mercury")]
let (at_fee_per_share_particular, at_fee_per_share_universal, at_shares) = (
    read_fee_per_share_particular(&env, from.clone()),
    get_fee_per_share_universal(&env),
    get_tot_supply(&env),
);
```

This code won't have any impact when the binary is compiled with the `mercury` flag.

{% hint style="info" %}
Tip: beware that .clone() are just compiler stubs in Soroban. So if you end up having to clone `Val` don't worry, because it won't change the resulting binary.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.mercurydata.app/retroshades/get-started/writing-and-emitting-retroshades.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.