From bae8b8fe86eaa754b6600128b3c207aa88617601 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Mon, 10 Mar 2025 18:21:13 +0100 Subject: [PATCH 01/23] initial dir and md file --- ICRCs/ICRC-122/ICRC-122.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 ICRCs/ICRC-122/ICRC-122.md diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md new file mode 100644 index 00000000..e69de29b From e2c022dd69e68641b8f60648831b3d0dbfce08c5 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Mon, 10 Mar 2025 18:34:51 +0100 Subject: [PATCH 02/23] first draft --- ICRCs/ICRC-122/ICRC-122.md | Bin 0 -> 1976 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..19e5327a6d6202608574db39b5cac5f7b3d4aa88 100644 GIT binary patch literal 1976 zcmaJ?T~8Z16on!hH0n$L!Bu#nEF^@mn~RS%+oFO@E2aUVs8hwzy(RTUO)MX7}m zg{4-iA_^|et^ukA=*C2Fptw{3`K&cv5MT=Zq>BmmNdftisf55I%_?Cg(J4&l0#d1s zZMLKVi)%zZ6+#mzwJew{Y1XTajlht6+uBqK4RFZ`Jk2GW0|rv1LyW%gHHAV!Yvp!L zDVR*9;3t?7-|=t8;oCoVQ%HoXLFA=f)R}so5=74)V7e#;qB%ZpU*U%4;`n$11j$U0 zMDoJ^j?G0*qic$&*87n7SUw$=m{nZ(!c&!H>dEot@gPaj68`egVErsT1~~G)7y|j% z@ku@aEa6XKn3le9SVqg!t>=e@u)n#Cen1k7Ws)W(E=^Go1npE%_Ya(B-9qa$85HI?6}$gE$y8;TEndKM z1Z$4U$`;Kqkoj`X7pEoD}Y{vK=on4OJC7tnpdcbC5-Wl$ReSSa>*qd~3{Pyx}pU>E+Gnlc< z-*(e+XZXjA{oWbP#Krq{mes1s*AfsKw^0p>8^I3Zv$Hezfe942@`|rDulkKH2Jvuk z9*>5jcrd<*$D@mQczOOZj^os|$Xz5?3j2nQLS^AyqO^54%->$M2Bhn0j@@@hUUMBa zVzxN-Tc;vkMWrfGV< Date: Tue, 11 Mar 2025 11:11:13 +0100 Subject: [PATCH 03/23] added a mint block, added example blocks --- ICRCs/ICRC-122/ICRC-122.md | Bin 1976 -> 5183 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md index 19e5327a6d6202608574db39b5cac5f7b3d4aa88..98a4af630c7d5036b607806a9f0f20ac4a743751 100644 GIT binary patch literal 5183 zcmds5+iu%N5PjEI3>2V94ab&5NtB$nK$50FfTjf!w@(9zOYSlvOpz=}#dT`~{f+)! zzoch&c`;?DSGOoC*oM5^nVmUjZrn%o>cyKEPo}fk8J*`BCZp&3GE1^|^bx&IvKrq; zqeqYESrp~_tfn`nC{1OuTGdIOjht}%v?5g+DovD^+Gt8L3e!Bgz%qU^3Z9jvx(X%@T?x>RGf-F?y=P{F`V|LzIZK5WE4puFF3La$=Va_U#a?y4|R z5+_C zxGP#GJ5$waSG4kt;K)Wwo~HSwa1BZ&9xFIft0c9KHtUcNX09;WFeX2*tagJrWD&=6k?D{9Jdj+B;^Y z<1*j%n;~rz`|*1dAwmC0svh67tIr*z8{K>yz+WM`O<_5-3Cdaul`A%q3`U;_8WgCV z)Tq`nEZCSDIwde#wRW$KDyMCzX8L618n4O5h$w;_YCz zMd$w#iOw<0c%3`cEOf%tzY&ROa3*=*wivMnMa9MBLjF)-jX#J-H@fDCj zr;(w7o=N$wrHM78gUi>hLj$sXB^%KPkB*c~2JK*g;u+d*Cmq~P1F|G7RaOo<|FNy! z@}TMKxA*o%rEUIQk#OC3UrA?#u&WhP7Rgo`SABo^>F27gz->Q|?C8_$yTy>x=>{OD z_BV?|UYN2`CNtK{?*%dd^A;@`qgPbf^nQ*K0vOL>WNP#~Og%Q6(aH9av9?$HqDUQl zO=ZN`Q)-}_UUhc5qTN>0P^Bt^csq?aZJI*NBTX5#lBLS3*p!vq_|?~LbO}=&oP$6^ zu57m9-`Lsr3y^_%racAz!ZY-LSbKX+6at)YXt>f`Un5%Y@fj7YGzzC$y8npRQXoF$ zbF1yH*Afrt?~*e?GY8+kAT?3oP%?vW8o13QxLPGaI##Y9`335t*J`9z?+Gfv~CzD%0Gy8qY6U`I+ zo#H%q+;3`FvWYm->?vOR9EYq{yofoBc%@l+>=|BY4wbCTV)jT2%F&t^ z9#3QTC$fLJXlXEWznZ^I3Sg+u3E1P|QDC;;!Ko5^G%zjQ_!R_>GS@_8UXgl9eH z6>ORFWGNna9&5wXHODJf@M+4%um`k!UK?J*3C(`Yi#5+ZUijj%*1QHDOL@BTc)jGw zOmIE$#j+|e_n)yHxW_#M{iBY}d&J0289l>G;A&W}dFrvh5bW1eYZ#b^<#P^U+l2j) zS2K>+Y(UOTIP})6Jy^@D3CH-m5<;}k6T>r)XPRegUissDOt^U}rXB=pT@7$^5%_^pZnua!I;AY;uXl`;x292R1)kYS|Fzkn89?pbkOz z-%G8qQ1gwI{(YTOQMPoG&7gArvO$$|_g@N8XcW%t3@y>8(ViXzr z7nHNjqPv1!x@lMaM_u&?^bW)dp4~a;<9q#H{yA|wdsnW0jkJh`N<;uG2Bv_%(VAUT z;Gs&GR8pNo(hGs^bwZ!QCF^uW+$5`T+7{4~I!+#6GKR$5XxLLiQ;4)wTt=+3HUP)M zPzKM@^KsW_oQGYN&=u&lC2xaa3Zq1ZigobFI@&Fl!Km{uaC#jH!&a$0t?-Urh)Sgi zbfa4JyIN5~{^L)0TU@Y*xA}raGXE Date: Tue, 11 Mar 2025 11:26:42 +0100 Subject: [PATCH 04/23] restructuring --- ICRCs/ICRC-122/ICRC-122.md | 27 +++++++++++---------------- 1 file changed, 11 insertions(+), 16 deletions(-) diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md index 98a4af63..4086e360 100644 --- a/ICRCs/ICRC-122/ICRC-122.md +++ b/ICRCs/ICRC-122/ICRC-122.md @@ -1,25 +1,20 @@ # ICRC-122: Token Burning & Minting -## Account Representation -ICRC-1 Accounts are recorded in blocks as an `Array` of two `Value` variants: -- The first element is a `variant { Blob = }`, representing the account owner. -- The second element is a `variant { Blob = }`, representing the subaccount. If no subaccount is specified, this field MUST be an empty `Blob`. +ICRC-122 introduces new block types for recording token minting and burning events in ICRC-compliant ledgers. These blocks provide a standardized way to document authorized supply modifications, ensuring transparent tracking of token issuance and removal. The `122burn` block records token reductions, while the `122mint` block tracks token increases. By integrating these blocks into the ledger history, implementations enhance auditability and enforceability of token supply constraints. -## Block Types -- **Burn Tokens**: `122burn` -- **Mint Tokens**: `122mint` - +## Common Elements +This standard follows the conventions set by ICRC-3, inheriting key structural components. Accounts are recorded as an `Array` of two `Value` variants, where the first element is a `variant { Blob = }`, representing the account owner, and the second element is a `variant { Blob = }`, representing the subaccount. If no subaccount is specified, this field MUST be an empty `Blob`. Additionally, each block includes `phash`, a `Blob` representing the hash of the parent block, and `ts`, a `Nat` representing the timestamp of the block. These elements ensure consistency with the ICRC-3 ledger structure and facilitate seamless integration. -Each block adheres to the generic block schema defined in ICRC-3, which includes common fields such as: -- `phash`: A `Blob` representing the hash of the parent block. -- `ts`: A `Nat` representing the timestamp of the block. -The following sections detail the specific fields required for the `122burn` and `122mint` block types. +## Block Types & Schema +This standard introduces two new block types: -## Block Schema +- **Burn Tokens**: `122burn` +- **Mint Tokens**: `122mint` +The specific fields required for the `122burn` and `122mint` block types are as follows: ### 122burn Block @@ -31,7 +26,7 @@ Each `122burn` block MUST include the following fields: | `from` | `Array(vec { variant { Blob = }, variant { Blob = } })` | The account from which tokens are burned. | | `amount` | `Nat` | The amount of tokens burned. | | `authorizer` | `Blob` | The principal who authorized the burn. | -| `metadata` | `Map(Text, Blob)` | Optional metadata for additional details. | +| `metadata` | `Map(Text, Value)` | Optional metadata for additional details. | ### 122mint Block Each `122mint` block MUST include the following fields: @@ -42,7 +37,7 @@ Each `122mint` block MUST include the following fields: | `to` | `Array(vec { variant { Blob = }, variant { Blob = } })` | The account receiving the minted tokens. | | `amount` | `Nat` | The amount of tokens minted. | | `authorizer` | `Blob` | The principal who authorized the mint. | -| `metadata` | `Map(Text, Blob)` | Optional metadata for additional details. | +| `metadata` | `Map(Text, Value)` | Optional metadata for additional details. | ### Interesting Aspects - Accounts are represented using an **array of two blobs**: the first blob is the owner principal, and the second blob is the subaccount. @@ -70,7 +65,7 @@ variant { Map = vec { variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" }; }} }; - record { "amount"; variant { Nat = 1_000_000 : nat } }; + record { "amt"; variant { Nat = 1_000_000 : nat } }; record { "authorizer"; variant { Blob = blob "\94\85\a4\06\ba\33\de\19\f8\ad\b1\ee\3d\07\9e\63\1d\7f\59\43\57\bc\dd\98\56\63\83\96\02" };}; record { "phash"; From 7b7a180a102f7e9867906a838f8a419791337022 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Tue, 11 Mar 2025 11:56:00 +0100 Subject: [PATCH 05/23] removed some unncessary stuff --- ICRCs/ICRC-122/ICRC-122.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md index 4086e360..e5f47154 100644 --- a/ICRCs/ICRC-122/ICRC-122.md +++ b/ICRCs/ICRC-122/ICRC-122.md @@ -1,10 +1,10 @@ # ICRC-122: Token Burning & Minting -ICRC-122 introduces new block types for recording token minting and burning events in ICRC-compliant ledgers. These blocks provide a standardized way to document authorized supply modifications, ensuring transparent tracking of token issuance and removal. The `122burn` block records token reductions, while the `122mint` block tracks token increases. By integrating these blocks into the ledger history, implementations enhance auditability and enforceability of token supply constraints. +ICRC-122 introduces new block types for recording token minting and burning events in ICRC-compliant ledgers. These blocks provide a standardized way to document authorized supply modifications, ensuring transparent tracking of token issuance and removal. The `122burn` block records token reductions, while the `122mint` block tracks token increases. ## Common Elements -This standard follows the conventions set by ICRC-3, inheriting key structural components. Accounts are recorded as an `Array` of two `Value` variants, where the first element is a `variant { Blob = }`, representing the account owner, and the second element is a `variant { Blob = }`, representing the subaccount. If no subaccount is specified, this field MUST be an empty `Blob`. Additionally, each block includes `phash`, a `Blob` representing the hash of the parent block, and `ts`, a `Nat` representing the timestamp of the block. These elements ensure consistency with the ICRC-3 ledger structure and facilitate seamless integration. +This standard follows the conventions set by ICRC-3, inheriting key structural components. Accounts are recorded as an `Array` of two `Value` variants, where the first element is a `variant { Blob = }`, representing the account owner, and the second element is a `variant { Blob = }`, representing the subaccount. If no subaccount is specified, this field MUST be an empty `Blob`. Additionally, each block includes `phash`, a `Blob` representing the hash of the parent block, and `ts`, a `Nat` representing the timestamp of the block. ## Block Types & Schema From ff1929536c815bc0a43efe88c3b438ef73076973 Mon Sep 17 00:00:00 2001 From: Bogdan Warinschi Date: Wed, 12 Mar 2025 11:54:43 +0100 Subject: [PATCH 06/23] fixed the urls --- ICRCs/ICRC-122/ICRC-122.md | Bin 5561 -> 4869 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md index e5f47154ea65a3b4e3e51e42d8aa9b7bccd69671..7f640ce8c8abf2685558af61498fc85ec6bc9860 100644 GIT binary patch delta 1368 zcmb7DO>fgc5RH@64sP0rg7^>>3=LEwkkB>(>{fiW0*OjRh!!EiO4#v^TZ_a7+X(_% z^;B^{AXR(k$RFqhZk)LQ5*JRKxbqVjC$`(tQ}^WAeLM5s+vm^cH^%E_xHETut~xnY zpN5;3<#pT;Zu^L@9CsPU;el(%g{mgN&1z-TjG@UXm@bD-AH3Oqyw2N>>ja^1hE5m3 zv_i*o1Mrcy94e@{=l4p_kBX#S1nfHD%Ni`LAQ;4|HvkQ2wmj=8-LO2L2Q)3c(gy%` z(G4%aixsDZ5YEQ8V@BzH?pd8S0RspL;bYtDnl12b2s+lvHa+56+uD%kv*JhY?(FTz z0ZiPfRHk##^#4hc@B;&}fyTZy({4 z0fqGPZ`l-I4}26~RAaqw7y0sV1>GI=4RE3aL=TAkLhk{BXJ|RLgXBk|1Qs4FEq$c$Y{L(?1LW7zR2 zNG_o7dw#FMuGEPS#VhOO9}BbTCJ2eRc`O+Fk4aVBMrNwDP)|!6-udfL$(!UTpzqD>r9`FFcTS` zFI=8bnoOH2>J0TMMa$`o*RxEUC{8g=W7uH)N(K*Qc~*QYbq}QRie#KgtNjZpk3`}! zL_*eUl0*$=*2GY0R8&hx#gmcB^_)e+2YAlTqGU6TIBU6PsaizYENEG-aHd^4E9<16 zHxv@8UCY~wULLR&lj)88)}N6#QtJ8h!^=`#{5s5b2%x=V^;(;6bB`WlO*ITd{RdR_ BydVGo literal 5561 zcmds5ZExE~68^4VF;IXaH5^$IB~fzj4oK4!2+*`Z;`Y-5;*wlOg!xvIva35A=-=qy z>o4guvwV?gr|liw7C0giq~*@+%ro=MjQ1J6ef|FRi`jgBNmu!`$>@uHnZ?;h`i$Pi zS&eU_QM-k(Q0C!2FcoFymi#0SuBkp0_#NdXl_to`kcDeem0AU)vyl8ot+_E-T|tvQ zILOl?iFH;}V#1H6tR{4|GnKKrD=NzTCJqg0s%ogwQ2%ce(ycz=3<~pLpF$t$eZ9*| zc~$L;A~{f+hjA1Kx{mX#IwzA=`%)|`bygL+WU0E;!8I@DQDbpjRePNUI1eV5Ce3ej zA{LPch}Z|O@!I-YHFBi^D$P;1yErja?~KSW2Ca;o*NVhhP#RsCYBCy)o;{=2d79=K zy-5svRE@57an(5uc#|Z*g)GztdBz~JV^o=%{DZ~PIR~seQ^p)Mx;6)hmoRHz>I6b* zk!P%VLa%}#-*XfILlZP$s_{D`?^RjqgC~&O=Hz{^lfCiiMwc8VAbE=utb0*hRy7%G zFu__)UbBz>LtiAhPyeKU*c<_!Wf{A?0Z2xYzZ>dH!gqme%k z@T%j~fDviYY7o&0*<8YjAm)`2^E3Jo>`bahgN!=ja*aR__okJf}_m&x!8nOH&19TyWIs zZglrz@H|+s?@yN@N1o61(rb^z!j<_E5k7tHy4>p>6X~eT(|$9gg|5$UOaRLL5%Qfs zva9C;=tK9Pd+?V-*piYD1@B|vEQQ?`4vw7(CyWMpI^~MeT80Hl+f%0)Mo}w!yP{i3 zZ|F6(rMzTq(1a-a{PpCqn!2h2>+<6!!1=}YHP)r3)}gMoCpw_>oi3g;?&l=+4IcAz zN8d_-Q7&5v$yVLbokD1e6V%YVE)_XzhpBj+$^TcWXdRP~*SSSapyNRO6{(1}YvLPe zHV*`_+o~5F>Lis*9B(#ia|tYJ3G_d z@!N)vKH^KQXA0R4&r94Sd1cVeA9U*Dy?t4kz!GMDS0-$K-DCO@t+rZlVI-+Fw*LO| z)6Zz6%>dH26B+1weMcd(I=i_H$Ngq`$O}_8%6R;G^CLqBU_PK%VlD|PX*Jvc8{_SO zY74W>dv*$H=FN75L~X<0Bwou^S=doFsZhuz+ZTVnG4ggMG2yq!#S+hH%y}3Uf&^IAMv>zSViCu zdCe8#Q$Dxa9(v7rG8hK_OBWDKOh$kSts}U$fox}n=GDmayiwmT(GM`IN*5h*J+t_r zrH-Xtk6#{jP3{}mJZ?0O>HhxZK#0SAA|s{o9tx$$`8~!RN7IFQOi*InpftLa@K0KQL8C02CmXG z6>QYfQL{+7Q{KN?sbHzJtIR^pdmHXCE)1R5X?@~5CIPrM+fJub{!f>bVdXKwj?5?W zr`T*3Y7IjcYPw?c9Y=*m%{D4pD-DNc${6JUDpzfcTET-*xsh6K)WT6qm)#9RwE-9_ ze!F(mW~HWc26f$!?H${;dx4xqD9p#y8xda5FPt~nZ^tENWH9W@Wte52Ox_z@HCU$Uu# zEUl{(oZC3Li`mwh&9|=OZfEPocI_^<&SribH_mt_P&=XBG$d*q+tdpWMRpFEq6D;Y9&izUHbWm9ie1aMsj)Uz( zN*FLX;A}?yaUwMbr6aWlF_84Wnz?GZR1x@$dbQ?6cSEiM3n33UA1=5?fe-FVEx<0z z_DE?|zlB-^LrNS~P&R+Sd>TIqGx$bF?zV89^xhPCDVJ$q+iNb0xk2$wkDX=t4x+i> zY9|cb+t}vZ|LKbP4wpD+{OJE)9F&2xu6MY5`0oAJROH~2 zoRZtt-JTPgD3+_fqYDfc$DhX19rcTT=0~5!7cM5)o~_2EBWN>%t;#d^`q_3PvyvIb^41PxtHkt E3j7_<`v3p{ From daf5a77ad47c93ed0debeb6a9fe18b7f5745907c Mon Sep 17 00:00:00 2001 From: Bogdan Warinschi Date: Mon, 31 Mar 2025 13:21:00 +0200 Subject: [PATCH 07/23] fixed some blobs --- ICRCs/ICRC-122/ICRC-122.md | Bin 4869 -> 4966 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md index 7f640ce8c8abf2685558af61498fc85ec6bc9860..1c440ca74966f32015cfce29438778b591cda201 100644 GIT binary patch delta 1046 zcmdUsO=}cE5QZ`C#W8W?K~RuTY&3%8V`gXPi#-_>J(w(E4MHd|Jv}wq#!b)C)8o2< zjVJFygGYaZ5K!?Cc=s%L6Z{wUtT_ZE2k~UnG)+}^J#W4BdgaH;d(}Ak+Bk0XpihTP zYQam#S%aqolE7f!Yx}t(I--3@hXsEQq69^}P#I;bpa%p)$__}u)^7g^kSr@jHq5j+ zc5cjx(!6tmoA=}dnAUVS(x3~_ipi334P&7P=BIOa`wXp;f5B5!>S6{YV5t}iJ%J*x z(W{mtq|kzCo03^An#2pM?G!EwS+3hgHw&xbZR6I3(tN+Xmaf50MQS4Cf&B%H^P-aa zP6?%Ex+vdGxQlI5#}kf z7=s*Bj&X*}N1rgrFlBY5oueOPm|*DEK^`IVkS7@U=;au>_4_bH9w3X5I@tDF@SEMQ z($nT0uxmQCaeFgcO?MBI4#xJ2?INr}zK12$ sx~ItOG*|H)_u_wdZ`w6)n%DmDZ~pc<$fPx!?QFg?cSk257JGBQ0I1SSBLDyZ delta 900 zcmZvaK~K~`6vwx_%XV2=0TT&CVqRFpWCIJhi)kUKKs3>)iD8L}>0xI(uk6G!turkM zW`h@xp629dFeWA(^vihlb2!r?VstL;yqWj^{r|81x$t4(t0>QR2M97op9Rc^fMG}_ z2z-+=ffRyBKr%ozsLfA7avY-sA`pnwCt(;J$@R0i{JwnJfX6&RfihuyAGVBMB5O;q z<@-^}le|k{tZ$&cNFkNxBH_?%5+TSjL;)m65%j~TFPqJEL)C7COtKO%nN^}AjsjxA zxX)q|E@}m;4|a3}^dtRl`hQ=RX`kf$mbPMY_DGrxBEe2j^zy7asvij*IZ><%Poo$G zNm#^NwOXSA58s*~+U_nM5S}n!>S_ZX3B(iBnlA^)p|^Uc9b}cBA?Jcf7uEgI8T;AZ zZWsEfUX89zbp_#)_(om=i7S!Hy4bbf=5>>ZYy^*teKwtJHWea zlOxn_efHFx=`?-V%zu_S4@t@QuroqSK@qLMb6jn+)E{3O!wRW7MQT&eS-Vwnbu8Mk twSVVcIk4TvNMIAs?UenwbBNJ4Yq;@O;e4ApQa|cXlr=eZHa+>g_zMS{2*&^b From 97744ab350d37f007971442710768dff593f0e75 Mon Sep 17 00:00:00 2001 From: Bogdan Warinschi Date: Mon, 31 Mar 2025 15:04:11 +0200 Subject: [PATCH 08/23] Revert "fixed some blobs" This reverts commit daf5a77ad47c93ed0debeb6a9fe18b7f5745907c. --- ICRCs/ICRC-122/ICRC-122.md | Bin 4966 -> 4869 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md index 1c440ca74966f32015cfce29438778b591cda201..7f640ce8c8abf2685558af61498fc85ec6bc9860 100644 GIT binary patch delta 900 zcmZvaK~K~`6vwx_%XV2=0TT&CVqRFpWCIJhi)kUKKs3>)iD8L}>0xI(uk6G!turkM zW`h@xp629dFeWA(^vihlb2!r?VstL;yqWj^{r|81x$t4(t0>QR2M97op9Rc^fMG}_ z2z-+=ffRyBKr%ozsLfA7avY-sA`pnwCt(;J$@R0i{JwnJfX6&RfihuyAGVBMB5O;q z<@-^}le|k{tZ$&cNFkNxBH_?%5+TSjL;)m65%j~TFPqJEL)C7COtKO%nN^}AjsjxA zxX)q|E@}m;4|a3}^dtRl`hQ=RX`kf$mbPMY_DGrxBEe2j^zy7asvij*IZ><%Poo$G zNm#^NwOXSA58s*~+U_nM5S}n!>S_ZX3B(iBnlA^)p|^Uc9b}cBA?Jcf7uEgI8T;AZ zZWsEfUX89zbp_#)_(om=i7S!Hy4bbf=5>>ZYy^*teKwtJHWea zlOxn_efHFx=`?-V%zu_S4@t@QuroqSK@qLMb6jn+)E{3O!wRW7MQT&eS-Vwnbu8Mk twSVVcIk4TvNMIAs?UenwbBNJ4Yq;@O;e4ApQa|cXlr=eZHa+>g_zMS{2*&^b delta 1046 zcmdUsO=}cE5QZ`C#W8W?K~RuTY&3%8V`gXPi#-_>J(w(E4MHd|Jv}wq#!b)C)8o2< zjVJFygGYaZ5K!?Cc=s%L6Z{wUtT_ZE2k~UnG)+}^J#W4BdgaH;d(}Ak+Bk0XpihTP zYQam#S%aqolE7f!Yx}t(I--3@hXsEQq69^}P#I;bpa%p)$__}u)^7g^kSr@jHq5j+ zc5cjx(!6tmoA=}dnAUVS(x3~_ipi334P&7P=BIOa`wXp;f5B5!>S6{YV5t}iJ%J*x z(W{mtq|kzCo03^An#2pM?G!EwS+3hgHw&xbZR6I3(tN+Xmaf50MQS4Cf&B%H^P-aa zP6?%Ex+vdGxQlI5#}kf z7=s*Bj&X*}N1rgrFlBY5oueOPm|*DEK^`IVkS7@U=;au>_4_bH9w3X5I@tDF@SEMQ z($nT0uxmQCaeFgcO?MBI4#xJ2?INr}zK12$ sx~ItOG*|H)_u_wdZ`w6)n%DmDZ~pc<$fPx!?QFg?cSk257JGBQ0I1SSBLDyZ From 89eba860a1ff4ec155c864b4e30e2fb723b7399b Mon Sep 17 00:00:00 2001 From: Bogdan Warinschi Date: Mon, 31 Mar 2025 15:04:34 +0200 Subject: [PATCH 09/23] Revert "fixed the urls" This reverts commit ff1929536c815bc0a43efe88c3b438ef73076973. --- ICRCs/ICRC-122/ICRC-122.md | Bin 4869 -> 5561 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md index 7f640ce8c8abf2685558af61498fc85ec6bc9860..e5f47154ea65a3b4e3e51e42d8aa9b7bccd69671 100644 GIT binary patch literal 5561 zcmds5ZExE~68^4VF;IXaH5^$IB~fzj4oK4!2+*`Z;`Y-5;*wlOg!xvIva35A=-=qy z>o4guvwV?gr|liw7C0giq~*@+%ro=MjQ1J6ef|FRi`jgBNmu!`$>@uHnZ?;h`i$Pi zS&eU_QM-k(Q0C!2FcoFymi#0SuBkp0_#NdXl_to`kcDeem0AU)vyl8ot+_E-T|tvQ zILOl?iFH;}V#1H6tR{4|GnKKrD=NzTCJqg0s%ogwQ2%ce(ycz=3<~pLpF$t$eZ9*| zc~$L;A~{f+hjA1Kx{mX#IwzA=`%)|`bygL+WU0E;!8I@DQDbpjRePNUI1eV5Ce3ej zA{LPch}Z|O@!I-YHFBi^D$P;1yErja?~KSW2Ca;o*NVhhP#RsCYBCy)o;{=2d79=K zy-5svRE@57an(5uc#|Z*g)GztdBz~JV^o=%{DZ~PIR~seQ^p)Mx;6)hmoRHz>I6b* zk!P%VLa%}#-*XfILlZP$s_{D`?^RjqgC~&O=Hz{^lfCiiMwc8VAbE=utb0*hRy7%G zFu__)UbBz>LtiAhPyeKU*c<_!Wf{A?0Z2xYzZ>dH!gqme%k z@T%j~fDviYY7o&0*<8YjAm)`2^E3Jo>`bahgN!=ja*aR__okJf}_m&x!8nOH&19TyWIs zZglrz@H|+s?@yN@N1o61(rb^z!j<_E5k7tHy4>p>6X~eT(|$9gg|5$UOaRLL5%Qfs zva9C;=tK9Pd+?V-*piYD1@B|vEQQ?`4vw7(CyWMpI^~MeT80Hl+f%0)Mo}w!yP{i3 zZ|F6(rMzTq(1a-a{PpCqn!2h2>+<6!!1=}YHP)r3)}gMoCpw_>oi3g;?&l=+4IcAz zN8d_-Q7&5v$yVLbokD1e6V%YVE)_XzhpBj+$^TcWXdRP~*SSSapyNRO6{(1}YvLPe zHV*`_+o~5F>Lis*9B(#ia|tYJ3G_d z@!N)vKH^KQXA0R4&r94Sd1cVeA9U*Dy?t4kz!GMDS0-$K-DCO@t+rZlVI-+Fw*LO| z)6Zz6%>dH26B+1weMcd(I=i_H$Ngq`$O}_8%6R;G^CLqBU_PK%VlD|PX*Jvc8{_SO zY74W>dv*$H=FN75L~X<0Bwou^S=doFsZhuz+ZTVnG4ggMG2yq!#S+hH%y}3Uf&^IAMv>zSViCu zdCe8#Q$Dxa9(v7rG8hK_OBWDKOh$kSts}U$fox}n=GDmayiwmT(GM`IN*5h*J+t_r zrH-Xtk6#{jP3{}mJZ?0O>HhxZK#0SAA|s{o9tx$$`8~!RN7IFQOi*InpftLa@K0KQL8C02CmXG z6>QYfQL{+7Q{KN?sbHzJtIR^pdmHXCE)1R5X?@~5CIPrM+fJub{!f>bVdXKwj?5?W zr`T*3Y7IjcYPw?c9Y=*m%{D4pD-DNc${6JUDpzfcTET-*xsh6K)WT6qm)#9RwE-9_ ze!F(mW~HWc26f$!?H${;dx4xqD9p#y8xda5FPt~nZ^tENWH9W@Wte52Ox_z@HCU$Uu# zEUl{(oZC3Li`mwh&9|=OZfEPocI_^<&SribH_mt_P&=XBG$d*q+tdpWMRpFEq6D;Y9&izUHbWm9ie1aMsj)Uz( zN*FLX;A}?yaUwMbr6aWlF_84Wnz?GZR1x@$dbQ?6cSEiM3n33UA1=5?fe-FVEx<0z z_DE?|zlB-^LrNS~P&R+Sd>TIqGx$bF?zV89^xhPCDVJ$q+iNb0xk2$wkDX=t4x+i> zY9|cb+t}vZ|LKbP4wpD+{OJE)9F&2xu6MY5`0oAJROH~2 zoRZtt-JTPgD3+_fqYDfc$DhX19rcTT=0~5!7cM5)o~_2EBWN>%t;#d^`q_3PvyvIb^41PxtHkt E3j7_<`v3p{ delta 1368 zcmb7DO>fgc5RH@64sP0rg7^>>3=LEwkkB>(>{fiW0*OjRh!!EiO4#v^TZ_a7+X(_% z^;B^{AXR(k$RFqhZk)LQ5*JRKxbqVjC$`(tQ}^WAeLM5s+vm^cH^%E_xHETut~xnY zpN5;3<#pT;Zu^L@9CsPU;el(%g{mgN&1z-TjG@UXm@bD-AH3Oqyw2N>>ja^1hE5m3 zv_i*o1Mrcy94e@{=l4p_kBX#S1nfHD%Ni`LAQ;4|HvkQ2wmj=8-LO2L2Q)3c(gy%` z(G4%aixsDZ5YEQ8V@BzH?pd8S0RspL;bYtDnl12b2s+lvHa+56+uD%kv*JhY?(FTz z0ZiPfRHk##^#4hc@B;&}fyTZy({4 z0fqGPZ`l-I4}26~RAaqw7y0sV1>GI=4RE3aL=TAkLhk{BXJ|RLgXBk|1Qs4FEq$c$Y{L(?1LW7zR2 zNG_o7dw#FMuGEPS#VhOO9}BbTCJ2eRc`O+Fk4aVBMrNwDP)|!6-udfL$(!UTpzqD>r9`FFcTS` zFI=8bnoOH2>J0TMMa$`o*RxEUC{8g=W7uH)N(K*Qc~*QYbq}QRie#KgtNjZpk3`}! zL_*eUl0*$=*2GY0R8&hx#gmcB^_)e+2YAlTqGU6TIBU6PsaizYENEG-aHd^4E9<16 zHxv@8UCY~wULLR&lj)88)}N6#QtJ8h!^=`#{5s5b2%x=V^;(;6bB`WlO*ITd{RdR_ BydVGo From 3e1578604e870834d3d3e577dac8fd45baa3dd30 Mon Sep 17 00:00:00 2001 From: Bogdan Warinschi Date: Tue, 1 Apr 2025 16:11:29 +0200 Subject: [PATCH 10/23] addex a tx structure in the block --- ICRCs/ICRC-122/ICRC-122.md | 153 +++++++++++++++++++++++-------------- 1 file changed, 96 insertions(+), 57 deletions(-) diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md index e5f47154..a8de86b7 100644 --- a/ICRCs/ICRC-122/ICRC-122.md +++ b/ICRCs/ICRC-122/ICRC-122.md @@ -4,96 +4,135 @@ ICRC-122 introduces new block types for recording token minting and burning even ## Common Elements -This standard follows the conventions set by ICRC-3, inheriting key structural components. Accounts are recorded as an `Array` of two `Value` variants, where the first element is a `variant { Blob = }`, representing the account owner, and the second element is a `variant { Blob = }`, representing the subaccount. If no subaccount is specified, this field MUST be an empty `Blob`. Additionally, each block includes `phash`, a `Blob` representing the hash of the parent block, and `ts`, a `Nat` representing the timestamp of the block. +This standard follows the conventions set by ICRC-3, inheriting key structural components. Accounts are recorded as an `Array` of two `Value` variants, where the first element is a `variant { Blob = }`, representing the account owner, and the second element is a `variant { Blob = }`, representing the subaccount. If no subaccount is specified, this field MUST be an empty `Blob`. Additionally, each block includes `phash`, a `Blob` representing the hash of the parent block, and `ts`, a `Nat` representing the timestamp of the block. ## Block Types & Schema -This standard introduces two new block types: +Each block introduced by this standard MUST include a `tx` field containing a map that encodes the token mint or burn transaction submitted to the ledger that caused this block to be created, similarly to how transaction blocks defined in ICRC-1 and ICRC-2 include the submitted transaction. -- **Burn Tokens**: `122burn` -- **Mint Tokens**: `122mint` +This enables canister clients, indexers, and auditors to reconstruct the exact instruction that led to the block being appended to the ledger. -The specific fields required for the `122burn` and `122mint` block types are as follows: +Each `122burn` or `122mint` block consists of the following top-level fields: +| Field | Type (ICRC-3 `Value`) | Required | Description | +|----------|------------------------|----------|-------------| +| `btype` | `Text` | Yes | MUST be one of: `"122burn"` or `"122mint"`. | +| `ts` | `Nat` | Yes | Timestamp in nanoseconds when the block was added to the ledger. | +| `phash` | `Blob` | Yes | Hash of the parent block. | +| `tx` | `Map(Text, Value)` | Yes | Encodes the token mint or burn transaction submitted to the ledger that caused this block to be created. | -### 122burn Block -Each `122burn` block MUST include the following fields: +### `tx` Field Schemas -| Field | Type (ICRC-3 `Value`) | Description | -|----------------|----------------------|-------------| -| `btype` | `Text` | MUST be `122burn` | -| `from` | `Array(vec { variant { Blob = }, variant { Blob = } })` | The account from which tokens are burned. | -| `amount` | `Nat` | The amount of tokens burned. | -| `authorizer` | `Blob` | The principal who authorized the burn. | -| `metadata` | `Map(Text, Value)` | Optional metadata for additional details. | +#### For `122burn` -### 122mint Block -Each `122mint` block MUST include the following fields: +| Field | Type (ICRC-3 `Value`) | Required | Description | +|--------------|-------------------------------|----------|-------------| +| `from` | `Array(vec { Blob [, Blob] })` | Yes | The account from which tokens are burned. | +| `amount` | `Nat` | Yes | The number of tokens to burn. | +| `authorizer` | `Blob` | Yes | The principal who authorized the burn. | +| `metadata` | `Map(Text, Value)` | Optional | Additional metadata. | -| Field | Type (ICRC-3 `Value`) | Description | -|----------------|----------------------|-------------| -| `btype` | `Text` | MUST be `122mint` | -| `to` | `Array(vec { variant { Blob = }, variant { Blob = } })` | The account receiving the minted tokens. | -| `amount` | `Nat` | The amount of tokens minted. | -| `authorizer` | `Blob` | The principal who authorized the mint. | -| `metadata` | `Map(Text, Value)` | Optional metadata for additional details. | +#### For `122mint` -### Interesting Aspects -- Accounts are represented using an **array of two blobs**: the first blob is the owner principal, and the second blob is the subaccount. +| Field | Type (ICRC-3 `Value`) | Required | Description | +|--------------|-------------------------------|----------|-------------| +| `to` | `Array(vec { Blob [, Blob] })` | Yes | The account to which tokens are minted. | +| `amount` | `Nat` | Yes | The number of tokens to mint. | +| `authorizer` | `Blob` | Yes | The principal who authorized the mint. | +| `metadata` | `Map(Text, Value)` | Optional | Additional metadata. | + + +## Interesting Aspects + +- Accounts are represented using an **array of one or two blobs**: the first blob is the owner principal, and the second blob is the subaccount (if present). If no subaccount is specified, only the owner is included. - The `amount` field uses the `Nat` type from ICRC-3’s `Value` specification. -- The `authorizer` field records the principal who authorized the operation. +- The `authorizer` field in the `tx` object identifies the principal who authorized the operation. +- Each `122burn` or `122mint` block contains a `tx` field that encodes the mint or burn instruction that caused the block to be appended to the ledger. + +## Semantics -## Expected Semantics ### Burn -- The ledger MUST reduce the supply of tokens accordingly. -- The `from` account balance MUST be reduced by `amount`. -- Transfers MUST NOT be able to use burned tokens. + +When a block of type `122burn` is recorded: + +- The ledger MUST reduce the total supply of tokens by the amount specified in `tx.amount`. +- The balance of the `tx.from` account MUST be decreased by `tx.amount`. +- Tokens burned in this way MUST NOT be available for future transfers. - The `122burn` block MUST be permanently recorded in the ledger. + ### Mint -- The ledger MUST increase the supply of tokens accordingly. -- The `to` account balance MUST be increased by `amount`. + +When a block of type `122mint` is recorded: + +- The ledger MUST increase the total supply of tokens by the amount specified in `tx.amount`. +- The balance of the `tx.to` account MUST be increased by `tx.amount`. - The `122mint` block MUST be permanently recorded in the ledger. ## Example Blocks ### 122burn Example ``` variant { Map = vec { + // Block type identifier record { "btype"; variant { Text = "122burn" }}; - record { "from"; variant { Array = vec { - variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; - variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" }; - }} }; - record { "amt"; variant { Nat = 1_000_000 : nat } }; - record { "authorizer"; variant { Blob = blob "\94\85\a4\06\ba\33\de\19\f8\ad\b1\ee\3d\07\9e\63\1d\7f\59\43\57\bc\dd\98\56\63\83\96\02" };}; - record { - "phash"; - variant { - Blob = blob "\6f\7e\d9\13\75\69\91\bc\d0\0d\04\b6\60\7b\82\f9\e9\62\a8\39\d3\02\80\f2\88\e4\d7\0e\23\2d\29\87" - }; - record { "ts"; variant { Nat = 1_741_312_737_184_874_392 : nat } }; + + // Timestamp when the block was appended (nanoseconds since epoch) + record { "ts"; variant { Nat = 1_741_312_737_184_874_392 : nat }}; + + // Hash of the previous block in the ledger chain + record { "phash"; variant { + Blob = blob "\6f\7e\d9\13\75\69\91\bc\d0\0d\04\b6\60\7b\82\f9\e9\62\a8\39\d3\02\80\f2\88\e4\d7\0e\23\2d\29\87" + }}; + + // The burn transaction + record { "tx"; variant { Map = vec { + // The account from which tokens are burned + record { "from"; variant { Array = vec { + variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; + variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" }; + }}}; + + // The amount to burn + record { "amount"; variant { Nat = 1_000_000 : nat }}; + + // The principal that authorized the burn + record { "authorizer"; variant { Blob = blob "\94\85\a4\06\ba\33\de\19\f8\ad\b1\ee\3d\07\9e\63\1d\7f\59\43\57\bc\dd\98\56\63\83\96\02" }}; + }}}; }}; + ``` ### 122mint Example ``` variant { Map = vec { + // Block type identifier record { "btype"; variant { Text = "122mint" }}; - record { "to"; variant { Array = vec { - variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\02" }; - variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" }; - }} }; - record { "amount"; variant { Nat = 500_000 : nat } }; - record { "authorizer"; variant { Blob = blob "\00\00\00\00\00\d0\69\56\01\01" };} - record { - "phash"; - variant { - Blob = blob "\ea\3c\e4\5d\3f\2e\1f\89\98\3b\17\55\fe\6a\b8\2d\7d\85\45\69\b1\d4\a3\88\76\4f\79\43\5f\aa\94\4c" - }; - }; - record { "ts"; variant { Nat = 1_741_312_737_184_874_392 : nat } }; + + // Timestamp when the block was appended (nanoseconds since epoch) + record { "ts"; variant { Nat = 1_741_312_737_184_874_392 : nat }}; + + // Hash of the previous block in the ledger chain + record { "phash"; variant { + Blob = blob "\7a\61\cf\18\a4\9d\ac\20\39\33\78\f1\c2\fd\45\81\ab\55\37\20\1d\fe\77\a3\c6\55\de\01\92\a4\3b\ee" + }}; + + // The mint transaction + record { "tx"; variant { Map = vec { + // The account to which tokens are minted (principal + subaccount) + record { "to"; variant { Array = vec { + variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; // owner principal + variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" } // subaccount + }}}; + + // The amount to mint + record { "amount"; variant { Nat = 2_000_000 : nat }}; + + // The principal that authorized the mint + record { "authorizer"; variant { Blob = blob "\aa\bc\34\12\cd\78\ef\90\01\23\45\67\89\ab\cd\ef\01\02\03\04\05\06\07\08\09\0a\0b\0c\0d\0e\0f" }}; + }}}; }}; + ``` ## Compliance Reporting From 9fcf09ea8feb82e51ca4769c059ad6f44a58d5a6 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Fri, 4 Apr 2025 16:09:58 +0200 Subject: [PATCH 11/23] appended -> recorded --- ICRCs/ICRC-122/ICRC-122.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md index a8de86b7..90f6cd7c 100644 --- a/ICRCs/ICRC-122/ICRC-122.md +++ b/ICRCs/ICRC-122/ICRC-122.md @@ -11,7 +11,7 @@ This standard follows the conventions set by ICRC-3, inheriting key structural c Each block introduced by this standard MUST include a `tx` field containing a map that encodes the token mint or burn transaction submitted to the ledger that caused this block to be created, similarly to how transaction blocks defined in ICRC-1 and ICRC-2 include the submitted transaction. -This enables canister clients, indexers, and auditors to reconstruct the exact instruction that led to the block being appended to the ledger. +This enables canister clients, indexers, and auditors to reconstruct the exact instruction that led to the block being recorded to the ledger. Each `122burn` or `122mint` block consists of the following top-level fields: @@ -48,7 +48,7 @@ Each `122burn` or `122mint` block consists of the following top-level fields: - Accounts are represented using an **array of one or two blobs**: the first blob is the owner principal, and the second blob is the subaccount (if present). If no subaccount is specified, only the owner is included. - The `amount` field uses the `Nat` type from ICRC-3’s `Value` specification. - The `authorizer` field in the `tx` object identifies the principal who authorized the operation. -- Each `122burn` or `122mint` block contains a `tx` field that encodes the mint or burn instruction that caused the block to be appended to the ledger. +- Each `122burn` or `122mint` block contains a `tx` field that encodes the mint or burn instruction that caused the block to be recorded in the ledger. ## Semantics @@ -77,7 +77,7 @@ variant { Map = vec { // Block type identifier record { "btype"; variant { Text = "122burn" }}; - // Timestamp when the block was appended (nanoseconds since epoch) + // Timestamp when the block was recorded (nanoseconds since epoch) record { "ts"; variant { Nat = 1_741_312_737_184_874_392 : nat }}; // Hash of the previous block in the ledger chain @@ -109,7 +109,7 @@ variant { Map = vec { // Block type identifier record { "btype"; variant { Text = "122mint" }}; - // Timestamp when the block was appended (nanoseconds since epoch) + // Timestamp when the block was recorded (nanoseconds since epoch) record { "ts"; variant { Nat = 1_741_312_737_184_874_392 : nat }}; // Hash of the previous block in the ledger chain From a7c66d9a88fe6f1cf356d75d8c97be7bcf72529e Mon Sep 17 00:00:00 2001 From: Bogdan Warinschi Date: Fri, 11 Apr 2025 11:28:10 +0200 Subject: [PATCH 12/23] fixed conflicts --- ICRCs/ICRC-122/ICRC-122.md | 52 +++++++++++++------------------------- 1 file changed, 17 insertions(+), 35 deletions(-) diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md index 90f6cd7c..d5e9eb66 100644 --- a/ICRCs/ICRC-122/ICRC-122.md +++ b/ICRCs/ICRC-122/ICRC-122.md @@ -2,11 +2,9 @@ ICRC-122 introduces new block types for recording token minting and burning events in ICRC-compliant ledgers. These blocks provide a standardized way to document authorized supply modifications, ensuring transparent tracking of token issuance and removal. The `122burn` block records token reductions, while the `122mint` block tracks token increases. - ## Common Elements This standard follows the conventions set by ICRC-3, inheriting key structural components. Accounts are recorded as an `Array` of two `Value` variants, where the first element is a `variant { Blob = }`, representing the account owner, and the second element is a `variant { Blob = }`, representing the subaccount. If no subaccount is specified, this field MUST be an empty `Blob`. Additionally, each block includes `phash`, a `Blob` representing the hash of the parent block, and `ts`, a `Nat` representing the timestamp of the block. - ## Block Types & Schema Each block introduced by this standard MUST include a `tx` field containing a map that encodes the token mint or burn transaction submitted to the ledger that caused this block to be created, similarly to how transaction blocks defined in ICRC-1 and ICRC-2 include the submitted transaction. @@ -17,7 +15,7 @@ Each `122burn` or `122mint` block consists of the following top-level fields: | Field | Type (ICRC-3 `Value`) | Required | Description | |----------|------------------------|----------|-------------| -| `btype` | `Text` | Yes | MUST be one of: `"122burn"` or `"122mint"`. | +| `btype` | `Text` | Yes | MUST be one of: "122burn" or "122mint". | | `ts` | `Nat` | Yes | Timestamp in nanoseconds when the block was added to the ledger. | | `phash` | `Blob` | Yes | Hash of the parent block. | | `tx` | `Map(Text, Value)` | Yes | Encodes the token mint or burn transaction submitted to the ledger that caused this block to be created. | @@ -30,8 +28,7 @@ Each `122burn` or `122mint` block consists of the following top-level fields: |--------------|-------------------------------|----------|-------------| | `from` | `Array(vec { Blob [, Blob] })` | Yes | The account from which tokens are burned. | | `amount` | `Nat` | Yes | The number of tokens to burn. | -| `authorizer` | `Blob` | Yes | The principal who authorized the burn. | -| `metadata` | `Map(Text, Value)` | Optional | Additional metadata. | +| `reason` | `Text` | Yes | Human-readable reason for the burn. | #### For `122mint` @@ -39,16 +36,18 @@ Each `122burn` or `122mint` block consists of the following top-level fields: |--------------|-------------------------------|----------|-------------| | `to` | `Array(vec { Blob [, Blob] })` | Yes | The account to which tokens are minted. | | `amount` | `Nat` | Yes | The number of tokens to mint. | -| `authorizer` | `Blob` | Yes | The principal who authorized the mint. | -| `metadata` | `Map(Text, Value)` | Optional | Additional metadata. | - +| `reason` | `Text` | Yes | Human-readable reason for the mint. | ## Interesting Aspects - Accounts are represented using an **array of one or two blobs**: the first blob is the owner principal, and the second blob is the subaccount (if present). If no subaccount is specified, only the owner is included. - The `amount` field uses the `Nat` type from ICRC-3’s `Value` specification. +<<<<<<< HEAD - The `authorizer` field in the `tx` object identifies the principal who authorized the operation. - Each `122burn` or `122mint` block contains a `tx` field that encodes the mint or burn instruction that caused the block to be recorded in the ledger. +======= +- Each `122burn` or `122mint` block contains a `tx` field that encodes the mint or burn instruction that caused the block to be appended to the ledger. +>>>>>>> 1e6e02d (removed memo, added reason) ## Semantics @@ -61,7 +60,6 @@ When a block of type `122burn` is recorded: - Tokens burned in this way MUST NOT be available for future transfers. - The `122burn` block MUST be permanently recorded in the ledger. - ### Mint When a block of type `122mint` is recorded: @@ -74,65 +72,49 @@ When a block of type `122mint` is recorded: ### 122burn Example ``` variant { Map = vec { - // Block type identifier record { "btype"; variant { Text = "122burn" }}; +<<<<<<< HEAD // Timestamp when the block was recorded (nanoseconds since epoch) +======= +>>>>>>> 1e6e02d (removed memo, added reason) record { "ts"; variant { Nat = 1_741_312_737_184_874_392 : nat }}; - - // Hash of the previous block in the ledger chain record { "phash"; variant { Blob = blob "\6f\7e\d9\13\75\69\91\bc\d0\0d\04\b6\60\7b\82\f9\e9\62\a8\39\d3\02\80\f2\88\e4\d7\0e\23\2d\29\87" }}; - - // The burn transaction record { "tx"; variant { Map = vec { - // The account from which tokens are burned record { "from"; variant { Array = vec { variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" }; }}}; - - // The amount to burn record { "amount"; variant { Nat = 1_000_000 : nat }}; - - // The principal that authorized the burn - record { "authorizer"; variant { Blob = blob "\94\85\a4\06\ba\33\de\19\f8\ad\b1\ee\3d\07\9e\63\1d\7f\59\43\57\bc\dd\98\56\63\83\96\02" }}; + record { "reason"; variant { Text = "Token supply adjustment" }}; }}}; }}; - ``` ### 122mint Example ``` variant { Map = vec { - // Block type identifier record { "btype"; variant { Text = "122mint" }}; +<<<<<<< HEAD // Timestamp when the block was recorded (nanoseconds since epoch) +======= +>>>>>>> 1e6e02d (removed memo, added reason) record { "ts"; variant { Nat = 1_741_312_737_184_874_392 : nat }}; - - // Hash of the previous block in the ledger chain record { "phash"; variant { Blob = blob "\7a\61\cf\18\a4\9d\ac\20\39\33\78\f1\c2\fd\45\81\ab\55\37\20\1d\fe\77\a3\c6\55\de\01\92\a4\3b\ee" }}; - - // The mint transaction record { "tx"; variant { Map = vec { - // The account to which tokens are minted (principal + subaccount) record { "to"; variant { Array = vec { - variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; // owner principal - variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" } // subaccount + variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; + variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" } }}}; - - // The amount to mint record { "amount"; variant { Nat = 2_000_000 : nat }}; - - // The principal that authorized the mint - record { "authorizer"; variant { Blob = blob "\aa\bc\34\12\cd\78\ef\90\01\23\45\67\89\ab\cd\ef\01\02\03\04\05\06\07\08\09\0a\0b\0c\0d\0e\0f" }}; + record { "reason"; variant { Text = "Initial distribution" }}; }}}; }}; - ``` ## Compliance Reporting From c05a1b6312c675964b3a5340418a7181cf28fe5e Mon Sep 17 00:00:00 2001 From: Bogdan Warinschi Date: Fri, 11 Apr 2025 11:53:54 +0200 Subject: [PATCH 13/23] cleaned the examples --- ICRCs/ICRC-122/ICRC-122.md | 117 +++++++++++++++++++++---------------- 1 file changed, 68 insertions(+), 49 deletions(-) diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md index d5e9eb66..552fe615 100644 --- a/ICRCs/ICRC-122/ICRC-122.md +++ b/ICRCs/ICRC-122/ICRC-122.md @@ -1,3 +1,4 @@ + # ICRC-122: Token Burning & Minting ICRC-122 introduces new block types for recording token minting and burning events in ICRC-compliant ledgers. These blocks provide a standardized way to document authorized supply modifications, ensuring transparent tracking of token issuance and removal. The `122burn` block records token reductions, while the `122mint` block tracks token increases. @@ -9,7 +10,7 @@ This standard follows the conventions set by ICRC-3, inheriting key structural c Each block introduced by this standard MUST include a `tx` field containing a map that encodes the token mint or burn transaction submitted to the ledger that caused this block to be created, similarly to how transaction blocks defined in ICRC-1 and ICRC-2 include the submitted transaction. -This enables canister clients, indexers, and auditors to reconstruct the exact instruction that led to the block being recorded to the ledger. +This enables canister clients, indexers, and auditors to reconstruct the exact instruction that led to the block being appended to the ledger. Each `122burn` or `122mint` block consists of the following top-level fields: @@ -38,97 +39,115 @@ Each `122burn` or `122mint` block consists of the following top-level fields: | `amount` | `Nat` | Yes | The number of tokens to mint. | | `reason` | `Text` | Yes | Human-readable reason for the mint. | -## Interesting Aspects +## Usage + +### Purpose of the New Mint and Burn Blocks + +The `122mint` and `122burn` blocks introduced in ICRC-122 serve as an updated method for tracking token supply changes compared to the mint and burn blocks from ICRC-1. + +- **ICRC-1**: In the original ICRC-1 standard, mint and burn events were recorded in a much more basic form, typically involving only the amount of tokens and the affected account. However, this method lacked detailed information on the transaction context and authorization. -- Accounts are represented using an **array of one or two blobs**: the first blob is the owner principal, and the second blob is the subaccount (if present). If no subaccount is specified, only the owner is included. -- The `amount` field uses the `Nat` type from ICRC-3’s `Value` specification. -<<<<<<< HEAD -- The `authorizer` field in the `tx` object identifies the principal who authorized the operation. -- Each `122burn` or `122mint` block contains a `tx` field that encodes the mint or burn instruction that caused the block to be recorded in the ledger. -======= -- Each `122burn` or `122mint` block contains a `tx` field that encodes the mint or burn instruction that caused the block to be appended to the ledger. ->>>>>>> 1e6e02d (removed memo, added reason) +- **ICRC-122**: With ICRC-122, each mint and burn event is recorded with a more comprehensive structure, ensuring full transparency. The `tx` field in particular captures all the necessary transaction details, such as the involved accounts and the reason for the transaction. This allows for better auditing, validation, and traceability of token supply modifications. The new format ensures that the system is extensible, allowing for future use cases where additional information (e.g., authorization principals) may need to be recorded. -## Semantics +### Purpose of the `tx` Field -### Burn +The `tx` field in the block schema is designed to fully capture the transaction that resulted in the minting or burning of tokens. The key purpose of this field is to preserve enough information to reconstruct the original transaction. This means that, if necessary, external parties or auditors should be able to verify the context of the mint or burn by looking at the `tx` data. -When a block of type `122burn` is recorded: +For example: +- If the transaction includes an additional principal (such as an authority or administrative account) that authorized the minting or burning, this principal needs to be included in the `tx` record. +- The flexibility of the `tx` field allows the system to accommodate future changes or new requirements, such as additional metadata or other necessary details about the transaction. -- The ledger MUST reduce the total supply of tokens by the amount specified in `tx.amount`. -- The balance of the `tx.from` account MUST be decreased by `tx.amount`. -- Tokens burned in this way MUST NOT be available for future transfers. -- The `122burn` block MUST be permanently recorded in the ledger. +The `tx` field ensures that the ledger remains transparent and fully auditable while also leaving room for future extensibility. -### Mint +### Minimal Format -When a block of type `122mint` is recorded: +The current format for both `122mint` and `122burn` blocks is intentionally minimal. It records only the essential data needed to track the effect on balances and token supply: +- The **amount** of tokens affected (either minted or burned). +- The **from** or **to** account, depending on whether tokens are being burned or minted. +- The **reason** for the burn or mint, providing context to the event. -- The ledger MUST increase the total supply of tokens by the amount specified in `tx.amount`. -- The balance of the `tx.to` account MUST be increased by `tx.amount`. -- The `122mint` block MUST be permanently recorded in the ledger. +This minimalism ensures that the ledger is efficient while still recording sufficient information for auditing and verifying the impact of each transaction. + + +## Compliance Reporting + +Ledgers implementing this standard MUST return the following response to `icrc3_supported_block_types` with a URL pointing to the standard defining each block type: + +``` +vec { + variant { Record = vec { + record { "btype"; variant { Text = "122burn" }}; + record { "url"; variant { Text = "https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-122.md" }}; + }}; + variant { Record = vec { + record { "btype"; variant { Text = "122mint" }}; + record { "url"; variant { Text = "https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-122.md" }}; + }}; +} +``` ## Example Blocks + ### 122burn Example + ``` variant { Map = vec { + // Block type identifier record { "btype"; variant { Text = "122burn" }}; -<<<<<<< HEAD - // Timestamp when the block was recorded (nanoseconds since epoch) -======= ->>>>>>> 1e6e02d (removed memo, added reason) + // Timestamp when the block was appended (nanoseconds since epoch) record { "ts"; variant { Nat = 1_741_312_737_184_874_392 : nat }}; + + // Hash of the previous block in the ledger chain record { "phash"; variant { Blob = blob "\6f\7e\d9\13\75\69\91\bc\d0\0d\04\b6\60\7b\82\f9\e9\62\a8\39\d3\02\80\f2\88\e4\d7\0e\23\2d\29\87" }}; + + // The burn transaction record { "tx"; variant { Map = vec { + // The account from which tokens are burned record { "from"; variant { Array = vec { variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" }; }}}; + + // The amount to burn record { "amount"; variant { Nat = 1_000_000 : nat }}; + + // The reason for the burn record { "reason"; variant { Text = "Token supply adjustment" }}; }}}; }}; ``` -### 122mint Example +### 123mint example + ``` variant { Map = vec { + // Block type identifier record { "btype"; variant { Text = "122mint" }}; -<<<<<<< HEAD - // Timestamp when the block was recorded (nanoseconds since epoch) -======= ->>>>>>> 1e6e02d (removed memo, added reason) + // Timestamp when the block was appended (nanoseconds since epoch) record { "ts"; variant { Nat = 1_741_312_737_184_874_392 : nat }}; + + // Hash of the previous block in the ledger chain record { "phash"; variant { Blob = blob "\7a\61\cf\18\a4\9d\ac\20\39\33\78\f1\c2\fd\45\81\ab\55\37\20\1d\fe\77\a3\c6\55\de\01\92\a4\3b\ee" }}; + + // The mint transaction record { "tx"; variant { Map = vec { + // The account to which tokens are minted (principal + subaccount) record { "to"; variant { Array = vec { - variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; - variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" } + variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; // owner principal + variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" } // subaccount }}}; + + // The amount to mint record { "amount"; variant { Nat = 2_000_000 : nat }}; + + // The reason for the mint record { "reason"; variant { Text = "Initial distribution" }}; }}}; }}; ``` - -## Compliance Reporting -Ledgers implementing this standard MUST return the following response to `icrc3_supported_block_types` with a URL pointing to the standard defining each block type: - -``` -vec { - variant { Record = vec { - record { "btype"; variant { Text = "122burn" }}; - record { "url"; variant { Text = "https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-122.md" }}; - }}; - variant { Record = vec { - record { "btype"; variant { Text = "122mint" }}; - record { "url"; variant { Text = "https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-122.md" }}; - }}; -} -``` From aa9e592a3fcb531403ffc1d38572fe127efe31b4 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Mon, 14 Apr 2025 14:35:59 +0200 Subject: [PATCH 14/23] refined explanations --- ICRCs/ICRC-122/ICRC-122.md | 105 +++++++++++++++++-------------------- 1 file changed, 49 insertions(+), 56 deletions(-) diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md index 552fe615..55b75f4a 100644 --- a/ICRCs/ICRC-122/ICRC-122.md +++ b/ICRCs/ICRC-122/ICRC-122.md @@ -1,87 +1,80 @@ - -# ICRC-122: Token Burning & Minting +# ICRC-122: Token Burning & Minting (Consolidated) ICRC-122 introduces new block types for recording token minting and burning events in ICRC-compliant ledgers. These blocks provide a standardized way to document authorized supply modifications, ensuring transparent tracking of token issuance and removal. The `122burn` block records token reductions, while the `122mint` block tracks token increases. ## Common Elements -This standard follows the conventions set by ICRC-3, inheriting key structural components. Accounts are recorded as an `Array` of two `Value` variants, where the first element is a `variant { Blob = }`, representing the account owner, and the second element is a `variant { Blob = }`, representing the subaccount. If no subaccount is specified, this field MUST be an empty `Blob`. Additionally, each block includes `phash`, a `Blob` representing the hash of the parent block, and `ts`, a `Nat` representing the timestamp of the block. +This standard follows the conventions set by ICRC-3, inheriting key structural components. Accounts are represented using the ICRC-3 `Value` type, specifically as a `variant { Array = vec { V1 [, V2] } }` where `V1` is `variant { Blob = }` representing the account owner, and `V2` is `variant { Blob = }` representing the subaccount. If no subaccount is specified, the `Array` MUST contain only one element (`V1`, the owner's principal). Additionally, each block includes `phash`, a `Blob` representing the hash of the parent block, and `ts`, a `Nat` representing the timestamp of the block. ## Block Types & Schema -Each block introduced by this standard MUST include a `tx` field containing a map that encodes the token mint or burn transaction submitted to the ledger that caused this block to be created, similarly to how transaction blocks defined in ICRC-1 and ICRC-2 include the submitted transaction. +Each block introduced by this standard MUST include a `tx` field containing a map that encodes the minimal information about the token mint or burn transaction required for balance calculation and basic context. -This enables canister clients, indexers, and auditors to reconstruct the exact instruction that led to the block being appended to the ledger. +**Important Note on Transaction Recoverability:** The `tx` field defined below is intentionally minimal, containing only the data strictly necessary to update account balances, total supply, and provide a basic reason according to the block's semantics. For full auditability and transparency, ledger implementations compliant with ICRC-122 **MUST** ensure that the complete details of the original transaction invocation can be recovered independently. This includes, but is not limited to, the principal that invoked the ledger operation (the authorizer/caller), the specific ledger method called (e.g., `icrc122_burn`), and the full arguments passed to that method. Mechanisms for recovering this data (e.g., via archive queries or specific lookup methods) are implementation-dependent but necessary for compliance. The `tx` field itself is *not* designed to hold this exhaustive information. Each `122burn` or `122mint` block consists of the following top-level fields: | Field | Type (ICRC-3 `Value`) | Required | Description | |----------|------------------------|----------|-------------| -| `btype` | `Text` | Yes | MUST be one of: "122burn" or "122mint". | +| `btype` | `Text` | Yes | MUST be one of: `"122burn"` or `"122mint"`. | | `ts` | `Nat` | Yes | Timestamp in nanoseconds when the block was added to the ledger. | | `phash` | `Blob` | Yes | Hash of the parent block. | -| `tx` | `Map(Text, Value)` | Yes | Encodes the token mint or burn transaction submitted to the ledger that caused this block to be created. | +| `tx` | `Map(Text, Value)` | Yes | Encodes minimal information about the token mint or burn transaction. See schemas below. | ### `tx` Field Schemas #### For `122burn` -| Field | Type (ICRC-3 `Value`) | Required | Description | -|--------------|-------------------------------|----------|-------------| -| `from` | `Array(vec { Blob [, Blob] })` | Yes | The account from which tokens are burned. | -| `amount` | `Nat` | Yes | The number of tokens to burn. | -| `reason` | `Text` | Yes | Human-readable reason for the burn. | +| Field | Type (ICRC-3 `Value`) | Required | Description | +|--------------|--------------------------------------------------------------|----------|-------------| +| `from` | `Value` (Must be `variant { Array = vec { V1 [, V2] } }`)¹ | Yes | The account from which tokens are burned. | +| `amount` | `Nat` | Yes | The number of tokens to burn. | +| `reason` | `Text` | Optional | Human-readable reason for the burn. | #### For `122mint` -| Field | Type (ICRC-3 `Value`) | Required | Description | -|--------------|-------------------------------|----------|-------------| -| `to` | `Array(vec { Blob [, Blob] })` | Yes | The account to which tokens are minted. | -| `amount` | `Nat` | Yes | The number of tokens to mint. | -| `reason` | `Text` | Yes | Human-readable reason for the mint. | - -## Usage - -### Purpose of the New Mint and Burn Blocks +| Field | Type (ICRC-3 `Value`) | Required | Description | +|--------------|--------------------------------------------------------------|----------|-------------| +| `to` | `Value` (Must be `variant { Array = vec { V1 [, V2] } }`)¹ | Yes | The account to which tokens are minted. | +| `amount` | `Nat` | Yes | The number of tokens to mint. | +| `reason` | `Text` | Optional | Human-readable reason for the mint. | -The `122mint` and `122burn` blocks introduced in ICRC-122 serve as an updated method for tracking token supply changes compared to the mint and burn blocks from ICRC-1. +¹ Where `V1` is `variant { Blob = }` and `V2` is `variant { Blob = }`. If no subaccount exists, the `Array` contains only `V1`. -- **ICRC-1**: In the original ICRC-1 standard, mint and burn events were recorded in a much more basic form, typically involving only the amount of tokens and the affected account. However, this method lacked detailed information on the transaction context and authorization. +## Usage -- **ICRC-122**: With ICRC-122, each mint and burn event is recorded with a more comprehensive structure, ensuring full transparency. The `tx` field in particular captures all the necessary transaction details, such as the involved accounts and the reason for the transaction. This allows for better auditing, validation, and traceability of token supply modifications. The new format ensures that the system is extensible, allowing for future use cases where additional information (e.g., authorization principals) may need to be recorded. +### Comparison with ICRC-1 Mint/Burn -### Purpose of the `tx` Field +The `122mint` and `122burn` blocks introduced in ICRC-122 serve as a standardized method for tracking token supply changes, offering more structure than the implicit mint/burn events inferred from ICRC-1 transfer blocks involving the zero account. -The `tx` field in the block schema is designed to fully capture the transaction that resulted in the minting or burning of tokens. The key purpose of this field is to preserve enough information to reconstruct the original transaction. This means that, if necessary, external parties or auditors should be able to verify the context of the mint or burn by looking at the `tx` data. +- **ICRC-1**: In the original ICRC-1 standard, mint and burn events were typically represented by transfers to or from a conventionally designated zero account or address. While functional, this lacked explicit block types for supply changes and didn't standardize fields for context (like a reason) or facilitate easy querying of *only* mint/burn events. -For example: -- If the transaction includes an additional principal (such as an authority or administrative account) that authorized the minting or burning, this principal needs to be included in the `tx` record. -- The flexibility of the `tx` field allows the system to accommodate future changes or new requirements, such as additional metadata or other necessary details about the transaction. +- **ICRC-122**: This standard defines explicit `122mint` and `122burn` block types. The minimal `tx` field standardizes the essential data (account, amount) and includes an optional `reason` field for human-readable context directly within the block relevant to the supply change. This allows for clearer auditing, validation, and direct querying of supply modification events recorded on the ledger. -The `tx` field ensures that the ledger remains transparent and fully auditable while also leaving room for future extensibility. +### Purpose and Limitations of the `tx` Field -### Minimal Format +The `tx` field within `122mint` and `122burn` blocks is designed to be **minimal**. It records only the essential data needed to verify the effect on balances and token supply, along with an optional contextual reason: -The current format for both `122mint` and `122burn` blocks is intentionally minimal. It records only the essential data needed to track the effect on balances and token supply: -- The **amount** of tokens affected (either minted or burned). -- The **from** or **to** account, depending on whether tokens are being burned or minted. -- The **reason** for the burn or mint, providing context to the event. +- The **amount** of tokens affected. +- The **from** (burn) or **to** (mint) account. +- An optional **reason** for the operation. -This minimalism ensures that the ledger is efficient while still recording sufficient information for auditing and verifying the impact of each transaction. +This minimalism ensures efficiency while providing core audit data related to the supply change itself. +Crucially, the `tx` field **does not** aim to capture the full details of the transaction invocation that *caused* the block to be created (like the caller/authorizer principal or exact method arguments). As stated in the "Important Note on Transaction Recoverability" earlier, retrieving those comprehensive details for full auditing **must** be supported by the ledger implementation through other means, adhering to the principle of separating minimal block data from potentially larger contextual/invocation data. ## Compliance Reporting Ledgers implementing this standard MUST return the following response to `icrc3_supported_block_types` with a URL pointing to the standard defining each block type: -``` +```candid vec { variant { Record = vec { record { "btype"; variant { Text = "122burn" }}; - record { "url"; variant { Text = "https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-122.md" }}; + record { "url"; variant { Text = "https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-122.md" }}; // Placeholder URL }}; variant { Record = vec { record { "btype"; variant { Text = "122mint" }}; - record { "url"; variant { Text = "https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-122.md" }}; + record { "url"; variant { Text = "https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-122.md" }}; // Placeholder URL }}; } ``` @@ -90,63 +83,63 @@ vec { ### 122burn Example -``` +```candid variant { Map = vec { // Block type identifier record { "btype"; variant { Text = "122burn" }}; - // Timestamp when the block was appended (nanoseconds since epoch) - record { "ts"; variant { Nat = 1_741_312_737_184_874_392 : nat }}; + // Timestamp when the block was added (nanoseconds since epoch) + record { "ts"; variant { Nat = 1_741_317_147_000_000_000 : nat }}; // Approx 2025-04-14T14:32:27Z (Using current time) // Hash of the previous block in the ledger chain record { "phash"; variant { Blob = blob "\6f\7e\d9\13\75\69\91\bc\d0\0d\04\b6\60\7b\82\f9\e9\62\a8\39\d3\02\80\f2\88\e4\d7\0e\23\2d\29\87" }}; - // The burn transaction + // The minimal burn transaction details record { "tx"; variant { Map = vec { - // The account from which tokens are burned + // The account from which tokens are burned (owner + subaccount) record { "from"; variant { Array = vec { - variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; - variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" }; + variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; // Example owner principal + variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" }; // Example subaccount }}}; // The amount to burn record { "amount"; variant { Nat = 1_000_000 : nat }}; - // The reason for the burn + // Optional reason for the burn record { "reason"; variant { Text = "Token supply adjustment" }}; }}}; }}; ``` -### 123mint example +### 122mint Example -``` +```candid variant { Map = vec { // Block type identifier record { "btype"; variant { Text = "122mint" }}; - // Timestamp when the block was appended (nanoseconds since epoch) - record { "ts"; variant { Nat = 1_741_312_737_184_874_392 : nat }}; + // Timestamp when the block was added (nanoseconds since epoch) + record { "ts"; variant { Nat = 1_741_317_147_000_000_000 : nat }}; // Approx 2025-04-14T14:32:27Z (Using current time) // Hash of the previous block in the ledger chain record { "phash"; variant { Blob = blob "\7a\61\cf\18\a4\9d\ac\20\39\33\78\f1\c2\fd\45\81\ab\55\37\20\1d\fe\77\a3\c6\55\de\01\92\a4\3b\ee" }}; - // The mint transaction + // The minimal mint transaction details record { "tx"; variant { Map = vec { - // The account to which tokens are minted (principal + subaccount) + // The account to which tokens are minted (owner + subaccount) record { "to"; variant { Array = vec { - variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; // owner principal - variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" } // subaccount + variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; // Example owner principal + variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" } // Example subaccount }}}; // The amount to mint record { "amount"; variant { Nat = 2_000_000 : nat }}; - // The reason for the mint + // Optional reason for the mint record { "reason"; variant { Text = "Initial distribution" }}; }}}; }}; From 104a2f30996c2a451c95bf001f44a2c718462233 Mon Sep 17 00:00:00 2001 From: Bogdan Warinschi Date: Mon, 19 May 2025 10:30:05 +0200 Subject: [PATCH 15/23] small fix --- ICRCs/ICRC-122/ICRC-122.md | 84 ++++++++++++++++++++------------------ 1 file changed, 44 insertions(+), 40 deletions(-) diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md index 55b75f4a..6ab99f86 100644 --- a/ICRCs/ICRC-122/ICRC-122.md +++ b/ICRCs/ICRC-122/ICRC-122.md @@ -1,42 +1,47 @@ # ICRC-122: Token Burning & Minting (Consolidated) -ICRC-122 introduces new block types for recording token minting and burning events in ICRC-compliant ledgers. These blocks provide a standardized way to document authorized supply modifications, ensuring transparent tracking of token issuance and removal. The `122burn` block records token reductions, while the `122mint` block tracks token increases. +ICRC-122 introduces new block types for recording token minting and burning events in ICRC-compliant ledgers. These blocks provide a standardized way to document authorized supply modifications, ensuring transparent tracking of token issuance and removal. The `122burn` block records token reductions, while the `122mint` block tracks token increases. The transaction details (`tx`) within each block explicitly include the `caller` principal that authorized the operation. ## Common Elements -This standard follows the conventions set by ICRC-3, inheriting key structural components. Accounts are represented using the ICRC-3 `Value` type, specifically as a `variant { Array = vec { V1 [, V2] } }` where `V1` is `variant { Blob = }` representing the account owner, and `V2` is `variant { Blob = }` representing the subaccount. If no subaccount is specified, the `Array` MUST contain only one element (`V1`, the owner's principal). Additionally, each block includes `phash`, a `Blob` representing the hash of the parent block, and `ts`, a `Nat` representing the timestamp of the block. +This standard follows the conventions set by ICRC-3, inheriting key structural components. +- **Accounts** are represented using the ICRC-3 `Value` type, specifically as a `variant { Array = vec { V1 [, V2] } }` where `V1` is `variant { Blob = }` representing the account owner, and `V2` is `variant { Blob = }` representing the subaccount. If no subaccount is specified, the `Array` MUST contain only one element (`V1`, the owner's principal). +- **Principals** (such as the `caller`) are represented using the ICRC-3 `Value` type as `variant { Blob = }`. +- Each block includes `phash`, a `Blob` representing the hash of the parent block, and `ts`, a `Nat` representing the timestamp of the block. ## Block Types & Schema -Each block introduced by this standard MUST include a `tx` field containing a map that encodes the minimal information about the token mint or burn transaction required for balance calculation and basic context. +Each block introduced by this standard MUST include a `tx` field containing a map. This map encodes information about the token mint or burn transaction, including the `caller` principal, the data required for balance calculation, and basic context. -**Important Note on Transaction Recoverability:** The `tx` field defined below is intentionally minimal, containing only the data strictly necessary to update account balances, total supply, and provide a basic reason according to the block's semantics. For full auditability and transparency, ledger implementations compliant with ICRC-122 **MUST** ensure that the complete details of the original transaction invocation can be recovered independently. This includes, but is not limited to, the principal that invoked the ledger operation (the authorizer/caller), the specific ledger method called (e.g., `icrc122_burn`), and the full arguments passed to that method. Mechanisms for recovering this data (e.g., via archive queries or specific lookup methods) are implementation-dependent but necessary for compliance. The `tx` field itself is *not* designed to hold this exhaustive information. +**Important Note on Transaction Recoverability:** The `tx` field defined below now includes the `caller` principal. However, for full auditability and transparency in complex scenarios, ledger implementations compliant with ICRC-122 **MUST** ensure that any other details of the original transaction invocation not captured in `tx` can be recovered independently. This could include, but is not limited to, the full arguments passed to the ledger method (if more complex than the data in `tx`), or any intermediary calls if the operation was part of a multi-step process. Mechanisms for recovering such extended data (e.g., via archive queries or specific lookup methods) remain implementation-dependent. Each `122burn` or `122mint` block consists of the following top-level fields: -| Field | Type (ICRC-3 `Value`) | Required | Description | +| Field    | Type (ICRC-3 `Value`) | Required | Description | |----------|------------------------|----------|-------------| -| `btype` | `Text` | Yes | MUST be one of: `"122burn"` or `"122mint"`. | -| `ts` | `Nat` | Yes | Timestamp in nanoseconds when the block was added to the ledger. | -| `phash` | `Blob` | Yes | Hash of the parent block. | -| `tx` | `Map(Text, Value)` | Yes | Encodes minimal information about the token mint or burn transaction. See schemas below. | +| `btype`  | `Text`                 | Yes      | MUST be one of: `"122burn"` or `"122mint"`. | +| `ts`     | `Nat`                  | Yes      | Timestamp in nanoseconds when the block was added to the ledger. | +| `phash`  | `Blob`                 | Yes      | Hash of the parent block. | +| `tx`     | `Map(Text, Value)`     | Yes      | Encodes information about the token mint or burn transaction, including the caller. See schemas below. | ### `tx` Field Schemas #### For `122burn` -| Field | Type (ICRC-3 `Value`) | Required | Description | +| Field        | Type (ICRC-3 `Value`)                                        | Required | Description | |--------------|--------------------------------------------------------------|----------|-------------| -| `from` | `Value` (Must be `variant { Array = vec { V1 [, V2] } }`)¹ | Yes | The account from which tokens are burned. | -| `amount` | `Nat` | Yes | The number of tokens to burn. | -| `reason` | `Text` | Optional | Human-readable reason for the burn. | +| `caller` | `Value` (Must be `variant { Blob = }`) | Yes | The principal that invoked the ledger method (e.g., `icrc122_burn`) causing this block to be created. | +| `from`       | `Value` (Must be `variant { Array = vec { V1 [, V2] } }`)¹ | Yes      | The account from which tokens are burned. | +| `amount`     | `Nat`                                                        | Yes      | The number of tokens to burn. This value **MUST be greater than 0**. | +| `reason`     | `Text`                                                       | Optional | Human-readable reason for the burn. | #### For `122mint` -| Field | Type (ICRC-3 `Value`) | Required | Description | +| Field        | Type (ICRC-3 `Value`)                                        | Required | Description | |--------------|--------------------------------------------------------------|----------|-------------| -| `to` | `Value` (Must be `variant { Array = vec { V1 [, V2] } }`)¹ | Yes | The account to which tokens are minted. | -| `amount` | `Nat` | Yes | The number of tokens to mint. | -| `reason` | `Text` | Optional | Human-readable reason for the mint. | +| `caller` | `Value` (Must be `variant { Blob = }`) | Yes | The principal that invoked the ledger method (e.g., `icrc122_mint`) causing this block to be created. | +| `to`         | `Value` (Must be `variant { Array = vec { V1 [, V2] } }`)¹ | Yes      | The account to which tokens are minted. | +| `amount`     | `Nat`                                                        | Yes      | The number of tokens to mint. This value **MUST be greater than 0**. | +| `reason`     | `Text`                                                       | Optional | Human-readable reason for the mint. | ¹ Where `V1` is `variant { Blob = }` and `V2` is `variant { Blob = }`. If no subaccount exists, the `Array` contains only `V1`. @@ -46,21 +51,19 @@ Each `122burn` or `122mint` block consists of the following top-level fields: The `122mint` and `122burn` blocks introduced in ICRC-122 serve as a standardized method for tracking token supply changes, offering more structure than the implicit mint/burn events inferred from ICRC-1 transfer blocks involving the zero account. -- **ICRC-1**: In the original ICRC-1 standard, mint and burn events were typically represented by transfers to or from a conventionally designated zero account or address. While functional, this lacked explicit block types for supply changes and didn't standardize fields for context (like a reason) or facilitate easy querying of *only* mint/burn events. +- **ICRC-1**: In the original ICRC-1 standard, mint and burn events were typically represented by transfers to or from a conventionally designated zero account or address. While functional, this lacked explicit block types for supply changes and didn't standardize fields for context (like a reason or the authorizer of the supply change) or facilitate easy querying of *only* mint/burn events. -- **ICRC-122**: This standard defines explicit `122mint` and `122burn` block types. The minimal `tx` field standardizes the essential data (account, amount) and includes an optional `reason` field for human-readable context directly within the block relevant to the supply change. This allows for clearer auditing, validation, and direct querying of supply modification events recorded on the ledger. +- **ICRC-122**: This standard defines explicit `122mint` and `122burn` block types. The `tx` field within each block includes the `caller` principal who initiated the supply change, the essential data for the operation (account, amount), and an optional `reason` field for human-readable context. This allows for clearer auditing, validation, and direct querying of supply modification events and their authorizers recorded on the ledger. -### Purpose and Limitations of the `tx` Field +### Purpose of the `tx` Field -The `tx` field within `122mint` and `122burn` blocks is designed to be **minimal**. It records only the essential data needed to verify the effect on balances and token supply, along with an optional contextual reason: +The `tx` field within `122mint` and `122burn` blocks is designed to provide a comprehensive summary of the transaction directly within the block: +- The `caller` identifies the principal that invoked the ledger operation. +- The `from` (burn) or `to` (mint) account specifies the target of the operation. +- The `amount` of tokens affected. +- An optional `reason` for the operation provides human-readable context. -- The **amount** of tokens affected. -- The **from** (burn) or **to** (mint) account. -- An optional **reason** for the operation. - -This minimalism ensures efficiency while providing core audit data related to the supply change itself. - -Crucially, the `tx` field **does not** aim to capture the full details of the transaction invocation that *caused* the block to be created (like the caller/authorizer principal or exact method arguments). As stated in the "Important Note on Transaction Recoverability" earlier, retrieving those comprehensive details for full auditing **must** be supported by the ledger implementation through other means, adhering to the principle of separating minimal block data from potentially larger contextual/invocation data. +This structure ensures that key information about the operation and its initiator is directly available in the `tx` field, enhancing transparency. For further details beyond what's in the block, such as the full original arguments passed to the ledger method (if applicable), implementations should provide separate recovery mechanisms as highlighted in the "Important Note on Transaction Recoverability." ## Compliance Reporting @@ -68,15 +71,16 @@ Ledgers implementing this standard MUST return the following response to `icrc3_ ```candid vec { - variant { Record = vec { - record { "btype"; variant { Text = "122burn" }}; - record { "url"; variant { Text = "https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-122.md" }}; // Placeholder URL - }}; - variant { Record = vec { - record { "btype"; variant { Text = "122mint" }}; - record { "url"; variant { Text = "https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-122.md" }}; // Placeholder URL - }}; +    variant { Record = vec { +        record { "btype"; variant { Text = "122burn" }}; +        record { "url"; variant { Text = "[https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-122.md](https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-122.md)" }}; // Placeholder URL +    }}; +    variant { Record = vec { +        record { "btype"; variant { Text = "122mint" }}; +        record { "url"; variant { Text = "[https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-122.md](https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-122.md)" }}; // Placeholder URL +    }}; } + ``` ## Example Blocks @@ -88,8 +92,8 @@ variant { Map = vec { // Block type identifier record { "btype"; variant { Text = "122burn" }}; - // Timestamp when the block was added (nanoseconds since epoch) - record { "ts"; variant { Nat = 1_741_317_147_000_000_000 : nat }}; // Approx 2025-04-14T14:32:27Z (Using current time) + // Timestamp when the block was added (nanoseconds since Unix epoch) + record { "ts"; variant { Nat = 1_741_317_147_000_000_000 : nat }}; // Approx 2025-04-14T14:32:27Z // Hash of the previous block in the ledger chain record { "phash"; variant { @@ -120,8 +124,8 @@ variant { Map = vec { // Block type identifier record { "btype"; variant { Text = "122mint" }}; - // Timestamp when the block was added (nanoseconds since epoch) - record { "ts"; variant { Nat = 1_741_317_147_000_000_000 : nat }}; // Approx 2025-04-14T14:32:27Z (Using current time) + // Timestamp when the block was added (nanoseconds since Unix epoch) + record { "ts"; variant { Nat = 1_741_317_147_000_000_000 : nat }}; // Approx 2025-04-14T14:32:27Z // Hash of the previous block in the ledger chain record { "phash"; variant { From 7ca3a59e6e3450db53ecb972877da54e6477bab7 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Tue, 20 May 2025 15:47:28 +0200 Subject: [PATCH 16/23] Update ICRCs/ICRC-122/ICRC-122.md --- ICRCs/ICRC-122/ICRC-122.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md index 6ab99f86..03bcec0e 100644 --- a/ICRCs/ICRC-122/ICRC-122.md +++ b/ICRCs/ICRC-122/ICRC-122.md @@ -1,4 +1,4 @@ -# ICRC-122: Token Burning & Minting (Consolidated) +# ICRC-122: Token Burning & Minting ICRC-122 introduces new block types for recording token minting and burning events in ICRC-compliant ledgers. These blocks provide a standardized way to document authorized supply modifications, ensuring transparent tracking of token issuance and removal. The `122burn` block records token reductions, while the `122mint` block tracks token increases. The transaction details (`tx`) within each block explicitly include the `caller` principal that authorized the operation. From 5ae6ffee966ea2cb602c2e5119d68523b84a4f22 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Tue, 20 May 2025 15:47:44 +0200 Subject: [PATCH 17/23] Update ICRCs/ICRC-122/ICRC-122.md --- ICRCs/ICRC-122/ICRC-122.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md index 03bcec0e..a5610e68 100644 --- a/ICRCs/ICRC-122/ICRC-122.md +++ b/ICRCs/ICRC-122/ICRC-122.md @@ -49,11 +49,19 @@ Each `122burn` or `122mint` block consists of the following top-level fields: ### Comparison with ICRC-1 Mint/Burn -The `122mint` and `122burn` blocks introduced in ICRC-122 serve as a standardized method for tracking token supply changes, offering more structure than the implicit mint/burn events inferred from ICRC-1 transfer blocks involving the zero account. +The `122mint` and `122burn` blocks introduced in ICRC-122 offer a more explicit and structured method for tracking token supply changes compared to how these operations are handled under the ICRC-1 standard. It is important to note that a ledger implementing both ICRC-1 and ICRC-122 may feature blocks resulting from both mechanisms, reflecting the distinct operations invoked. -- **ICRC-1**: In the original ICRC-1 standard, mint and burn events were typically represented by transfers to or from a conventionally designated zero account or address. While functional, this lacked explicit block types for supply changes and didn't standardize fields for context (like a reason or the authorizer of the supply change) or facilitate easy querying of *only* mint/burn events. +- **ICRC-1 Mint/Burn Mechanism**: + - **Operation & Block Type**: ICRC-1 defines a `minting_account`. Minting is achieved by an `icrc1_transfer` from this `minting_account` to the recipient, increasing total supply. Burning is an `icrc1_transfer` to the `minting_account`, decreasing total supply. ICRC-3 compliant ledgers supporting ICRC-1 mint and burn operations typically record these events using specific block types, often designated as `1mint` and `1burn` respectively (or similar, such as `icrc1_mint` and `icrc1_burn`). These blocks, while distinct from standard transfers, primarily confirm the transfer details associated with the minting or burning action as defined by ICRC-1. + - **Authorization**: Authorization for minting is tied to the control of the `minting_account`. Only the principal that can initiate `icrc1_transfer` calls from this specific account can mint tokens. This centralizes minting authority to the controller of the minting account. + - **Contextual Data**: The ICRC-1 `1mint` and `1burn` block structures, as typically derived from the underlying `icrc1_transfer` operation, do not have dedicated fields for a structured `reason` for the supply change beyond what might be placed in the generic `memo` field of the transfer. They also do not explicitly identify an ultimate `caller` or authorizer of the mint/burn operation beyond the `from` field of the transfer (which would be the minting account itself). + +- **ICRC-122 Mint/Burn Blocks**: + - **Explicit Block Types & Dedicated Methods**: This standard defines distinct block types (`122mint`, `122burn`) which result from calls to new, dedicated ledger methods (e.g., `icrc122_mint`, `icrc122_burn`). These are not special cases of `icrc1_transfer`. + - **Flexible Authorization & Direct Caller Identification**: Authorization to call the `icrc122_mint` or `icrc122_burn` endpoints can be managed by the ledger implementation's governance logic, potentially allowing multiple, distinct whitelisted principals to initiate minting or burning. The `caller` field within the `tx` map of each `122mint` or `122burn` block directly records the principal that invoked this specific supply change operation. + - **Enhanced Context**: The `tx` map includes an optional `reason` field, providing a standardized way to include human-readable context specifically for the supply change. + - **Auditability**: The combination of dedicated block types, distinct methods, direct recording of the `caller`, and the optional `reason` field significantly enhances the auditability and transparency of token supply modifications compared to the ICRC-1 mechanism. -- **ICRC-122**: This standard defines explicit `122mint` and `122burn` block types. The `tx` field within each block includes the `caller` principal who initiated the supply change, the essential data for the operation (account, amount), and an optional `reason` field for human-readable context. This allows for clearer auditing, validation, and direct querying of supply modification events and their authorizers recorded on the ledger. ### Purpose of the `tx` Field From 925597f7e6da2c425c82c592f05034063dbadea3 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Tue, 20 May 2025 15:50:25 +0200 Subject: [PATCH 18/23] Update ICRCs/ICRC-122/ICRC-122.md --- ICRCs/ICRC-122/ICRC-122.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md index a5610e68..7d963831 100644 --- a/ICRCs/ICRC-122/ICRC-122.md +++ b/ICRCs/ICRC-122/ICRC-122.md @@ -19,7 +19,7 @@ Each `122burn` or `122mint` block consists of the following top-level fields: | Field    | Type (ICRC-3 `Value`) | Required | Description | |----------|------------------------|----------|-------------| | `btype`  | `Text`                 | Yes      | MUST be one of: `"122burn"` or `"122mint"`. | -| `ts`     | `Nat`                  | Yes      | Timestamp in nanoseconds when the block was added to the ledger. | +| `ts`     | `Nat`                  | Yes      | Timestamp (in nanoseconds since the Unix epoch) when the block was added to the ledger. | | `phash`  | `Blob`                 | Yes      | Hash of the parent block. | | `tx`     | `Map(Text, Value)`     | Yes      | Encodes information about the token mint or burn transaction, including the caller. See schemas below. | From fa7ca986632ae76ecbfb07e28deb98df948c4eb5 Mon Sep 17 00:00:00 2001 From: bogwar <51327868+bogwar@users.noreply.github.com> Date: Tue, 1 Jul 2025 10:30:44 +0200 Subject: [PATCH 19/23] implemented Thomas' suggestions; alignment with the ICRC-107 structure --- ICRCs/ICRC-122/ICRC-122.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md index 7d963831..95f01058 100644 --- a/ICRCs/ICRC-122/ICRC-122.md +++ b/ICRCs/ICRC-122/ICRC-122.md @@ -31,7 +31,7 @@ Each `122burn` or `122mint` block consists of the following top-level fields: |--------------|--------------------------------------------------------------|----------|-------------| | `caller` | `Value` (Must be `variant { Blob = }`) | Yes | The principal that invoked the ledger method (e.g., `icrc122_burn`) causing this block to be created. | | `from`       | `Value` (Must be `variant { Array = vec { V1 [, V2] } }`)¹ | Yes      | The account from which tokens are burned. | -| `amount`     | `Nat`                                                        | Yes      | The number of tokens to burn. This value **MUST be greater than 0**. | +| `amt` | `Nat` | Yes | The number of tokens to mint. This value MUST be greater than 0. The amount is denominated in the smallest indivisible unit of the token. | | `reason`     | `Text`                                                       | Optional | Human-readable reason for the burn. | #### For `122mint` @@ -40,7 +40,7 @@ Each `122burn` or `122mint` block consists of the following top-level fields: |--------------|--------------------------------------------------------------|----------|-------------| | `caller` | `Value` (Must be `variant { Blob = }`) | Yes | The principal that invoked the ledger method (e.g., `icrc122_mint`) causing this block to be created. | | `to`         | `Value` (Must be `variant { Array = vec { V1 [, V2] } }`)¹ | Yes      | The account to which tokens are minted. | -| `amount`     | `Nat`                                                        | Yes      | The number of tokens to mint. This value **MUST be greater than 0**. | +| `amt` | `Nat` | Yes | The number of tokens to mint. This value MUST be greater than 0. The amount is denominated in the smallest indivisible unit of the token. | This value **MUST be greater than 0**. | | `reason`     | `Text`                                                       | Optional | Human-readable reason for the mint. | ¹ Where `V1` is `variant { Blob = }` and `V2` is `variant { Blob = }`. If no subaccount exists, the `Array` contains only `V1`. @@ -68,7 +68,7 @@ The `122mint` and `122burn` blocks introduced in ICRC-122 offer a more explicit The `tx` field within `122mint` and `122burn` blocks is designed to provide a comprehensive summary of the transaction directly within the block: - The `caller` identifies the principal that invoked the ledger operation. - The `from` (burn) or `to` (mint) account specifies the target of the operation. -- The `amount` of tokens affected. +- The amount `amt` of tokens affected. - An optional `reason` for the operation provides human-readable context. This structure ensures that key information about the operation and its initiator is directly available in the `tx` field, enhancing transparency. For further details beyond what's in the block, such as the full original arguments passed to the ledger method (if applicable), implementations should provide separate recovery mechanisms as highlighted in the "Important Note on Transaction Recoverability." @@ -101,7 +101,7 @@ variant { Map = vec { record { "btype"; variant { Text = "122burn" }}; // Timestamp when the block was added (nanoseconds since Unix epoch) - record { "ts"; variant { Nat = 1_741_317_147_000_000_000 : nat }}; // Approx 2025-04-14T14:32:27Z + record { "ts"; variant { Nat = 1_741_317_147_000_000_000 : nat }}; // Approx 2025-04-14T14:32:27Z // Hash of the previous block in the ledger chain record { "phash"; variant { @@ -115,9 +115,10 @@ variant { Map = vec { variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; // Example owner principal variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" }; // Example subaccount }}}; - + // The caller principal + record { "caller"; variant { Blob = blob "\de\ad\be\ef\01\23\45\67\89\ab\cd\ef\fe\dc\ba\98\76\54\32\10" } }; // The amount to burn - record { "amount"; variant { Nat = 1_000_000 : nat }}; + record { "amt"; variant { Nat = 1_000_000 : nat }}; // Optional reason for the burn record { "reason"; variant { Text = "Token supply adjustment" }}; @@ -147,10 +148,10 @@ variant { Map = vec { variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; // Example owner principal variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" } // Example subaccount }}}; - + // The caller principal + record { "caller"; variant { Blob = blob "\de\ad\be\ef\01\23\45\67\89\ab\cd\ef\fe\dc\ba\98\76\54\32\10" } }; // The amount to mint - record { "amount"; variant { Nat = 2_000_000 : nat }}; - + record { "amt"; variant { Nat = 2_000_000 : nat }}; // Optional reason for the mint record { "reason"; variant { Text = "Initial distribution" }}; }}}; From 2e80b7039c830fdfe1d21a8ab5d51a812f61d537 Mon Sep 17 00:00:00 2001 From: Bogdan Warinschi Date: Fri, 12 Sep 2025 10:59:50 +0200 Subject: [PATCH 20/23] alignment with new icrc-3 guideliness --- ICRCs/ICRC-122/ICRC-122.md | 164 ++++++++++++++++++++----------------- 1 file changed, 91 insertions(+), 73 deletions(-) diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md index 7d963831..54fc2825 100644 --- a/ICRCs/ICRC-122/ICRC-122.md +++ b/ICRCs/ICRC-122/ICRC-122.md @@ -1,6 +1,6 @@ # ICRC-122: Token Burning & Minting -ICRC-122 introduces new block types for recording token minting and burning events in ICRC-compliant ledgers. These blocks provide a standardized way to document authorized supply modifications, ensuring transparent tracking of token issuance and removal. The `122burn` block records token reductions, while the `122mint` block tracks token increases. The transaction details (`tx`) within each block explicitly include the `caller` principal that authorized the operation. +ICRC-122 introduces new block types for recording token minting and burning events in ICRC-compliant ledgers. These blocks provide a standardized way to document authorized supply modifications, ensuring transparent tracking of token issuance and removal. The `122burn` block records token reductions, while the `122mint` block tracks token increases. ## Common Elements This standard follows the conventions set by ICRC-3, inheriting key structural components. @@ -10,9 +10,8 @@ This standard follows the conventions set by ICRC-3, inheriting key structural c ## Block Types & Schema -Each block introduced by this standard MUST include a `tx` field containing a map. This map encodes information about the token mint or burn transaction, including the `caller` principal, the data required for balance calculation, and basic context. +Each block introduced by this standard MUST include a `tx` field containing a map. This map encodes information about the mint or burn operation sufficient to compute balances. Additional provenance data MAY be included but is not required for semantics. -**Important Note on Transaction Recoverability:** The `tx` field defined below now includes the `caller` principal. However, for full auditability and transparency in complex scenarios, ledger implementations compliant with ICRC-122 **MUST** ensure that any other details of the original transaction invocation not captured in `tx` can be recovered independently. This could include, but is not limited to, the full arguments passed to the ledger method (if more complex than the data in `tx`), or any intermediary calls if the operation was part of a multi-step process. Mechanisms for recovering such extended data (e.g., via archive queries or specific lookup methods) remain implementation-dependent. Each `122burn` or `122mint` block consists of the following top-level fields: @@ -21,7 +20,7 @@ Each `122burn` or `122mint` block consists of the following top-level fields: | `btype`  | `Text`                 | Yes      | MUST be one of: `"122burn"` or `"122mint"`. | | `ts`     | `Nat`                  | Yes      | Timestamp (in nanoseconds since the Unix epoch) when the block was added to the ledger. | | `phash`  | `Blob`                 | Yes      | Hash of the parent block. | -| `tx`     | `Map(Text, Value)`     | Yes      | Encodes information about the token mint or burn transaction, including the caller. See schemas below. | +| `tx`     | `Map(Text, Value)`     | Yes      | Encodes information about the token mint or burn transaction sufficient to compute balances. See schemas below. | ### `tx` Field Schemas @@ -29,49 +28,33 @@ Each `122burn` or `122mint` block consists of the following top-level fields: | Field        | Type (ICRC-3 `Value`)                                        | Required | Description | |--------------|--------------------------------------------------------------|----------|-------------| -| `caller` | `Value` (Must be `variant { Blob = }`) | Yes | The principal that invoked the ledger method (e.g., `icrc122_burn`) causing this block to be created. | | `from`       | `Value` (Must be `variant { Array = vec { V1 [, V2] } }`)¹ | Yes      | The account from which tokens are burned. | -| `amount`     | `Nat`                                                        | Yes      | The number of tokens to burn. This value **MUST be greater than 0**. | -| `reason`     | `Text`                                                       | Optional | Human-readable reason for the burn. | +| `amt`     | `Nat`                                                        | Yes      | The number of tokens to burn. This value **MUST be greater than 0**. | + #### For `122mint` | Field        | Type (ICRC-3 `Value`)                                        | Required | Description | |--------------|--------------------------------------------------------------|----------|-------------| -| `caller` | `Value` (Must be `variant { Blob = }`) | Yes | The principal that invoked the ledger method (e.g., `icrc122_mint`) causing this block to be created. | | `to`         | `Value` (Must be `variant { Array = vec { V1 [, V2] } }`)¹ | Yes      | The account to which tokens are minted. | -| `amount`     | `Nat`                                                        | Yes      | The number of tokens to mint. This value **MUST be greater than 0**. | -| `reason`     | `Text`                                                       | Optional | Human-readable reason for the mint. | - -¹ Where `V1` is `variant { Blob = }` and `V2` is `variant { Blob = }`. If no subaccount exists, the `Array` contains only `V1`. +| `amt`     | `Nat`                                                        | Yes      | The number of tokens to mint. This value **MUST be greater than 0**. | ## Usage -### Comparison with ICRC-1 Mint/Burn - -The `122mint` and `122burn` blocks introduced in ICRC-122 offer a more explicit and structured method for tracking token supply changes compared to how these operations are handled under the ICRC-1 standard. It is important to note that a ledger implementing both ICRC-1 and ICRC-122 may feature blocks resulting from both mechanisms, reflecting the distinct operations invoked. - -- **ICRC-1 Mint/Burn Mechanism**: - - **Operation & Block Type**: ICRC-1 defines a `minting_account`. Minting is achieved by an `icrc1_transfer` from this `minting_account` to the recipient, increasing total supply. Burning is an `icrc1_transfer` to the `minting_account`, decreasing total supply. ICRC-3 compliant ledgers supporting ICRC-1 mint and burn operations typically record these events using specific block types, often designated as `1mint` and `1burn` respectively (or similar, such as `icrc1_mint` and `icrc1_burn`). These blocks, while distinct from standard transfers, primarily confirm the transfer details associated with the minting or burning action as defined by ICRC-1. - - **Authorization**: Authorization for minting is tied to the control of the `minting_account`. Only the principal that can initiate `icrc1_transfer` calls from this specific account can mint tokens. This centralizes minting authority to the controller of the minting account. - - **Contextual Data**: The ICRC-1 `1mint` and `1burn` block structures, as typically derived from the underlying `icrc1_transfer` operation, do not have dedicated fields for a structured `reason` for the supply change beyond what might be placed in the generic `memo` field of the transfer. They also do not explicitly identify an ultimate `caller` or authorizer of the mint/burn operation beyond the `from` field of the transfer (which would be the minting account itself). - -- **ICRC-122 Mint/Burn Blocks**: - - **Explicit Block Types & Dedicated Methods**: This standard defines distinct block types (`122mint`, `122burn`) which result from calls to new, dedicated ledger methods (e.g., `icrc122_mint`, `icrc122_burn`). These are not special cases of `icrc1_transfer`. - - **Flexible Authorization & Direct Caller Identification**: Authorization to call the `icrc122_mint` or `icrc122_burn` endpoints can be managed by the ledger implementation's governance logic, potentially allowing multiple, distinct whitelisted principals to initiate minting or burning. The `caller` field within the `tx` map of each `122mint` or `122burn` block directly records the principal that invoked this specific supply change operation. - - **Enhanced Context**: The `tx` map includes an optional `reason` field, providing a standardized way to include human-readable context specifically for the supply change. - - **Auditability**: The combination of dedicated block types, distinct methods, direct recording of the `caller`, and the optional `reason` field significantly enhances the auditability and transparency of token supply modifications compared to the ICRC-1 mechanism. - +### Comparison with ICRC-1 Mint/Burn -### Purpose of the `tx` Field +The `122mint` and `122burn` blocks introduced in ICRC-122 provide a more explicit and structured mechanism for tracking token supply changes compared to how these operations are represented under ICRC-1. A ledger that supports both ICRC-1 and ICRC-122 may therefore produce blocks of both kinds, reflecting distinct ways of invoking supply modifications. -The `tx` field within `122mint` and `122burn` blocks is designed to provide a comprehensive summary of the transaction directly within the block: -- The `caller` identifies the principal that invoked the ledger operation. -- The `from` (burn) or `to` (mint) account specifies the target of the operation. -- The `amount` of tokens affected. -- An optional `reason` for the operation provides human-readable context. +- **ICRC-1 Mint/Burn Mechanism**: + - *Operation & Block Type*: ICRC-1 defines a `minting_account`. Minting is achieved by an `icrc1_transfer` from this account to a recipient, increasing total supply. Burning is an `icrc1_transfer` to the `minting_account`, reducing supply. ICRC-3-compliant ledgers typically encode these as legacy blocks with `op = "mint"` or `op = "burn"`. + - *Authorization*: Control of the `minting_account` implies authority to mint. Only the principal able to submit `icrc1_transfer` calls from this account can change supply. + - *Contextual Data*: These legacy blocks do not have a dedicated field for the supply change rationale; any context must be encoded in the generic `memo`. They also do not explicitly identify the ultimate caller beyond the fact that the `from` account was the `minting_account`. -This structure ensures that key information about the operation and its initiator is directly available in the `tx` field, enhancing transparency. For further details beyond what's in the block, such as the full original arguments passed to the ledger method (if applicable), implementations should provide separate recovery mechanisms as highlighted in the "Important Note on Transaction Recoverability." +- **ICRC-122 Mint/Burn Blocks**: + - *Typed Blocks*: This standard defines distinct block types, `122mint` and `122burn`. They are not special cases of `icrc1_transfer`; they represent supply changes directly. + - *Minimal Structure*: The minimal `tx` structure contains only the target account (`to` for mint, `from` for burn) and the amount (`amt`). These fields are sufficient to determine the ledger’s state transition. + - *Optional Provenance*: Producers may include additional non-semantic fields in `tx` such as `caller` (the principal that invoked the supply change), `reason` (a human-readable string), or `created_at_time`. These fields aid transparency and auditability but do not affect ledger semantics. + - *Auditability*: By separating the minimal state-changing fields from optional provenance, ICRC-122 ensures clear semantics while still supporting enhanced transparency compared to the ICRC-1 mechanism. ## Compliance Reporting @@ -81,11 +64,11 @@ Ledgers implementing this standard MUST return the following response to `icrc3_ vec {     variant { Record = vec {         record { "btype"; variant { Text = "122burn" }}; -        record { "url"; variant { Text = "[https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-122.md](https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-122.md)" }}; // Placeholder URL +        record { "url"; variant { Text = "https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-122.md" }}; // Placeholder URL     }};     variant { Record = vec {         record { "btype"; variant { Text = "122mint" }}; -        record { "url"; variant { Text = "[https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-122.md](https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-122.md)" }}; // Placeholder URL +        record { "url"; variant { Text = "https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-122.md" }}; // Placeholder URL     }}; } @@ -93,66 +76,101 @@ vec { ## Example Blocks +The following examples illustrate how `122burn` and `122mint` blocks are encoded on-chain. +Each operation is shown in two forms: + +- **Minimal form**, which includes only the required fields needed to define the state change. +- **Extended form**, which demonstrates how optional provenance fields such as `caller`, `reason`, or `created_at_time` may be included to enhance transparency and auditability. + +These examples are intended to guide implementers and tool builders in interpreting both the essential and optional elements of ICRC-122 blocks. + + ### 122burn Example -```candid -variant { Map = vec { - // Block type identifier - record { "btype"; variant { Text = "122burn" }}; +### 122burn (Minimal Example) +The following block shows the minimal `122burn` structure with only the required `from` and `amt` fields inside the `tx` map. - // Timestamp when the block was added (nanoseconds since Unix epoch) - record { "ts"; variant { Nat = 1_741_317_147_000_000_000 : nat }}; // Approx 2025-04-14T14:32:27Z - // Hash of the previous block in the ledger chain - record { "phash"; variant { - Blob = blob "\6f\7e\d9\13\75\69\91\bc\d0\0d\04\b6\60\7b\82\f9\e9\62\a8\39\d3\02\80\f2\88\e4\d7\0e\23\2d\29\87" - }}; - // The minimal burn transaction details +``` +variant { Map = vec { + record { "btype"; variant { Text = "122burn" }}; + record { "ts"; variant { Nat = 1_741_317_147_000_000_000 : nat }}; + record { "phash"; variant { Blob = blob "\6f\7e\d9\13\75\69\91\bc\d0\0d\04\b6\60\7b\82\f9\e9\62\a8\39\d3\02\80\f2\88\e4\d7\0e\23\2d\29\87" }}; record { "tx"; variant { Map = vec { - // The account from which tokens are burned (owner + subaccount) record { "from"; variant { Array = vec { - variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; // Example owner principal - variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" }; // Example subaccount + variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; + variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" }; }}}; + record { "amt"; variant { Nat = 1_000_000 : nat }}; + }}}; +}} +``` + + +### 122burn (Extended Example with Provenance and Deduplication Information) +This block demonstrates an extended `122burn` including optional provenance fields (`caller`, `reason`, `created_at_time`) alongside the required fields. These additions provide auditability without altering semantics. + - // The amount to burn - record { "amount"; variant { Nat = 1_000_000 : nat }}; - // Optional reason for the burn +``` +variant { Map = vec { + record { "btype"; variant { Text = "122burn" }}; + record { "ts"; variant { Nat = 1_741_317_147_000_000_000 : nat }}; + record { "phash"; variant { Blob = blob "\6f\7e\d9\13\75\69\91\bc\d0\0d\04\b6\60\7b\82\f9\e9\62\a8\39\d3\02\80\f2\88\e4\d7\0e\23\2d\29\87" }}; + record { "tx"; variant { Map = vec { + record { "from"; variant { Array = vec { + variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; + variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" }; + }}}; + record { "amt"; variant { Nat = 1_000_000 : nat }}; + record { "caller"; variant { Blob = blob "\00\00\00\00\00\00\00\00\01\01" }}; record { "reason"; variant { Text = "Token supply adjustment" }}; + record { "created_at_time"; variant { Nat = 1_741_317_146_900_000_000 : nat }}; }}}; -}}; +}} ``` -### 122mint Example +### 122mint (Minimal Example) +The following block shows the minimal `122mint` structure with only the required `to` and `amt` fields inside the `tx` map. -```candid + +``` variant { Map = vec { - // Block type identifier record { "btype"; variant { Text = "122mint" }}; + record { "ts"; variant { Nat = 1_741_317_147_000_000_000 : nat }}; + record { "phash"; variant { Blob = blob "\7a\61\cf\18\a4\9d\ac\20\39\33\78\f1\c2\fd\45\81\ab\55\37\20\1d\fe\77\a3\c6\55\de\01\92\a4\3b\ee" }}; + record { "tx"; variant { Map = vec { + record { "to"; variant { Array = vec { + variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; + variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" }; + }}}; + record { "amt"; variant { Nat = 2_000_000 : nat }}; + }}}; +}} +``` - // Timestamp when the block was added (nanoseconds since Unix epoch) - record { "ts"; variant { Nat = 1_741_317_147_000_000_000 : nat }}; // Approx 2025-04-14T14:32:27Z +--- - // Hash of the previous block in the ledger chain - record { "phash"; variant { - Blob = blob "\7a\61\cf\18\a4\9d\ac\20\39\33\78\f1\c2\fd\45\81\ab\55\37\20\1d\fe\77\a3\c6\55\de\01\92\a4\3b\ee" - }}; +### 122mint (Extended Example with Provenance and Deduplication Information) +This block demonstrates an extended `122mint` including optional provenance fields (`caller`, `reason`, `created_at_time`) alongside the required fields. These additions provide auditability without altering semantics. - // The minimal mint transaction details + +``` +variant { Map = vec { + record { "btype"; variant { Text = "122mint" }}; + record { "ts"; variant { Nat = 1_741_317_147_000_000_000 : nat }}; + record { "phash"; variant { Blob = blob "\7a\61\cf\18\a4\9d\ac\20\39\33\78\f1\c2\fd\45\81\ab\55\37\20\1d\fe\77\a3\c6\55\de\01\92\a4\3b\ee" }}; record { "tx"; variant { Map = vec { - // The account to which tokens are minted (owner + subaccount) record { "to"; variant { Array = vec { - variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; // Example owner principal - variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" } // Example subaccount + variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; + variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" }; }}}; - - // The amount to mint - record { "amount"; variant { Nat = 2_000_000 : nat }}; - - // Optional reason for the mint + record { "amt"; variant { Nat = 2_000_000 : nat }}; + record { "caller"; variant { Blob = blob "\00\00\00\00\00\00\00\00\01\01" }}; record { "reason"; variant { Text = "Initial distribution" }}; + record { "created_at_time"; variant { Nat = 1_741_317_146_900_000_000 : nat }}; }}}; -}}; +}} ``` + From 8f3fb0b378f76113c1e61b510335ad8657cbfca6 Mon Sep 17 00:00:00 2001 From: Bogdan Warinschi Date: Fri, 12 Sep 2025 11:09:40 +0200 Subject: [PATCH 21/23] dedup information in blocks --- ICRCs/ICRC-122/ICRC-122.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md index 54fc2825..b4acf886 100644 --- a/ICRCs/ICRC-122/ICRC-122.md +++ b/ICRCs/ICRC-122/ICRC-122.md @@ -109,7 +109,7 @@ variant { Map = vec { ### 122burn (Extended Example with Provenance and Deduplication Information) -This block demonstrates an extended `122burn` including optional provenance fields (`caller`, `reason`, `created_at_time`) alongside the required fields. These additions provide auditability without altering semantics. +This block demonstrates an extended `122burn` including optional provenance and deduplication information fields (`caller`, `reason`, `created_at_time`) alongside the required fields. These additions provide auditability and deduplication functionality without altering semantics. @@ -153,7 +153,7 @@ variant { Map = vec { --- ### 122mint (Extended Example with Provenance and Deduplication Information) -This block demonstrates an extended `122mint` including optional provenance fields (`caller`, `reason`, `created_at_time`) alongside the required fields. These additions provide auditability without altering semantics. +This block demonstrates an extended `122mint` including optional provenance and deduplication fields (`caller`, `reason`, `created_at_time`) alongside the required fields. These additions provide auditability and deduplication functionality without altering semantics. ``` From f46e7bd6c25278c445afa8a10478c31105ee4d90 Mon Sep 17 00:00:00 2001 From: Bogdan Warinschi Date: Fri, 12 Sep 2025 12:46:15 +0200 Subject: [PATCH 22/23] added interaction with other standards section --- ICRCs/ICRC-122/ICRC-122.md | 64 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md index b4acf886..0976983b 100644 --- a/ICRCs/ICRC-122/ICRC-122.md +++ b/ICRCs/ICRC-122/ICRC-122.md @@ -56,6 +56,33 @@ The `122mint` and `122burn` blocks introduced in ICRC-122 provide a more explici - *Optional Provenance*: Producers may include additional non-semantic fields in `tx` such as `caller` (the principal that invoked the supply change), `reason` (a human-readable string), or `created_at_time`. These fields aid transparency and auditability but do not affect ledger semantics. - *Auditability*: By separating the minimal state-changing fields from optional provenance, ICRC-122 ensures clear semantics while still supporting enhanced transparency compared to the ICRC-1 mechanism. +### Guidance for Standards That Define Methods + +ICRC-122 itself defines only block types (`122mint`, `122burn`) and their semantics. +It does not define ledger methods. However, other standards may define methods that +directly produce ICRC-122 blocks. + +Such standards SHOULD: + +1. **Include `tx.op`** in the resulting block’s `tx` map. + - Use a namespaced value as recommended in ICRC-3: ``. + - Examples: `145mint`, `145burn` if defined in ICRC-145. + - This **prevents collisions** between blocks created by different methods or standards; it does *not* uniquely identify an individual call. + +2. **Define a canonical mapping** from method arguments to the minimal `tx` fields: + - `icrcX_mint` → `tx.to`, `tx.amt`. + - `icrcX_burn` → `tx.from`, `tx.amt`. + - Optional provenance (`caller`, `reason`, `created_at_time`) MAY be included but MUST NOT affect semantics. + +3. **Document deduplication inputs** (if any). If a method accepts a caller-supplied timestamp, + it SHOULD be recorded in `tx.created_at_time` (nanoseconds, MUST fit into `nat64`). + +This guidance ensures that when future standards define mint/burn methods, they can be +reliably mapped into ICRC-122 block types while remaining compatible with ICRC-3 rules +for canonical `tx` mappings and optional provenance. + + + ## Compliance Reporting Ledgers implementing this standard MUST return the following response to `icrc3_supported_block_types` with a URL pointing to the standard defining each block type: @@ -174,3 +201,40 @@ variant { Map = vec { }} ``` +### Informative Example: Integration with a Standardized Method + +ICRC-122 defines only block types (`122mint`, `122burn`) and their semantics. +It does not define ledger methods. However, future standards may specify methods +that directly produce these block types. + +For illustration, suppose a future standard (e.g., ICRC-145) introduces the method: + +```icrc145_mint : (account, nat, opt text) -> result nat``` + + +Calling this method with a target account, an amount, and an optional reason could +produce a `122mint` block on-chain. A possible encoding is shown below: + +``` +variant { Map = vec { +record { "btype"; variant { Text = "122mint" }}; +record { "ts"; variant { Nat = 1_747_900_000_000_000_000 : nat }}; +record { "phash"; variant { Blob = blob "\aa\bb\cc\dd\ee\ff\00\11\22\33\44\55\66\77\88\99" }}; +record { "tx"; variant { Map = vec { +// Namespaced op from the method-defining standard (ICRC-145) +record { "op"; variant { Text = "145mint" }}; +// Optional provenance (non-semantic) +record { "caller"; variant { Blob = blob "\00\00\00\00\00\00\f0\0d\01\02" }}; +record { "to"; variant { Array = vec { +variant { Blob = blob "\00\00\00\00\02\00\01\0d\01\01" }; +variant { Blob = blob "\06\ec\cd\3a\97\fb\a8\5f\bc\8d\a3\3e\5d\ba\bc\2f\38\69\60\5d\c7\a1\c9\53\1f\70\a3\66\c5\a7\e4\21" }; +}}}; +record { "amt"; variant { Nat = 1_000_000 : nat }}; +record { "reason"; variant { Text = "Community treasury distribution" }}; +}}}; +}} +``` + +This example is non-normative and illustrates how a standardized method can map into +the ICRC-122 block structure while using a namespaced `tx.op` to prevent collisions +across standards. The authoritative semantics remain defined by the ICRC-122 block types. \ No newline at end of file From 3a39cbba345e1f3d0cae6cd47ac2ef7f65324f5d Mon Sep 17 00:00:00 2001 From: Bogdan Warinschi Date: Fri, 26 Sep 2025 10:10:50 +0200 Subject: [PATCH 23/23] clarify it's blocks that are being standardised --- ICRCs/ICRC-122/ICRC-122.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ICRCs/ICRC-122/ICRC-122.md b/ICRCs/ICRC-122/ICRC-122.md index 0976983b..4a2d0df2 100644 --- a/ICRCs/ICRC-122/ICRC-122.md +++ b/ICRCs/ICRC-122/ICRC-122.md @@ -1,4 +1,4 @@ -# ICRC-122: Token Burning & Minting +# ICRC-122: Token Burning & Minting Blocks ICRC-122 introduces new block types for recording token minting and burning events in ICRC-compliant ledgers. These blocks provide a standardized way to document authorized supply modifications, ensuring transparent tracking of token issuance and removal. The `122burn` block records token reductions, while the `122mint` block tracks token increases.