Update README

Author: shesek

README.md

@@ -1,20 +1,58 @@
-[![Build Status](https://travis-ci.org/shesek/minsc.svg?branch=master)](https://travis-ci.org/shesek/minsc)
+[![Build Status](https://github.com/shesek/minsc/actions/workflows/minsc.yml/badge.svg)](https://github.com/shesek/minsc/actions/workflows/minsc.yml)
 [![crates.io](https://img.shields.io/crates/v/minsc.svg)](https://crates.io/crates/minsc)
 [![npm](https://img.shields.io/npm/v/minsc.svg?color=blue)](https://www.npmjs.com/package/minsc)
 [![MIT license](https://img.shields.io/github/license/shesek/minsc.svg?color=yellow)](https://github.com/shesek/minsc/blob/master/LICENSE)
 ![Pull Requests Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)
 
 # Minsc
 
-### A Miniscript-based scripting language for Bitcoin contracts
-
-Minsc is a high-level scripting language for expressing Bitcoin Script spending conditions.
+### A mini scripting language for all things Bitcoin
+
+Minsc is a high-level, domain-specific, embeddable language for Bitcoin scripting that simplifies the creation and fulfillment of complex spending conditions, using an expressive pseudo-code-like syntax.
+
+It includes built-in support for Descriptors, Miniscript, Script, Transactions, PSBT, Taproot, Xpubs/Xprvs, CTV and more.
+
+The language is dynamically typed, purely functional and immutable.
+
+> [!NOTE]
+> The documentation and playground on the [`min.sc`](https://min.sc/) website are severely outdated.
+>
+> To explore some of Minsc's new abilities, check out the [`min.sc/v0.3`](https://min.sc/v0.3/) playground and the following examples:
+>
+> #### Descriptors, Miniscript & PSBT
+> - [Simple Taproot](https://min.sc/v0.3/#github=examples/taproot-psbt-simple.minsc) (P2TR key-path)
+> - [Simple Multisig](https://min.sc/v0.3/#github=examples/multisig-simple.minsc) (P2WSH 2-of-2)
+> - [Co-signer with expiry](https://min.sc/v0.3/#github=examples/cosigner-with-expiry.minsc) (P2TR with Miniscript, Green-like)
+> - [Multisig 3-of-3 into 2-of-3](https://min.sc/v0.3/#github=examples/3of3-into-2of3.minsc) (decays after a timeout)
+> - [Hashed Timelock Contract](https://min.sc/v0.3/#github=examples/htlc.minsc) (traditional HTLC)
+> - [Recovery after a delay period](https://min.sc/v0.3/#github=examples/recovery-after-delay.minsc) (simple CSV-based, delay period since the coins last moved)
+> - [Inheritance after a contest period](https://min.sc/v0.3/#github=examples/inheritance-after-contest-presigned.minsc) (2-stage using pre-signed txs, contest delay period following the 'trigger')
+>
+> #### Manual Scripting/Signing
+> - [Manual Signing](https://min.sc/v0.3/#github=examples/manual-signing-p2wpkh.minsc) (P2WPKH *without* Descriptors, Miniscript or PSBT)
+> - [Manual Scripting & Signing](https://min.sc/v0.3/#github=examples/manual-scripting-signing-p2wsh.minsc) (P2WSH *without* Descriptors, Miniscript or PSBT)
+> - [Simple CTV Whitelist](https://min.sc/v0.3/#github=examples/ctv-simple.minsc) (P2TR with raw Script)
+> - [CTV Vault](https://min.sc/v0.3/#github=examples/ctv-vault.minsc) (P2TR with raw Script)
+> - [Simplest CAT](https://min.sc/v0.3/#github=examples/cat-simplest.minsc)
+> - More scripting examples are available in [the playground's default code](https://min.sc/v0.3/)
+>
+> #### Elements/Liquid Introspection
+> - [Dutch Auction](https://min.sc/v0.3/#github=examples/elements-dutch-auction.minsc)
+> - [Token Sale with royalty](https://min.sc/v0.3/#github=examples/elements-sale-royalty.minsc) (recursive stateful contract, WIP code)
+>
+> To learn more about the language internals, you can also check out the Minsc standard library parts implemented in Minsc:
+> 
+> - [`src/stdlib/stdlib.minsc`](https://min.sc/v0.3/#github=src/stdlib/stdlib.minsc) (utilities for arrays, strings, testing and more)
+> - [`src/stdlib/btc.minsc`](https://min.sc/v0.3/#github=src/stdlib/btc.minsc) (transaction utilities, script opcodes, loop unrolling, control structures and more)
+> - [`src/stdlib/elements.minsc`](https://min.sc/v0.3/#github=src/stdlib/elements.minsc) (Elements introspection, 64-bit arithmetic and more)
+
+<!-- Minsc is a high-level scripting language for expressing Bitcoin Script spending conditions.
 It is based on the [Miniscript](http://bitcoin.sipa.be/miniscript/) Policy language,
 with additional features and syntactic sugar sprinkled on top, including variables, functions, infix notation, human-readable times and more.
 
-Documentation & live playground are available on the website: https://min.sc
+Documentation & live playground are available on the website: https://min.sc 
 
-Support development: [⛓️ on-chain or ⚡ lightning via BTCPay](https://btcpay.shesek.info/)
+Support development: [⛓️ on-chain or ⚡ lightning via BTCPay](https://btcpay.shesek.info/) 
 
 ## Examples
 
@@ -68,7 +106,7 @@ Support development: [⛓️ on-chain or ⚡ lightning via BTCPay](https://btcpa
   ```
   [:arrow_forward: Try it live](https://min.sc/#c=%2F%2F%20Two%20factor%20authentication%20with%20a%20timeout%20recovery%20clause%0Afn%20two_factor%28%24user%2C%20%24provider%2C%20%24delay%29%20%3D%20%0A%20%20%24user%20%26%26%20%28likely%40%24provider%20%7C%7C%20older%28%24delay%29%29%3B%0A%0A%2F%2F%202FA%20where%20the%20user%20has%20a%202-of-2%20setup%20and%20the%20provider%20is%20a%203-of-4%20federation%0A%0A%24user%20%3D%20pk%28desktop_pk%29%20%26%26%20pk%28mobile_pk%29%3B%0A%24providers%20%3D%20%5B%20pk%28A%29%2C%20pk%28B%29%2C%20pk%28C%29%2C%20pk%28D%29%20%5D%3B%0A%0Atwo_factor%28%24user%2C%203%20of%20%24providers%2C%204%20months%29)
 
-More examples are available on https://min.sc.
+More examples are available on https://min.sc.-->
 
 ## Local installation
 
@@ -77,29 +115,26 @@ More examples are available on https://min.sc.
 ```bash
 $ cargo install minsc
 
-# Compile a minsc file
+# Execute a minsc file
 $ minsc examples/htlc.minsc
 
-# Compile from stdin
-$ echo 'pk(A) && older(1 week)' | minsc -
+# Execute from stdin
+$ echo 'pk(d0de0aaeaefad02b8bdc8a01a1b8b11c696bd3d66a2c5f10780d95b7df42645c) && older(1 week)' | minsc -
 
 # Dump AST
 $ minsc examples/htlc.minsc --ast
 ```
 
 Using the Rust API:
 ```rust
-use minsc::{parse, run, eval};
-
-let code = "pk(A) && older(1 week)";
-let ast = parse(&code).unwrap();
-let result = eval(ast).unwrap();
-// or parse+eval in one go with `run(&code)`
+use minsc::eval;
 
-let policy = result.into_policy().unwrap();
-println!("{}", policy);
+let code = "pk(d0de0aaeaefad02b8bdc8a01a1b8b11c696bd3d66a2c5f10780d95b7df42645c) && older(1 week)";
+let res = eval(&code).unwrap(); // a minsc::Value
+println!("{}", res);
 
-// also available: into_miniscript() and into_desc()
+// Extract the miniscript::Policy
+let policy = res.into_policy().unwrap();
 ```
 
 Full documentation for the Rust API is [available here](https://docs.rs/minsc/).
@@ -109,15 +144,53 @@ Full documentation for the Rust API is [available here](https://docs.rs/minsc/).
 Install with `npm install minsc` and:
 
 ```js
-import { run } from 'minsc'
-
-const policy = run('pk(A) && older(1 week)')
-const miniscript = run('miniscript(pk(A) && older(1 week))')
-const descriptor = run('wsh(miniscript(pk(A) && older(1 week)))')
-const address = run('address(wsh(miniscript(pk(A) && older(1 week))))')
-const address2 = run('address(pk(A) && older(1 week))')
-
-console.log({ policy, miniscript, descriptor, address, address2 })
+import m from 'minsc'
+
+// A multisig between Alice and Bob
+const alice_pk = 'xpub661MyMwAqRbcFjVEmr9dDxeGKJznf41v5bEd83wMwu7CJ6PFeqJk3cSECPTh6wzsh32xceVsPvBgJ1q3Cqqie2dvH9nMFdL5865WrtRNhiB'
+    , bob_pk = 'xpub661MyMwAqRbcFG1mzmcbw7oZss2Fn9y3d27D1KVjyKQdYGqNsZ8nSvLSexZAtkCNwvhFrAkTWAixvN9wjmnLNR22EsQczTiKccAJoLYW8CK'
+
+const multisig = m`wsh(${alice_pk}/0/* && ${bob_pk}/0/*)`
+
+// Generate receive address #0
+const address = m`address(${multisig}/0)`
+console.log(`Address: ${address}`)
+
+// An output funding address #0
+const prevout = '72877bd944be3433d5030ef102922e52f7c40de8b5ca26fa8b7c724d341e936e:1'
+    , amount = '0.5 BTC'
+
+// Create PSBT
+const psbt = m`psbt[
+  "input": [
+    "prevout": ${prevout},
+    "utxo": ${multisig}/0:${amount},
+  ],
+  "outputs": [
+    bcrt1ql8nqx3q3v7napchr6ewy4tpyq5y08ywat84pen: 0.4 BTC,
+    (${multisig}/1): 0.099 BTC, // change back to multisig
+  ],
+]`
+
+// Export PSBT for external signing
+const psbt_base64 = m.base64(psbt)
+
+// Or sign with Minsc:
+const alice_sk = 'xprv9s21ZrQH143K3FQmfpccrphXmHAJFbJ4iNK2KfXkPZaDRJ477HzVVp7kM7RV3ihdLh4Wy163wJahwXcdcrpu4R6xSu6CUvKYwftQYCbowYM'
+    , bob_sk = 'xprv9s21ZrQH143K2mwJtk5bZyrqKqBmNhFCFoBcCw68QysefUWEL1pXu81xoeva2ZWpCjsJzzmYqph6vw6FjCMjg3q8obNzxYY9bCVgt9bKoHQ'
+
+const signed = m`psbt::sign(${psbt}, ${[ alice_sk, bob_sk ]})`
+
+// Finalize & Extract
+const tx = m`psbt::extract(psbt::finalize(${signed}))`
+console.log(m.pretty(tx))
+console.log(m.bytes(tx).toString('hex'))
+
+// Alternative style, with Minsc functions as JavaScript methods (translated into the same as above)
+const address = m.address(m.wsh(m.and(m`${alice_pk}/0/1`, m`${bob_pk}/0/1`)))
+const psbt = m.psbt({ inputs: [ ... ], outputs: [ ... ] })
+const signed = m.psbt.sign(psbt, [ alice_sk, bob_sk ])
+const tx = m.psbt.extract(m.psbt.finalize(signed))
 ```