Skip to content

Commit 8b42cd8

Browse files
fasskofassko
committed
feat(docs): add Morpho lending tutorials for Flare Smart Accounts
1 parent 8da6504 commit 8b42cd8

12 files changed

Lines changed: 1548 additions & 2 deletions

File tree

‎docs/smart-accounts/guides/typescript-viem.mdx‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
title: TypeScript + Viem
3+
description: TypeScript and Viem guides for Flare Smart Accounts on Coston2
4+
keywords:
5+
[
6+
flare-smart-accounts,
7+
viem,
8+
typescript,
9+
xrpl,
10+
account-abstraction,
11+
flare-network,
12+
]
13+
---
14+
15+
import DocCardList from "@theme/DocCardList";
16+
import DocCard from "@theme/DocCard";
17+
18+
Use [Viem](https://viem.sh/) and the [`xrpl`](https://js.xrpl.org) library to read smart-account state on Flare and drive on-chain actions from an XRPL wallet.
19+
20+
Example code is maintained in the [flare-viem-starter](https://github.com/flare-foundation/flare-viem-starter) repository.
21+
Read the [Smart Accounts overview](/smart-accounts/overview) and [Custom Instruction](/smart-accounts/custom-instruction) pages first if you are new to the protocol.
22+
23+
## Getting started
24+
25+
Read on-chain state and send arbitrary contract calls through XRPL memo-field instructions.
26+
27+
<DocCardList
28+
items={[
29+
{
30+
type: "link",
31+
label: "State Lookup",
32+
href: "/smart-accounts/guides/typescript-viem/state-lookup-ts",
33+
docId: "smart-accounts/guides/typescript-viem/state-lookup",
34+
},
35+
{
36+
type: "link",
37+
label: "Custom Instruction",
38+
href: "/smart-accounts/guides/typescript-viem/custom-instruction-ts",
39+
docId: "smart-accounts/guides/typescript-viem/custom-instruction",
40+
},
41+
]}
42+
/>
43+
44+
## Cross-chain FXRP (LayerZero)
45+
46+
Mint [FXRP](/fxrp/overview) on Flare from XRPL and bridge to Sepolia testnet, or send FXRP back and redeem to XRP.
47+
48+
<div className="row">
49+
<div className="col col--4 margin-bottom--lg">
50+
<DocCard
51+
item={{
52+
type: "link",
53+
label: "Cross-Chain Mint",
54+
href: "/smart-accounts/guides/typescript-viem/cross-chain-mint-ts",
55+
docId: "smart-accounts/guides/typescript-viem/cross-chain-mint",
56+
}}
57+
/>
58+
</div>
59+
<div className="col col--4 margin-bottom--lg">
60+
<DocCard
61+
item={{
62+
type: "link",
63+
label: "Cross-Chain Redeem",
64+
href: "/smart-accounts/guides/typescript-viem/cross-chain-redeem-ts",
65+
docId: "smart-accounts/guides/typescript-viem/cross-chain-redeem",
66+
}}
67+
/>
68+
</div>
69+
<div className="col col--4 margin-bottom--lg">
70+
<DocCard
71+
item={{
72+
type: "link",
73+
label: "Cross-Chain Redeem to Tag",
74+
href: "/smart-accounts/guides/typescript-viem/cross-chain-redeem-to-tag-ts",
75+
docId:
76+
"smart-accounts/guides/typescript-viem/cross-chain-redeem-to-tag",
77+
}}
78+
/>
79+
</div>
80+
</div>
81+
82+
## Morpho Blue
83+
84+
Borrow and repay on a Coston2 Morpho Blue test market through a smart account.
85+
86+
<div className="row">
87+
<div className="col col--4 margin-bottom--lg">
88+
<DocCard
89+
item={{
90+
type: "link",
91+
label: "Morpho Setup",
92+
href: "/smart-accounts/guides/typescript-viem/morpho-setup-ts",
93+
docId: "smart-accounts/guides/typescript-viem/morpho-setup",
94+
}}
95+
/>
96+
</div>
97+
<div className="col col--4 margin-bottom--lg">
98+
<DocCard
99+
item={{
100+
type: "link",
101+
label: "Morpho Borrow",
102+
href: "/smart-accounts/guides/typescript-viem/morpho-borrow-ts",
103+
docId: "smart-accounts/guides/typescript-viem/morpho-borrow",
104+
}}
105+
/>
106+
</div>
107+
<div className="col col--4 margin-bottom--lg">
108+
<DocCard
109+
item={{
110+
type: "link",
111+
label: "Morpho Repay",
112+
href: "/smart-accounts/guides/typescript-viem/morpho-repay-ts",
113+
docId: "smart-accounts/guides/typescript-viem/morpho-repay",
114+
}}
115+
/>
116+
</div>
117+
</div>

‎docs/smart-accounts/guides/typescript-viem/06-morpho-setup.mdx‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
sidebar_position: 6
3+
slug: morpho-setup-ts
4+
title: Morpho Setup
5+
authors: [nikerzetic]
6+
description: Fund a smart account and authorize Morpho Blue lending via the MorphoMarketShim on Coston2.
7+
tags: [intermediate, ethereum, flare-smart-accounts]
8+
keywords:
9+
[
10+
ethereum,
11+
flare-smart-accounts,
12+
evm,
13+
flare-network,
14+
account-abstraction,
15+
morpho,
16+
defi,
17+
]
18+
unlisted: false
19+
---
20+
21+
import CodeBlock from "@theme/CodeBlock";
22+
import MorphoSetupScript from "!!raw-loader!/examples/developer-hub-javascript/smart-accounts/morpho/setup.ts";
23+
24+
This guide walks through the one-shot setup script for [Morpho Blue](https://docs.morpho.org/), leveraging a Flare smart account.
25+
The smart account is the borrower's end-to-end: it holds tokens, supplies collateral, borrows, and later repays via the XRPL memo field [custom instructions](/smart-accounts/custom-instruction).
26+
27+
The setup script does two kinds of work:
28+
29+
1. **Flare EOA transactions** — mint mock ERC-20 collateral and loan tokens to the personal account via permissionless `setBalance`.
30+
2. **XRPL memo instructions** — up to three payments that approve the `MorphoMarketShim` for both tokens and call `setAuthorization` on Morpho Blue.
31+
32+
:::warning
33+
Run this script once before the [Morpho Borrow](/smart-accounts/guides/typescript-viem/morpho-borrow-ts) and [Morpho Repay](/smart-accounts/guides/typescript-viem/morpho-repay-ts) guides.
34+
Each step is idempotent, and skips work that has already been done on the chain.
35+
:::
36+
37+
The full Morpho cycle lives in the [flare-viem-starter](https://github.com/flare-foundation/flare-viem-starter) repository under `src/morpho/`.
38+
39+
## Prerequisites
40+
41+
- An XRPL testnet wallet (`XRPL_SEED`) registered with the Flare smart-accounts operator and funded with testnet XRP.
42+
- A Flare-side EOA (`PRIVATE_KEY`) used only to call permissionless mock-token `setBalance` — not to sign Morpho operations on behalf of the smart account.
43+
- `XRPL_TESTNET_RPC_URL` pointing at an XRPL testnet node.
44+
- Familiarity with [State Lookup](/smart-accounts/guides/typescript-viem/state-lookup-ts) and [Custom Instruction](/smart-accounts/guides/typescript-viem/custom-instruction-ts).
45+
46+
## Architecture
47+
48+
Morpho Blue markets are identified by a five-field [`MarketParams`](https://docs.morpho.org/get-started/resources/contracts/morpho#market-parameters) tuple (loan token, collateral token, oracle, IRM, LLTV).
49+
Opening a position normally requires multiple Morpho calls (`supplyCollateral`, `borrow`, and so on).
50+
Each call encoded in an XRPL memo must stay under the roughly 1024-byte memo cap.
51+
52+
The `MorphoMarketShim` contract pins the market parameters in immutable storage at deploy time.
53+
That shrinks each memo payload so a bundled operation fits in one payment:
54+
55+
- `supplyAndBorrow` — used in the [Morpho Borrow](/smart-accounts/guides/typescript-viem/morpho-borrow-ts) guide.
56+
- `repayAndWithdrawCollateral` — used in the [Morpho Repay](/smart-accounts/guides/typescript-viem/morpho-repay-ts) guide.
57+
58+
The smart account remains `onBehalf` for the position; borrowed assets are returned to the smart account, so the position remains self-contained.
59+
60+
### Coston2 Deployment Addresses
61+
62+
| Contract | Address |
63+
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
64+
| Morpho Blue | [`0x8aE0b3CE90F16E88063516f2d88C8ac2ab552d95`](https://coston2-explorer.flare.network/address/0x8aE0b3CE90F16E88063516f2d88C8ac2ab552d95) |
65+
| Loan token (mock) | [`0x4984B127c3065f4348858fAFdBa020f2c8633905`](https://coston2-explorer.flare.network/address/0x4984B127c3065f4348858fAFdBa020f2c8633905) |
66+
| Collateral token (mock) | [`0x98bf2F2fF322d5eb61D6aE04Df50856525a85D16`](https://coston2-explorer.flare.network/address/0x98bf2F2fF322d5eb61D6aE04Df50856525a85D16) |
67+
| Oracle (mock) | [`0x1e80830e9903c839Db803442c976DD2360D47FE0`](https://coston2-explorer.flare.network/address/0x1e80830e9903c839Db803442c976DD2360D47FE0) |
68+
| IRM (mock) | [`0xDC275701300865D882D44ffe7cb1153535636d1a`](https://coston2-explorer.flare.network/address/0xDC275701300865D882D44ffe7cb1153535636d1a) |
69+
| MorphoMarketShim | [`0x33d81a1d7986bB3AbAB4F67Ad6117233ADd6F87A`](https://coston2-explorer.flare.network/address/0x33d81a1d7986bB3AbAB4F67Ad6117233ADd6F87A) |
70+
71+
The market uses an LLTV of `86%` (`860000000000000000` in WAD).
72+
The market ID is `keccak256(abi.encode(marketParams))`, matching Morpho Blue's `MarketParamsLib.id()`.
73+
74+
## Full Script
75+
76+
The script below is sets up the Morpho Blue position by funding the smart account with mock tokens, approving the shim smart contract, and authorizing the shim smart contract on Morpho Blue.
77+
78+
<CodeBlock language="typescript" title="src/morpho/setup.ts">
79+
{MorphoSetupScript}
80+
</CodeBlock>
81+
82+
## Code Breakdown
83+
84+
The numbered comments in the script above map to these steps.
85+
86+
**1., 2. Configure and connect.**
87+
Set funding sizes in whole token units (`100` collateral, `1000` loan token), then open an XRPL client and wallet.
88+
The XRPL wallet controls the personal account; the Flare EOA is only used for mock minting in step 6.
89+
90+
| Token | Units | Purpose |
91+
| ---------- | ------ | ---------------------------------------------- |
92+
| Collateral | `100` | Matches the supply size in the borrow script |
93+
| Loan | `1000` | Buffer for interest across borrow/repay cycles |
94+
95+
**3., 4. Resolve addresses and log them.**
96+
In parallel, the script looks up the personal account, the memo-only XRP fee, and market decimals.
97+
It then prints the personal account, operator EOA, market ID, and shim address.
98+
99+
**5. Snapshot before setup.**
100+
It logs the Morpho position and wallet balances.
101+
On a first run, borrow shares and position collateral should be zero.
102+
103+
**6. Fund mock tokens on Flare.**
104+
The `mintMock` function calls permissionless `setBalance` on the Coston2 mock ERC-20s, crediting the personal account.
105+
This is a normal Flare transaction from the operator EOA without interacting with the smart account.
106+
107+
**7. Approve and authorize the shim.**
108+
It sends up to 3 XRPL memos: unlimited `approve` for collateral and loan tokens, then `setAuthorization` for Morpho Blue.
109+
Each action uses its own memo because two calls do not fit under the 1024-byte cap.
110+
111+
**8. Snapshot after setup.**
112+
Wallet balances should reflect the mint; Morpho position fields stay zero until [Morpho Borrow](/smart-accounts/guides/typescript-viem/morpho-borrow-ts).
113+
114+
## Expected Output
115+
116+
When you run the script, you should see the following output.
117+
118+
```bash
119+
Personal account: 0x...
120+
Operator EOA: 0x...
121+
Morpho market id: 0x...
122+
Shim address: 0x33d81a1d7986bB3AbAB4F67Ad6117233ADd6F87A
123+
124+
=== Before setup ===
125+
position supply (≈loan tokens): 0
126+
position borrow (≈loan tokens): 0
127+
position collateral: 0
128+
...
129+
130+
Funded smart account with collateral and loan tokens.
131+
132+
[approve-collateral] XRPL transaction hash: ...
133+
[approve-loan] XRPL transaction hash: ...
134+
[set-authorization] XRPL transaction hash: ...
135+
136+
=== After setup ===
137+
smart-account collateral balance: 100
138+
smart-account loan-token balance: 1000
139+
...
140+
```
141+
142+
You can repeat borrow and repay without re-running the setup, as the loan-token buffer covers interest.
143+
Re-run setup if allowances are revoked or the loan-token balance is exhausted.
144+
145+
:::tip[What's next]
146+
147+
After you have completed the setup, you can:
148+
149+
- Open a position by running the [Morpho Borrow](/smart-accounts/guides/typescript-viem/morpho-borrow-ts) guide.
150+
- Close a position by running the [Morpho Repay](/smart-accounts/guides/typescript-viem/morpho-repay-ts) guide.
151+
152+
:::

‎docs/smart-accounts/guides/typescript-viem/07-morpho-borrow.mdx‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
sidebar_position: 7
3+
slug: morpho-borrow-ts
4+
title: Morpho Borrow
5+
authors: [nikerzetic]
6+
description: Open a Morpho Blue borrow position from a Flare smart account via supplyAndBorrow.
7+
tags: [intermediate, ethereum, flare-smart-accounts]
8+
keywords:
9+
[
10+
ethereum,
11+
flare-smart-accounts,
12+
evm,
13+
flare-network,
14+
account-abstraction,
15+
morpho,
16+
defi,
17+
]
18+
unlisted: false
19+
---
20+
21+
import CodeBlock from "@theme/CodeBlock";
22+
import MorphoBorrowScript from "!!raw-loader!/examples/developer-hub-javascript/smart-accounts/morpho/borrow.ts";
23+
24+
This guide opens a [Morpho Blue](https://docs.morpho.org/) borrow position from a Flare smart account in a single XRPL memo.
25+
It calls the `MorphoMarketShim` smart contract `supplyAndBorrow` function, which supplies `100` units of collateral and borrows up to roughly `99%` of the maximum healthy loan amount.
26+
27+
:::info Setup
28+
Run the [Morpho Setup](/smart-accounts/guides/typescript-viem/morpho-setup-ts) guide first.
29+
Without funded tokens, shim smart contract approvals, and Morpho authorization, the transaction reverts.
30+
:::
31+
32+
To close the position follow the [Morpho Repay](/smart-accounts/guides/typescript-viem/morpho-repay-ts) guide.
33+
34+
The full Morpho cycle lives in the [flare-viem-starter](https://github.com/flare-foundation/flare-viem-starter).
35+
36+
## Full Script
37+
38+
To open a borrow position, explore the full script below.
39+
40+
<CodeBlock language="typescript" title="src/morpho/borrow.ts">
41+
{MorphoBorrowScript}
42+
</CodeBlock>
43+
44+
## Code Breakdown
45+
46+
**1. Connect to XRPL.**
47+
Open an XRPL client and wallet.
48+
The XRPL wallet controls the personal account.
49+
Morpho operations are sent as memo-field custom instructions from the smart account, not as Flare EOA (External Owned Account) transactions.
50+
51+
**2. Resolve on-chain inputs in parallel.**
52+
The script fetches the personal account address, the memo-only XRP fee, market token decimals, and the mock oracle price in parallel.
53+
54+
**3. Set collateral supply size.**
55+
Collateral is fixed at `100` whole token units, scaled by `collateralDecimals`.
56+
This matches the collateral funding amount from [Morpho Setup](/smart-accounts/guides/typescript-viem/morpho-setup-ts).
57+
58+
**4. Log addresses.**
59+
It prints the personal account, operator EOA, Morpho market ID, and shim address for this run.
60+
61+
**5. Snapshot before borrowing.**
62+
It logs the Morpho position and wallet balances before the borrow.
63+
On a first borrow after setup, the borrowed shares and the position collateral should be zero while the smart account holds the funded tokens.
64+
65+
**6. Compute borrow size off-chain.**
66+
The script reads the mock oracle price and applies Morpho Blue's health formula to derive the maximum borrowable amount:
67+
68+
```
69+
maxBorrowAssets = collateral * oraclePrice * lltv / (oraclePriceScale * WAD)
70+
```
71+
72+
It then borrows `99%` of that value to leave a small safety margin for interest accrued during the transaction.
73+
74+
**7. Send the supply-and-borrow memo.**
75+
A single custom instruction executes the `MorphoMarketShim` smart contract `supplyAndBorrow` function.
76+
77+
Bundling supply and borrow inside the shim smart contract keeps the encoded user operation under the XRPL memo size limit.
78+
79+
**8. Snapshot after borrowing.**
80+
Print the Morpho position and wallet balances after the borrow.
81+
Expect position collateral to be near `100`, a non-zero borrow balance, and an increased loan-token wallet balance.
82+
83+
## Expected Output
84+
85+
When you run the script, you should see output similar to the following.
86+
87+
```bash
88+
Personal account: 0x...
89+
Operator EOA: 0x...
90+
Morpho market id: 0x...
91+
Shim address: 0x33d81a1d7986bB3AbAB4F67Ad6117233ADd6F87A
92+
93+
=== Before borrow ===
94+
position borrow (≈loan tokens): 0
95+
position collateral: 0
96+
...
97+
98+
Oracle price: ...
99+
Max borrowable: ... → borrowing: ...
100+
101+
[supply-and-borrow] XRPL transaction hash: ...
102+
[supply-and-borrow] UserOperationExecuted event: ...
103+
104+
=== After borrow ===
105+
position borrow (≈loan tokens): ...
106+
position collateral: 100
107+
...
108+
```
109+
110+
:::tip[What's next]
111+
After you have completed the borrow, you can explore how to [repay the borrow position](/smart-accounts/guides/typescript-viem/morpho-repay-ts).
112+
:::

0 commit comments

Comments
 (0)