Create tx folder inside frontend && create shared config && build plutus.json

Author: AgustinBadi

CLAUDE.md

@@ -97,9 +97,69 @@ The **Pyth State NFT** is a **reference input** (not spent) — the oracle relay
 
 ### Validator structure
 
-`validators/placeholder.ak` is the entry point to replace. Target structure:
-- `mint` handler — oracle price lookup, synth amount calculation, allow mint/burn
-- `spend` handler — pool UTxO continuity check, ADA balance update
+`validators/synth-dolar.ak` — multi-validator with four compile-time parameters:
+
+```aiken
+validator synth_dolar(
+  pyth_policy_id: PolicyId,     -- Pyth State NFT policy (testnet/mainnet differ)
+  ada_usd_feed_id: Int,         -- 16 (ADA/USD on Pyth Lazer)
+  collateral_ratio: Int,        -- e.g. 150 = 150% collateral requirement
+  liquidation_threshold: Int,   -- e.g. 120 = liquidate when health drops below 120%
+)
+```
+
+#### Types
+
+```aiken
+pub type PoolDatum {
+  owner: ByteArray   -- pubkey hash of the position owner
+}
+
+pub type Action { Mint | Burn | Liquidate }
+```
+
+#### `mint` handler — controls synth token supply
+
+**Mint:**
+1. ADA delta (pool output − pool input) must be ≥ 1 lovelace
+2. Collateralized ADA = `ada_deposited × collateral_ratio / 100`
+3. `minted_amount == compute_expected_synth_amount(collateralized_ada, raw_price, exponent)`
+
+**Burn:**
+1. ADA withdrawal must be ≥ 1 lovelace
+2. `minted_amount == -compute_expected_synth_amount(ada_withdrawn, raw_price, exponent)`
+3. Health after withdrawal ≥ `liquidation_threshold` (position must stay solvent)
+4. Transaction must be signed by `PoolDatum.owner`
+
+**Liquidate:**
+1. ADA withdrawal must be ≥ 1 lovelace
+2. Same burn math as Burn
+3. Health after withdrawal < `liquidation_threshold` (position must be unhealthy)
+4. No owner signature required — anyone can liquidate
+
+#### `spend` handler — guards pool UTxO
+
+Delegates all validation to the `mint` policy. Only checks that the mint policy is running in the same transaction (`get_minted_amount(mint, policy_id) != 0`). The `policy_id` is derived from the spent UTxO's script address.
+
+#### `else` handler
+
+`fail` — rejects all other script purposes (staking, governance, etc.)
+
+#### Helper functions (below validator)
+
+| Function | Purpose |
+|---|---|
+| `get_ada_usd_price` | Fetches `(raw_price, exponent)` from Pyth Lazer via `get_updates` |
+| `get_ada_delta` | Returns `output_lovelace - input_lovelace` for the pool UTxO |
+| `get_pool_ada` | Returns current lovelace balance of the pool input UTxO |
+| `get_minted_amount` | Sums all token quantities minted/burned under a policy |
+
+#### Price formula
+
+```
+synth_micro = ada_lovelaces × raw_price / 10^8
+```
+(ADA/USD exponent = −8; synth tokens have 6 decimals like ADA lovelaces)
 
 ### Plutus version
 Plutus v3 — use `ScriptContext` patterns accordingly.

frontend/src/tx/contract.ts

@@ -0,0 +1,67 @@
+// ── Contract configuration ────────────────────────────────────────────────────
+//
+// SCRIPT_CBOR is the raw compiled code from plutus.json (unparameterised).
+// Before using it on-chain you must apply the four compile-time parameters with
+// applyParamsToScript (see mint.ts), which produces the final script and its hash.
+//
+// Pyth Lazer preprod values: fill TODO fields once the Pyth team shares the
+// testnet deployment addresses.
+
+export const UNPARAMETERISED_SCRIPT_CBOR =
+  "591acc010100222229800aba4aba2aba1aba0aab9faab9eaab9dab9a9bae0059bad0049bad0039bad00248888888888896600330013007375401b2259800800c52f5c113300b3009300c00133002002300d0014029223232330010010042259800800c00e2646644b30013372200e00515980099b8f0070028800c01900d44cc014014c04c01100d1bae300c0013756601a002601e002806852f5bded8c1370e90004dc3a4005370e90024dd2a40012300b300c00148888888a6002602601130120089803803c88c966002601000315980098091baa0038014590134566002600e00315980098091baa0038014590134566002600c00315980098091baa0038014590134590102020404060206ea800a44646600200200644b30010018a60103d87a80008992cc004c0100062600e6602c00297ae0899801801980c00120243016001405091111194c004c050dd5000c88ca600200330073300f003002a400080088896600200510018cc00400e603c005337000026eb4c0740090032036980c0032444b3001300e003899198038010cc0048c074c078c0780066e0120019ba54800a6e3d22100980c9baa0099b814800244646600200200644b30010018a5eb8226644b3001300500289981080119802002000c4cc01001000501d18100009810800a03c980c1baa0029b8948009222222222980099194c00489660026038604a6ea800a2646464b3001302d002899803181600189980300080245902a1815800981580098131baa0028b204891191980080080191198018009801001488c96600260166eb8c0a8c0ac006260540031640946004002911192cc004c0b0006264b3001301f302837540031323259800981098151baa0018992cc004c088c0acdd5000c4c966002604660586ea800626605e6060605a6ea8008cc0bcc0c0c0b4dd5000a5eb822c8158c0bcc0c0c0c0c0c0c0c0c0c0c0b0dd5001c5902a181718159baa0018b2052301c302a3754002605860526ea80062c8138cc054dd618159816181618141baa302b00123370e6eb4c0b0c0a4dd5000812c59029192cc004c078c09cdd5000c4c966002603e60506ea80062646600a00244b300100289919800800802112cc004006297ae08998184c004dc4a4001371890024dc024007371290044dc624001371890044dc02400e91111111991198089191acc004cdc79bae303c0014890475d3c793008cc004888c8cc00cdd698200009bae3040304100130030019b89480426e3120109b804803e600e90082444446600a464660846ea0cde5250375c6086002660846086608800297ae05980098029b8d0018998209ba930020013304137526600860066e340040052f5c11640f44646600e4660866ea0cdc7000a4000660866ea4cc008c09cdc6800800a5eb808cc0208cc110dd419b8e00148000cc110dd49980198141b8d0010014bd7011191919823981c198239ba800733047375000a6608e609000297ae033047304830490014bd7018008012cc004c05400a2653001001a5eb82006800888966002607800312323304a374e002660946ea40092f5c065300100180252f5c080088896600200510018cc00400e609c0053304c304d002001400c825a246530010059982518258008024c0b800e6eb8c12cc1300050054c004c8cc128dd419bca4a06eb8c12c004cc128c12cc1300052f5c0b30013016371a00313304937526022002660926ea4cc050c04cdc6800800a5eb822c822a4466096004660966ea40052f5c1370e90034dc3a4010911119191919803194c0040066eb0c14800a6084660a260a4010660a298103d87a8000330514c103d87a8000330514c103d87a8000330514c103d87a8000330514c103d87a8000330514c103d87a8000330514c103d87a8000330514c103d87a8000330514c103d87a8000330514c103d87a8000330514c103d87a8000330514c103d87a8000330514c103d87a80004bd702002222598008014400633001003982a8014c8c966002609200313230473305630570013305630473305630573054375400697ae030583058001305337540071598009824000c4c8c8c120cc15cc160008cc15cc160004cc15cc120cc15cc160c154dd500225eb80c164c164004c160004c14cdd5001c566002608e003132323230493305830590033305830590023305830590013305830493305830593056375400a97ae0305a305a00130590013058001305337540071598009805000c4c8c8c8c8c128cc164c168010cc164c16800ccc164c168008cc164c168004cc164c128cc164c168c15cdd500325eb80c16cc16c004c168004c164004c160004c14cdd5001c566002601200313232323232304b3305a305b0053305a305b0043305a305b0033305a305b0023305a305b0013305a304b3305a305b3058375400e97ae0305c305c001305b001305a001305900130580013053375400715980099b874802800626464646464646098660b660b800c660b660b800a660b660b8008660b660b8006660b660b8004660b660b8002660b66098660b660b860b26ea80212f5c060ba60ba00260b800260b600260b400260b200260b000260a66ea800e2b30013370e9006000c4c8c8c8c8c8c8c8c134cc170c17401ccc170c174018cc170c174014cc170c174010cc170c17400ccc170c174008cc170c174004cc170c134cc170c174c168dd5004a5eb80c178c178004c174004c170004c16c004c168004c164004c160004c14cdd5001c56600266e1d200e0018991919191919191918271982e982f0041982e982f0039982e982f0031982e982f0029982e982f0021982e982f0019982e982f0011982e982f0009982e98271982e982f182d9baa00a4bd70182f982f800982f000982e800982e000982d800982d000982c800982c00098299baa0038acc004cdc3a40200031323232323232323232304f3305e305f0093305e305f0083305e305f0073305e305f0063305e305f0053305e305f0043305e305f0033305e305f0023305e305f0013305e304f3305e305f305c375401697ae030603060001305f001305e001305d001305c001305b001305a001305900130580013053375400715980099b874804800626464646464646464646460a0660be60c0014660be60c0012660be60c0010660be60c000e660be60c000c660be60c000a660be60c0008660be60c0006660be60c0004660be60c0002660be60a0660be60c060ba6ea80312f5c060c260c200260c000260be00260bc00260ba00260b800260b600260b400260b200260b000260a66ea800e2b30013370e900a000c4c8c8c8c8c8c8c8c8c8c8c8c144cc180c18402ccc180c184028cc180c184024cc180c184020cc180c18401ccc180c184018cc180c184014cc180c184010cc180c18400ccc180c184008cc180c184004cc180c144cc180c184c178dd5006a5eb80c188c188004c184004c180004c17c004c178004c174004c170004c16c004c168004c164004c160004c14cdd5001c56600266e1d201600189919191919191919191919191829198309831006198309831005998309831005198309831004998309831004198309831003998309831003198309831002998309831002198309831001998309831001198309831000998309829198309831182f9baa00e4bd7018319831800983100098308009830000982f800982f000982e800982e000982d800982d000982c800982c00098299baa003899191919191919191919191918291983098310061983098310059983098310051983098310049983098310041983098310039983098310031983098310029983098310021983098310019983098310011983098310009983098311831800998309829198309831182f9baa00e4bd7025eb80c188004c184004c180004c17c004c178004c174004c170004c16c004c168004c164004c160004c14cdd5001a0a24144828905120a24144828905120a24144828905118289baa0013054002400c8290dd718289829000991acc004c08000a2653001001a5eb82006800888966002608e003123233055374e002660aa6ea40092f5c065300100180252f5c080088896600200510018cc00400e60b2005330573058002001400c82b2246530010059982a982b0008024c0e400e6eb8c158c15c0050051802800a09e8b2098375c60a260a4006530012232598009800a40211598009800a4001148002266e39220108010204081020408000002413d1598009800a408113370490400219801801980a80144cdc124101010100406600600666e00009203f413c8278dc4000c888c8cc150c00cdd6982a8009982a182a982b000a5eb80c00c006660a06ea0cdc7000a4000660a06ea4cc03cc0d0dc6800800a5eb81222323298009198029191982c1ba833794940dd7182c8009982c182c982d000a5eb816600260366e340062660ae6ea4c060004cc15cdd49980d180c9b8d0010014bd704590531191801acc004c130006298103d87a8000898249982c1ba80014bd7020a830030019bad3056003911191acc0066002609a6eb4c16800694294505544cc02000c8c014c12ccc168dd4000a5eb822601e600898103d87a800041546eb8c168c16c004cc160dd419b8e00148000cc160dd49980b981e1b8d0010014bd7024446b3001304c00289801918251982c800a5eb822b3001304b002898019181e1982c800a5eb822b3001304a00289801919ba548010cc1640052f5c1159800980680144cc01c8c8cc168dd419bca4a06eb8c16c004cc168c16cc1700052f5c0b30013035371a00313305937526044002660b26ea4cc0a0c09cdc6800800a5eb822c82a88cdd2a400c660b26ea00052f5c1159800980600144cc01c8c8cc168dd419bca4a06eb8c16c004cc168c16cc1700052f5c0b30013035371a00313305937526044002660b26ea4cc0a0c09cdc6800800a5eb822c82a88cdd2a4010660b26ea16600266e20005208080048800c4cdc080098032404082a92f5c115980099b874802800a26006466e95200a330590014bd70456600266e1d200c002899800919ba548030cc1640052f5c0464660b46ea0c018dd6982d8009982d182d982e000a5eb80c8cc168dd419bca4a06eb8c16c004cc168c16cc1700052f5c0b3001301d371a00313305937526034002660b26ea4cc070c06cdc6800800a5eb822c82aa2b30013370e900700144cc0048cdd2a401c660b200297ae02323305a375066f29281bae305b0013305a305b305c0014bd702cc004c074dc6800c4cc164dd4980d0009982c9ba93301c301b371a00200297ae08b20aa8acc004cdc3a402000513300123374a90081982c800a5eb808c8cc168dd419bca4a06eb8c16c004cc168c16cc1700052f5c0b3001301d371a00313305937526034002660b26ea4cc070c06cdc6800800a5eb822c82aa2b30013370e9009001448c8c8cc16ccdd2a4024660b660b800297ae03305b305c305d0014bd701800801198041191982d9ba833794940dd7182e0009982d982e182e800a5eb8166002606c6e340062660b46ea4c08c004cc168dd49981498141b8d0010014bd7045905612cc004c1380062980103d87980008acc004c134006298103d87a80008acc004c130006298103d87b80008acc004c03c006298103d87c80008acc004c038006298103d87d80008b20ac415882b105620ac8acc004cdc3a40280051300323374a900a1982c800a5eb822b30013370e900b00144c00c8cdd2a402c660b200297ae08acc004cdc3a403000513300123374a900c1982c800a5eb808c8cc168dd419bca4a06eb8c16c004cc168c16cc1700052f5c0b3001301d371a00313305937526034002660b26ea4cc070c06cdc6800800a5eb822c82aa2c82a105420a8415082a105420a8415082a105420a8415082a0dd7182c982d003096600266e2000520808080808080808080028800c4cdc0800980124100028288c00c00c6eb4c13c004c8cc138dd419b8e00148000cc138dd49980698191b8d0010014bd701bae304e304f00420888b20823718900122c81b8dd7181e181e800acc004c01cdc6800c4cc0e8dd498010009981d1ba9330053004371a00200297ae08b206c375c603c606e6ea8cc0448c8d6600266e3cdd7181e000a44104b9011a820089191919191919199119822181a998221822803998221ba90013304430450024bd70198221822982300125eb80d660026024003125980099b89002371a00313304337526601e004002660866ea66002005337026e3400400a002b8c25eb822c81fa2c81f0dd7182198220011bae3043004375a608400264660826ea0cde5250375c6084002660826084608600297ae059800980e1b8d0018998201ba930090013304037526601e601c6e340040052f5c11640f06eb8c100c104004d6600294624b30013371290201b8d00189981f9ba93300b48100004cc0fcdd4cc005204099b80371a002901fc0057184bd7045903b45903a1bae303f3040001300100259800a51892cc004cdc4a4100026e3400626607a6ea4cc0252080010013303d37533001482000666e00dc6800a40ff0015c612f5c11640e51640e11640dc6eb8c0f0c0f400566002600e6e340062660746ea4c008004cc0e8dd49980298021b8d0010014bd704590361bae303a00a300348010c00d2008198010011819000a05e899180118188019bae302f00240b46eb0c0b0c0a4dd5000c5902719199119801001000912cc004006298103d87a80008992cc004cdd78021815800c4c07ccc0b8c0b00052f5c1133003003303000240a8605c0028160dd5981618169816981698169816981698169816981698149baa0193374a900219815180699815181598161816181618141baa302b3028375400297ae04bd7045902619198008009bac301a3028375403044b30010018a6103d87a80008992cc006600266ebc00530103d87a8000a50a5140a1100189980180198170012050325980099912cc00400a294226530013259800981218169baa00189bad302e303137566062605c6ea800629000205830300019baf303030310019bab003488966002003159800980100344cc01400d20008a5040b91325980099baf30300014c010140008acc004cc018010dd69818981a1bab3031001898019ba630350028a5040bd1598009980300224001130030078a5040bc8178c0cc0050310ca60020033756603e605a6ea8c07cc0b4dd5002488cc0c4008cc0c4dd3000a5eb810011112cc00400a26600298103d87a80004bd6f7b63044ca60026eb8c0bc0066eacc0c000660680069112cc004cdc8a441000038acc004c05c00e26600a604c6606a6e980092f5c00031330054c103d87a800000640c519800803c006446600e0046606e66ec0dd48029ba6004001401c8188606400481822942294229410311ba63302c337606ea409cdd31981619bb04c10b4a50797468205374617465004c010101004bd6f7b63025eb7bdb1808928c566002603e60526ea8c0b4c0a8dd5181698151baa301c302a375400313259800980f98151baa0018992cc004c088c0acdd5000c4c8c8c8c8cc8966002606c00713259800981498191baa0018991919194c004dd6981d000cdd7181d0024dd6981d001cdd7181d00124444b3001303f00589980b1bab303e00e225980080144cc060030896600200513032330410144bd7044c8c8cc074c1000084c00cc114010dd7182000098210012080899191980d981f8010980198218021bae303d001304000240f91640f0303a00130390013038001303337540031640c4606a00d1640cc6eb8c0cc004dd5981980118198009819000981880098161baa0018b2054302e302b37540031640a4602260546ea8c070c0a8dd5000c590284530103d87a800040a06058002815044b3001301b30243754005132323259800981600144c8c966002604000315980098151baa00280345902b4566002603e0031323259800981800140222c8168dd6981700098151baa0028acc004c0780062b3001302a37540050068b20568b205040a08140c0a0dd50009815801c59029192cc004c0a00062b3001300630270018b44c074c09c0050264590291baa302a001302a0013025375400516408c6e25200498131813002cdd61812802c88c8cc0040040088966002603800314800a266e08010cc008008c03000502448c8cc88cc008008004896600200300389919912cc004cdc8a441000028acc004c03400a2003006409d133005005302d004409c6eb8c098004dd698138009814800a04e3301b0024881001480012222298009bad302a0059bad302a302b005981598158024dd61815002488896600266e212000003899b833370466e0ccdc10020011980324028b300133710002900044c0340062002814920c8010038b205291192cc004c0b8006260086eacc070c0a8dd5180e18151baa302d0018b20563300a00123375e605a60546ea8c0b4c0a8dd5180e18151baa001300f3302c375200697ae091119b83337040060046600a900a2cc004cdc4000a40011300c0018800a050911192cc004c0bc006264b30013030001899b8130063756603c60586ea8c0bc004c018dd5980f18161baa301e302c3754605e0051640b466018004466ebcc0bcc0b0dd5181798161baa00130113302e375200a97ae08b20583300b00223375e605c60566ea8c0b8c0acdd5180e98159baa00130103302d375200897ae0488888888c8c966002604e023132598009808800c4c008cdc199b829800800c02e014802920c80102d8a5040c13001019806c01d0034566002604c0231980099b82980080cc03600e801920019980280c806ccc0480348cdd7981a98191baa303530323754604860646ea8004c05ccc0d0dd480d25eb8122259800981c000c4c966002605260686ea8006264b3001302c303537540031323259800981e0014566002602e00f1598009804180d4c00401e023010402d15980099b89032980099b8100600799b80980080340460208058026023010403513232330010013758607a607c607c607c607c02244b30010018a508acc004cdc79bae303e0010038a51899801001181f800a07240f06eb8c0ecc0e0dd5001c528206c8a5040d914a081b22c81c8dd7181d000981b1baa0018b20683038303537540031640cc603660686ea8c098c0d0dd5181b800c59035226644b300130120028acc004c00cc056600200500c805a00c899b88980099b8100100299b809800800c032016803001201900b402005b14a0818a294103119b82980080cc03600e801920013300501900d40bc8178dc38009980c9bab303200601706eb8c06cc060dd50024566002601a00713233223300900413232598009809980e1baa0018992cc004c04cc074dd5000c660026028660106eacc084c088c088c088c08800cdd71810980f1baa001a50a5140711640706040603a6ea8c080c074dd51807980e9baa3020301d375400316406c660126eb0c07c0048cdd79810180e9baa001004301b375401660380026038603a00260306ea80122c80b10160c05cc0600148a4d1365640141";
+
+// ── Protocol parameters (must match the on-chain validator) ───────────────────
+
+export const PARAMS = {
+  // Pyth State NFT policy ID on preprod — ask Pyth team or check their docs
+  PYTH_POLICY_ID: "TODO" as string,
+
+  // ADA/USD feed ID in Pyth Lazer
+  ADA_USD_FEED_ID: 16,
+
+  // 150 % collateral — $1.50 ADA collateral mints $1.00 synth
+  COLLATERAL_RATIO: 150,
+
+  // Liquidate when health drops below 120 %
+  LIQUIDATION_THRESHOLD: 120,
+};
+
+// ── Pyth on-chain infrastructure (preprod) ────────────────────────────────────
+
+export const PYTH = {
+  // UTxO carrying the Pyth State NFT (reference input, never spent)
+  STATE_UTXO_HASH: "TODO" as string,
+  STATE_UTXO_INDEX: 0,
+
+  // The Pyth withdraw script verifies the Ed25519 price signature.
+  // Its reward address is used for the zero-ADA withdrawal.
+  WITHDRAW_SCRIPT_CBOR: "TODO" as string,
+  WITHDRAW_ADDRESS: "TODO" as string, // bech32 reward address on preprod
+};
+
+// ── Amount helpers ────────────────────────────────────────────────────────────
+// Mirrors the on-chain integer arithmetic so the validator accepts the tx.
+
+/**
+ * Synth micro-USD to mint for a given ADA deposit.
+ *
+ * On-chain formula (integer division):
+ *   synth_base = lovelaces × raw_price / 10^8
+ *   minted     = synth_base × 100 / collateral_ratio
+ */
+export function computeMintAmount(lovelaces: bigint, price: number): bigint {
+  const rawPrice = BigInt(Math.round(price * 1e8));
+  const synthBase = (lovelaces * rawPrice) / 100_000_000n;
+  return (synthBase * 100n) / BigInt(PARAMS.COLLATERAL_RATIO);
+}
+
+/**
+ * ADA lovelaces returned when burning a given synth amount.
+ *
+ * On-chain formula (integer division):
+ *   lovelaces = synth_micro × 10^8 / raw_price
+ */
+export function computeBurnReturn(synthMicro: bigint, price: number): bigint {
+  const rawPrice = BigInt(Math.round(price * 1e8));
+  return (synthMicro * 100_000_000n) / rawPrice;
+}