CIP-0102 | Reference Implementation

CIP-0102/.vscode/settings.json

@@ -0,0 +1,9 @@
+{
+	"deno.cacheOnSave": true,
+	"deno.codeLens.test": false,
+	"deno.codeLens.referencesAllFunctions": false,
+	"deno.codeLens.references": false,
+	"deno.codeLens.implementations": false,
+	"deno.enable": false,
+	"deno.unstable": false
+}

CIP-0102/ref_impl/Spec.md

@@ -0,0 +1,59 @@
+# Minting a CIP 102 compliant NFT with royalties
+
+## Timelocked Minting Policy
+- Checks
+  - Owner has signed tx
+  - Tx validity window is before MP deadline
+
+## Validators
+
+### Always Fails
+- Checks nothing
+- Returns false or throws error
+
+### Reducible 
+- Checks
+	- tx is signed by recipient
+	- amount sent to recipient is < previous amount
+	- all other recipients remain the same
+		- amount
+		- address
+
+## Offchain
+- Constructs well formed CIP-68 & CIP-102 Datums
+- Sends reference NFT & datum to arbitrary address
+- Sends royalty NFT & datum to
+	- arbitrary address
+	- always-fails script
+	- reducible validator
+
+# Reading a CIP 102 NFT’s royalties off chain
+
+- Querying the datum
+	- Check if datum is required
+	- Request datum
+	- Fail depending on whether datum is required
+- Parsing the datum
+
+
+# Reading and validating against CIP 102 NFT royalties on chain
+
+A simple listing contract which locks a CIP 102 NFT & a datum with a price & seller and must pay out royalties according to that price to be withdrawn.
+
+## Onchain
+
+- Royalty datum
+	- If empty, check if royalty is required
+		- Parse reference datum
+		- Fail if royalty field > 1
+	- If not, check if royalties are being paid correctly
+		- Fail if not
+- Listing datum
+	- Confirm the amount is getting paid to the seller, minus royalties
+
+## Offchain
+
+- Find & read the requested listing datum
+- Find & read the associated royalty datum using the approach above
+- Calculate payments
+- Construct & Submit tx

CIP-0102/ref_impl/TODO.md

@@ -0,0 +1,9 @@
+- [x] Create Specification
+- [x] Select Onchain Language
+- [x] Minting a CIP 102 compliant NFT with royalties
+  - [x] Timelocked MP
+  - [x] Always-Fails Validator
+  - [x] Reducible Validator
+- [x] Reading a CIP 102 NFT’s royalties off chain
+- [x] Reading and validating against CIP 102 NFT royalties on chain
+- [ ] Final Cleanup

CIP-0102/ref_impl/offchain-reference/.env.example

@@ -0,0 +1,5 @@
+PUBLIC_CARDANO_NETWORK=Preprod
+BLOCKFROST_URL=https://cardano-preprod.blockfrost.io/api/v0
+BLOCKFROST_PROJECT_KEY=PLACEHOLDER
+WALLET_ADDRESS=PLACEHOLDER
+WALLET_PRIVATE_KEY=PLACEHOLDER

CIP-0102/ref_impl/offchain-reference/.gitignore

@@ -0,0 +1,2 @@
+.env
+.vscode

CIP-0102/ref_impl/offchain-reference/README

@@ -0,0 +1,56 @@
+# Using the CIP-102 Offchain Library
+
+## Importing
+The contents of this library are available to be imported from `index.ts` and will eventually be published to a public package manager (or two). I will add instructions here when I do.
+
+In the meantime, you can clone or copy the contents of the `/lib/` folder wherever you need it.
+
+## Direct Use
+
+If you want to interact with the library directly without setting up your own project, you can run the code directly with the mock frontend defined in `scripts/mock-frontend.ts`
+
+### Setup
+
+- Make sure you have [Deno](https://deno.com/) installed.
+
+- Create a Blockfrost project if you don't already have one. These are free up to a certain number of queries.
+
+- Create a `.env` file in the parent directory with the structure defined in `.env.example`:
+  - Fill in the `PUBLIC_CARDANO_NETWORK` variable with "Preview", "Preprod" or "Mainnet" depending on which network you want to use.
+  - Fill in the corresponding `BLOCKFROST_URL`.
+  - Fill in the 
+
+- Set up your wallet by filling in the `WALLET_ADDRESS` and `WALLET_PRIVATE_KEY` variables.
+  - I recommend using `deno task generate-wallet` to generate a new wallet for testing this specifically. Once generated you can send the minimal funds you need for testing to the wallet from your hot wallet or from a testnet faucet.
+
+To verify your setup worked, or if you want to check the contents of the wallet you have connected, I've included a handy `deno task print-utxos` script.
+
+You should see something like this:
+```
+addr_test1vqhjcudw5m5pmehwtwduts2ayz2rlpm7vjq0ql6exsz6czq2gr7h8
+[
+  {
+    txHash: "6b369bac955857261566812acde749t9d438032ac6633a004cceeb2c4dc5b287",
+    outputIndex: 7,
+    assets: { lovelace: 9980876490n },
+    address: "addr_test1vqhjcudw5m5pmehwtwduts2ayz2rlpm7vjq0ql6exsz6czq2gr7h8",
+    datumHash: undefined,
+    datum: undefined,
+    scriptRef: undefined
+  }
+]
+```
+
+### Reading Royalties
+You can query the royalty information for a given collection with the following query:
+
+`deno task get-royalties [policyId]`
+
+This does not return CIP-27 royalties.
+
+### Minting CIP-102 Compliant NFTs
+You can mint a collection with multiple CIP-68 nfts & a royalty policy with
+
+`deno task mint-collection`
+
+Instead of using the command line, this takes its parameters from the `mock_` prefixed consts at the start of the `testTimelockedMint` function in `mock-frontend.ts`.

CIP-0102/ref_impl/offchain-reference/conversion.ts

@@ -0,0 +1,11 @@
+export const CIP102_ROYALTY_TOKEN_NAME = '001f4d70526f79616c7479'; // (500)Royalty
+
+// convert from percentage to onchain royalty value
+export function toOnchainRoyalty(percentage: number): number {
+	return Math.floor(1 / (percentage / 1000));
+}
+
+// convert from onchain royalty value to percentage
+export function fromOnchainRoyalty(value: number): number {
+	return Math.trunc((10 / value) * 1000) / 10;
+}

CIP-0102/ref_impl/offchain-reference/deno.json

@@ -0,0 +1,8 @@
+{
+  "tasks": {
+    "generate-wallet": "deno run --allow-net --allow-read --allow-env --allow-write scripts/generate-wallet.js",
+    "print-utxos": "deno run --allow-net --allow-read --allow-env --allow-write scripts/print-utxos.ts",
+    "mint-collection": "deno run --allow-net --allow-read --allow-env --allow-write scripts/mock-frontend.ts mint-collection",
+    "get-royalties": "deno run --allow-net --allow-read --allow-env --allow-write scripts/mock-frontend.ts get-royalties"
+  }
+}

CIP-0102/ref_impl/offchain-reference/index.ts

@@ -0,0 +1,3 @@
+export * from "./lib/mint.ts"
+export * from "./lib/read.ts"
+export * from "./lib/types.ts"