From 49ed7ee054fa36d216f115d732437b483050d48d Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Tue, 2 Apr 2024 09:24:12 -0500 Subject: [PATCH 01/47] Add markdowns --- radix-engine/README.md | 34 ---------------------------- radix-engine/docs/architecture.md | 29 ++++++++++++++++++++++++ radix-engine/docs/bootup.drawio.png | Bin 0 -> 16008 bytes radix-engine/docs/bootup.md | 21 +++++++++++++++++ radix-engine/docs/overview.md | 21 +++++++++++++++++ 5 files changed, 71 insertions(+), 34 deletions(-) delete mode 100644 radix-engine/README.md create mode 100644 radix-engine/docs/architecture.md create mode 100644 radix-engine/docs/bootup.drawio.png create mode 100644 radix-engine/docs/bootup.md create mode 100644 radix-engine/docs/overview.md diff --git a/radix-engine/README.md b/radix-engine/README.md deleted file mode 100644 index 2f8e2e5851..0000000000 --- a/radix-engine/README.md +++ /dev/null @@ -1,34 +0,0 @@ -# Radix Engine - -Radix Engine is the underlying execution engine designed to run DeFi-based Scrypto applications. - -The architecture is heavily influenced by traditional Kernel design (though much simplified) and Rust's -Ownership and Type-Checking paradigms (also much simplified). The novel idea here is in combining -ideas from the two worlds, Operating System and Language, or simply "Implement Rust -Semantics at the System Layer". - -## Architecture - -Radix Engine execution is organized into 5 layers, each layer providing an API to the layer above. - -Execution layers may also optionally provide a Callback API which the layer above must implement. - -| Execution Layer | Layer ID | Description | Responsibilities | API | Callback API | Implementation | -|-----------------|----------|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|------------------------------------------------------------------------------------------------------------| -| Application | 5 | "User Space" | Application Logic (e.g. Blueprints written in Scrypto) | | | [Native Blueprints](src/blueprints)
[Scrypto Blueprints](../radix-engine-tests/tests/blueprints) | -| VM | 4 | "Virtual CPU" | Application Execution | WASM + [Scrypto API](../scrypto/src/engine/scrypto_env.rs) | | [VM](src/vm) | -| System | 3 | "Operating System" | Type Checking
Package/Blueprint/Object semantics
Application Standardization (e.g. Authorization, Versioning) | [Substate API](../radix-engine-interface/src/api/locked_substate_api)
[Object API](../radix-engine-interface/src/api/object_api.rs)
[Blueprint API](../radix-engine-interface/src/api/blueprint_api.rs)
[Costing API](../radix-engine-interface/src/api/costing_api.rs) | [System Callback API](src/system/system_callback_api.rs) | [System](src/system) | -| Kernel | 2 | "I/O Device Management" | Call Frame Message Passing
Ownership/Reference handling
State Virtualization Mechanism
Substate Device Management
Transaction Execution | [Kernel API](src/kernel/kernel_api.rs) | [Kernel Callback API](src/kernel/kernel_callback_api.rs) | [Kernel](src/kernel) | -| Database | 1 | "Persistence" | Runtime Read-Only Physical Storage | [Substate Database](../radix-substate-store-interface/src/interface.rs) | | [InMemoryDB](../radix-substate-store-impls/src/memory_db.rs)
[RocksDB](../radix-substate-store-impls/src/rocks_db.rs) | - - -## Data Abstraction - -If looked at from a purely state perspective, the layers can be reduced to the following 4 layers: - -| Data Layer | Layer ID | Abstraction | -|-------------|----------|--------------------------------------------------------------------------------------------| -| Application | 5 | Application Interface (e.g. Amount of money in my account) | -| System | 3 | Package/Blueprint/Object semantics
Blueprint Fields and Collections
Blueprint Typing | -| Kernel | 2 | Node/Partition/Substate semantics
Substate Ownership/References
| -| Database | 1 | Key/Value Database | diff --git a/radix-engine/docs/architecture.md b/radix-engine/docs/architecture.md new file mode 100644 index 0000000000..c16d282d0a --- /dev/null +++ b/radix-engine/docs/architecture.md @@ -0,0 +1,29 @@ +# Architecture + +The Radix Engine architecture is influenced by traditional Kernel design and Rust's Ownership +and Type-Checking paradigms. The novel idea here is in combining ideas from the two worlds, +Operating System and Language, or simply "Implement Rust Semantics at the System Layer". + +Radix Engine is organized into 5 layers. Each layer has specific responsibilities and +provides an API to the layer above. Middle layers also provide a Callback API which the +layer above must implement. + +| Layer Name | Layer ID | Responsibilities | API | Callback API | Implementation | +|-------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| +| Application | 5 | Application Logic (e.g. Blueprints written in Scrypto) | | | [Native Blueprints](src/blueprints)
[Scrypto Blueprints](../radix-engine-tests/tests/blueprints) | +| VM | 4 | Application Execution | [Scrypto VM API](../scrypto/src/engine/scrypto_env.rs) | | [VM](src/vm) | +| System | 3 | Type Checking
Package/Blueprint/Object semantics
Application Standardization (e.g. Authorization, Versioning) | [Object API](../radix-engine-interface/src/api/object_api.rs)
[Blueprint API](../radix-engine-interface/src/api/blueprint_api.rs)
[Costing API](../radix-engine-interface/src/api/costing_api.rs) | [System Callback API](src/system/system_callback_api.rs) | [System](src/system) | +| Kernel | 2 | Call Frame Message Passing
Ownership/Reference handling
State Virtualization Mechanism
Substate Device Management
Transaction Execution | [Kernel API](src/kernel/kernel_api.rs) | [Kernel Callback API](src/kernel/kernel_callback_api.rs) | [Kernel](src/kernel) | +| Database | 1 | Runtime Read-Only Physical Storage | [Substate Database](../radix-substate-store-interface/src/interface.rs) | | [InMemoryDB](../radix-substate-store-impls/src/memory_db.rs)
[RocksDB](../radix-substate-store-impls/src/rocks_db.rs) | + +## Application + +The application layer is responsible for + +## VM + +## System + +## Kernel + +## Database diff --git a/radix-engine/docs/bootup.drawio.png b/radix-engine/docs/bootup.drawio.png new file mode 100644 index 0000000000000000000000000000000000000000..826b5662063cae3258df7150196d22e50850dbad GIT binary patch literal 16008 zcmeHu2Rzl^|Nk{EGOwMzmCcncTef7U?0d~?UwhB4glHf{C1hokA~O;ZY1oQXWvtZ+w62|Nnm<|G&b$=brOA=e*8qJkRs>mS|+CMM26;3WLEYbhI^$VKBTj z@J&TR1X^MZwou>~o}aOn8myw1bruFg+{6sy`SkMGM_wYiwI=P}zhkcOZ$WtQXk|IbsQweE4NmVIX@Izcu zR7y_T>af4PGurb=pn+G2D+XiFhdd)CDh@=QG_ZGc^~8Glx$sG8- zSrhQX5`0UD+e%2;$_Rj$s@~ohv<2Eh&lRlZjFhB|sH8M#KB=c|YM{@DR0ppyuI^~? zOAGDj?gb4|ck%V|04--EkdmU}&_B>-q-~(9Y0Ud*{Pl`J?3=3=H&r(G!`%d+ef?a$JdZYy6qOK_kUjha8|;lfYjrek$jSxeB!D=GW1_k z{YaPKji)_W(SeSQfOsl!1s}G^%E%oyIQ#yd=cotNVB#8bv>*wvSV$Sp{;nvr-;uP# zCajki2J7nm=SD{_PfxVt(E%SxwD#HUIJ7^0{JWD!kUAOzndxsm9?b)+=|4X9FWdC}iZ?m5gU(fxyZ@ zn+w(h1Kvr1m-ZM}XUGpQXeXdE;J%PB;2v1?ZyP*p^0xo$)(&?2Z|nE3TGm1Xzs33n z1F=UEC8dvab7a$}pw7^=fq%7-Q@`!N~%phZGlR8kVO{5J4|j{&U3sC!|& zd=K)zq>~d`+7XiPhxPSxNB`jyl#HAMaFO2$42}9bSn^*_U%yud)bbm@{4qQIZu3QB zfN2N(836rDDeK=(L5CUiuX)tS3t;TOCQ+&12=6F~{^kAenf$!`eI3z9qyDk{_#d27 z66z00{yinu-q#t8{ZC9O2@pR>%zuFj|F&k1dLQKHf3N31md1bU@(=Ucg8sR?1r;cgSsV4XYZtqYC(qKcA8>c7T6;?ZJlNO3%jYCuo<23{ds=$k*h~XsERG+I( z9&`@?Z${Z#c8c&#qez2{q7ciR>`BIWpd-d23Q;wV*AV&t!8=lk``E1`$iH$H}*6>a|IYq2&SzA;|yIW9k3?_a98|Ldpk z+6N20`GIol4=>b!VvXI#!2-Gu1V349$L9Un7BvUAXx6h{TZ)zrS+&#+1V{35B8oKS4; z+w1I7p%3L3EOxhssvK8Z2&g&>4YI$aX|boh&X&OB@lF>kGp?xe9>+6cRstYlxuDs5l5*g>wh_{1~e<8F}I*7P-5Y z@k(vw+iRgqR2=3LnezT64a*%Y$lw*!?1$0}`6AbMg{1f}-3(D{I@69+4zYV@lG7y| zI|@__EUO$`$Ir7V1YEbU3D#5yM8BdFIA2|W|C-S@jEhYkdo`Ars-%oy4d2pl zy7xxl$6zhIsj8RkCc`8XOS>DNy0_Qn(Qooq-{z|l1piuoc^^CbHs;D4*k?wTq;m-p zMm=(&#_4r?$mIr>gVn2$qM|$50>`*GB7apelga&P_-V=?T?TVxqSWyH`s#i)-4!38 z5_R9{UXiv03KOw4g&z$j3s4Zv?e8=ajW0kp8wE{hb%gqXFhIGZuQu> zMRkKZ1+1m}?R`CXi(K$Z!JMydUgCu2rwVHYc;YH?OPr|SqtFRk^O-S-MWQ4< zMr$dKQIkhZg@7RNaE?-az^G84DHyo@*OwfTrkth5_b&@yd}?&&%5kpU?X_!WrRH66 z$7tUNCB4gy$2jfp?UFipHLl&9Q`(t`r7BQ~#y2iC7g1|JyHV*WXotg}om@7%+*$qF znZ>-Zth4-UZwn!D4Q(Tp2!RIh_!AduG3UgVR*7wTGjAmgn*=51$@-{~(hC+i>E2;+ z-}|-YX4hz#D^E%&YyQxtypY)OjA^ky_sLXGWEB3md8hX6@b&W#Y@3_rEY#J=9Nk7Q${O(w-pg2+T~Jks^1$htDrC(K2?XQdJd;Z^mHs9{4{Sep7J$_LTDRZeLv7@9SuxIUyaEE9u zCwkUQ%tw**>ZGhhi;Sl+Bm=f6B~~1#$;3g{TT;gpTOxte{_2^XbCAh+c7lOcL%fqR zs$qA1^nArYrM>`mpjl?XC1SrDRp!1OFhQD zDAtyK&}WFwyKr_Jo@!LCqwM*-hqr!O6Q@x`+jke=lrx*IQ_;X8@Ei4O4+MXIG4>m) z8gEE>5I-<|B|+~B*Lo$J^&B(5GZv_?$I?2Pm&t*1hMB5N+tt~==GA{Lq=(!5DnFnH zFK&^e#}Nmin(z#%dbhQYQ4`4n5yK@aiqCoI^p_+JslH`u*Ah{Qoq=P_Tl!qv!1LkW*!TZd_KJod^SZZ!nMSq)Xq^N87IfdBA?(Rj}wY*PS#%|yX#I{d^_PanQ zn`JQK?r;X#l#;%R+17>L%RDBP4@^08@UxzkM~pC*nfHYC&ix>dAzss1VhdvJa_{}M zf6Z&PHV)BWdIGr4a79$j6SG=d*&cZI7$;J3`1%0hr<6s5-lmpVujGiU2<}2fv)Wiv zUL3yHV=j%i%DO5A;{}AlPq{o}5jtbe-3s^cqfe^fP}g%2$J!GbAQZP;0^?G{wU-7C zdjd-%2Oy41gS?U}8%nVaf+{!!_wt-|Z8kt51azDlB-8|$PJSaiLBvB+1b3WvLrBK= zLI50L012wK!&s`1fo-;z;>VG2(LDT!e)a%HFRp^87Ke~%Nx}x8iUw5M60Jm+;%Ja;c*>mnL-+ zonGJSdgS_!7hoUb0&Qw|8oK*t*L49C6aXP}Ibd$Rmnm%bL)PZvaCKE|e%(2)^%1Q+ zrm=5Rv&AJ7x6+u-0l8*Skm*?cV{iRDC2M076MB6?)8c&2l`q%M>R#hFC;-#U z>9#t~k}^%utfaHVth7KQk)|YR zZl?d<+efY@I);XZvDyGa^YZa&US<#xJYkq~m4KL1I}3^a^6W&cW*S1kni z&bY{sO)lb>EZ1khsO@u&y{*2=BbVfl(KcWIU@HbpO#4$)`2BPD&Qznj8RP;MGO=^- zbsl`iI^%Hz)NEmWQ7eV@T3s#Rao5Qik5g7$ zsoHz;xiF#&0Nas;GUNNYT@}{PNT@})W+M5PNm7l(Tl-{B4@EY&hrodcog*!?tWvwo zC|2Qw%2f)t+ARy)T5-!IDcogO3bSMovk_*r3A$rt5wl;TAT;3J{qg562wjbVzUyu| z?5x*UCLcmB@U1Rg#J5}p@eXS(GvKJ&JF{{!zwk4(rY_wwer>pZW+BV_U0QyCg1^;6 zUR*{H?0=RtQ`TVc9YyfT9wuw{_Mb-AL6A@!x}+Iv%t=kuz56yrd|7Y!%^Kt+>+&fU zKMO!UXbc0>Hk#Y?@&dmS+p{0W7)LF6i=A@D)(wi@N{3`8pA9lpA?5viYCNjIv~j6ta7F%DT^?t}IHj{vs*k-Qz&>Gk&!0D+N$~IDKsTj=242)rNgB zT`=OKbvv`7K#Obr?Jw_)GbQWCy0t;;;&@y7Z75Hi*a{QS&ukYJf@0kw^UWo&!bzPb zj6lz9Yk#*s=-U4*-Z=!UaEaHJGhXhVQ1t?|!eKteHYf$m>nQP%((+Go5C8$ksS6T^ zNS^ah=ecz}6pdIhaQNsb9H`n|O8DO|pn@By|RbN<**$fVkzPirh;v3t!gfg+B4O6I>k=wziYLZH% zqJhFLU+)lQ2B|piJE=p4^m6&}UFVE_;Fo*?Qs7HKpi9Q2>hpqGlq$vo;r#F!w{7xX zO?PCR_LofDGs)xa0q`nUqWk*`D;!)7R)lUYRIx)9oC9`DErX8HM zLb%u7jvM2N6pNT?;K|=kG+ekh1U=E^gm-3jyo&!q~_mGf4Ou~F`?NOsEb@83k&~VFG z^docCgY9X!Z)TojI@n2@e~-rV)5M-FF1OT&Z{rRUw8ph1Lcx3;JSXm3ai<~{Nw|A3aar3@wDJvv17$?25`oG6&ewZtNuNC%C=WEF~ilG>FMdHx%UsM?c0c$ zB%Q9XDh3&$Spauov@|pNy`lyd8*QgR*Em8DmK^ zkHP_AGamRUSt~Kz)z1=lF=Y1s%Ajqez;bYV#sRLgO`*S`*|7OJ>Fr~8iyKlCFR&E^ zQ+&OdBuHwk8P~g$fHrxh3rhnty?S#;9lbQsN=kZMIqQ^b`rJ0NQrOdyyF?5SX5jTBxv0vMlv>#dDVSo5HKyidgZu;TD|`~!`YSX zj|1cgpKaRt_Ydw7<$FgB%*X(>H8gC`l_I@9D)I@ZKtK;5)(-@PE+e%brR+4lnr@_S zJYO#Ypvu{{HTr3fAEHu}+tk&vq}&IJ-&2Pt=PSImDo6>kj3uH-cdw{B15ob$xhd-0 z17pcGSx_X4Qe7t~&T${(Ym~QaUYX8|ERmpPXQJ>H`4J+{EEECzomf(kp2dkHWKiV00&D zVf>jz+Q-@6`p=hzAQUb*uCae2f<;C7gt0-HK3oHEcI6$0;@>I#@y#u9*zHx08F zjVp44sEgoEvwkjF9K{Ytst|@pcb*YP#1mAiY|tPPD5g&7H(H6!j^7vLa8BWURGRR3*(O>B1YbXSTYRJglYyor3#^tVXg-iN!k#*Gz6l)9lvb=9}~KY z#~t**YwYQ{WKFwKJQM*1^C_b#rkN5o{wUX=<0k_-qYS#mDJcD_tE6D{g_YvO*~JD~ zNX_IT80XBk8YAO3d&hiM6P$#{@%@Afz!dDN_gqW|=yJ6#QR-Z@pAd99!=2e)Owf5z^`R&L-& zrtjb56{*(lM^f2$&__&aZYYMB1hp5cbkfgf7AD=ugQ=a2wHFkvFUxt*^pux@;VwBc zwTCQLoS-{vGQQQ1yuy*%sBGTQ;h9uuA3w;jF5{_*LPMJf;(<8(?{J%H*-EDckk4?n zg0{VF)dbjV$JZnuc{byv`1oGDd+Z=WCGTa#EGaFNZ`QQxw8BY&rhc*F<(Qti2;O=iL5W>BIM*omOq~71(I8 zm9E@3DeMS3KotJuHl>cag_Cj$>UVUf3yUPwJ0@sRQO3Vu*TY~vKRJ?aL#0AESOzlE zNNUwBHt*+|;v<*m?{+tW8r4r(=L`NZvuJ6OI-+j?t)i2RtjcX{;X+V065fS$-^N0#0fK6Pu9Ng!_v+ z`QN2{PX?Q0-V80S&37M{gHbL!B`sE{qGJW;UOlx4Jg-d8Ek44Zj-KM9|}=A$Lq zrSJ22(ou-g@hTfivg7B7h+#<;GMJq>eP?iKEU_N4g15nk=xDOcPKG}pXE}xU>&I39jn<{P_OuIhuhIm~yyj|5JQF~zz5k`>?On18(Vyd#N2OcKKuLk<`FxVO7g z`cpiSNGt@!Jw!*{96a?Tu)(E2G#a@n!eMRJ8B$3HV?x+mo~iY%RcwuMWHk(Auz4QU z2}(^x9ViK#n0-eJn=9yvCt<=OBp(=1@L4W=qwww7qB*S@tCwOOo#{&sTEQqf%hxFj z1d>L0N~}+*^yTq2d?GtVy;XShS)Vh@x+GM;A=^k^4HQo(gT4@X6mHYCeBYh-k-TQpSmx+b|=A zfO^%^PLD^JSS0}lv+EbP$qAyKQn5I`KB&I2*}S(V_BdX_rsw#j)^3`sE&Gz{giM6J zud^hJZmC`_&w`y0=4i3hdRkj>N&DNP@bo8EoUA_q4whS!B*wpy|BRG29EOkLmxZyR zq&jcENm$KWf5EB5dFcwd_ltmYZwL|HWvTbni$mLLU@iuu_?Hnrv>pi=2mZy7Oh}FK z#(kPt=E#rox0{Y3sc(Z3V*KJ56(ba0T8TG&>1T_}5UT$nG&*oP4kY-Fy*dmLIUYcG-dd(HH6YmCWeqaDm4 z&dxzP8E3_j;B#p;@47)=A}5)u1*Of~ph-tzJc2iy<-vfyar0&&-edF6Q4BVwFrJD( zMlun<{p)96X$4!@Cjzl^zZ3>CCZG6`pX$qzGx6}n=@Y+cu?an1q>@2PbSGD!Y38jO zf2?2s_jn&NtQ;Qqossl91tDYpn00PH{DmAU<4O4;e)jPTomVRf#EGVt`%CZ$h>CqE zqX;%GNwDUm_TVefDNHeSmKe!Yi!H2D>*jfHB*P%pWQ5MlZAHXu1&<9@(JAyPGjxxg#L`V6@Ucc0_sy zl(KrNJ>vZuR}qO=Q7(t37x$L)wgT@wjE}=9iJUi)7C;yv7#pjawp)%%*R>hmuTtS1 z8=L~1XL*z2rPJw^t!&c$&$hm0n~e`OF>@YULpQ7?Ow%y5}; zNPlj#IkUM*9dP>ve|V2Zb=Spn7x{s9&KW$A=I$|vA_X#A?+cGy&gmnL zZLG5k*yFXN@0!m8q{;GJ9rZ+tDV&fDClDzb23AxMVP2DJ9*+70rfv z;yEq|iooU<+^6P!I)mQ$pTT8L{c!o^Z0Nr0b&TtCb4Npr6CBL*5OHh`h$ni#^-+C$ zQP??$z)|o{)0Ink@yxWXz2!p*EVhwtgJVm09GLsb?h`E=Y~qx$UZx1{TLxe5)Vute zzO(&QNEg>W&f^$+?@-(%N7(i0i-^`If@W6pVtlaiP^Y#MKhBFowMeqJv9 z;=E55R}2-L%g-B0eFYu2jkGz5d;h>h%RgGqHa7OmW&j+?`sgblR!ye(kMp!@C4(wn zK-$hWFo&IysfWB=G?9Hh+YDN??US5u%g#%#eLaOWxUY;<=Y2moWz?~?!m30&0v=c} z>jPz9dIT&BQg2}CyFlkVl+*6MhAd0p-LMxXO^SDSHY_+cTB8@7K*19%zT#h4{Ca2= z*TA)j3-31zvD-WYVpH*NJGS1k5)J2yy^^5q|IWR!ra7g&@%W{!jyoq!WNLy4Wl>9e ztqxLgYixUyB5ff;K8^D&pq&C_x<=+f*X(vY4Vv*tod@7++A0zAj^J!uX!181)ltsp zjWyMM!~L6LJ65#6Zj^Na7&q~{uoO=I`HC)o2x5LExgrE&wq8;k_t#8OT{~ddV#|td zsU5H~{~eLwh*x8iO!MyJ>OT39ZxK>v{s`sl|wa*ru=KeEJ*vqNyigPj5nMe__UT8MZF+uz+V z1`z^qPPW%+0AY3W%NJDeV%;>VB?^yOn4#%1vy@vW^guy|ZA9I}L7mlC&>E^-BML#R z|0Kr+o*JM97vr0&i{lrdTj{69kWr5(T{&`oyk~DKHrWcLiM2p3qDb}zQBW&Ark&;cmpgJ3n47zzr;RiJ&@T`LqH?u?5pJ-t4 z*vi!jh~~-mtk(gR3{i!E1)~y}=;@HvtECn7x<-g$ZC%~V7kysPzXcDG%#J)R-Tn#K zEf5d+xIC^ir`5kUX4?6l90jwg#rJOLoh#+ZdGX)ja?Wz$FHB6Uw@bR zluLeniT9VDEEDK1U48TR=}@O=k`4_(73Se_&v2_}Fm`A{#LphZ(r{Dwv+F_@DTsbV z@1Ka>W}HcwL`rl;A$Sz(mDJ$HdoXXn$QDHt5d4UOBa?fwv`^x&GjCKWDhTAECz(KH zt_yIP^jApfK!MkV#Q9Gs#8v}mH^DltZ>bz3kz(JLptG?!enaON$t|UT0Gbs1Nv=p zAiBDu_OyUyWxf@Hq!NJ3w>OS~8d^EgVBq4I05KIi){K}e-u$4%kj+30S)d=B`kj9F zI?D90@mu6S=)SogM?U@UQs$Y7aiNsII_m!$BbR(iqPKqBCrcR-2J0u60OG!wt);FC ztsLYY#Hm8FR>-kumEX}-f(i<5c+c;Hyjpt&X8@XpgRK9cT(T^Y8B=l#atY$EHQs~& z4TY7zDTZWeKb>xA{NEEYU+Qb9zsWR*Lk>~6uW!-<)k~aq`po7@s6nmehEABU#$ir) zX-8V(2H7L)^}grU2bCRHgv4tcCN&h!5BztsYq9%;m5%Vbn}UQ?zi0Q*&Yk^gHQxT+ z4AXoSyfc|qTuh;DHm<%=2%QrwoNp!TR2I~#o>Z(SJM~Sqj8EbMaK*zFfxbjK3+I9(4k`g;^QlbDlwcj(~Bat!{vpM7Uq|rp^c~p zi@f)rJ=op9yOF@cquuFWR-y0!l`h71X3V{EQ0Ym6dn%op5CiSTk^e52w|+?sq?>n<`~r5+K)>DT5_B9c zTy^2qNhSJ&dAUBD0K6d*JJba5hWi}|Z~P<5Zjgj-T#zCU4lic2l#YU)Pn-V9P1@P4 zi=3*99lu8N_mN6GEWkiAIWi<3SK18IO5}RAb>(?Ay-657^_hLPxh$2de|IDDqO~;t V6$Yn0@TcW49Zf@x3N^c!{{_ij5;y<= literal 0 HcmV?d00001 diff --git a/radix-engine/docs/bootup.md b/radix-engine/docs/bootup.md new file mode 100644 index 0000000000..59e0f5e582 --- /dev/null +++ b/radix-engine/docs/bootup.md @@ -0,0 +1,21 @@ +# Transaction Bootup + +The initialization of a transaction execution consists of two steps: +1. Initialization of Kernel/System/VM +2. Invocation of the Transaction Processor + +![](bootup.drawio.png) + +## Initialization + +Before a transaction can be executed, initialization of Kernel/System/VM must occur. Several things occur +at the point: +1. Kernel creates the initial call frame +2. Loading of System Layer configuration such as Fee Configuration from Ledger +3. Loading of VM Configuration from Ledger + +This is also the point where the system modules to run are decided on. For example, if we are executing +in preview mode with auth disabled, we may have the auth system module disabled. + +The substates read for configuration load are not accessible to any other packages as it is part of the special +Transaction Processor Component of which there is only one. \ No newline at end of file diff --git a/radix-engine/docs/overview.md b/radix-engine/docs/overview.md new file mode 100644 index 0000000000..d39ec1cfad --- /dev/null +++ b/radix-engine/docs/overview.md @@ -0,0 +1,21 @@ +# Radix Engine + +Radix Engine is an execution engine designed to run DeFi-based Scrypto applications. + +## Architecture +* [Layered Architecture](architecture.md) +* Execution + * [Transaction Bootup](bootup.md) + * System Calls + * Invocations + * Transaction Shutdown +* Move/Borrow Checking +* System/Object Modules +* WASM environment + +## Built-in Systems +* Native Type System +* Native Resources +* Native Auth +* Native Royalties +* Native Metadata From 782c09df58680da77b4e98d3ac262585563ea6a9 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Tue, 2 Apr 2024 18:09:02 -0500 Subject: [PATCH 02/47] Update overview.md --- radix-engine/docs/overview.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/radix-engine/docs/overview.md b/radix-engine/docs/overview.md index d39ec1cfad..8d3f7b1a80 100644 --- a/radix-engine/docs/overview.md +++ b/radix-engine/docs/overview.md @@ -4,18 +4,20 @@ Radix Engine is an execution engine designed to run DeFi-based Scrypto applicati ## Architecture * [Layered Architecture](architecture.md) -* Execution - * [Transaction Bootup](bootup.md) - * System Calls - * Invocations - * Transaction Shutdown -* Move/Borrow Checking +* Substates / SBOR * System/Object Modules * WASM environment + +## Execution +* [Transaction Bootup](bootup.md) +* System Calls +* Invocations +* Transaction Shutdown +* Move/Borrow Checking ## Built-in Systems -* Native Type System -* Native Resources -* Native Auth -* Native Royalties -* Native Metadata +* Type System +* Resources +* Auth +* Royalties +* Metadata From 5c92f16bf7b2dff25ad489e16d07d81270997080 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Thu, 18 Apr 2024 17:30:45 -0500 Subject: [PATCH 03/47] Add documentation on Transaction Processor Invocation --- radix-engine/docs/bootup.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/radix-engine/docs/bootup.md b/radix-engine/docs/bootup.md index 59e0f5e582..3d7d9c826b 100644 --- a/radix-engine/docs/bootup.md +++ b/radix-engine/docs/bootup.md @@ -18,4 +18,9 @@ This is also the point where the system modules to run are decided on. For examp in preview mode with auth disabled, we may have the auth system module disabled. The substates read for configuration load are not accessible to any other packages as it is part of the special -Transaction Processor Component of which there is only one. \ No newline at end of file +Transaction Processor Component of which there is only one. + +## Transaction Processor Invocation + +Once the kernel has been initialized the invocation of a function can be made. The system layer then +makes a function call to a well-known blueprint in our case the TRANSACTION_PROCESSOR run function. \ No newline at end of file From 6d4bbeaf52a03f1ff6704347df9dd71c2a56c2c1 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Fri, 19 Apr 2024 13:15:11 -0500 Subject: [PATCH 04/47] Use md book organization --- radix-engine/docs/README.md | 3 +++ radix-engine/docs/SUMMARY.md | 26 ++++++++++++++++++++++++++ radix-engine/docs/overview.md | 23 ----------------------- 3 files changed, 29 insertions(+), 23 deletions(-) create mode 100644 radix-engine/docs/README.md create mode 100644 radix-engine/docs/SUMMARY.md delete mode 100644 radix-engine/docs/overview.md diff --git a/radix-engine/docs/README.md b/radix-engine/docs/README.md new file mode 100644 index 0000000000..43f8d347f6 --- /dev/null +++ b/radix-engine/docs/README.md @@ -0,0 +1,3 @@ +# Radix Engine + +Radix Engine is an execution engine designed to run DeFi-based Scrypto applications. diff --git a/radix-engine/docs/SUMMARY.md b/radix-engine/docs/SUMMARY.md new file mode 100644 index 0000000000..3a4c23c97d --- /dev/null +++ b/radix-engine/docs/SUMMARY.md @@ -0,0 +1,26 @@ +# Radix Engine + +[Overview](README.md) + +# Architecture + +- [Layered Architecture](architecture.md) +- Substates / SBOR +- System / Object Modules +- WASM environment + +# Execution + +- [Transaction Bootup](bootup.md) +- Transaction Shutdown +- System Calls +- Invocations +- Move/Borrow Checking + +# Built-in Systems + +- Type System +- Resources +- Auth +- Royalties +- Metadata diff --git a/radix-engine/docs/overview.md b/radix-engine/docs/overview.md deleted file mode 100644 index 8d3f7b1a80..0000000000 --- a/radix-engine/docs/overview.md +++ /dev/null @@ -1,23 +0,0 @@ -# Radix Engine - -Radix Engine is an execution engine designed to run DeFi-based Scrypto applications. - -## Architecture -* [Layered Architecture](architecture.md) -* Substates / SBOR -* System/Object Modules -* WASM environment - -## Execution -* [Transaction Bootup](bootup.md) -* System Calls -* Invocations -* Transaction Shutdown -* Move/Borrow Checking - -## Built-in Systems -* Type System -* Resources -* Auth -* Royalties -* Metadata From 9b9b6b22734353299e97af8f40da9ed747a50762 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Fri, 19 Apr 2024 13:44:08 -0500 Subject: [PATCH 05/47] Add more to docs --- radix-engine/docs/README.md | 6 ++++++ radix-engine/docs/SUMMARY.md | 16 ++++++++++------ .../layers.md} | 16 ---------------- .../docs/{ => execution}/bootup.drawio.png | Bin radix-engine/docs/{ => execution}/bootup.md | 0 radix-engine/docs/execution/lifecycle.md | 17 +++++++++++++++++ 6 files changed, 33 insertions(+), 22 deletions(-) rename radix-engine/docs/{architecture.md => architecture/layers.md} (91%) rename radix-engine/docs/{ => execution}/bootup.drawio.png (100%) rename radix-engine/docs/{ => execution}/bootup.md (100%) create mode 100644 radix-engine/docs/execution/lifecycle.md diff --git a/radix-engine/docs/README.md b/radix-engine/docs/README.md index 43f8d347f6..b390099494 100644 --- a/radix-engine/docs/README.md +++ b/radix-engine/docs/README.md @@ -1,3 +1,9 @@ # Radix Engine Radix Engine is an execution engine designed to run DeFi-based Scrypto applications. + +Radix Engine is influenced by traditional Kernel design and Rust's Ownership +and Type-Checking paradigms. The novel idea here is in combining ideas from the two worlds, +Operating System and Language, or simply "Implement Rust Semantics at the System Layer". + + diff --git a/radix-engine/docs/SUMMARY.md b/radix-engine/docs/SUMMARY.md index 3a4c23c97d..5f136b1d2a 100644 --- a/radix-engine/docs/SUMMARY.md +++ b/radix-engine/docs/SUMMARY.md @@ -4,21 +4,25 @@ # Architecture -- [Layered Architecture](architecture.md) +- [Layered Architecture](architecture/layers) - Substates / SBOR - System / Object Modules - WASM environment # Execution -- [Transaction Bootup](bootup.md) -- Transaction Shutdown -- System Calls -- Invocations -- Move/Borrow Checking +- [Transaction Lifecycle](execution/lifecycle.md) +- [Bootup](execution/bootup.md) +- Runtime + - System Calls + - Invocations + - Move/Borrow Checking +- Shutdown + # Built-in Systems +- Transaction Manifest - Type System - Resources - Auth diff --git a/radix-engine/docs/architecture.md b/radix-engine/docs/architecture/layers.md similarity index 91% rename from radix-engine/docs/architecture.md rename to radix-engine/docs/architecture/layers.md index c16d282d0a..06bf132d72 100644 --- a/radix-engine/docs/architecture.md +++ b/radix-engine/docs/architecture/layers.md @@ -1,9 +1,5 @@ # Architecture -The Radix Engine architecture is influenced by traditional Kernel design and Rust's Ownership -and Type-Checking paradigms. The novel idea here is in combining ideas from the two worlds, -Operating System and Language, or simply "Implement Rust Semantics at the System Layer". - Radix Engine is organized into 5 layers. Each layer has specific responsibilities and provides an API to the layer above. Middle layers also provide a Callback API which the layer above must implement. @@ -15,15 +11,3 @@ layer above must implement. | System | 3 | Type Checking
Package/Blueprint/Object semantics
Application Standardization (e.g. Authorization, Versioning) | [Object API](../radix-engine-interface/src/api/object_api.rs)
[Blueprint API](../radix-engine-interface/src/api/blueprint_api.rs)
[Costing API](../radix-engine-interface/src/api/costing_api.rs) | [System Callback API](src/system/system_callback_api.rs) | [System](src/system) | | Kernel | 2 | Call Frame Message Passing
Ownership/Reference handling
State Virtualization Mechanism
Substate Device Management
Transaction Execution | [Kernel API](src/kernel/kernel_api.rs) | [Kernel Callback API](src/kernel/kernel_callback_api.rs) | [Kernel](src/kernel) | | Database | 1 | Runtime Read-Only Physical Storage | [Substate Database](../radix-substate-store-interface/src/interface.rs) | | [InMemoryDB](../radix-substate-store-impls/src/memory_db.rs)
[RocksDB](../radix-substate-store-impls/src/rocks_db.rs) | - -## Application - -The application layer is responsible for - -## VM - -## System - -## Kernel - -## Database diff --git a/radix-engine/docs/bootup.drawio.png b/radix-engine/docs/execution/bootup.drawio.png similarity index 100% rename from radix-engine/docs/bootup.drawio.png rename to radix-engine/docs/execution/bootup.drawio.png diff --git a/radix-engine/docs/bootup.md b/radix-engine/docs/execution/bootup.md similarity index 100% rename from radix-engine/docs/bootup.md rename to radix-engine/docs/execution/bootup.md diff --git a/radix-engine/docs/execution/lifecycle.md b/radix-engine/docs/execution/lifecycle.md new file mode 100644 index 0000000000..cee788466b --- /dev/null +++ b/radix-engine/docs/execution/lifecycle.md @@ -0,0 +1,17 @@ +# Transaction Lifecycle + +Radix Engine is a state machine which follows: +``` +RadixEngine(State, Transaction) -> StateChange +``` + +There are three stages in the transaction lifecycle: +1. Bootup +2. Execution +3. Shutdown + +Bootup consists of setting up the state of the layered stack. + +Execution is running application logic. + +Shutdown is cleaning up the layered stack and creating the final StateChange receipt. \ No newline at end of file From d57bd111fbcab8701e80a1e7e84ef409531a3a7e Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Fri, 19 Apr 2024 14:31:52 -0500 Subject: [PATCH 06/47] Add markdown files for different layers in system --- radix-engine/docs/SUMMARY.md | 10 ++++++++-- radix-engine/docs/architecture/layers.md | 1 + radix-engine/docs/architecture/layers/application.md | 7 +++++++ radix-engine/docs/architecture/layers/database.md | 1 + radix-engine/docs/architecture/layers/kernel.md | 8 ++++++++ radix-engine/docs/architecture/layers/system.md | 5 +++++ radix-engine/docs/architecture/layers/vm.md | 4 ++++ 7 files changed, 34 insertions(+), 2 deletions(-) create mode 100644 radix-engine/docs/architecture/layers/application.md create mode 100644 radix-engine/docs/architecture/layers/database.md create mode 100644 radix-engine/docs/architecture/layers/kernel.md create mode 100644 radix-engine/docs/architecture/layers/system.md create mode 100644 radix-engine/docs/architecture/layers/vm.md diff --git a/radix-engine/docs/SUMMARY.md b/radix-engine/docs/SUMMARY.md index 5f136b1d2a..a6ce386c9c 100644 --- a/radix-engine/docs/SUMMARY.md +++ b/radix-engine/docs/SUMMARY.md @@ -4,8 +4,14 @@ # Architecture -- [Layered Architecture](architecture/layers) -- Substates / SBOR +- [Layered Architecture](architecture/layers.md) + - [Application Layer](architecture/layers/application.md) + - [VM Layer](architecture/layers/vm.md) + - [System Layer](architecture/layers/system.md) + - [Kernel Layer](architecture/layers/kernel.md) + - [Database Layer](architecture/layers/database.md) +- Data Architecture + - Substates / SBOR - System / Object Modules - WASM environment diff --git a/radix-engine/docs/architecture/layers.md b/radix-engine/docs/architecture/layers.md index 06bf132d72..61d984b9c6 100644 --- a/radix-engine/docs/architecture/layers.md +++ b/radix-engine/docs/architecture/layers.md @@ -11,3 +11,4 @@ layer above must implement. | System | 3 | Type Checking
Package/Blueprint/Object semantics
Application Standardization (e.g. Authorization, Versioning) | [Object API](../radix-engine-interface/src/api/object_api.rs)
[Blueprint API](../radix-engine-interface/src/api/blueprint_api.rs)
[Costing API](../radix-engine-interface/src/api/costing_api.rs) | [System Callback API](src/system/system_callback_api.rs) | [System](src/system) | | Kernel | 2 | Call Frame Message Passing
Ownership/Reference handling
State Virtualization Mechanism
Substate Device Management
Transaction Execution | [Kernel API](src/kernel/kernel_api.rs) | [Kernel Callback API](src/kernel/kernel_callback_api.rs) | [Kernel](src/kernel) | | Database | 1 | Runtime Read-Only Physical Storage | [Substate Database](../radix-substate-store-interface/src/interface.rs) | | [InMemoryDB](../radix-substate-store-impls/src/memory_db.rs)
[RocksDB](../radix-substate-store-impls/src/rocks_db.rs) | + diff --git a/radix-engine/docs/architecture/layers/application.md b/radix-engine/docs/architecture/layers/application.md new file mode 100644 index 0000000000..37de121cf3 --- /dev/null +++ b/radix-engine/docs/architecture/layers/application.md @@ -0,0 +1,7 @@ +# Application Layer + +The application layer is responsible for defining high level logic. Bytecode that describes this logic, +along with other static information, is bundled up in an executable format called a Package. Packages +are then stored on-ledger and available for execution. + +## Packages diff --git a/radix-engine/docs/architecture/layers/database.md b/radix-engine/docs/architecture/layers/database.md new file mode 100644 index 0000000000..4a79ce0cd5 --- /dev/null +++ b/radix-engine/docs/architecture/layers/database.md @@ -0,0 +1 @@ +# Database \ No newline at end of file diff --git a/radix-engine/docs/architecture/layers/kernel.md b/radix-engine/docs/architecture/layers/kernel.md new file mode 100644 index 0000000000..e7480f318d --- /dev/null +++ b/radix-engine/docs/architecture/layers/kernel.md @@ -0,0 +1,8 @@ +# Kernel Layer +The kernel layer is responsible for the two core functionalities of Radix Engine: storage access and communication between applications. This is somewhat similar to the traditional Operating System’s responsibility for disk and network access. + +For Radix Engine, this includes the following low-level management: + +* Check that move/borrow semantics are maintained on any invocation or data write. The single owner rule and borrow rules are enforced by the kernel. On failure on any of these rules, the transaction will panic. +* Manage transient vs. persistent objects. An object at any point in time may be in the global space or may be owned by a call frame. The kernel maintains correct pointers to these objects during runtime as references to these objects are passed around. +* Manage transaction state updates. The kernel keeps track of the state updates which have occurred during a transaction and which will be subsequently committed to the database at the end of the transaction. \ No newline at end of file diff --git a/radix-engine/docs/architecture/layers/system.md b/radix-engine/docs/architecture/layers/system.md new file mode 100644 index 0000000000..dcef9d3130 --- /dev/null +++ b/radix-engine/docs/architecture/layers/system.md @@ -0,0 +1,5 @@ +# System Layer + +The System Layer is responsible for maintaining a set of System Modules, or pluggable software which can extend the functionality of the system. + +On every system call, each system module gets called before the system layer passes control to the kernel layer. When called, each system module may update some particular state (e.g. update fees spent) or panic to end the transaction (e.g. if the type checker fails). \ No newline at end of file diff --git a/radix-engine/docs/architecture/layers/vm.md b/radix-engine/docs/architecture/layers/vm.md new file mode 100644 index 0000000000..6744e1908d --- /dev/null +++ b/radix-engine/docs/architecture/layers/vm.md @@ -0,0 +1,4 @@ +# VM Layer +The VM Layer is responsible for providing the computing environment to the application layer. This includes a Turing-complete VM as well as the interface to access the system layer. + +Radix Engine currently supports two VMs: a Scrypto WASM VM used to execute Scrypto applications and a native VM which executes native packages which are compiled to the host’s environment. \ No newline at end of file From bca66fb2a1b0fde68ae7b7d11df1197758bf14db Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Tue, 23 Apr 2024 10:42:55 -0500 Subject: [PATCH 07/47] More updates to documentation --- radix-engine/docs/README.md | 13 ++++++--- radix-engine/docs/SUMMARY.md | 28 ++++++++++--------- radix-engine/docs/architecture/layers.md | 14 +++++----- .../docs/architecture/layers/application.md | 8 +++--- .../layers/application/wasm_environment.md | 5 ++++ 5 files changed, 40 insertions(+), 28 deletions(-) create mode 100644 radix-engine/docs/architecture/layers/application/wasm_environment.md diff --git a/radix-engine/docs/README.md b/radix-engine/docs/README.md index b390099494..ee3c0cb7fd 100644 --- a/radix-engine/docs/README.md +++ b/radix-engine/docs/README.md @@ -1,9 +1,14 @@ # Radix Engine -Radix Engine is an execution engine designed to run DeFi-based Scrypto applications. +Radix Engine is a transaction-based state machine that updates the ledger state by incrementally +executing transactions. -Radix Engine is influenced by traditional Kernel design and Rust's Ownership -and Type-Checking paradigms. The novel idea here is in combining ideas from the two worlds, -Operating System and Language, or simply "Implement Rust Semantics at the System Layer". +Unlike Ethereum where the ledger state is a flat mapping between addresses and account states, Radix +Engine organizes its state into a forest of objects. Child objects are exclusively owned by its +parent in the tree hierarchy. Each root object is assigned a global address. +Every object has an associated blueprint, which defines logic for updating the object's internal +state. Multiple blueprints can be packed into a package and published as a single unit. +A set of native packages are defined by Radix Engine which form built-in system standards such as +accounts, access control, resources, etc. \ No newline at end of file diff --git a/radix-engine/docs/SUMMARY.md b/radix-engine/docs/SUMMARY.md index a6ce386c9c..fad41cc2af 100644 --- a/radix-engine/docs/SUMMARY.md +++ b/radix-engine/docs/SUMMARY.md @@ -6,31 +6,33 @@ - [Layered Architecture](architecture/layers.md) - [Application Layer](architecture/layers/application.md) + - [WASM environment](architecture/layers/application/wasm_environment.md) + - Native environment (TODO) + - Blueprint Definition (TODO) - [VM Layer](architecture/layers/vm.md) - [System Layer](architecture/layers/system.md) + - System / Object Modules (TODO) - [Kernel Layer](architecture/layers/kernel.md) - [Database Layer](architecture/layers/database.md) -- Data Architecture - - Substates / SBOR -- System / Object Modules -- WASM environment +- Data Architecture (TODO) + - Substates / SBOR (TODO) # Execution - [Transaction Lifecycle](execution/lifecycle.md) -- [Bootup](execution/bootup.md) -- Runtime - - System Calls - - Invocations - - Move/Borrow Checking -- Shutdown - + - [Bootup](execution/bootup.md) + - Runtime (TODO) + - System Calls (TODO) + - Invocations (TODO) + - Move/Borrow Checking (TODO) + - Shutdown (TODO) +- Protocol Updates (TODO) -# Built-in Systems +# Native Systems - Transaction Manifest - Type System - Resources -- Auth +- Access Control - Royalties - Metadata diff --git a/radix-engine/docs/architecture/layers.md b/radix-engine/docs/architecture/layers.md index 61d984b9c6..a931d3be19 100644 --- a/radix-engine/docs/architecture/layers.md +++ b/radix-engine/docs/architecture/layers.md @@ -4,11 +4,11 @@ Radix Engine is organized into 5 layers. Each layer has specific responsibilitie provides an API to the layer above. Middle layers also provide a Callback API which the layer above must implement. -| Layer Name | Layer ID | Responsibilities | API | Callback API | Implementation | -|-------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| -| Application | 5 | Application Logic (e.g. Blueprints written in Scrypto) | | | [Native Blueprints](src/blueprints)
[Scrypto Blueprints](../radix-engine-tests/tests/blueprints) | -| VM | 4 | Application Execution | [Scrypto VM API](../scrypto/src/engine/scrypto_env.rs) | | [VM](src/vm) | -| System | 3 | Type Checking
Package/Blueprint/Object semantics
Application Standardization (e.g. Authorization, Versioning) | [Object API](../radix-engine-interface/src/api/object_api.rs)
[Blueprint API](../radix-engine-interface/src/api/blueprint_api.rs)
[Costing API](../radix-engine-interface/src/api/costing_api.rs) | [System Callback API](src/system/system_callback_api.rs) | [System](src/system) | -| Kernel | 2 | Call Frame Message Passing
Ownership/Reference handling
State Virtualization Mechanism
Substate Device Management
Transaction Execution | [Kernel API](src/kernel/kernel_api.rs) | [Kernel Callback API](src/kernel/kernel_callback_api.rs) | [Kernel](src/kernel) | -| Database | 1 | Runtime Read-Only Physical Storage | [Substate Database](../radix-substate-store-interface/src/interface.rs) | | [InMemoryDB](../radix-substate-store-impls/src/memory_db.rs)
[RocksDB](../radix-substate-store-impls/src/rocks_db.rs) | +| Layer Name | Layer ID | Responsibilities | API | Callback API | Implementation | +|-------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| +| Application | 5 | Defines Types and Application Logic | | | [Native Blueprints](src/blueprints)
[Scrypto Blueprints](../radix-engine-tests/tests/blueprints) | +| VM | 4 | Interprets Application Code | [Scrypto VM API](../scrypto/src/engine/scrypto_env.rs) | | [VM](src/vm) | +| System | 3 | Responsible for:
- Type Checking
- Package/Blueprint/Object abstractions
- Defining Universal Standards (e.g. Authorization, Versioning) | [Object API](../radix-engine-interface/src/api/object_api.rs)
[Blueprint API](../radix-engine-interface/src/api/blueprint_api.rs)
[Costing API](../radix-engine-interface/src/api/costing_api.rs) | [System Callback API](src/system/system_callback_api.rs) | [System](src/system) | +| Kernel | 2 | Responsible for:
- Call Frame Message Passing
- Ownership/Reference handling
- State Virtualization Mechanism | [Kernel API](src/kernel/kernel_api.rs) | [Kernel Callback API](src/kernel/kernel_callback_api.rs) | [Kernel](src/kernel) | +| Database | 1 | Interacts with a Read-Only Database | [Substate Database](../radix-substate-store-interface/src/interface.rs) | | [InMemoryDB](../radix-substate-store-impls/src/memory_db.rs)
[RocksDB](../radix-substate-store-impls/src/rocks_db.rs) | diff --git a/radix-engine/docs/architecture/layers/application.md b/radix-engine/docs/architecture/layers/application.md index 37de121cf3..99c181ce6f 100644 --- a/radix-engine/docs/architecture/layers/application.md +++ b/radix-engine/docs/architecture/layers/application.md @@ -1,7 +1,7 @@ # Application Layer -The application layer is responsible for defining high level logic. Bytecode that describes this logic, -along with other static information, is bundled up in an executable format called a Package. Packages -are then stored on-ledger and available for execution. +Applications in Radix Engine are responsible for defining two things: +1. New Blueprint Definitions +2. Associated Logic with each Blueprint -## Packages +These are bundled up in a format called a Package. diff --git a/radix-engine/docs/architecture/layers/application/wasm_environment.md b/radix-engine/docs/architecture/layers/application/wasm_environment.md new file mode 100644 index 0000000000..5ec879456e --- /dev/null +++ b/radix-engine/docs/architecture/layers/application/wasm_environment.md @@ -0,0 +1,5 @@ +# WASM Environment + +## Syscalls + +[System calls](../../../../../scrypto/src/engine/wasm_api.rs) \ No newline at end of file From 29515ee3090b5c77ede0ce6595597cbfa4073553 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Tue, 23 Apr 2024 12:02:15 -0500 Subject: [PATCH 08/47] Add more documentation --- radix-engine/docs/SUMMARY.md | 5 +- radix-engine/docs/execution/bootup.md | 29 ++++++------ radix-engine/docs/execution/shutdown.md | 5 ++ radix-engine/src/kernel/kernel.rs | 19 ++++---- radix-engine/src/system/system_callback.rs | 46 ++++++++----------- .../src/system/system_callback_api.rs | 10 ++-- .../src/transaction/transaction_executor.rs | 2 +- radix-engine/src/vm/vm.rs | 2 +- .../ledger_simulator/inject_costing_err.rs | 2 +- 9 files changed, 62 insertions(+), 58 deletions(-) create mode 100644 radix-engine/docs/execution/shutdown.md diff --git a/radix-engine/docs/SUMMARY.md b/radix-engine/docs/SUMMARY.md index fad41cc2af..f61b2bbb24 100644 --- a/radix-engine/docs/SUMMARY.md +++ b/radix-engine/docs/SUMMARY.md @@ -11,7 +11,8 @@ - Blueprint Definition (TODO) - [VM Layer](architecture/layers/vm.md) - [System Layer](architecture/layers/system.md) - - System / Object Modules (TODO) + - System Modules (TODO) + - Object Modules (TODO) - [Kernel Layer](architecture/layers/kernel.md) - [Database Layer](architecture/layers/database.md) - Data Architecture (TODO) @@ -25,7 +26,7 @@ - System Calls (TODO) - Invocations (TODO) - Move/Borrow Checking (TODO) - - Shutdown (TODO) + - [Shutdown](execution/shutdown.md) - Protocol Updates (TODO) # Native Systems diff --git a/radix-engine/docs/execution/bootup.md b/radix-engine/docs/execution/bootup.md index 3d7d9c826b..ac6a0fc898 100644 --- a/radix-engine/docs/execution/bootup.md +++ b/radix-engine/docs/execution/bootup.md @@ -1,26 +1,25 @@ # Transaction Bootup The initialization of a transaction execution consists of two steps: -1. Initialization of Kernel/System/VM -2. Invocation of the Transaction Processor +1. Initialize Stack +2. Invoke Transaction Processor ![](bootup.drawio.png) -## Initialization +## Initialize Stack -Before a transaction can be executed, initialization of Kernel/System/VM must occur. Several things occur -at the point: -1. Kernel creates the initial call frame -2. Loading of System Layer configuration such as Fee Configuration from Ledger -3. Loading of VM Configuration from Ledger +Before a transaction is executed, initialization of the Kernel/System/VM stack occurs. During this +initialization phase, configuration is loaded from the database and the state of each layer is +initialized. -This is also the point where the system modules to run are decided on. For example, if we are executing -in preview mode with auth disabled, we may have the auth system module disabled. +For example, during System initialization the system modules to run are decided on. +If we are executing in preview mode with auth disabled, the auth system module may be disabled. -The substates read for configuration load are not accessible to any other packages as it is part of the special -Transaction Processor Component of which there is only one. +The code for this can be found in [kernel.rs](../../src/kernel/kernel.rs) in the `Bootloader::execute` +method. -## Transaction Processor Invocation +## Invoke Transaction Processor -Once the kernel has been initialized the invocation of a function can be made. The system layer then -makes a function call to a well-known blueprint in our case the TRANSACTION_PROCESSOR run function. \ No newline at end of file +Once the entire stack has been initialized along with the initial call frame, an invocation of a +well-known blueprint, `TRANSACTION_PROCESSOR`, is made with the arguments specified in the transaction. +From this point forward, normal transaction execution occurs. diff --git a/radix-engine/docs/execution/shutdown.md b/radix-engine/docs/execution/shutdown.md new file mode 100644 index 0000000000..cacd62ef05 --- /dev/null +++ b/radix-engine/docs/execution/shutdown.md @@ -0,0 +1,5 @@ +# Transaction Shutdown + +Finishing transaction execution consists of two steps: +1. Finalizing state updates +2. Creating a transaction receipt \ No newline at end of file diff --git a/radix-engine/src/kernel/kernel.rs b/radix-engine/src/kernel/kernel.rs index 613ed4cdf8..d62ce197d0 100644 --- a/radix-engine/src/kernel/kernel.rs +++ b/radix-engine/src/kernel/kernel.rs @@ -39,7 +39,9 @@ pub struct BootLoader<'h, M: KernelCallbackObject, S: SubstateDatabase> { } impl<'h, M: KernelCallbackObject, S: SubstateDatabase> BootLoader<'h, M, S> { - pub fn check_references( + + /// Checks that references exist in the store + fn check_references( &mut self, references: &IndexSet, ) -> Result<(IndexSet, IndexSet), BootloadingError> { @@ -136,23 +138,23 @@ impl<'h, M: KernelCallbackObject, S: SubstateDatabase> BootLoader<'h, M, S> { v.borrow_mut(); }); - // Create System + // System Initialization let mut callback = M::init(&mut self.track, executable, self.init.clone())?; - // Create Kernel + // Kernel Initialization let mut kernel = { // Check references - let engine_references = self + let (global_refs, direct_access_refs) = self .check_references(executable.references()) .map_err(RejectionReason::BootloadingError)?; let mut kernel = Kernel::new(&mut self.track, &mut self.id_allocator, &mut callback); - // Add visibility - for global_ref in engine_references.0 { + // Initialize initial frame + for global_ref in global_refs { kernel.current_frame.add_global_reference(global_ref); } - for direct_access in engine_references.1 { + for direct_access in direct_access_refs { kernel .current_frame .add_direct_access_reference(direct_access); @@ -178,14 +180,15 @@ impl<'h, M: KernelCallbackObject, S: SubstateDatabase> BootLoader<'h, M, S> { // Sanity check heap assert!(kernel.substate_io.heap.is_empty()); + // Finalize state updates based on what has occurred let commit_info = kernel.substate_io.store.get_commit_info(); - kernel.callback.finish(commit_info)?; Ok(output) }() .map_err(|e| TransactionExecutionError::RuntimeError(e)); + // Create receipt representing the result of a transaction let receipt = M::create_receipt(callback, self.track, executable, result); Ok(receipt) diff --git a/radix-engine/src/system/system_callback.rs b/radix-engine/src/system/system_callback.rs index 9e19b56717..036d3127f8 100644 --- a/radix-engine/src/system/system_callback.rs +++ b/radix-engine/src/system/system_callback.rs @@ -178,7 +178,7 @@ impl System { println!("References: {:?}", executable.references()); } - pub fn read_epoch(store: &mut S) -> Option { + fn read_epoch(store: &mut S) -> Option { // TODO - Instead of doing a check of the exact epoch, we could do a check in range [X, Y] // Which could allow for better caching of transaction validity over epoch boundaries match store.read_substate( @@ -195,7 +195,7 @@ impl System { } } - pub fn validate_epoch_range( + fn validate_epoch_range( current_epoch: Epoch, start_epoch_inclusive: Epoch, end_epoch_exclusive: Epoch, @@ -216,7 +216,7 @@ impl System { Ok(()) } - pub fn validate_intent_hash( + fn validate_intent_hash( track: &mut S, intent_hash: Hash, expiry_epoch: Epoch, @@ -726,14 +726,14 @@ impl System { impl KernelCallbackObject for System { type LockData = SystemLockData; type CallFrameData = Actor; - type Init = SystemInit; + type Init = SystemInit; type ExecutionOutput = Vec; type Receipt = TransactionReceipt; fn init( store: &mut S, executable: &Executable, - init_input: SystemInit, + init_input: SystemInit, ) -> Result { // Dump executable #[cfg(not(feature = "alloc"))] @@ -848,14 +848,6 @@ impl KernelCallbackObject for System { modules.init().map_err(RejectionReason::BootloadingError)?; - let system = System { - blueprint_cache: NonIterMap::new(), - auth_cache: NonIterMap::new(), - schema_cache: NonIterMap::new(), - callback, - modules, - }; - // Perform runtime validation. // TODO: the following assumptions can be removed with better interface. // We are assuming that intent hash store is ready when epoch manager is ready. @@ -866,21 +858,23 @@ impl KernelCallbackObject for System { current_epoch, range.start_epoch_inclusive, range.end_epoch_exclusive, - ) - .and_then(|_| { - Self::validate_intent_hash( - store, - executable.intent_hash().to_hash(), - range.end_epoch_exclusive, - ) - }) - .and_then(|_| Ok(system)) - } else { - Ok(system) + )?; + Self::validate_intent_hash( + store, + executable.intent_hash().to_hash(), + range.end_epoch_exclusive, + )?; } - } else { - Ok(system) } + + let system = System { + blueprint_cache: NonIterMap::new(), + auth_cache: NonIterMap::new(), + schema_cache: NonIterMap::new(), + callback, + modules, + }; + Ok(system) } fn start( diff --git a/radix-engine/src/system/system_callback_api.rs b/radix-engine/src/system/system_callback_api.rs index 513aa33391..7f9380a135 100644 --- a/radix-engine/src/system/system_callback_api.rs +++ b/radix-engine/src/system/system_callback_api.rs @@ -6,14 +6,16 @@ use crate::track::BootStore; use radix_engine_interface::api::ClientApi; use radix_engine_interface::blueprints::package::PackageExport; -/// Invocation callback invoked by the system layer +/// Callback object invoked by the system layer pub trait SystemCallbackObject: Sized { - type InitInput: Clone; + /// Initialization Object + type Init: Clone; - /// Initialize the layer above the system with data from the substate store - fn init(store: &S, init_input: Self::InitInput) + /// Initialize and create the callback object above the system + fn init(store: &S, init_input: Self::Init) -> Result; + /// Invoke a function fn invoke( package_address: &PackageAddress, package_export: PackageExport, diff --git a/radix-engine/src/transaction/transaction_executor.rs b/radix-engine/src/transaction/transaction_executor.rs index dad803b3bc..4ab89227a6 100644 --- a/radix-engine/src/transaction/transaction_executor.rs +++ b/radix-engine/src/transaction/transaction_executor.rs @@ -310,7 +310,7 @@ where pub fn execute_transaction_with_configuration( substate_db: &S, - vms: V::InitInput, + vms: V::Init, execution_config: &ExecutionConfig, transaction: &Executable, ) -> TransactionReceipt { diff --git a/radix-engine/src/vm/vm.rs b/radix-engine/src/vm/vm.rs index b9acfcaa65..b47dff2645 100644 --- a/radix-engine/src/vm/vm.rs +++ b/radix-engine/src/vm/vm.rs @@ -79,7 +79,7 @@ pub enum VmBoot { } impl<'g, W: WasmEngine + 'g, E: NativeVmExtension> SystemCallbackObject for Vm<'g, W, E> { - type InitInput = VmInit<'g, W, E>; + type Init = VmInit<'g, W, E>; fn init(store: &S, vm_init: VmInit<'g, W, E>) -> Result { let vm_boot = store diff --git a/scrypto-test/src/ledger_simulator/inject_costing_err.rs b/scrypto-test/src/ledger_simulator/inject_costing_err.rs index 0422fd37c6..d985effac2 100644 --- a/scrypto-test/src/ledger_simulator/inject_costing_err.rs +++ b/scrypto-test/src/ledger_simulator/inject_costing_err.rs @@ -87,7 +87,7 @@ impl KernelCallbackObject for InjectCostingError { type LockData = SystemLockData; type CallFrameData = Actor; - type Init = InjectCostingErrorInput>; + type Init = InjectCostingErrorInput>; type ExecutionOutput = Vec; type Receipt = TransactionReceipt; From b8f7ac3943647e1d3a57dcb2fa982a88249ce004 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Tue, 23 Apr 2024 13:02:21 -0500 Subject: [PATCH 09/47] Add more documentation --- radix-engine/docs/SUMMARY.md | 7 +++- radix-engine/docs/execution/shutdown.md | 9 +++-- .../docs/native/access_control/README.md | 17 +++++++++ .../native/access_control/authorization.md | 9 +++++ .../docs/native/access_control/authzone.md | 8 ++++ .../native/access_control/role_assignment.md | 7 ++++ .../native/access_control/role_definition.md | 4 ++ .../src/system/system_modules/auth/README.md | 37 ------------------- 8 files changed, 57 insertions(+), 41 deletions(-) create mode 100644 radix-engine/docs/native/access_control/README.md create mode 100644 radix-engine/docs/native/access_control/authorization.md create mode 100644 radix-engine/docs/native/access_control/authzone.md create mode 100644 radix-engine/docs/native/access_control/role_assignment.md create mode 100644 radix-engine/docs/native/access_control/role_definition.md delete mode 100644 radix-engine/src/system/system_modules/auth/README.md diff --git a/radix-engine/docs/SUMMARY.md b/radix-engine/docs/SUMMARY.md index f61b2bbb24..04d08aa25f 100644 --- a/radix-engine/docs/SUMMARY.md +++ b/radix-engine/docs/SUMMARY.md @@ -27,6 +27,7 @@ - Invocations (TODO) - Move/Borrow Checking (TODO) - [Shutdown](execution/shutdown.md) +- Bootstrapping (TODO) - Protocol Updates (TODO) # Native Systems @@ -34,6 +35,10 @@ - Transaction Manifest - Type System - Resources -- Access Control +- [Access Control](native/access_control/README) + - [Role Definition](native/access_control/role_definition.md) + - [Role Assignment](native/access_control/role_assignment.md) + - [Auth Zone](native/access_control/authzone.md) + - [Authorization](native/access_control/authorization.md) - Royalties - Metadata diff --git a/radix-engine/docs/execution/shutdown.md b/radix-engine/docs/execution/shutdown.md index cacd62ef05..052ae8a76e 100644 --- a/radix-engine/docs/execution/shutdown.md +++ b/radix-engine/docs/execution/shutdown.md @@ -1,5 +1,8 @@ # Transaction Shutdown -Finishing transaction execution consists of two steps: -1. Finalizing state updates -2. Creating a transaction receipt \ No newline at end of file +Once the `TRANSACTION_PROCESSOR` call returns, the transaction shutdown procedure begins. + +Transaction Shutdown consists of two steps: +1. Finalize State Updates +2. Create a Transaction Receipt + diff --git a/radix-engine/docs/native/access_control/README.md b/radix-engine/docs/native/access_control/README.md new file mode 100644 index 0000000000..081db345e6 --- /dev/null +++ b/radix-engine/docs/native/access_control/README.md @@ -0,0 +1,17 @@ +# Access Control + +Unlike the majority of blockchains which rely on a caller identifier for access control, the Access Control +system uses a more distributed "Proof" system. Before accessing a protected method a caller must provide +specific "Proofs" of resources they have access to. These proofs must then match the required proofs +defined by protected method or function of the callee. + +The Access Control System is composed of four parts: + +1. A Package Module, which defines roles available to use for a given blueprint in a package +2. An Object Module, which provides role assignment or which resources are required to show proof for a given role +3. A System Module, which maintains an AuthZone, or the current proofs a runtime caller has +3. An AuthZone Blueprint, which allows a caller to update their current proofs + +These three modules allow a package creator to define roles which a component creator can assign definitions to, +which a caller must show proof for by updating their AuthZone. + diff --git a/radix-engine/docs/native/access_control/authorization.md b/radix-engine/docs/native/access_control/authorization.md new file mode 100644 index 0000000000..e53f91c00a --- /dev/null +++ b/radix-engine/docs/native/access_control/authorization.md @@ -0,0 +1,9 @@ +# Authorization + +On rule check time, the AuthModule checks the proofs on the caller's AuthZone and determines which roles for this +object the caller has. If any of these roles match the list of roles assigned to the method, the caller is then +authorized to make the call. + +Unlike traditional RBAC where the role a user is acting is explicit, in this model roles are more implicit and +defined on what proofs the user has in their AuthZone. This makes it a cross between the well-known RBAC and +ABAC models. diff --git a/radix-engine/docs/native/access_control/authzone.md b/radix-engine/docs/native/access_control/authzone.md new file mode 100644 index 0000000000..9c9b98217e --- /dev/null +++ b/radix-engine/docs/native/access_control/authzone.md @@ -0,0 +1,8 @@ +# AuthZone + +To call a protected method, the caller must place these proofs into their [AuthZone](../../../blueprints/resource/auth_zone), +a space dedicated for using proofs for the purpose of authorized method access. On method call, the Auth Module +then checks the caller's AuthZone and compares it to the rules specified by the Callee. + +These rules are specified by the Callee on Object instantiation and are defined by using a mixture of **Role-Based +Access Control** (RBAC) and **Attribute-Based Access Control** (ABAC) techniques. \ No newline at end of file diff --git a/radix-engine/docs/native/access_control/role_assignment.md b/radix-engine/docs/native/access_control/role_assignment.md new file mode 100644 index 0000000000..9999e77ada --- /dev/null +++ b/radix-engine/docs/native/access_control/role_assignment.md @@ -0,0 +1,7 @@ +# Role Assignment + +On the callee side, instead of roles being assigned to a "user" (of which there is no concept in our decentralized +ledger), roles are assigned through resource ownership. For example, a "Staff" role could be assigned to anyone who +can show proof that they own a "Staff" resource token. This is defined at the callee's Object instantiation +through the [RoleAssignment](../../attached_modules/role_assignment) object module. + diff --git a/radix-engine/docs/native/access_control/role_definition.md b/radix-engine/docs/native/access_control/role_definition.md new file mode 100644 index 0000000000..a7fd907696 --- /dev/null +++ b/radix-engine/docs/native/access_control/role_definition.md @@ -0,0 +1,4 @@ +# Role Definition + +All roles for a given object are defined (though not assigned!) at the Blueprint level by the Package creator. This +includes definitions regarding which methods a given role is given access to. \ No newline at end of file diff --git a/radix-engine/src/system/system_modules/auth/README.md b/radix-engine/src/system/system_modules/auth/README.md deleted file mode 100644 index dd70b60481..0000000000 --- a/radix-engine/src/system/system_modules/auth/README.md +++ /dev/null @@ -1,37 +0,0 @@ -# Auth Module - -Unlike the majority of blockchains which rely on a caller identifier for auth, the Auth Module -uses a more distributed "Proof" system. Before accessing a protected method a caller must provide -specific "Proofs" of resources they have access to. These proofs must then match the required proofs -defined by protected method or function of the callee. - -## AuthZone - -To call a protected method, the caller must place these proofs into their [AuthZone](../../../blueprints/resource/auth_zone), -a space dedicated for using proofs for the purpose of authorized method access. On method call, the Auth Module -then checks the caller's AuthZone and compares it to the rules specified by the Callee. - -These rules are specified by the Callee on Object instantiation and are defined by using a mixture of **Role-Based -Access Control** (RBAC) and **Attribute-Based Access Control** (ABAC) techniques. - -## Role Assignment - -On the callee side, instead of roles being assigned to a "user" (of which there is no concept in our decentralized -ledger), roles are assigned through resource ownership. For example, a "Staff" role could be assigned to anyone who -can show proof that they own a "Staff" resource token. This is defined at the callee's Object instantiation -through the [RoleAssignment](../../attached_modules/role_assignment) object module. - -## Role Definition - -All roles for a given object are defined (though not assigned!) at the Blueprint level by the Package creator. This -includes definitions regarding which methods a given role is given access to. - -## Authorization - -On rule check time, the AuthModule checks the proofs on the caller's AuthZone and determines which roles for this -object the caller has. If any of these roles match the list of roles assigned to the method, the caller is then -authorized to make the call. - -Unlike traditional RBAC where the role a user is acting is explicit, in this model roles are more implicit and -defined on what proofs the user has in their AuthZone. This makes it a cross between the well-known RBAC and -ABAC models. From 2098f320db701ba0e5564dde9d53bef2db4195dc Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Wed, 24 Apr 2024 10:51:56 -0500 Subject: [PATCH 10/47] Add more documentation --- radix-blueprint-schema-init/src/lib.rs | 9 ++++++- .../src/blueprints/package/invocations.rs | 18 +++++++++++++ radix-engine/docs/SUMMARY.md | 23 ++++++++-------- radix-engine/docs/architecture/layers.md | 14 +++++----- .../docs/architecture/layers/application.md | 7 ----- .../architecture/layers/application/README.md | 7 +++++ .../application/blueprint_definition.md | 27 +++++++++++++++++++ .../layers/application/blueprint_schema.md | 13 +++++++++ .../layers/application/wasm_environment.md | 23 ++++++++++++++-- .../docs/native/access_control/README.md | 4 +-- radix-engine/src/kernel/kernel.rs | 1 - .../src/system/system_callback_api.rs | 3 +-- scrypto/src/engine/wasm_api.rs | 5 +++- 13 files changed, 120 insertions(+), 34 deletions(-) delete mode 100644 radix-engine/docs/architecture/layers/application.md create mode 100644 radix-engine/docs/architecture/layers/application/README.md create mode 100644 radix-engine/docs/architecture/layers/application/blueprint_definition.md create mode 100644 radix-engine/docs/architecture/layers/application/blueprint_schema.md diff --git a/radix-blueprint-schema-init/src/lib.rs b/radix-blueprint-schema-init/src/lib.rs index db74908143..f40c5ed624 100644 --- a/radix-blueprint-schema-init/src/lib.rs +++ b/radix-blueprint-schema-init/src/lib.rs @@ -29,13 +29,20 @@ pub enum BlueprintHook { #[derive(Debug, Clone, PartialEq, Eq, ScryptoSbor, ManifestSbor)] pub struct BlueprintSchemaInit { + /// List of generic parameters which must be provided on component instantiation and the bounds of these generics pub generics: Vec, + /// Sbor schema which describes types by index pub schema: VersionedScryptoSchema, + /// Describes schema of state by mapping fields/collection indices as a generic or directly into the Sbor schema pub state: BlueprintStateSchemaInit, + /// Describes schema of events by mapping event names as a generic or directly into the Sbor schema pub events: BlueprintEventSchemaInit, - /// Registered types for generic substitution + /// Describes schema of types by mapping types names directly into the Sbor schema + /// These types are used for external generic substitution pub types: BlueprintTypeSchemaInit, + /// Describes interface of function by mapping function names to input/output schema and the code exported function name it maps to pub functions: BlueprintFunctionsSchemaInit, + /// Maps hooks to a code exported function name pub hooks: BlueprintHooksInit, } diff --git a/radix-engine-interface/src/blueprints/package/invocations.rs b/radix-engine-interface/src/blueprints/package/invocations.rs index 57915b3061..190ee6be83 100644 --- a/radix-engine-interface/src/blueprints/package/invocations.rs +++ b/radix-engine-interface/src/blueprints/package/invocations.rs @@ -89,11 +89,15 @@ pub struct PackageClaimRoyaltiesInput {} pub type PackageClaimRoyaltiesOutput = Bucket; +/// The set of blueprints and their associated definitions for a package #[derive(Debug, Clone, Eq, PartialEq, Default, ScryptoSbor, ManifestSbor)] pub struct PackageDefinition { pub blueprints: IndexMap, } +/// A blueprint may be specified as either an Outer or Inner Blueprint. If an inner blueprint, an associated outer +/// blueprint must be specified and only a component of the outer blueprint may instantiate the inner blueprint. +/// Inner blueprint components may access the state of its outer blueprint component directly. #[derive(Debug, Clone, Eq, PartialEq, ScryptoSbor, ManifestSbor)] pub enum BlueprintType { Outer, @@ -106,14 +110,28 @@ impl Default for BlueprintType { } } +/// Structure which defines static interface qualities of a Blueprint #[derive(Debug, Clone, Eq, PartialEq, ScryptoSbor, ManifestSbor)] pub struct BlueprintDefinitionInit { + /// Whether the blueprint is an Outer or Inner Blueprint pub blueprint_type: BlueprintType, + + /// If true, all components of this blueprint type may not be persisted. pub is_transient: bool, + + /// The set of all possible features a component instantiator may specify. pub feature_set: IndexSet, + + /// A set of addresses which will always be visible to call frames of this blueprint. pub dependencies: IndexSet, + + /// The schema of the blueprint including interface, state, and events pub schema: BlueprintSchemaInit, + + /// Blueprint module: Royalty configuration pub royalty_config: PackageRoyaltyConfig, + + /// Blueprint module: Auth configuration such as role definitions pub auth_config: AuthConfig, } diff --git a/radix-engine/docs/SUMMARY.md b/radix-engine/docs/SUMMARY.md index 04d08aa25f..e730fbd7f1 100644 --- a/radix-engine/docs/SUMMARY.md +++ b/radix-engine/docs/SUMMARY.md @@ -5,15 +5,17 @@ # Architecture - [Layered Architecture](architecture/layers.md) - - [Application Layer](architecture/layers/application.md) - - [WASM environment](architecture/layers/application/wasm_environment.md) - - Native environment (TODO) - - Blueprint Definition (TODO) + - [Application Layer](architecture/layers/application/README) + - [Blueprint Definition](architecture/layers/application/blueprint_definition.md) + - [Blueprint Schema](architecture/layers/application/blueprint_schema.md) + - [WASM Environment](architecture/layers/application/wasm_environment.md) - [VM Layer](architecture/layers/vm.md) - [System Layer](architecture/layers/system.md) + - Type System (TODO) - System Modules (TODO) - Object Modules (TODO) - [Kernel Layer](architecture/layers/kernel.md) + - Move/Borrow Checking (TODO) - [Database Layer](architecture/layers/database.md) - Data Architecture (TODO) - Substates / SBOR (TODO) @@ -25,20 +27,19 @@ - Runtime (TODO) - System Calls (TODO) - Invocations (TODO) - - Move/Borrow Checking (TODO) - [Shutdown](execution/shutdown.md) -- Bootstrapping (TODO) +- Substate Flashing (TODO) +- Genesis Bootstrap (TODO) - Protocol Updates (TODO) # Native Systems -- Transaction Manifest -- Type System -- Resources - [Access Control](native/access_control/README) - [Role Definition](native/access_control/role_definition.md) - [Role Assignment](native/access_control/role_assignment.md) - [Auth Zone](native/access_control/authzone.md) - [Authorization](native/access_control/authorization.md) -- Royalties -- Metadata +- Transaction Manifest (TODO) +- Resources (TODO) +- Royalties (TODO) +- Metadata (TODO) diff --git a/radix-engine/docs/architecture/layers.md b/radix-engine/docs/architecture/layers.md index a931d3be19..e8e45e1db2 100644 --- a/radix-engine/docs/architecture/layers.md +++ b/radix-engine/docs/architecture/layers.md @@ -4,11 +4,11 @@ Radix Engine is organized into 5 layers. Each layer has specific responsibilitie provides an API to the layer above. Middle layers also provide a Callback API which the layer above must implement. -| Layer Name | Layer ID | Responsibilities | API | Callback API | Implementation | -|-------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| -| Application | 5 | Defines Types and Application Logic | | | [Native Blueprints](src/blueprints)
[Scrypto Blueprints](../radix-engine-tests/tests/blueprints) | -| VM | 4 | Interprets Application Code | [Scrypto VM API](../scrypto/src/engine/scrypto_env.rs) | | [VM](src/vm) | -| System | 3 | Responsible for:
- Type Checking
- Package/Blueprint/Object abstractions
- Defining Universal Standards (e.g. Authorization, Versioning) | [Object API](../radix-engine-interface/src/api/object_api.rs)
[Blueprint API](../radix-engine-interface/src/api/blueprint_api.rs)
[Costing API](../radix-engine-interface/src/api/costing_api.rs) | [System Callback API](src/system/system_callback_api.rs) | [System](src/system) | -| Kernel | 2 | Responsible for:
- Call Frame Message Passing
- Ownership/Reference handling
- State Virtualization Mechanism | [Kernel API](src/kernel/kernel_api.rs) | [Kernel Callback API](src/kernel/kernel_callback_api.rs) | [Kernel](src/kernel) | -| Database | 1 | Interacts with a Read-Only Database | [Substate Database](../radix-substate-store-interface/src/interface.rs) | | [InMemoryDB](../radix-substate-store-impls/src/memory_db.rs)
[RocksDB](../radix-substate-store-impls/src/rocks_db.rs) | +| Layer Name | Layer ID | Responsibilities | API | Callback API | Implementation | +|-------------|----------|---------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| +| Application | 5 | Defines Types and Application Logic | | | [Native Blueprints](src/blueprints)
[Scrypto Blueprints](../radix-engine-tests/tests/blueprints) | +| VM | 4 | Interprets Application Code | [Scrypto VM API](../scrypto/src/engine/scrypto_env.rs) | | [VM](src/vm) | +| System | 3 | Type Checks
Defines Package/Blueprint/Object abstractions
Defines System Standards (e.g. Authorization, Versioning) | [Object API](../radix-engine-interface/src/api/object_api.rs)
[Blueprint API](../radix-engine-interface/src/api/blueprint_api.rs)
[Costing API](../radix-engine-interface/src/api/costing_api.rs) | [System Callback API](src/system/system_callback_api.rs) | [System](src/system) | +| Kernel | 2 | Maintains Call Frame Stack
Manages Ownership/Reference handling invariants
Provides State Virtualization Mechanism | [Kernel API](src/kernel/kernel_api.rs) | [Kernel Callback API](src/kernel/kernel_callback_api.rs) | [Kernel](src/kernel) | +| Database | 1 | Interacts with a Read-Only Database | [Substate Database](../radix-substate-store-interface/src/interface.rs) | | [InMemoryDB](../radix-substate-store-impls/src/memory_db.rs)
[RocksDB](../radix-substate-store-impls/src/rocks_db.rs) | diff --git a/radix-engine/docs/architecture/layers/application.md b/radix-engine/docs/architecture/layers/application.md deleted file mode 100644 index 99c181ce6f..0000000000 --- a/radix-engine/docs/architecture/layers/application.md +++ /dev/null @@ -1,7 +0,0 @@ -# Application Layer - -Applications in Radix Engine are responsible for defining two things: -1. New Blueprint Definitions -2. Associated Logic with each Blueprint - -These are bundled up in a format called a Package. diff --git a/radix-engine/docs/architecture/layers/application/README.md b/radix-engine/docs/architecture/layers/application/README.md new file mode 100644 index 0000000000..27cf875af8 --- /dev/null +++ b/radix-engine/docs/architecture/layers/application/README.md @@ -0,0 +1,7 @@ +# Application Layer + +Applications in Radix Engine are responsible for defining two things: +1. New Blueprint Definitions. This includes static information about blueprints such as the schema of a blueprint. +2. Associated Logic for each Blueprint function/method. This may be described as WASM bytecode or Native binary code (though native code can only be used by native packages). + +These are bundled up in a format called a Package. diff --git a/radix-engine/docs/architecture/layers/application/blueprint_definition.md b/radix-engine/docs/architecture/layers/application/blueprint_definition.md new file mode 100644 index 0000000000..37ec6c13c0 --- /dev/null +++ b/radix-engine/docs/architecture/layers/application/blueprint_definition.md @@ -0,0 +1,27 @@ +# Blueprint Definition + +A Blueprint Definition defines the static interface qualities of a Blueprint such as function signatures. + +The structure used to initialize the definition is `BlueprintDefinitionInit` found in [invocations.rs](../../../../../radix-engine-interface/src/blueprints/package/invocations.rs): + +``` +pub struct BlueprintDefinitionInit { + pub blueprint_type: BlueprintType, + pub is_transient: bool, + pub feature_set: IndexSet, + pub dependencies: IndexSet, + pub schema: BlueprintSchemaInit, + pub royalty_config: PackageRoyaltyConfig, + pub auth_config: AuthConfig, +} +``` + +| Name | Description | +|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Blueprint Type | A blueprint may be specified as either an Outer or Inner Blueprint. If an inner blueprint, an associated outer blueprint must be specified. Inner blueprint components may access the state of its outer blueprint component directly.

*Inner Blueprints are currently only available for use by native packages.* | +| Transience | If a blueprint is specified to be transient, all components of this blueprint type may not be persisted.

*Transience is currently only available for use by native packages.* | +| Feature Set | Features provide a mechanism to express conditional execution and stored state. The feature set is the set of all possible features a component instantiator may specify.

*A non-empty Feature Set is currently only available for use by native packages.* | +| Dependencies | The set of all addresses which will always be visible to the call frames of this blueprint. | +| Blueprint Schema | The schema of the blueprint including generics, interface, state, and events. | +| Royalty Config | Royalty configuration for this blueprint. | +| Auth Config | Auth configuration such as role definitions for this blueprint. | diff --git a/radix-engine/docs/architecture/layers/application/blueprint_schema.md b/radix-engine/docs/architecture/layers/application/blueprint_schema.md new file mode 100644 index 0000000000..775d366106 --- /dev/null +++ b/radix-engine/docs/architecture/layers/application/blueprint_schema.md @@ -0,0 +1,13 @@ +# Blueprint Schema + +## Generics + +## State Schema + +## Event Schema + +## Function Schema + +## Type Schema + +## Hooks diff --git a/radix-engine/docs/architecture/layers/application/wasm_environment.md b/radix-engine/docs/architecture/layers/application/wasm_environment.md index 5ec879456e..f65fdcc832 100644 --- a/radix-engine/docs/architecture/layers/application/wasm_environment.md +++ b/radix-engine/docs/architecture/layers/application/wasm_environment.md @@ -1,5 +1,24 @@ # WASM Environment -## Syscalls +## Function Entrypoint -[System calls](../../../../../scrypto/src/engine/wasm_api.rs) \ No newline at end of file +An exported function in WASM may be called if it is mapped via `export_name` in a function of a Blueprint Definition. +The argument to the function is a single `i64` which represents a buffer. The first 32 bits refers to a `BufferId` +and the second 32 bits refers to the length of the buffer. + +Once sufficient space has been allocated for the buffer, the contents of the buffer can be retrieved by using +the `buffer_consume` call. The contents of the buffer will match the sbor schema described in the function +schema of the Blueprint Definition. + +## System Calls + +Various `extern` functions are available to be called during execution. These are referred to as `system calls` +and provide the ability to read/write state, invoke methods and functions, and other system-related logic. + +The full set of calls can be found in [wasm_api.rs](../../../../../scrypto/src/engine/wasm_api.rs). + +## Function Return + +The return value from a called exported function in WASM must be an `i64` where the first 32 bits refers to the +32-bit address pointer and the second 32 bits refers to the size of the return object. The contents of the buffer +must match the return value schema of the function in the Blueprint Definition. diff --git a/radix-engine/docs/native/access_control/README.md b/radix-engine/docs/native/access_control/README.md index 081db345e6..bea80644bb 100644 --- a/radix-engine/docs/native/access_control/README.md +++ b/radix-engine/docs/native/access_control/README.md @@ -7,10 +7,10 @@ defined by protected method or function of the callee. The Access Control System is composed of four parts: -1. A Package Module, which defines roles available to use for a given blueprint in a package +1. A Blueprint Module, which defines roles available to use for a given blueprint in a package 2. An Object Module, which provides role assignment or which resources are required to show proof for a given role 3. A System Module, which maintains an AuthZone, or the current proofs a runtime caller has -3. An AuthZone Blueprint, which allows a caller to update their current proofs +4. An AuthZone Blueprint, which allows a caller to update their current proofs These three modules allow a package creator to define roles which a component creator can assign definitions to, which a caller must show proof for by updating their AuthZone. diff --git a/radix-engine/src/kernel/kernel.rs b/radix-engine/src/kernel/kernel.rs index d62ce197d0..a6d2a3db2a 100644 --- a/radix-engine/src/kernel/kernel.rs +++ b/radix-engine/src/kernel/kernel.rs @@ -39,7 +39,6 @@ pub struct BootLoader<'h, M: KernelCallbackObject, S: SubstateDatabase> { } impl<'h, M: KernelCallbackObject, S: SubstateDatabase> BootLoader<'h, M, S> { - /// Checks that references exist in the store fn check_references( &mut self, diff --git a/radix-engine/src/system/system_callback_api.rs b/radix-engine/src/system/system_callback_api.rs index 7f9380a135..ccf137c065 100644 --- a/radix-engine/src/system/system_callback_api.rs +++ b/radix-engine/src/system/system_callback_api.rs @@ -12,8 +12,7 @@ pub trait SystemCallbackObject: Sized { type Init: Clone; /// Initialize and create the callback object above the system - fn init(store: &S, init_input: Self::Init) - -> Result; + fn init(store: &S, init_input: Self::Init) -> Result; /// Invoke a function fn invoke( diff --git a/scrypto/src/engine/wasm_api.rs b/scrypto/src/engine/wasm_api.rs index fda3b0c7dd..620d4b4790 100644 --- a/scrypto/src/engine/wasm_api.rs +++ b/scrypto/src/engine/wasm_api.rs @@ -176,6 +176,7 @@ pub mod actor { } } +/// API to create or modify Key Value stores pub mod kv_store { pub use radix_engine_interface::types::{Buffer, BufferId, Slice}; @@ -237,6 +238,7 @@ pub mod field_entry { } } +/// API to retrieve info about current costing state pub mod costing { pub use radix_engine_interface::types::{Buffer, BufferId, Slice}; @@ -284,7 +286,7 @@ pub mod system { } } -/// Various environment-based API calls +/// Api to execute various crypto functions pub mod crypto_utils { pub use radix_engine_interface::types::{Buffer, BufferId, Slice}; @@ -321,6 +323,7 @@ pub mod crypto_utils { } } +/// Api for handling buffers pub mod buffer { pub use radix_engine_interface::types::{Buffer, BufferId, Slice}; From b15b8ae3ee4d7bb34962c71a5f0c455bd64b96f5 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Wed, 24 Apr 2024 14:46:19 -0500 Subject: [PATCH 11/47] Add more docs --- radix-blueprint-schema-init/src/lib.rs | 7 +++++++ radix-engine/docs/SUMMARY.md | 15 +++++++++++---- .../architecture/layers/application/README.md | 16 ++++++++++++---- .../layers/application/blueprint_definition.md | 8 ++++++-- .../layers/application/blueprint_schema.md | 13 ------------- .../architecture/layers/application/functions.md | 1 + .../architecture/layers/application/state.md | 13 +++++++++++++ 7 files changed, 50 insertions(+), 23 deletions(-) delete mode 100644 radix-engine/docs/architecture/layers/application/blueprint_schema.md create mode 100644 radix-engine/docs/architecture/layers/application/functions.md create mode 100644 radix-engine/docs/architecture/layers/application/state.md diff --git a/radix-blueprint-schema-init/src/lib.rs b/radix-blueprint-schema-init/src/lib.rs index d4e9e01831..f129750694 100644 --- a/radix-blueprint-schema-init/src/lib.rs +++ b/radix-blueprint-schema-init/src/lib.rs @@ -27,6 +27,7 @@ pub enum BlueprintHook { OnDrop, } +/// An initialization object which describes a blueprint's schema including interface, state, and events #[derive(Debug, Clone, PartialEq, Eq, ScryptoSbor, ManifestSbor)] pub struct BlueprintSchemaInit { /// List of generic parameters which must be provided on component instantiation and the bounds of these generics @@ -65,6 +66,8 @@ impl Default for BlueprintSchemaInit { } } +/// Describes the number of fields and collections some Blueprint has as well +/// as the schema and properties of each field and collection #[derive(Debug, Clone, PartialEq, Eq, Default, ScryptoSbor, ManifestSbor)] pub struct BlueprintStateSchemaInit { pub fields: Vec>>, @@ -164,6 +167,7 @@ pub trait BlueprintFeature { fn feature_name(&self) -> &'static str; } +/// Expresses a condition based on features enabled on a component #[derive(Debug, Clone, PartialEq, Eq, Sbor)] pub enum Condition { Always, @@ -191,10 +195,13 @@ pub enum FieldTransience { }, } +/// Describes a field for a Blueprint #[derive(Debug, Clone, PartialEq, Eq, ScryptoSbor, ManifestSbor)] pub struct FieldSchema { pub field: V, + /// Condition for this field to exist pub condition: Condition, + /// Describes if this field should be persisted pub transience: FieldTransience, } diff --git a/radix-engine/docs/SUMMARY.md b/radix-engine/docs/SUMMARY.md index e730fbd7f1..ec7f0631cb 100644 --- a/radix-engine/docs/SUMMARY.md +++ b/radix-engine/docs/SUMMARY.md @@ -7,11 +7,18 @@ - [Layered Architecture](architecture/layers.md) - [Application Layer](architecture/layers/application/README) - [Blueprint Definition](architecture/layers/application/blueprint_definition.md) - - [Blueprint Schema](architecture/layers/application/blueprint_schema.md) + - Inner vs. Outer Blueprint + - Transience + - Features + - Generics + - [State](architecture/layers/application/state.md) + - Events (TODO) + - [Functions](architecture/layers/application/functions.md) + - Types (TODO) - [WASM Environment](architecture/layers/application/wasm_environment.md) + - Type System (TODO) - [VM Layer](architecture/layers/vm.md) - [System Layer](architecture/layers/system.md) - - Type System (TODO) - System Modules (TODO) - Object Modules (TODO) - [Kernel Layer](architecture/layers/kernel.md) @@ -34,11 +41,11 @@ # Native Systems -- [Access Control](native/access_control/README) +- [Authorization](native/access_control/README) - [Role Definition](native/access_control/role_definition.md) - [Role Assignment](native/access_control/role_assignment.md) - [Auth Zone](native/access_control/authzone.md) - - [Authorization](native/access_control/authorization.md) + - [Authorization Flow](native/access_control/authorization.md) - Transaction Manifest (TODO) - Resources (TODO) - Royalties (TODO) diff --git a/radix-engine/docs/architecture/layers/application/README.md b/radix-engine/docs/architecture/layers/application/README.md index 27cf875af8..7aef6a3b0b 100644 --- a/radix-engine/docs/architecture/layers/application/README.md +++ b/radix-engine/docs/architecture/layers/application/README.md @@ -1,7 +1,15 @@ # Application Layer -Applications in Radix Engine are responsible for defining two things: -1. New Blueprint Definitions. This includes static information about blueprints such as the schema of a blueprint. -2. Associated Logic for each Blueprint function/method. This may be described as WASM bytecode or Native binary code (though native code can only be used by native packages). +Applications in Radix Engine are deployed through a format called a Package. +Packages consist of zero or more blueprints each of which are uniquely identified +by string name within a package. A blueprint is globally identifiable by +` + `. + +Each blueprint is defined by its *Blueprint Definition* which includes information such as the function +definition and state schemas of the Blueprint. Methods/Functions are mapped either to exported WASM +functions in a provided WASM binary or to native binary. + +## Package Deployment + +Deployment of new packages are done through invoking the `publish_wasm` or `publish_wasm_advanced` function. -These are bundled up in a format called a Package. diff --git a/radix-engine/docs/architecture/layers/application/blueprint_definition.md b/radix-engine/docs/architecture/layers/application/blueprint_definition.md index 37ec6c13c0..f44d96ab13 100644 --- a/radix-engine/docs/architecture/layers/application/blueprint_definition.md +++ b/radix-engine/docs/architecture/layers/application/blueprint_definition.md @@ -1,6 +1,6 @@ # Blueprint Definition -A Blueprint Definition defines the static interface qualities of a Blueprint such as function signatures. +A Blueprint Definition defines everything about a Blueprint outside of the code logic itself. The structure used to initialize the definition is `BlueprintDefinitionInit` found in [invocations.rs](../../../../../radix-engine-interface/src/blueprints/package/invocations.rs): @@ -16,7 +16,11 @@ pub struct BlueprintDefinitionInit { } ``` -| Name | Description | +## Properties + +A description of each property is as follows. + +| Property Name | Description | |------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Blueprint Type | A blueprint may be specified as either an Outer or Inner Blueprint. If an inner blueprint, an associated outer blueprint must be specified. Inner blueprint components may access the state of its outer blueprint component directly.

*Inner Blueprints are currently only available for use by native packages.* | | Transience | If a blueprint is specified to be transient, all components of this blueprint type may not be persisted.

*Transience is currently only available for use by native packages.* | diff --git a/radix-engine/docs/architecture/layers/application/blueprint_schema.md b/radix-engine/docs/architecture/layers/application/blueprint_schema.md deleted file mode 100644 index 775d366106..0000000000 --- a/radix-engine/docs/architecture/layers/application/blueprint_schema.md +++ /dev/null @@ -1,13 +0,0 @@ -# Blueprint Schema - -## Generics - -## State Schema - -## Event Schema - -## Function Schema - -## Type Schema - -## Hooks diff --git a/radix-engine/docs/architecture/layers/application/functions.md b/radix-engine/docs/architecture/layers/application/functions.md new file mode 100644 index 0000000000..b226316972 --- /dev/null +++ b/radix-engine/docs/architecture/layers/application/functions.md @@ -0,0 +1 @@ +# Features \ No newline at end of file diff --git a/radix-engine/docs/architecture/layers/application/state.md b/radix-engine/docs/architecture/layers/application/state.md new file mode 100644 index 0000000000..8507cb63d6 --- /dev/null +++ b/radix-engine/docs/architecture/layers/application/state.md @@ -0,0 +1,13 @@ +# Blueprint State Schema + +A blueprint's state schema describes the number of fields and collections that exist in a blueprint. +Each field and collection are identified by field index and collection index. + +## Fields + +### Field Conditions + +### Field Transience + +## Collections + From e9128c3a57ba558c487fbacb1139886200c68487 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Wed, 24 Apr 2024 15:09:21 -0500 Subject: [PATCH 12/47] Update to use mddoc structure --- radix-engine/book/.gitignore | 1 + radix-engine/book/book.toml | 6 ++ radix-engine/{docs => book/src}/README.md | 0 radix-engine/book/src/SUMMARY.md | 52 ++++++++++++++++++ radix-engine/book/src/architecture/layers.md | 14 +++++ .../architecture/layers/application/README | 1 + .../architecture/layers/application/README.md | 0 .../application/blueprint_definition.md | 0 .../layers/application/functions.md | 0 .../architecture/layers/application/state.md | 0 .../layers/application/wasm_environment.md | 0 .../src}/architecture/layers/database.md | 0 .../src}/architecture/layers/kernel.md | 0 .../src}/architecture/layers/system.md | 0 .../src}/architecture/layers/vm.md | 0 .../src}/execution/bootup.drawio.png | Bin .../{docs => book/src}/execution/bootup.md | 0 .../{docs => book/src}/execution/lifecycle.md | 0 .../{docs => book/src}/execution/shutdown.md | 0 .../book/src/native/access_control/README | 1 + .../src}/native/access_control/README.md | 0 .../native/access_control/authorization.md | 0 .../src}/native/access_control/authzone.md | 0 .../native/access_control/role_assignment.md | 0 .../native/access_control/role_definition.md | 0 radix-engine/docs/SUMMARY.md | 52 ------------------ radix-engine/docs/architecture/layers.md | 14 ----- 27 files changed, 75 insertions(+), 66 deletions(-) create mode 100644 radix-engine/book/.gitignore create mode 100644 radix-engine/book/book.toml rename radix-engine/{docs => book/src}/README.md (100%) create mode 100644 radix-engine/book/src/SUMMARY.md create mode 100644 radix-engine/book/src/architecture/layers.md create mode 100644 radix-engine/book/src/architecture/layers/application/README rename radix-engine/{docs => book/src}/architecture/layers/application/README.md (100%) rename radix-engine/{docs => book/src}/architecture/layers/application/blueprint_definition.md (100%) rename radix-engine/{docs => book/src}/architecture/layers/application/functions.md (100%) rename radix-engine/{docs => book/src}/architecture/layers/application/state.md (100%) rename radix-engine/{docs => book/src}/architecture/layers/application/wasm_environment.md (100%) rename radix-engine/{docs => book/src}/architecture/layers/database.md (100%) rename radix-engine/{docs => book/src}/architecture/layers/kernel.md (100%) rename radix-engine/{docs => book/src}/architecture/layers/system.md (100%) rename radix-engine/{docs => book/src}/architecture/layers/vm.md (100%) rename radix-engine/{docs => book/src}/execution/bootup.drawio.png (100%) rename radix-engine/{docs => book/src}/execution/bootup.md (100%) rename radix-engine/{docs => book/src}/execution/lifecycle.md (100%) rename radix-engine/{docs => book/src}/execution/shutdown.md (100%) create mode 100644 radix-engine/book/src/native/access_control/README rename radix-engine/{docs => book/src}/native/access_control/README.md (100%) rename radix-engine/{docs => book/src}/native/access_control/authorization.md (100%) rename radix-engine/{docs => book/src}/native/access_control/authzone.md (100%) rename radix-engine/{docs => book/src}/native/access_control/role_assignment.md (100%) rename radix-engine/{docs => book/src}/native/access_control/role_definition.md (100%) delete mode 100644 radix-engine/docs/SUMMARY.md delete mode 100644 radix-engine/docs/architecture/layers.md diff --git a/radix-engine/book/.gitignore b/radix-engine/book/.gitignore new file mode 100644 index 0000000000..7585238efe --- /dev/null +++ b/radix-engine/book/.gitignore @@ -0,0 +1 @@ +book diff --git a/radix-engine/book/book.toml b/radix-engine/book/book.toml new file mode 100644 index 0000000000..308b658d27 --- /dev/null +++ b/radix-engine/book/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["Joshua Primero"] +language = "en" +multilingual = false +src = "src" +title = "Radix Engine" diff --git a/radix-engine/docs/README.md b/radix-engine/book/src/README.md similarity index 100% rename from radix-engine/docs/README.md rename to radix-engine/book/src/README.md diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md new file mode 100644 index 0000000000..e10b683278 --- /dev/null +++ b/radix-engine/book/src/SUMMARY.md @@ -0,0 +1,52 @@ +# Radix Engine + +[Introduction](README.md) + +# Architecture + +- [Layered Architecture](architecture/layers.md) +- [Application Layer](architecture/layers/application/README.md) + - [Blueprint Definition](architecture/layers/application/blueprint_definition.md) + - [Inner vs. Outer Blueprint]() + - [Transience]() + - [Features]() + - [Generics]() + - [State](architecture/layers/application/state.md) + - [Events]() + - [Functions](architecture/layers/application/functions.md) + - [Types]() + - [WASM Environment](architecture/layers/application/wasm_environment.md) + - [Type System]() +- [VM Layer](architecture/layers/vm.md) +- [System Layer](architecture/layers/system.md) + - [System Modules]() + - [Object Modules]() +- [Kernel Layer](architecture/layers/kernel.md) + - [Move/Borrow Checking]() +- [Database Layer](architecture/layers/database.md) +- [Data Architecture]() + - [Substates / SBOR]() + +# Execution + +- [Transaction Lifecycle](execution/lifecycle.md) + - [Bootup](execution/bootup.md) + - [Runtime]() + - [System Calls]() + - [Invocations]() + - [Shutdown](execution/shutdown.md) +- [Substate Flashing]() +- [Genesis Bootstrap]() +- [Protocol Updates]() + +# Native Systems + +- [Authorization](native/access_control/README) + - [Role Definition](native/access_control/role_definition.md) + - [Role Assignment](native/access_control/role_assignment.md) + - [Auth Zone](native/access_control/authzone.md) + - [Authorization Flow](native/access_control/authorization.md) +- [Transaction Manifest]() +- [Resources]() +- [Royalties]() +- [Metadata]() diff --git a/radix-engine/book/src/architecture/layers.md b/radix-engine/book/src/architecture/layers.md new file mode 100644 index 0000000000..c5c80f9f89 --- /dev/null +++ b/radix-engine/book/src/architecture/layers.md @@ -0,0 +1,14 @@ +# Architecture + +Radix Engine is organized into 5 layers. Each layer has specific responsibilities and +provides an API to the layer above. Middle layers also provide a Callback API which the +layer above must implement. + +| Layer Name | Layer ID | Responsibilities | +|-------------|----------|---------------------------------------------------------------------------------------------------------------------------| +| Application | 5 | Defines Types and Application Logic | +| VM | 4 | Interprets Application Code | +| System | 3 | Type Checks
Defines Package/Blueprint/Object abstractions
Defines System Standards (e.g. Authorization, Versioning) | +| Kernel | 2 | Maintains Call Frame Stack
Manages Ownership/Reference handling invariants
Provides State Virtualization Mechanism | +| Database | 1 | Interacts with a Read-Only Database | + diff --git a/radix-engine/book/src/architecture/layers/application/README b/radix-engine/book/src/architecture/layers/application/README new file mode 100644 index 0000000000..ac187d0887 --- /dev/null +++ b/radix-engine/book/src/architecture/layers/application/README @@ -0,0 +1 @@ +# Application Layer diff --git a/radix-engine/docs/architecture/layers/application/README.md b/radix-engine/book/src/architecture/layers/application/README.md similarity index 100% rename from radix-engine/docs/architecture/layers/application/README.md rename to radix-engine/book/src/architecture/layers/application/README.md diff --git a/radix-engine/docs/architecture/layers/application/blueprint_definition.md b/radix-engine/book/src/architecture/layers/application/blueprint_definition.md similarity index 100% rename from radix-engine/docs/architecture/layers/application/blueprint_definition.md rename to radix-engine/book/src/architecture/layers/application/blueprint_definition.md diff --git a/radix-engine/docs/architecture/layers/application/functions.md b/radix-engine/book/src/architecture/layers/application/functions.md similarity index 100% rename from radix-engine/docs/architecture/layers/application/functions.md rename to radix-engine/book/src/architecture/layers/application/functions.md diff --git a/radix-engine/docs/architecture/layers/application/state.md b/radix-engine/book/src/architecture/layers/application/state.md similarity index 100% rename from radix-engine/docs/architecture/layers/application/state.md rename to radix-engine/book/src/architecture/layers/application/state.md diff --git a/radix-engine/docs/architecture/layers/application/wasm_environment.md b/radix-engine/book/src/architecture/layers/application/wasm_environment.md similarity index 100% rename from radix-engine/docs/architecture/layers/application/wasm_environment.md rename to radix-engine/book/src/architecture/layers/application/wasm_environment.md diff --git a/radix-engine/docs/architecture/layers/database.md b/radix-engine/book/src/architecture/layers/database.md similarity index 100% rename from radix-engine/docs/architecture/layers/database.md rename to radix-engine/book/src/architecture/layers/database.md diff --git a/radix-engine/docs/architecture/layers/kernel.md b/radix-engine/book/src/architecture/layers/kernel.md similarity index 100% rename from radix-engine/docs/architecture/layers/kernel.md rename to radix-engine/book/src/architecture/layers/kernel.md diff --git a/radix-engine/docs/architecture/layers/system.md b/radix-engine/book/src/architecture/layers/system.md similarity index 100% rename from radix-engine/docs/architecture/layers/system.md rename to radix-engine/book/src/architecture/layers/system.md diff --git a/radix-engine/docs/architecture/layers/vm.md b/radix-engine/book/src/architecture/layers/vm.md similarity index 100% rename from radix-engine/docs/architecture/layers/vm.md rename to radix-engine/book/src/architecture/layers/vm.md diff --git a/radix-engine/docs/execution/bootup.drawio.png b/radix-engine/book/src/execution/bootup.drawio.png similarity index 100% rename from radix-engine/docs/execution/bootup.drawio.png rename to radix-engine/book/src/execution/bootup.drawio.png diff --git a/radix-engine/docs/execution/bootup.md b/radix-engine/book/src/execution/bootup.md similarity index 100% rename from radix-engine/docs/execution/bootup.md rename to radix-engine/book/src/execution/bootup.md diff --git a/radix-engine/docs/execution/lifecycle.md b/radix-engine/book/src/execution/lifecycle.md similarity index 100% rename from radix-engine/docs/execution/lifecycle.md rename to radix-engine/book/src/execution/lifecycle.md diff --git a/radix-engine/docs/execution/shutdown.md b/radix-engine/book/src/execution/shutdown.md similarity index 100% rename from radix-engine/docs/execution/shutdown.md rename to radix-engine/book/src/execution/shutdown.md diff --git a/radix-engine/book/src/native/access_control/README b/radix-engine/book/src/native/access_control/README new file mode 100644 index 0000000000..17257a2e81 --- /dev/null +++ b/radix-engine/book/src/native/access_control/README @@ -0,0 +1 @@ +# Authorization diff --git a/radix-engine/docs/native/access_control/README.md b/radix-engine/book/src/native/access_control/README.md similarity index 100% rename from radix-engine/docs/native/access_control/README.md rename to radix-engine/book/src/native/access_control/README.md diff --git a/radix-engine/docs/native/access_control/authorization.md b/radix-engine/book/src/native/access_control/authorization.md similarity index 100% rename from radix-engine/docs/native/access_control/authorization.md rename to radix-engine/book/src/native/access_control/authorization.md diff --git a/radix-engine/docs/native/access_control/authzone.md b/radix-engine/book/src/native/access_control/authzone.md similarity index 100% rename from radix-engine/docs/native/access_control/authzone.md rename to radix-engine/book/src/native/access_control/authzone.md diff --git a/radix-engine/docs/native/access_control/role_assignment.md b/radix-engine/book/src/native/access_control/role_assignment.md similarity index 100% rename from radix-engine/docs/native/access_control/role_assignment.md rename to radix-engine/book/src/native/access_control/role_assignment.md diff --git a/radix-engine/docs/native/access_control/role_definition.md b/radix-engine/book/src/native/access_control/role_definition.md similarity index 100% rename from radix-engine/docs/native/access_control/role_definition.md rename to radix-engine/book/src/native/access_control/role_definition.md diff --git a/radix-engine/docs/SUMMARY.md b/radix-engine/docs/SUMMARY.md deleted file mode 100644 index ec7f0631cb..0000000000 --- a/radix-engine/docs/SUMMARY.md +++ /dev/null @@ -1,52 +0,0 @@ -# Radix Engine - -[Overview](README.md) - -# Architecture - -- [Layered Architecture](architecture/layers.md) - - [Application Layer](architecture/layers/application/README) - - [Blueprint Definition](architecture/layers/application/blueprint_definition.md) - - Inner vs. Outer Blueprint - - Transience - - Features - - Generics - - [State](architecture/layers/application/state.md) - - Events (TODO) - - [Functions](architecture/layers/application/functions.md) - - Types (TODO) - - [WASM Environment](architecture/layers/application/wasm_environment.md) - - Type System (TODO) - - [VM Layer](architecture/layers/vm.md) - - [System Layer](architecture/layers/system.md) - - System Modules (TODO) - - Object Modules (TODO) - - [Kernel Layer](architecture/layers/kernel.md) - - Move/Borrow Checking (TODO) - - [Database Layer](architecture/layers/database.md) -- Data Architecture (TODO) - - Substates / SBOR (TODO) - -# Execution - -- [Transaction Lifecycle](execution/lifecycle.md) - - [Bootup](execution/bootup.md) - - Runtime (TODO) - - System Calls (TODO) - - Invocations (TODO) - - [Shutdown](execution/shutdown.md) -- Substate Flashing (TODO) -- Genesis Bootstrap (TODO) -- Protocol Updates (TODO) - -# Native Systems - -- [Authorization](native/access_control/README) - - [Role Definition](native/access_control/role_definition.md) - - [Role Assignment](native/access_control/role_assignment.md) - - [Auth Zone](native/access_control/authzone.md) - - [Authorization Flow](native/access_control/authorization.md) -- Transaction Manifest (TODO) -- Resources (TODO) -- Royalties (TODO) -- Metadata (TODO) diff --git a/radix-engine/docs/architecture/layers.md b/radix-engine/docs/architecture/layers.md deleted file mode 100644 index e8e45e1db2..0000000000 --- a/radix-engine/docs/architecture/layers.md +++ /dev/null @@ -1,14 +0,0 @@ -# Architecture - -Radix Engine is organized into 5 layers. Each layer has specific responsibilities and -provides an API to the layer above. Middle layers also provide a Callback API which the -layer above must implement. - -| Layer Name | Layer ID | Responsibilities | API | Callback API | Implementation | -|-------------|----------|---------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| -| Application | 5 | Defines Types and Application Logic | | | [Native Blueprints](src/blueprints)
[Scrypto Blueprints](../radix-engine-tests/tests/blueprints) | -| VM | 4 | Interprets Application Code | [Scrypto VM API](../scrypto/src/engine/scrypto_env.rs) | | [VM](src/vm) | -| System | 3 | Type Checks
Defines Package/Blueprint/Object abstractions
Defines System Standards (e.g. Authorization, Versioning) | [Object API](../radix-engine-interface/src/api/object_api.rs)
[Blueprint API](../radix-engine-interface/src/api/blueprint_api.rs)
[Costing API](../radix-engine-interface/src/api/costing_api.rs) | [System Callback API](src/system/system_callback_api.rs) | [System](src/system) | -| Kernel | 2 | Maintains Call Frame Stack
Manages Ownership/Reference handling invariants
Provides State Virtualization Mechanism | [Kernel API](src/kernel/kernel_api.rs) | [Kernel Callback API](src/kernel/kernel_callback_api.rs) | [Kernel](src/kernel) | -| Database | 1 | Interacts with a Read-Only Database | [Substate Database](../radix-substate-store-interface/src/interface.rs) | | [InMemoryDB](../radix-substate-store-impls/src/memory_db.rs)
[RocksDB](../radix-substate-store-impls/src/rocks_db.rs) | - From 8b280fd23e8f924f886f92a8cc598cb1948ff134 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Thu, 25 Apr 2024 10:48:11 -0500 Subject: [PATCH 13/47] Add inner vs outer blueprint documentation --- radix-engine/book/src/SUMMARY.md | 20 ++++++------ .../src/architecture/application/README.md | 15 +++++++++ .../application/blueprint_definition.md | 31 +++++++++++++++++++ .../src/architecture/application/functions.md | 1 + .../inner_outer_blueprints.drawio.svg | 4 +++ .../inner_outer_objects.drawio.svg | 4 +++ .../application/inner_vs_outer.md | 14 +++++++++ .../src/architecture/application/state.md | 13 ++++++++ .../application/wasm_environment.md | 24 ++++++++++++++ .../book/src/architecture/database.md | 1 + radix-engine/book/src/architecture/kernel.md | 8 +++++ .../architecture/layers/application/README | 1 - .../architecture/layers/application/README.md | 14 --------- .../application/blueprint_definition.md | 30 ------------------ .../layers/application/functions.md | 2 +- .../architecture/layers/application/state.md | 14 +-------- .../layers/application/wasm_environment.md | 23 -------------- .../book/src/architecture/layers/database.md | 2 +- .../book/src/architecture/layers/kernel.md | 7 ----- .../book/src/architecture/layers/system.md | 4 --- .../book/src/architecture/layers/vm.md | 3 -- radix-engine/book/src/architecture/system.md | 5 +++ radix-engine/book/src/architecture/vm.md | 4 +++ 23 files changed, 137 insertions(+), 107 deletions(-) create mode 100644 radix-engine/book/src/architecture/application/README.md create mode 100644 radix-engine/book/src/architecture/application/blueprint_definition.md create mode 100644 radix-engine/book/src/architecture/application/functions.md create mode 100644 radix-engine/book/src/architecture/application/inner_outer_blueprints.drawio.svg create mode 100644 radix-engine/book/src/architecture/application/inner_outer_objects.drawio.svg create mode 100644 radix-engine/book/src/architecture/application/inner_vs_outer.md create mode 100644 radix-engine/book/src/architecture/application/state.md create mode 100644 radix-engine/book/src/architecture/application/wasm_environment.md create mode 100644 radix-engine/book/src/architecture/database.md create mode 100644 radix-engine/book/src/architecture/kernel.md delete mode 100644 radix-engine/book/src/architecture/layers/application/README create mode 100644 radix-engine/book/src/architecture/system.md create mode 100644 radix-engine/book/src/architecture/vm.md diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index e10b683278..6cf0b23f69 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -5,25 +5,25 @@ # Architecture - [Layered Architecture](architecture/layers.md) -- [Application Layer](architecture/layers/application/README.md) - - [Blueprint Definition](architecture/layers/application/blueprint_definition.md) - - [Inner vs. Outer Blueprint]() +- [Application Layer](architecture/application/README.md) + - [Blueprint Definition](architecture/application/blueprint_definition.md) + - [Inner vs Outer Blueprints](architecture/application/inner_vs_outer.md) - [Transience]() - [Features]() - [Generics]() - - [State](architecture/layers/application/state.md) + - [State](architecture/application/state.md) - [Events]() - - [Functions](architecture/layers/application/functions.md) + - [Functions](architecture/application/functions.md) - [Types]() - - [WASM Environment](architecture/layers/application/wasm_environment.md) + - [WASM Environment](architecture/application/wasm_environment.md) - [Type System]() -- [VM Layer](architecture/layers/vm.md) -- [System Layer](architecture/layers/system.md) +- [VM Layer](architecture/vm.md) +- [System Layer](architecture/system.md) - [System Modules]() - [Object Modules]() -- [Kernel Layer](architecture/layers/kernel.md) +- [Kernel Layer](architecture/kernel.md) - [Move/Borrow Checking]() -- [Database Layer](architecture/layers/database.md) +- [Database Layer](architecture/database.md) - [Data Architecture]() - [Substates / SBOR]() diff --git a/radix-engine/book/src/architecture/application/README.md b/radix-engine/book/src/architecture/application/README.md new file mode 100644 index 0000000000..7aef6a3b0b --- /dev/null +++ b/radix-engine/book/src/architecture/application/README.md @@ -0,0 +1,15 @@ +# Application Layer + +Applications in Radix Engine are deployed through a format called a Package. +Packages consist of zero or more blueprints each of which are uniquely identified +by string name within a package. A blueprint is globally identifiable by +` + `. + +Each blueprint is defined by its *Blueprint Definition* which includes information such as the function +definition and state schemas of the Blueprint. Methods/Functions are mapped either to exported WASM +functions in a provided WASM binary or to native binary. + +## Package Deployment + +Deployment of new packages are done through invoking the `publish_wasm` or `publish_wasm_advanced` function. + diff --git a/radix-engine/book/src/architecture/application/blueprint_definition.md b/radix-engine/book/src/architecture/application/blueprint_definition.md new file mode 100644 index 0000000000..f44d96ab13 --- /dev/null +++ b/radix-engine/book/src/architecture/application/blueprint_definition.md @@ -0,0 +1,31 @@ +# Blueprint Definition + +A Blueprint Definition defines everything about a Blueprint outside of the code logic itself. + +The structure used to initialize the definition is `BlueprintDefinitionInit` found in [invocations.rs](../../../../../radix-engine-interface/src/blueprints/package/invocations.rs): + +``` +pub struct BlueprintDefinitionInit { + pub blueprint_type: BlueprintType, + pub is_transient: bool, + pub feature_set: IndexSet, + pub dependencies: IndexSet, + pub schema: BlueprintSchemaInit, + pub royalty_config: PackageRoyaltyConfig, + pub auth_config: AuthConfig, +} +``` + +## Properties + +A description of each property is as follows. + +| Property Name | Description | +|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Blueprint Type | A blueprint may be specified as either an Outer or Inner Blueprint. If an inner blueprint, an associated outer blueprint must be specified. Inner blueprint components may access the state of its outer blueprint component directly.

*Inner Blueprints are currently only available for use by native packages.* | +| Transience | If a blueprint is specified to be transient, all components of this blueprint type may not be persisted.

*Transience is currently only available for use by native packages.* | +| Feature Set | Features provide a mechanism to express conditional execution and stored state. The feature set is the set of all possible features a component instantiator may specify.

*A non-empty Feature Set is currently only available for use by native packages.* | +| Dependencies | The set of all addresses which will always be visible to the call frames of this blueprint. | +| Blueprint Schema | The schema of the blueprint including generics, interface, state, and events. | +| Royalty Config | Royalty configuration for this blueprint. | +| Auth Config | Auth configuration such as role definitions for this blueprint. | diff --git a/radix-engine/book/src/architecture/application/functions.md b/radix-engine/book/src/architecture/application/functions.md new file mode 100644 index 0000000000..b226316972 --- /dev/null +++ b/radix-engine/book/src/architecture/application/functions.md @@ -0,0 +1 @@ +# Features \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/inner_outer_blueprints.drawio.svg b/radix-engine/book/src/architecture/application/inner_outer_blueprints.drawio.svg new file mode 100644 index 0000000000..df85075492 --- /dev/null +++ b/radix-engine/book/src/architecture/application/inner_outer_blueprints.drawio.svg @@ -0,0 +1,4 @@ + + + +
Inner Blueprint
Inner Blueprint
Outer Blueprint
Outer Blueprint
Inner Blueprint
Inner Blueprint
Outer Blueprint
Outer Blueprint \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/inner_outer_objects.drawio.svg b/radix-engine/book/src/architecture/application/inner_outer_objects.drawio.svg new file mode 100644 index 0000000000..e4164a3953 --- /dev/null +++ b/radix-engine/book/src/architecture/application/inner_outer_objects.drawio.svg @@ -0,0 +1,4 @@ + + + +
Outer Object
Outer Object
Inner Object
Inner Object
Inner Object
Inner Object
Inner Object
Inner Object
Inner Object
Inner Object
Outer Object
Outer Object
Outer Object
Outer Object
Inner Object
Inner Object \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/inner_vs_outer.md b/radix-engine/book/src/architecture/application/inner_vs_outer.md new file mode 100644 index 0000000000..8adc1b73aa --- /dev/null +++ b/radix-engine/book/src/architecture/application/inner_vs_outer.md @@ -0,0 +1,14 @@ +# Inner vs. Outer Blueprints + +A blueprint may be specified as either an Outer or Inner Blueprint. If an inner blueprint, an associated outer blueprint +(from the same package) must be specified. + +![](inner_outer_blueprints.drawio.svg) + +Inner blueprint objects may only be instantiated by an associated outer blueprint object. After +instantiation, inner blueprint objects may access the state of its outer blueprint component directly +avoiding invocation and new call frame costs. + +![](inner_outer_objects.drawio.svg) + +*Inner Blueprints are currently only available for use by native packages.* diff --git a/radix-engine/book/src/architecture/application/state.md b/radix-engine/book/src/architecture/application/state.md new file mode 100644 index 0000000000..8507cb63d6 --- /dev/null +++ b/radix-engine/book/src/architecture/application/state.md @@ -0,0 +1,13 @@ +# Blueprint State Schema + +A blueprint's state schema describes the number of fields and collections that exist in a blueprint. +Each field and collection are identified by field index and collection index. + +## Fields + +### Field Conditions + +### Field Transience + +## Collections + diff --git a/radix-engine/book/src/architecture/application/wasm_environment.md b/radix-engine/book/src/architecture/application/wasm_environment.md new file mode 100644 index 0000000000..f65fdcc832 --- /dev/null +++ b/radix-engine/book/src/architecture/application/wasm_environment.md @@ -0,0 +1,24 @@ +# WASM Environment + +## Function Entrypoint + +An exported function in WASM may be called if it is mapped via `export_name` in a function of a Blueprint Definition. +The argument to the function is a single `i64` which represents a buffer. The first 32 bits refers to a `BufferId` +and the second 32 bits refers to the length of the buffer. + +Once sufficient space has been allocated for the buffer, the contents of the buffer can be retrieved by using +the `buffer_consume` call. The contents of the buffer will match the sbor schema described in the function +schema of the Blueprint Definition. + +## System Calls + +Various `extern` functions are available to be called during execution. These are referred to as `system calls` +and provide the ability to read/write state, invoke methods and functions, and other system-related logic. + +The full set of calls can be found in [wasm_api.rs](../../../../../scrypto/src/engine/wasm_api.rs). + +## Function Return + +The return value from a called exported function in WASM must be an `i64` where the first 32 bits refers to the +32-bit address pointer and the second 32 bits refers to the size of the return object. The contents of the buffer +must match the return value schema of the function in the Blueprint Definition. diff --git a/radix-engine/book/src/architecture/database.md b/radix-engine/book/src/architecture/database.md new file mode 100644 index 0000000000..4a79ce0cd5 --- /dev/null +++ b/radix-engine/book/src/architecture/database.md @@ -0,0 +1 @@ +# Database \ No newline at end of file diff --git a/radix-engine/book/src/architecture/kernel.md b/radix-engine/book/src/architecture/kernel.md new file mode 100644 index 0000000000..e7480f318d --- /dev/null +++ b/radix-engine/book/src/architecture/kernel.md @@ -0,0 +1,8 @@ +# Kernel Layer +The kernel layer is responsible for the two core functionalities of Radix Engine: storage access and communication between applications. This is somewhat similar to the traditional Operating System’s responsibility for disk and network access. + +For Radix Engine, this includes the following low-level management: + +* Check that move/borrow semantics are maintained on any invocation or data write. The single owner rule and borrow rules are enforced by the kernel. On failure on any of these rules, the transaction will panic. +* Manage transient vs. persistent objects. An object at any point in time may be in the global space or may be owned by a call frame. The kernel maintains correct pointers to these objects during runtime as references to these objects are passed around. +* Manage transaction state updates. The kernel keeps track of the state updates which have occurred during a transaction and which will be subsequently committed to the database at the end of the transaction. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/layers/application/README b/radix-engine/book/src/architecture/layers/application/README deleted file mode 100644 index ac187d0887..0000000000 --- a/radix-engine/book/src/architecture/layers/application/README +++ /dev/null @@ -1 +0,0 @@ -# Application Layer diff --git a/radix-engine/book/src/architecture/layers/application/README.md b/radix-engine/book/src/architecture/layers/application/README.md index 7aef6a3b0b..ac187d0887 100644 --- a/radix-engine/book/src/architecture/layers/application/README.md +++ b/radix-engine/book/src/architecture/layers/application/README.md @@ -1,15 +1 @@ # Application Layer - -Applications in Radix Engine are deployed through a format called a Package. -Packages consist of zero or more blueprints each of which are uniquely identified -by string name within a package. A blueprint is globally identifiable by -` + `. - -Each blueprint is defined by its *Blueprint Definition* which includes information such as the function -definition and state schemas of the Blueprint. Methods/Functions are mapped either to exported WASM -functions in a provided WASM binary or to native binary. - -## Package Deployment - -Deployment of new packages are done through invoking the `publish_wasm` or `publish_wasm_advanced` function. - diff --git a/radix-engine/book/src/architecture/layers/application/blueprint_definition.md b/radix-engine/book/src/architecture/layers/application/blueprint_definition.md index f44d96ab13..cc0bad22c6 100644 --- a/radix-engine/book/src/architecture/layers/application/blueprint_definition.md +++ b/radix-engine/book/src/architecture/layers/application/blueprint_definition.md @@ -1,31 +1 @@ # Blueprint Definition - -A Blueprint Definition defines everything about a Blueprint outside of the code logic itself. - -The structure used to initialize the definition is `BlueprintDefinitionInit` found in [invocations.rs](../../../../../radix-engine-interface/src/blueprints/package/invocations.rs): - -``` -pub struct BlueprintDefinitionInit { - pub blueprint_type: BlueprintType, - pub is_transient: bool, - pub feature_set: IndexSet, - pub dependencies: IndexSet, - pub schema: BlueprintSchemaInit, - pub royalty_config: PackageRoyaltyConfig, - pub auth_config: AuthConfig, -} -``` - -## Properties - -A description of each property is as follows. - -| Property Name | Description | -|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Blueprint Type | A blueprint may be specified as either an Outer or Inner Blueprint. If an inner blueprint, an associated outer blueprint must be specified. Inner blueprint components may access the state of its outer blueprint component directly.

*Inner Blueprints are currently only available for use by native packages.* | -| Transience | If a blueprint is specified to be transient, all components of this blueprint type may not be persisted.

*Transience is currently only available for use by native packages.* | -| Feature Set | Features provide a mechanism to express conditional execution and stored state. The feature set is the set of all possible features a component instantiator may specify.

*A non-empty Feature Set is currently only available for use by native packages.* | -| Dependencies | The set of all addresses which will always be visible to the call frames of this blueprint. | -| Blueprint Schema | The schema of the blueprint including generics, interface, state, and events. | -| Royalty Config | Royalty configuration for this blueprint. | -| Auth Config | Auth configuration such as role definitions for this blueprint. | diff --git a/radix-engine/book/src/architecture/layers/application/functions.md b/radix-engine/book/src/architecture/layers/application/functions.md index b226316972..0c5faf50f8 100644 --- a/radix-engine/book/src/architecture/layers/application/functions.md +++ b/radix-engine/book/src/architecture/layers/application/functions.md @@ -1 +1 @@ -# Features \ No newline at end of file +# Functions diff --git a/radix-engine/book/src/architecture/layers/application/state.md b/radix-engine/book/src/architecture/layers/application/state.md index 8507cb63d6..da704cc74e 100644 --- a/radix-engine/book/src/architecture/layers/application/state.md +++ b/radix-engine/book/src/architecture/layers/application/state.md @@ -1,13 +1 @@ -# Blueprint State Schema - -A blueprint's state schema describes the number of fields and collections that exist in a blueprint. -Each field and collection are identified by field index and collection index. - -## Fields - -### Field Conditions - -### Field Transience - -## Collections - +# State diff --git a/radix-engine/book/src/architecture/layers/application/wasm_environment.md b/radix-engine/book/src/architecture/layers/application/wasm_environment.md index f65fdcc832..84a5952980 100644 --- a/radix-engine/book/src/architecture/layers/application/wasm_environment.md +++ b/radix-engine/book/src/architecture/layers/application/wasm_environment.md @@ -1,24 +1 @@ # WASM Environment - -## Function Entrypoint - -An exported function in WASM may be called if it is mapped via `export_name` in a function of a Blueprint Definition. -The argument to the function is a single `i64` which represents a buffer. The first 32 bits refers to a `BufferId` -and the second 32 bits refers to the length of the buffer. - -Once sufficient space has been allocated for the buffer, the contents of the buffer can be retrieved by using -the `buffer_consume` call. The contents of the buffer will match the sbor schema described in the function -schema of the Blueprint Definition. - -## System Calls - -Various `extern` functions are available to be called during execution. These are referred to as `system calls` -and provide the ability to read/write state, invoke methods and functions, and other system-related logic. - -The full set of calls can be found in [wasm_api.rs](../../../../../scrypto/src/engine/wasm_api.rs). - -## Function Return - -The return value from a called exported function in WASM must be an `i64` where the first 32 bits refers to the -32-bit address pointer and the second 32 bits refers to the size of the return object. The contents of the buffer -must match the return value schema of the function in the Blueprint Definition. diff --git a/radix-engine/book/src/architecture/layers/database.md b/radix-engine/book/src/architecture/layers/database.md index 4a79ce0cd5..02e60f370e 100644 --- a/radix-engine/book/src/architecture/layers/database.md +++ b/radix-engine/book/src/architecture/layers/database.md @@ -1 +1 @@ -# Database \ No newline at end of file +# Database Layer diff --git a/radix-engine/book/src/architecture/layers/kernel.md b/radix-engine/book/src/architecture/layers/kernel.md index e7480f318d..6b2e5e987e 100644 --- a/radix-engine/book/src/architecture/layers/kernel.md +++ b/radix-engine/book/src/architecture/layers/kernel.md @@ -1,8 +1 @@ # Kernel Layer -The kernel layer is responsible for the two core functionalities of Radix Engine: storage access and communication between applications. This is somewhat similar to the traditional Operating System’s responsibility for disk and network access. - -For Radix Engine, this includes the following low-level management: - -* Check that move/borrow semantics are maintained on any invocation or data write. The single owner rule and borrow rules are enforced by the kernel. On failure on any of these rules, the transaction will panic. -* Manage transient vs. persistent objects. An object at any point in time may be in the global space or may be owned by a call frame. The kernel maintains correct pointers to these objects during runtime as references to these objects are passed around. -* Manage transaction state updates. The kernel keeps track of the state updates which have occurred during a transaction and which will be subsequently committed to the database at the end of the transaction. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/layers/system.md b/radix-engine/book/src/architecture/layers/system.md index dcef9d3130..1d6e0d2d49 100644 --- a/radix-engine/book/src/architecture/layers/system.md +++ b/radix-engine/book/src/architecture/layers/system.md @@ -1,5 +1 @@ # System Layer - -The System Layer is responsible for maintaining a set of System Modules, or pluggable software which can extend the functionality of the system. - -On every system call, each system module gets called before the system layer passes control to the kernel layer. When called, each system module may update some particular state (e.g. update fees spent) or panic to end the transaction (e.g. if the type checker fails). \ No newline at end of file diff --git a/radix-engine/book/src/architecture/layers/vm.md b/radix-engine/book/src/architecture/layers/vm.md index 6744e1908d..7596c6f6e8 100644 --- a/radix-engine/book/src/architecture/layers/vm.md +++ b/radix-engine/book/src/architecture/layers/vm.md @@ -1,4 +1 @@ # VM Layer -The VM Layer is responsible for providing the computing environment to the application layer. This includes a Turing-complete VM as well as the interface to access the system layer. - -Radix Engine currently supports two VMs: a Scrypto WASM VM used to execute Scrypto applications and a native VM which executes native packages which are compiled to the host’s environment. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/system.md b/radix-engine/book/src/architecture/system.md new file mode 100644 index 0000000000..dcef9d3130 --- /dev/null +++ b/radix-engine/book/src/architecture/system.md @@ -0,0 +1,5 @@ +# System Layer + +The System Layer is responsible for maintaining a set of System Modules, or pluggable software which can extend the functionality of the system. + +On every system call, each system module gets called before the system layer passes control to the kernel layer. When called, each system module may update some particular state (e.g. update fees spent) or panic to end the transaction (e.g. if the type checker fails). \ No newline at end of file diff --git a/radix-engine/book/src/architecture/vm.md b/radix-engine/book/src/architecture/vm.md new file mode 100644 index 0000000000..6744e1908d --- /dev/null +++ b/radix-engine/book/src/architecture/vm.md @@ -0,0 +1,4 @@ +# VM Layer +The VM Layer is responsible for providing the computing environment to the application layer. This includes a Turing-complete VM as well as the interface to access the system layer. + +Radix Engine currently supports two VMs: a Scrypto WASM VM used to execute Scrypto applications and a native VM which executes native packages which are compiled to the host’s environment. \ No newline at end of file From 71f2a17f48d38ca7a1c4c5338806f953977ae0cc Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Thu, 25 Apr 2024 11:37:10 -0500 Subject: [PATCH 14/47] More documentation --- radix-engine/book/src/SUMMARY.md | 26 ++++++++++------ .../src/architecture/application/blueprint.md | 5 +++ .../application/blueprint_definition.md | 31 ------------------- .../src/architecture/application/features.md | 6 ++++ .../{inner_vs_outer.md => inner_outer.md} | 2 +- .../architecture/application/transience.md | 5 +++ 6 files changed, 33 insertions(+), 42 deletions(-) create mode 100644 radix-engine/book/src/architecture/application/blueprint.md delete mode 100644 radix-engine/book/src/architecture/application/blueprint_definition.md create mode 100644 radix-engine/book/src/architecture/application/features.md rename radix-engine/book/src/architecture/application/{inner_vs_outer.md => inner_outer.md} (95%) create mode 100644 radix-engine/book/src/architecture/application/transience.md diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index 6cf0b23f69..7777621ceb 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -6,15 +6,16 @@ - [Layered Architecture](architecture/layers.md) - [Application Layer](architecture/application/README.md) - - [Blueprint Definition](architecture/application/blueprint_definition.md) - - [Inner vs Outer Blueprints](architecture/application/inner_vs_outer.md) - - [Transience]() - - [Features]() + - [Blueprint](architecture/application/blueprint.md) + - [Inner and Outer Blueprints](architecture/application/inner_outer.md) + - [Transience](architecture/application/transience.md) + - [Features](architecture/application/features.md) - [Generics]() - [State](architecture/application/state.md) - [Events]() - [Functions](architecture/application/functions.md) - [Types]() + - [Blueprint Modules]() - [WASM Environment](architecture/application/wasm_environment.md) - [Type System]() - [VM Layer](architecture/vm.md) @@ -32,13 +33,13 @@ - [Transaction Lifecycle](execution/lifecycle.md) - [Bootup](execution/bootup.md) - [Runtime]() - - [System Calls]() - - [Invocations]() - [Shutdown](execution/shutdown.md) -- [Substate Flashing]() -- [Genesis Bootstrap]() -- [Protocol Updates]() - +- [Object Lifecycle]() + - [Instantiation]() + - [State Reads/Writes]() + - [Destruction]() +- [Invocations]() + # Native Systems - [Authorization](native/access_control/README) @@ -50,3 +51,8 @@ - [Resources]() - [Royalties]() - [Metadata]() + +# Protocol +- [Genesis Bootstrap]() +- [Protocol Updates]() + \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/blueprint.md b/radix-engine/book/src/architecture/application/blueprint.md new file mode 100644 index 0000000000..10ddcae04d --- /dev/null +++ b/radix-engine/book/src/architecture/application/blueprint.md @@ -0,0 +1,5 @@ +# Blueprint + +A Blueprint is a similar notion to a Class/Type in Object-Oriented Languages and describes +properties of all objects of the given blueprint. This includes function/method interfaces, +state schemas, and royalty/auth configurations. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/blueprint_definition.md b/radix-engine/book/src/architecture/application/blueprint_definition.md deleted file mode 100644 index f44d96ab13..0000000000 --- a/radix-engine/book/src/architecture/application/blueprint_definition.md +++ /dev/null @@ -1,31 +0,0 @@ -# Blueprint Definition - -A Blueprint Definition defines everything about a Blueprint outside of the code logic itself. - -The structure used to initialize the definition is `BlueprintDefinitionInit` found in [invocations.rs](../../../../../radix-engine-interface/src/blueprints/package/invocations.rs): - -``` -pub struct BlueprintDefinitionInit { - pub blueprint_type: BlueprintType, - pub is_transient: bool, - pub feature_set: IndexSet, - pub dependencies: IndexSet, - pub schema: BlueprintSchemaInit, - pub royalty_config: PackageRoyaltyConfig, - pub auth_config: AuthConfig, -} -``` - -## Properties - -A description of each property is as follows. - -| Property Name | Description | -|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Blueprint Type | A blueprint may be specified as either an Outer or Inner Blueprint. If an inner blueprint, an associated outer blueprint must be specified. Inner blueprint components may access the state of its outer blueprint component directly.

*Inner Blueprints are currently only available for use by native packages.* | -| Transience | If a blueprint is specified to be transient, all components of this blueprint type may not be persisted.

*Transience is currently only available for use by native packages.* | -| Feature Set | Features provide a mechanism to express conditional execution and stored state. The feature set is the set of all possible features a component instantiator may specify.

*A non-empty Feature Set is currently only available for use by native packages.* | -| Dependencies | The set of all addresses which will always be visible to the call frames of this blueprint. | -| Blueprint Schema | The schema of the blueprint including generics, interface, state, and events. | -| Royalty Config | Royalty configuration for this blueprint. | -| Auth Config | Auth configuration such as role definitions for this blueprint. | diff --git a/radix-engine/book/src/architecture/application/features.md b/radix-engine/book/src/architecture/application/features.md new file mode 100644 index 0000000000..bc8001d10f --- /dev/null +++ b/radix-engine/book/src/architecture/application/features.md @@ -0,0 +1,6 @@ +# Features + +Features provide a mechanism to express conditional execution and stored state. The feature set +is the set of all possible features a component instantiator may specify. + +*Note: Features are currently only available for use by native packages.* diff --git a/radix-engine/book/src/architecture/application/inner_vs_outer.md b/radix-engine/book/src/architecture/application/inner_outer.md similarity index 95% rename from radix-engine/book/src/architecture/application/inner_vs_outer.md rename to radix-engine/book/src/architecture/application/inner_outer.md index 8adc1b73aa..b732a97326 100644 --- a/radix-engine/book/src/architecture/application/inner_vs_outer.md +++ b/radix-engine/book/src/architecture/application/inner_outer.md @@ -1,4 +1,4 @@ -# Inner vs. Outer Blueprints +# Inner and Outer Blueprints A blueprint may be specified as either an Outer or Inner Blueprint. If an inner blueprint, an associated outer blueprint (from the same package) must be specified. diff --git a/radix-engine/book/src/architecture/application/transience.md b/radix-engine/book/src/architecture/application/transience.md new file mode 100644 index 0000000000..e6135ee4d5 --- /dev/null +++ b/radix-engine/book/src/architecture/application/transience.md @@ -0,0 +1,5 @@ +# Transience + +If a blueprint is specified to be transient, all objects of this blueprint may not be persisted. + +*Note: Transience is currently only available for use by native packages.* From 85b68bdda8ebab53c42ca495034e3858407cd27d Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Thu, 25 Apr 2024 11:48:54 -0500 Subject: [PATCH 15/47] Some cleanup --- radix-engine/book/src/SUMMARY.md | 2 +- .../book/src/architecture/application/README.md | 4 ---- .../book/src/architecture/application/features.md | 3 ++- .../book/src/architecture/application/functions.md | 2 +- .../src/architecture/application/inner_outer.md | 3 ++- .../src/architecture/application/transience.md | 4 ++-- radix-engine/book/src/architecture/layers.md | 14 +++++++------- .../src/architecture/layers/application/README.md | 1 - .../layers/application/blueprint_definition.md | 1 - .../architecture/layers/application/functions.md | 1 - .../src/architecture/layers/application/state.md | 1 - .../layers/application/wasm_environment.md | 1 - .../book/src/architecture/layers/database.md | 1 - .../book/src/architecture/layers/kernel.md | 1 - .../book/src/architecture/layers/system.md | 1 - radix-engine/book/src/architecture/layers/vm.md | 1 - 16 files changed, 15 insertions(+), 26 deletions(-) delete mode 100644 radix-engine/book/src/architecture/layers/application/README.md delete mode 100644 radix-engine/book/src/architecture/layers/application/blueprint_definition.md delete mode 100644 radix-engine/book/src/architecture/layers/application/functions.md delete mode 100644 radix-engine/book/src/architecture/layers/application/state.md delete mode 100644 radix-engine/book/src/architecture/layers/application/wasm_environment.md delete mode 100644 radix-engine/book/src/architecture/layers/database.md delete mode 100644 radix-engine/book/src/architecture/layers/kernel.md delete mode 100644 radix-engine/book/src/architecture/layers/system.md delete mode 100644 radix-engine/book/src/architecture/layers/vm.md diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index 7777621ceb..d9152d3566 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -13,7 +13,7 @@ - [Generics]() - [State](architecture/application/state.md) - [Events]() - - [Functions](architecture/application/functions.md) + - [Functions]() - [Types]() - [Blueprint Modules]() - [WASM Environment](architecture/application/wasm_environment.md) diff --git a/radix-engine/book/src/architecture/application/README.md b/radix-engine/book/src/architecture/application/README.md index 7aef6a3b0b..6b922be1ee 100644 --- a/radix-engine/book/src/architecture/application/README.md +++ b/radix-engine/book/src/architecture/application/README.md @@ -9,7 +9,3 @@ Each blueprint is defined by its *Blueprint Definition* which includes informati definition and state schemas of the Blueprint. Methods/Functions are mapped either to exported WASM functions in a provided WASM binary or to native binary. -## Package Deployment - -Deployment of new packages are done through invoking the `publish_wasm` or `publish_wasm_advanced` function. - diff --git a/radix-engine/book/src/architecture/application/features.md b/radix-engine/book/src/architecture/application/features.md index bc8001d10f..d7143932f9 100644 --- a/radix-engine/book/src/architecture/application/features.md +++ b/radix-engine/book/src/architecture/application/features.md @@ -1,6 +1,7 @@ # Features +> **_NOTE:_** Features are currently only available for use by native packages. + Features provide a mechanism to express conditional execution and stored state. The feature set is the set of all possible features a component instantiator may specify. -*Note: Features are currently only available for use by native packages.* diff --git a/radix-engine/book/src/architecture/application/functions.md b/radix-engine/book/src/architecture/application/functions.md index b226316972..0c5faf50f8 100644 --- a/radix-engine/book/src/architecture/application/functions.md +++ b/radix-engine/book/src/architecture/application/functions.md @@ -1 +1 @@ -# Features \ No newline at end of file +# Functions diff --git a/radix-engine/book/src/architecture/application/inner_outer.md b/radix-engine/book/src/architecture/application/inner_outer.md index b732a97326..11d558d6ab 100644 --- a/radix-engine/book/src/architecture/application/inner_outer.md +++ b/radix-engine/book/src/architecture/application/inner_outer.md @@ -1,5 +1,7 @@ # Inner and Outer Blueprints +> **_NOTE:_** Inner Blueprints are currently only available for use by native packages. + A blueprint may be specified as either an Outer or Inner Blueprint. If an inner blueprint, an associated outer blueprint (from the same package) must be specified. @@ -11,4 +13,3 @@ avoiding invocation and new call frame costs. ![](inner_outer_objects.drawio.svg) -*Inner Blueprints are currently only available for use by native packages.* diff --git a/radix-engine/book/src/architecture/application/transience.md b/radix-engine/book/src/architecture/application/transience.md index e6135ee4d5..de07c9e16e 100644 --- a/radix-engine/book/src/architecture/application/transience.md +++ b/radix-engine/book/src/architecture/application/transience.md @@ -1,5 +1,5 @@ # Transience +> **_NOTE:_** Transience is currently only available for use by native packages. + If a blueprint is specified to be transient, all objects of this blueprint may not be persisted. - -*Note: Transience is currently only available for use by native packages.* diff --git a/radix-engine/book/src/architecture/layers.md b/radix-engine/book/src/architecture/layers.md index c5c80f9f89..24516b4e1c 100644 --- a/radix-engine/book/src/architecture/layers.md +++ b/radix-engine/book/src/architecture/layers.md @@ -4,11 +4,11 @@ Radix Engine is organized into 5 layers. Each layer has specific responsibilitie provides an API to the layer above. Middle layers also provide a Callback API which the layer above must implement. -| Layer Name | Layer ID | Responsibilities | -|-------------|----------|---------------------------------------------------------------------------------------------------------------------------| -| Application | 5 | Defines Types and Application Logic | -| VM | 4 | Interprets Application Code | -| System | 3 | Type Checks
Defines Package/Blueprint/Object abstractions
Defines System Standards (e.g. Authorization, Versioning) | -| Kernel | 2 | Maintains Call Frame Stack
Manages Ownership/Reference handling invariants
Provides State Virtualization Mechanism | -| Database | 1 | Interacts with a Read-Only Database | +| Layer Name | Layer ID | Responsibilities | +|-------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------| +| Application | 5 | Defines Blueprints and Application Logic | +| VM | 4 | Interprets Application Code | +| System | 3 | Type Checks during Runtime
Defines Package, Blueprint, Object abstractions
Defines System Standards such as Authorization and Versioning | +| Kernel | 2 | Maintains Call Frame Stack
Manages Ownership/Reference handling invariants
Provides State Virtualization Mechanism | +| Database | 1 | Interacts with a Read-Only Database | diff --git a/radix-engine/book/src/architecture/layers/application/README.md b/radix-engine/book/src/architecture/layers/application/README.md deleted file mode 100644 index ac187d0887..0000000000 --- a/radix-engine/book/src/architecture/layers/application/README.md +++ /dev/null @@ -1 +0,0 @@ -# Application Layer diff --git a/radix-engine/book/src/architecture/layers/application/blueprint_definition.md b/radix-engine/book/src/architecture/layers/application/blueprint_definition.md deleted file mode 100644 index cc0bad22c6..0000000000 --- a/radix-engine/book/src/architecture/layers/application/blueprint_definition.md +++ /dev/null @@ -1 +0,0 @@ -# Blueprint Definition diff --git a/radix-engine/book/src/architecture/layers/application/functions.md b/radix-engine/book/src/architecture/layers/application/functions.md deleted file mode 100644 index 0c5faf50f8..0000000000 --- a/radix-engine/book/src/architecture/layers/application/functions.md +++ /dev/null @@ -1 +0,0 @@ -# Functions diff --git a/radix-engine/book/src/architecture/layers/application/state.md b/radix-engine/book/src/architecture/layers/application/state.md deleted file mode 100644 index da704cc74e..0000000000 --- a/radix-engine/book/src/architecture/layers/application/state.md +++ /dev/null @@ -1 +0,0 @@ -# State diff --git a/radix-engine/book/src/architecture/layers/application/wasm_environment.md b/radix-engine/book/src/architecture/layers/application/wasm_environment.md deleted file mode 100644 index 84a5952980..0000000000 --- a/radix-engine/book/src/architecture/layers/application/wasm_environment.md +++ /dev/null @@ -1 +0,0 @@ -# WASM Environment diff --git a/radix-engine/book/src/architecture/layers/database.md b/radix-engine/book/src/architecture/layers/database.md deleted file mode 100644 index 02e60f370e..0000000000 --- a/radix-engine/book/src/architecture/layers/database.md +++ /dev/null @@ -1 +0,0 @@ -# Database Layer diff --git a/radix-engine/book/src/architecture/layers/kernel.md b/radix-engine/book/src/architecture/layers/kernel.md deleted file mode 100644 index 6b2e5e987e..0000000000 --- a/radix-engine/book/src/architecture/layers/kernel.md +++ /dev/null @@ -1 +0,0 @@ -# Kernel Layer diff --git a/radix-engine/book/src/architecture/layers/system.md b/radix-engine/book/src/architecture/layers/system.md deleted file mode 100644 index 1d6e0d2d49..0000000000 --- a/radix-engine/book/src/architecture/layers/system.md +++ /dev/null @@ -1 +0,0 @@ -# System Layer diff --git a/radix-engine/book/src/architecture/layers/vm.md b/radix-engine/book/src/architecture/layers/vm.md deleted file mode 100644 index 7596c6f6e8..0000000000 --- a/radix-engine/book/src/architecture/layers/vm.md +++ /dev/null @@ -1 +0,0 @@ -# VM Layer From 6c8e6ce1f96d2c67ced693e1939bfb9314773ad7 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Thu, 25 Apr 2024 13:06:20 -0500 Subject: [PATCH 16/47] Some updates to documentation structure --- radix-engine/book/src/SUMMARY.md | 6 +++--- .../book/src/architecture/application/README.md | 13 ++++++------- 2 files changed, 9 insertions(+), 10 deletions(-) diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index d9152d3566..203c8dfcf2 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -15,13 +15,12 @@ - [Events]() - [Functions]() - [Types]() - - [Blueprint Modules]() - - [WASM Environment](architecture/application/wasm_environment.md) + - [Blueprint Modules]() + - [Object Modules]() - [Type System]() - [VM Layer](architecture/vm.md) - [System Layer](architecture/system.md) - [System Modules]() - - [Object Modules]() - [Kernel Layer](architecture/kernel.md) - [Move/Borrow Checking]() - [Database Layer](architecture/database.md) @@ -34,6 +33,7 @@ - [Bootup](execution/bootup.md) - [Runtime]() - [Shutdown](execution/shutdown.md) +- [WASM Environment](architecture/application/wasm_environment.md) - [Object Lifecycle]() - [Instantiation]() - [State Reads/Writes]() diff --git a/radix-engine/book/src/architecture/application/README.md b/radix-engine/book/src/architecture/application/README.md index 6b922be1ee..4e173e8d98 100644 --- a/radix-engine/book/src/architecture/application/README.md +++ b/radix-engine/book/src/architecture/application/README.md @@ -1,11 +1,10 @@ # Application Layer -Applications in Radix Engine are deployed through a format called a Package. -Packages consist of zero or more blueprints each of which are uniquely identified -by string name within a package. A blueprint is globally identifiable by -` + `. +Applications in Radix Engine are organized in a format called a *Package* which is uniquely +identified through a `package_address`. -Each blueprint is defined by its *Blueprint Definition* which includes information such as the function -definition and state schemas of the Blueprint. Methods/Functions are mapped either to exported WASM -functions in a provided WASM binary or to native binary. +Each package defines zero or more *Blueprints* each with a unique name within the package. A +blueprint is globally identifiable by ` + `. +Each blueprint defines type information and logic which can then create/manipulate/destroy *objects* +which are instantiations of specific blueprints. From 19bba4b7f185935e210d6debc596f9102ed93ad7 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Thu, 25 Apr 2024 13:27:28 -0500 Subject: [PATCH 17/47] Update introduction --- radix-engine/book/src/README.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/radix-engine/book/src/README.md b/radix-engine/book/src/README.md index ee3c0cb7fd..465c77a0ca 100644 --- a/radix-engine/book/src/README.md +++ b/radix-engine/book/src/README.md @@ -1,14 +1,10 @@ # Radix Engine -Radix Engine is a transaction-based state machine that updates the ledger state by incrementally -executing transactions. +Radix Engine is a deterministic, transaction-based state machine that updates ledger state by +incrementally executing transactions. -Unlike Ethereum where the ledger state is a flat mapping between addresses and account states, Radix -Engine organizes its state into a forest of objects. Child objects are exclusively owned by its -parent in the tree hierarchy. Each root object is assigned a global address. +Radix Engine was built out of the lack of VMs specifically optimized for a DeFi shared computing +environment. -Every object has an associated blueprint, which defines logic for updating the object's internal -state. Multiple blueprints can be packed into a package and published as a single unit. - -A set of native packages are defined by Radix Engine which form built-in system standards such as -accounts, access control, resources, etc. \ No newline at end of file +Radix Engine is Object-Oriented, enforces ownership/move semantics, and introduces easy "pluggability" +of stateful modules within the system. From 4208289d0e958184f238bb6e53861af6a97e9b6f Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Thu, 25 Apr 2024 15:33:53 -0500 Subject: [PATCH 18/47] More updates --- radix-engine/book/src/README.md | 18 +++++++++---- radix-engine/book/src/SUMMARY.md | 22 ++++++++-------- .../src/architecture/application/README.md | 15 ++++++----- .../src/architecture/application/blueprint.md | 5 ---- .../application/blueprint/README.md | 5 ++++ .../application/blueprint/collections.md | 11 ++++++++ .../application/blueprint/events.md | 6 +++++ .../application/{ => blueprint}/features.md | 5 ++-- .../application/blueprint/fields.md | 25 +++++++++++++++++++ .../application/{ => blueprint}/functions.md | 0 .../application/blueprint/generics.md | 9 +++++++ .../{ => blueprint}/inner_outer.md | 8 +++--- .../inner_outer_blueprints.drawio.svg | 0 .../inner_outer_objects.drawio.svg | 0 .../application/{ => blueprint}/transience.md | 2 +- .../application/blueprint/types.md | 6 +++++ .../src/architecture/application/state.md | 13 ---------- .../book/src/execution/wasm_environment.md | 1 + 18 files changed, 105 insertions(+), 46 deletions(-) delete mode 100644 radix-engine/book/src/architecture/application/blueprint.md create mode 100644 radix-engine/book/src/architecture/application/blueprint/README.md create mode 100644 radix-engine/book/src/architecture/application/blueprint/collections.md create mode 100644 radix-engine/book/src/architecture/application/blueprint/events.md rename radix-engine/book/src/architecture/application/{ => blueprint}/features.md (53%) create mode 100644 radix-engine/book/src/architecture/application/blueprint/fields.md rename radix-engine/book/src/architecture/application/{ => blueprint}/functions.md (100%) create mode 100644 radix-engine/book/src/architecture/application/blueprint/generics.md rename radix-engine/book/src/architecture/application/{ => blueprint}/inner_outer.md (58%) rename radix-engine/book/src/architecture/application/{ => blueprint}/inner_outer_blueprints.drawio.svg (100%) rename radix-engine/book/src/architecture/application/{ => blueprint}/inner_outer_objects.drawio.svg (100%) rename radix-engine/book/src/architecture/application/{ => blueprint}/transience.md (82%) create mode 100644 radix-engine/book/src/architecture/application/blueprint/types.md delete mode 100644 radix-engine/book/src/architecture/application/state.md create mode 100644 radix-engine/book/src/execution/wasm_environment.md diff --git a/radix-engine/book/src/README.md b/radix-engine/book/src/README.md index 465c77a0ca..c018ef25fc 100644 --- a/radix-engine/book/src/README.md +++ b/radix-engine/book/src/README.md @@ -1,10 +1,18 @@ -# Radix Engine +# What is Radix Engine? Radix Engine is a deterministic, transaction-based state machine that updates ledger state by incrementally executing transactions. -Radix Engine was built out of the lack of VMs specifically optimized for a DeFi shared computing -environment. - -Radix Engine is Object-Oriented, enforces ownership/move semantics, and introduces easy "pluggability" +Radix Engine is Object-Oriented, enforces ownership/move semantics, and introduces easy pluggability of stateful modules within the system. + +# Why? + +Radix Engine was built out of the lack of Blockchain VMs specifically optimized for a DeFi +shared computing environment in terms of usability, security, performance, and modularity. + + + + + + diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index 203c8dfcf2..cefd377b6c 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -6,17 +6,19 @@ - [Layered Architecture](architecture/layers.md) - [Application Layer](architecture/application/README.md) - - [Blueprint](architecture/application/blueprint.md) - - [Inner and Outer Blueprints](architecture/application/inner_outer.md) - - [Transience](architecture/application/transience.md) - - [Features](architecture/application/features.md) - - [Generics]() - - [State](architecture/application/state.md) - - [Events]() + - [Blueprint](architecture/application/blueprint/README.md) + - [Inner and Outer Blueprints](architecture/application/blueprint/inner_outer.md) + - [Transience](architecture/application/blueprint/transience.md) + - [Features](architecture/application/blueprint/features.md) + - [Generics](architecture/application/blueprint/generics.md) + - [Fields](architecture/application/blueprint/fields.md) + - [Collections](architecture/application/blueprint/collections.md) + - [Events](architecture/application/blueprint/events.md) - [Functions]() - - [Types]() - - [Blueprint Modules]() - - [Object Modules]() + - [Types](architecture/application/blueprint/types.md) + - [Blueprint Modules]() + - [Object]() + - [Object Modules]() - [Type System]() - [VM Layer](architecture/vm.md) - [System Layer](architecture/system.md) diff --git a/radix-engine/book/src/architecture/application/README.md b/radix-engine/book/src/architecture/application/README.md index 4e173e8d98..453eea89b3 100644 --- a/radix-engine/book/src/architecture/application/README.md +++ b/radix-engine/book/src/architecture/application/README.md @@ -1,10 +1,13 @@ # Application Layer -Applications in Radix Engine are organized in a format called a *Package* which is uniquely -identified through a `package_address`. +The application layer is responsible for defining high level logic which manipulates +object state. + +Applications in Radix Engine are organized in a format called a *Package* which contain zero or +more *Blueprints*, each of which has a unique name within the package. Packages are uniquely identified +through a ``. Blueprints are globally identifiable by ` + `. + +Each blueprint defines type information and logic which can create/manipulate/destroy *objects*, +which are instantiations of blueprints. -Each package defines zero or more *Blueprints* each with a unique name within the package. A -blueprint is globally identifiable by ` + `. -Each blueprint defines type information and logic which can then create/manipulate/destroy *objects* -which are instantiations of specific blueprints. diff --git a/radix-engine/book/src/architecture/application/blueprint.md b/radix-engine/book/src/architecture/application/blueprint.md deleted file mode 100644 index 10ddcae04d..0000000000 --- a/radix-engine/book/src/architecture/application/blueprint.md +++ /dev/null @@ -1,5 +0,0 @@ -# Blueprint - -A Blueprint is a similar notion to a Class/Type in Object-Oriented Languages and describes -properties of all objects of the given blueprint. This includes function/method interfaces, -state schemas, and royalty/auth configurations. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/blueprint/README.md b/radix-engine/book/src/architecture/application/blueprint/README.md new file mode 100644 index 0000000000..34b9c8a2d6 --- /dev/null +++ b/radix-engine/book/src/architecture/application/blueprint/README.md @@ -0,0 +1,5 @@ +# Blueprint + +A Blueprint is the Radix Engine equivalent of Classes/Types in Object-Oriented Languages. +It acts as a type identifier for an object and describes shared properties of all objects +of that blueprint such as function/method interfaces. diff --git a/radix-engine/book/src/architecture/application/blueprint/collections.md b/radix-engine/book/src/architecture/application/blueprint/collections.md new file mode 100644 index 0000000000..1c43328b76 --- /dev/null +++ b/radix-engine/book/src/architecture/application/blueprint/collections.md @@ -0,0 +1,11 @@ +# Collections + +> **_NOTE:_** Collections are currently only available for use by native packages. + +A collections is a set of data which can be read/loaded incrementally. There are currently three types +of collections: +1. Key-Value Collection +2. Index Collection +3. Sorted Index Collection + +Collections are identified by collection index. diff --git a/radix-engine/book/src/architecture/application/blueprint/events.md b/radix-engine/book/src/architecture/application/blueprint/events.md new file mode 100644 index 0000000000..0608fa780f --- /dev/null +++ b/radix-engine/book/src/architecture/application/blueprint/events.md @@ -0,0 +1,6 @@ +# Events + +Events may be emitted during runtime for off-chain processing. A schema which +describes the data of every event type must be specified. + +Events are identified by string. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/features.md b/radix-engine/book/src/architecture/application/blueprint/features.md similarity index 53% rename from radix-engine/book/src/architecture/application/features.md rename to radix-engine/book/src/architecture/application/blueprint/features.md index d7143932f9..ecb72733a7 100644 --- a/radix-engine/book/src/architecture/application/features.md +++ b/radix-engine/book/src/architecture/application/blueprint/features.md @@ -2,6 +2,7 @@ > **_NOTE:_** Features are currently only available for use by native packages. -Features provide a mechanism to express conditional execution and stored state. The feature set -is the set of all possible features a component instantiator may specify. +Features provide a mechanism to express conditional execution and conditional stored state. +The set of features to be used are specified per object on instantiation. +Features are identified by string. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/blueprint/fields.md b/radix-engine/book/src/architecture/application/blueprint/fields.md new file mode 100644 index 0000000000..729b653b8f --- /dev/null +++ b/radix-engine/book/src/architecture/application/blueprint/fields.md @@ -0,0 +1,25 @@ +# Fields + +> **_NOTE:_** Use of more than one Field, Field Conditions and Field Transience are currently only available for use by native packages. + +A field is object state which gets loaded at once and maps to a single substate. A schema which +describes what is in the data must be specified for every field. + +Fields are identified by field index. + +## Field Condition + +Fields may be conditionally included in an object depending on the features instantiated +with that object. There are currently three options for field conditions: + +| Name | Description | +|----------------|---------------------------------------------------------------------------------------| +| Always | Always include the field | +| IfFeature | Only include the field if a given feature is specified | +| IfOuterFeature | Only include the field if a given feature in the associated outer object is specified | + +## Field Transience + +Fields may be specified to be transient. In this case, the field is never persisted. Instead, a default +value is initially loaded on first read and may be updated over the course of a transaction. At the end +of a transaction the field's value gets discarded. diff --git a/radix-engine/book/src/architecture/application/functions.md b/radix-engine/book/src/architecture/application/blueprint/functions.md similarity index 100% rename from radix-engine/book/src/architecture/application/functions.md rename to radix-engine/book/src/architecture/application/blueprint/functions.md diff --git a/radix-engine/book/src/architecture/application/blueprint/generics.md b/radix-engine/book/src/architecture/application/blueprint/generics.md new file mode 100644 index 0000000000..31f2bf75c6 --- /dev/null +++ b/radix-engine/book/src/architecture/application/blueprint/generics.md @@ -0,0 +1,9 @@ +# Generics + +> **_NOTE:_** Generics are currently only available for use by native packages. + +Generics to a blueprint may be specified which will then require an object instantiator to +specify generic parameters during instantiation. Such a generic can then be used in defining function +or state schemas. + +Generics in a Blueprint are identified by index. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/inner_outer.md b/radix-engine/book/src/architecture/application/blueprint/inner_outer.md similarity index 58% rename from radix-engine/book/src/architecture/application/inner_outer.md rename to radix-engine/book/src/architecture/application/blueprint/inner_outer.md index 11d558d6ab..be1fab67e4 100644 --- a/radix-engine/book/src/architecture/application/inner_outer.md +++ b/radix-engine/book/src/architecture/application/blueprint/inner_outer.md @@ -2,14 +2,14 @@ > **_NOTE:_** Inner Blueprints are currently only available for use by native packages. -A blueprint may be specified as either an Outer or Inner Blueprint. If an inner blueprint, an associated outer blueprint -(from the same package) must be specified. +A blueprint may be specified as either an Outer or Inner Blueprint. Inner blueprints must specify +an associated outer blueprint defined in the same package. ![](inner_outer_blueprints.drawio.svg) Inner blueprint objects may only be instantiated by an associated outer blueprint object. After -instantiation, inner blueprint objects may access the state of its outer blueprint component directly -avoiding invocation and new call frame costs. +instantiation, inner blueprint objects may directly access the state of its outer blueprint component +avoiding invocation and new call frame overhead + costs. ![](inner_outer_objects.drawio.svg) diff --git a/radix-engine/book/src/architecture/application/inner_outer_blueprints.drawio.svg b/radix-engine/book/src/architecture/application/blueprint/inner_outer_blueprints.drawio.svg similarity index 100% rename from radix-engine/book/src/architecture/application/inner_outer_blueprints.drawio.svg rename to radix-engine/book/src/architecture/application/blueprint/inner_outer_blueprints.drawio.svg diff --git a/radix-engine/book/src/architecture/application/inner_outer_objects.drawio.svg b/radix-engine/book/src/architecture/application/blueprint/inner_outer_objects.drawio.svg similarity index 100% rename from radix-engine/book/src/architecture/application/inner_outer_objects.drawio.svg rename to radix-engine/book/src/architecture/application/blueprint/inner_outer_objects.drawio.svg diff --git a/radix-engine/book/src/architecture/application/transience.md b/radix-engine/book/src/architecture/application/blueprint/transience.md similarity index 82% rename from radix-engine/book/src/architecture/application/transience.md rename to radix-engine/book/src/architecture/application/blueprint/transience.md index de07c9e16e..0b6b8ddebf 100644 --- a/radix-engine/book/src/architecture/application/transience.md +++ b/radix-engine/book/src/architecture/application/blueprint/transience.md @@ -2,4 +2,4 @@ > **_NOTE:_** Transience is currently only available for use by native packages. -If a blueprint is specified to be transient, all objects of this blueprint may not be persisted. +If a blueprint is specified to be transient, all objects of this blueprint cannot be persisted. diff --git a/radix-engine/book/src/architecture/application/blueprint/types.md b/radix-engine/book/src/architecture/application/blueprint/types.md new file mode 100644 index 0000000000..9bc7fb159c --- /dev/null +++ b/radix-engine/book/src/architecture/application/blueprint/types.md @@ -0,0 +1,6 @@ +# Types + +A blueprint may associate a schema to a name. This name can then be used externally to specify a +schema defined by this blueprint. + +Types are identified by string. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/state.md b/radix-engine/book/src/architecture/application/state.md deleted file mode 100644 index 8507cb63d6..0000000000 --- a/radix-engine/book/src/architecture/application/state.md +++ /dev/null @@ -1,13 +0,0 @@ -# Blueprint State Schema - -A blueprint's state schema describes the number of fields and collections that exist in a blueprint. -Each field and collection are identified by field index and collection index. - -## Fields - -### Field Conditions - -### Field Transience - -## Collections - diff --git a/radix-engine/book/src/execution/wasm_environment.md b/radix-engine/book/src/execution/wasm_environment.md new file mode 100644 index 0000000000..84a5952980 --- /dev/null +++ b/radix-engine/book/src/execution/wasm_environment.md @@ -0,0 +1 @@ +# WASM Environment From 67b9b87c1b19b582cdfbea6836c2b5cf673c7014 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Tue, 30 Apr 2024 13:26:14 -0500 Subject: [PATCH 19/47] Add more documentation --- radix-engine/book/src/README.md | 2 +- radix-engine/book/src/SUMMARY.md | 6 ++---- .../book/src/architecture/application/README.md | 10 +++++----- .../src/architecture/application/blueprint/README.md | 3 +++ .../application/blueprint/blueprint_modules.md | 8 ++++++++ .../architecture/application/blueprint/functions.md | 7 +++++++ 6 files changed, 26 insertions(+), 10 deletions(-) create mode 100644 radix-engine/book/src/architecture/application/blueprint/blueprint_modules.md diff --git a/radix-engine/book/src/README.md b/radix-engine/book/src/README.md index c018ef25fc..acba8d045f 100644 --- a/radix-engine/book/src/README.md +++ b/radix-engine/book/src/README.md @@ -3,7 +3,7 @@ Radix Engine is a deterministic, transaction-based state machine that updates ledger state by incrementally executing transactions. -Radix Engine is Object-Oriented, enforces ownership/move semantics, and introduces easy pluggability +Radix Engine is Object-Oriented, enforces move/ownership semantics, and introduces easy pluggability of stateful modules within the system. # Why? diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index cefd377b6c..b77d3776e8 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -14,11 +14,9 @@ - [Fields](architecture/application/blueprint/fields.md) - [Collections](architecture/application/blueprint/collections.md) - [Events](architecture/application/blueprint/events.md) - - [Functions]() + - [Functions](architecture/application/blueprint/functions.md) - [Types](architecture/application/blueprint/types.md) - - [Blueprint Modules]() - - [Object]() - - [Object Modules]() + - [Blueprint Modules](architecture/application/blueprint/blueprint_modules.md) - [Type System]() - [VM Layer](architecture/vm.md) - [System Layer](architecture/system.md) diff --git a/radix-engine/book/src/architecture/application/README.md b/radix-engine/book/src/architecture/application/README.md index 453eea89b3..197b238946 100644 --- a/radix-engine/book/src/architecture/application/README.md +++ b/radix-engine/book/src/architecture/application/README.md @@ -3,11 +3,11 @@ The application layer is responsible for defining high level logic which manipulates object state. -Applications in Radix Engine are organized in a format called a *Package* which contain zero or -more *Blueprints*, each of which has a unique name within the package. Packages are uniquely identified -through a ``. Blueprints are globally identifiable by ` + `. +An application in Radix Engine defines a *Package*, which contain zero or more *Blueprints*. +Each blueprint defines object type information and logic which can create/manipulate/destroy +objects of that blueprint type. + + -Each blueprint defines type information and logic which can create/manipulate/destroy *objects*, -which are instantiations of blueprints. diff --git a/radix-engine/book/src/architecture/application/blueprint/README.md b/radix-engine/book/src/architecture/application/blueprint/README.md index 34b9c8a2d6..03826c8db5 100644 --- a/radix-engine/book/src/architecture/application/blueprint/README.md +++ b/radix-engine/book/src/architecture/application/blueprint/README.md @@ -3,3 +3,6 @@ A Blueprint is the Radix Engine equivalent of Classes/Types in Object-Oriented Languages. It acts as a type identifier for an object and describes shared properties of all objects of that blueprint such as function/method interfaces. + +Each blueprint has a unique name within its package and are globally identifiable by +` + `. diff --git a/radix-engine/book/src/architecture/application/blueprint/blueprint_modules.md b/radix-engine/book/src/architecture/application/blueprint/blueprint_modules.md new file mode 100644 index 0000000000..32ee4941ff --- /dev/null +++ b/radix-engine/book/src/architecture/application/blueprint/blueprint_modules.md @@ -0,0 +1,8 @@ +# Blueprint Modules + +The system may define additional state to be stored per blueprint known as Blueprint modules. If defined, +every blueprint definition must initialize these modules. + +Currently there exists two blueprint modules: +* Auth Blueprint Module +* Royalty Blueprint Module \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/blueprint/functions.md b/radix-engine/book/src/architecture/application/blueprint/functions.md index 0c5faf50f8..d0827a1a24 100644 --- a/radix-engine/book/src/architecture/application/blueprint/functions.md +++ b/radix-engine/book/src/architecture/application/blueprint/functions.md @@ -1 +1,8 @@ # Functions + +Functions define executable logic. + +A function signature is defined by an input/output schema as well as whether an object receiver +must be specified. + +Functions are identified by string. From 8646b0a139cd67133f020b561a812a59552cad8a Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Wed, 1 May 2024 12:38:07 -0500 Subject: [PATCH 20/47] More updates to documentation --- radix-engine/book/src/SUMMARY.md | 25 +++++++++++-------- .../src/architecture/application/README.md | 5 ++-- .../application/wasm_environment.md | 24 ------------------ .../book/src/architecture/database.md | 2 +- .../book/src/architecture/database/README.md | 2 ++ radix-engine/book/src/architecture/kernel.md | 8 ------ .../book/src/architecture/kernel/README.md | 5 ++++ radix-engine/book/src/architecture/layers.md | 14 +++++------ radix-engine/book/src/architecture/system.md | 5 ---- .../book/src/architecture/system/README.md | 8 ++++++ radix-engine/book/src/architecture/vm.md | 4 --- .../book/src/architecture/vm/README.md | 7 ++++++ 12 files changed, 47 insertions(+), 62 deletions(-) delete mode 100644 radix-engine/book/src/architecture/application/wasm_environment.md create mode 100644 radix-engine/book/src/architecture/database/README.md delete mode 100644 radix-engine/book/src/architecture/kernel.md create mode 100644 radix-engine/book/src/architecture/kernel/README.md delete mode 100644 radix-engine/book/src/architecture/system.md create mode 100644 radix-engine/book/src/architecture/system/README.md delete mode 100644 radix-engine/book/src/architecture/vm.md create mode 100644 radix-engine/book/src/architecture/vm/README.md diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index b77d3776e8..4674ad24d7 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -17,15 +17,18 @@ - [Functions](architecture/application/blueprint/functions.md) - [Types](architecture/application/blueprint/types.md) - [Blueprint Modules](architecture/application/blueprint/blueprint_modules.md) - - [Type System]() -- [VM Layer](architecture/vm.md) -- [System Layer](architecture/system.md) - - [System Modules]() -- [Kernel Layer](architecture/kernel.md) - - [Move/Borrow Checking]() -- [Database Layer](architecture/database.md) -- [Data Architecture]() - - [Substates / SBOR]() +- [VM Layer](architecture/vm/README.md) +- [System Layer](architecture/system/README.md) + - [Nodes]() + - [Partitions]() + - [Substates]() + - [Blueprint Implementation]() + - [Object Implementation]() + - [System Module]() +- [Kernel Layer](architecture/kernel/README.md) + - [DB Partition Key]() + - [DB Sort Key]() +- [Database Layer](architecture/database/README.md) # Execution @@ -33,11 +36,11 @@ - [Bootup](execution/bootup.md) - [Runtime]() - [Shutdown](execution/shutdown.md) -- [WASM Environment](architecture/application/wasm_environment.md) +- [WASM Environment](execution/wasm_environment.md) - [Object Lifecycle]() - [Instantiation]() - - [State Reads/Writes]() - [Destruction]() +- [State Reads/Writes]() - [Invocations]() # Native Systems diff --git a/radix-engine/book/src/architecture/application/README.md b/radix-engine/book/src/architecture/application/README.md index 197b238946..09732c7a42 100644 --- a/radix-engine/book/src/architecture/application/README.md +++ b/radix-engine/book/src/architecture/application/README.md @@ -3,9 +3,10 @@ The application layer is responsible for defining high level logic which manipulates object state. -An application in Radix Engine defines a *Package*, which contain zero or more *Blueprints*. +An application is defined by a *Package*, which contain zero or more *Blueprints*. Each blueprint defines object type information and logic which can create/manipulate/destroy -objects of that blueprint type. +objects of that blueprint type. This logic may then be executed through function calls by other +objects/blueprints. diff --git a/radix-engine/book/src/architecture/application/wasm_environment.md b/radix-engine/book/src/architecture/application/wasm_environment.md deleted file mode 100644 index f65fdcc832..0000000000 --- a/radix-engine/book/src/architecture/application/wasm_environment.md +++ /dev/null @@ -1,24 +0,0 @@ -# WASM Environment - -## Function Entrypoint - -An exported function in WASM may be called if it is mapped via `export_name` in a function of a Blueprint Definition. -The argument to the function is a single `i64` which represents a buffer. The first 32 bits refers to a `BufferId` -and the second 32 bits refers to the length of the buffer. - -Once sufficient space has been allocated for the buffer, the contents of the buffer can be retrieved by using -the `buffer_consume` call. The contents of the buffer will match the sbor schema described in the function -schema of the Blueprint Definition. - -## System Calls - -Various `extern` functions are available to be called during execution. These are referred to as `system calls` -and provide the ability to read/write state, invoke methods and functions, and other system-related logic. - -The full set of calls can be found in [wasm_api.rs](../../../../../scrypto/src/engine/wasm_api.rs). - -## Function Return - -The return value from a called exported function in WASM must be an `i64` where the first 32 bits refers to the -32-bit address pointer and the second 32 bits refers to the size of the return object. The contents of the buffer -must match the return value schema of the function in the Blueprint Definition. diff --git a/radix-engine/book/src/architecture/database.md b/radix-engine/book/src/architecture/database.md index 4a79ce0cd5..02e60f370e 100644 --- a/radix-engine/book/src/architecture/database.md +++ b/radix-engine/book/src/architecture/database.md @@ -1 +1 @@ -# Database \ No newline at end of file +# Database Layer diff --git a/radix-engine/book/src/architecture/database/README.md b/radix-engine/book/src/architecture/database/README.md new file mode 100644 index 0000000000..b8e7b1219d --- /dev/null +++ b/radix-engine/book/src/architecture/database/README.md @@ -0,0 +1,2 @@ +# Database + diff --git a/radix-engine/book/src/architecture/kernel.md b/radix-engine/book/src/architecture/kernel.md deleted file mode 100644 index e7480f318d..0000000000 --- a/radix-engine/book/src/architecture/kernel.md +++ /dev/null @@ -1,8 +0,0 @@ -# Kernel Layer -The kernel layer is responsible for the two core functionalities of Radix Engine: storage access and communication between applications. This is somewhat similar to the traditional Operating System’s responsibility for disk and network access. - -For Radix Engine, this includes the following low-level management: - -* Check that move/borrow semantics are maintained on any invocation or data write. The single owner rule and borrow rules are enforced by the kernel. On failure on any of these rules, the transaction will panic. -* Manage transient vs. persistent objects. An object at any point in time may be in the global space or may be owned by a call frame. The kernel maintains correct pointers to these objects during runtime as references to these objects are passed around. -* Manage transaction state updates. The kernel keeps track of the state updates which have occurred during a transaction and which will be subsequently committed to the database at the end of the transaction. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/kernel/README.md b/radix-engine/book/src/architecture/kernel/README.md new file mode 100644 index 0000000000..dc13bf5124 --- /dev/null +++ b/radix-engine/book/src/architecture/kernel/README.md @@ -0,0 +1,5 @@ +# Kernel Layer + +The kernel layer implements Node/Partition/Substate abstraction on top of a key-value database as well +as maintains a call frame and transaction state updates, which are to be subsequently committed to the +database at the end of the transaction. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/layers.md b/radix-engine/book/src/architecture/layers.md index 24516b4e1c..f37e670205 100644 --- a/radix-engine/book/src/architecture/layers.md +++ b/radix-engine/book/src/architecture/layers.md @@ -4,11 +4,11 @@ Radix Engine is organized into 5 layers. Each layer has specific responsibilitie provides an API to the layer above. Middle layers also provide a Callback API which the layer above must implement. -| Layer Name | Layer ID | Responsibilities | -|-------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------| -| Application | 5 | Defines Blueprints and Application Logic | -| VM | 4 | Interprets Application Code | -| System | 3 | Type Checks during Runtime
Defines Package, Blueprint, Object abstractions
Defines System Standards such as Authorization and Versioning | -| Kernel | 2 | Maintains Call Frame Stack
Manages Ownership/Reference handling invariants
Provides State Virtualization Mechanism | -| Database | 1 | Interacts with a Read-Only Database | +| Layer Name | Layer ID | Responsibilities | +|-------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Application | 5 | Defines Blueprints and Application Logic | +| VM | 4 | Interprets Application Code | +| System | 3 | Defines Package, Blueprint, Object abstractions
Defines System Standards such as Authorization and Versioning
Type Checks during Runtime | +| Kernel | 2 | Defines Node, Partition, Substate abstractions
Maintains Call Frame Stack
Manages Ownership/Reference handling invariants
Provides State Virtualization Mechanism | +| Database | 1 | Defines PartitionKey, SortKey abstractions | diff --git a/radix-engine/book/src/architecture/system.md b/radix-engine/book/src/architecture/system.md deleted file mode 100644 index dcef9d3130..0000000000 --- a/radix-engine/book/src/architecture/system.md +++ /dev/null @@ -1,5 +0,0 @@ -# System Layer - -The System Layer is responsible for maintaining a set of System Modules, or pluggable software which can extend the functionality of the system. - -On every system call, each system module gets called before the system layer passes control to the kernel layer. When called, each system module may update some particular state (e.g. update fees spent) or panic to end the transaction (e.g. if the type checker fails). \ No newline at end of file diff --git a/radix-engine/book/src/architecture/system/README.md b/radix-engine/book/src/architecture/system/README.md new file mode 100644 index 0000000000..e60ab350c0 --- /dev/null +++ b/radix-engine/book/src/architecture/system/README.md @@ -0,0 +1,8 @@ +# System Layer + +The System Layer implements the application layer Package/Blueprint/Object abstraction on top of +the kernel Node/Partition/Substate abstraction. + +Additionally, the system layer maintains a set of System Modules, or pluggable software, which +extends the functionality of the system. For example, an Auth System Module provides a standard +mechanism for authorization/access control across the whole system. diff --git a/radix-engine/book/src/architecture/vm.md b/radix-engine/book/src/architecture/vm.md deleted file mode 100644 index 6744e1908d..0000000000 --- a/radix-engine/book/src/architecture/vm.md +++ /dev/null @@ -1,4 +0,0 @@ -# VM Layer -The VM Layer is responsible for providing the computing environment to the application layer. This includes a Turing-complete VM as well as the interface to access the system layer. - -Radix Engine currently supports two VMs: a Scrypto WASM VM used to execute Scrypto applications and a native VM which executes native packages which are compiled to the host’s environment. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/vm/README.md b/radix-engine/book/src/architecture/vm/README.md new file mode 100644 index 0000000000..0f47874e87 --- /dev/null +++ b/radix-engine/book/src/architecture/vm/README.md @@ -0,0 +1,7 @@ +# VM Layer + +The VM Layer is responsible for providing the computing environment to the application layer. This +includes a Turing-complete VM as well as the interface to access the system layer. + +Radix Engine currently supports two VMs: a Scrypto WASM VM used to execute Scrypto applications and +a native VM which executes native packages which are compiled to the host’s environment. \ No newline at end of file From 5f968e74f43c2e0a546802b6887e65093c7bc593 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Wed, 1 May 2024 12:58:03 -0500 Subject: [PATCH 21/47] Update README --- radix-engine/book/src/README.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/radix-engine/book/src/README.md b/radix-engine/book/src/README.md index acba8d045f..7df0710a6b 100644 --- a/radix-engine/book/src/README.md +++ b/radix-engine/book/src/README.md @@ -3,16 +3,10 @@ Radix Engine is a deterministic, transaction-based state machine that updates ledger state by incrementally executing transactions. -Radix Engine is Object-Oriented, enforces move/ownership semantics, and introduces easy pluggability -of stateful modules within the system. - -# Why? - Radix Engine was built out of the lack of Blockchain VMs specifically optimized for a DeFi shared computing environment in terms of usability, security, performance, and modularity. - - - - - +Unlike the EVM and other blockchain VMs, Radix Engine: +* Is Object-Oriented +* Enforces move/ownership semantics +* Introduces the ability to add system plugins to extend system functionality From 925c13aade02d0a10bf4c5bafaee411017046b56 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Thu, 2 May 2024 12:22:10 -0500 Subject: [PATCH 22/47] Add rustdocs to system api --- .../src/api/actor_key_value_entry_api.rs | 7 ++++- .../src/api/actor_sorted_index_api.rs | 3 -- .../src/api/blueprint_api.rs | 1 + radix-engine-interface/src/api/costing_api.rs | 9 ++++++ .../src/api/key_value_entry_api.rs | 7 +++++ .../src/api/key_value_store_api.rs | 4 ++- radix-engine-interface/src/api/mod.rs | 6 ++-- radix-engine-interface/src/api/object_api.rs | 6 +++- .../src/api/transaction_runtime_api.rs | 5 ++++ radix-engine/book/src/SUMMARY.md | 23 +++++++++------- radix-engine/book/src/execution/bootup.md | 25 ----------------- .../book/src/execution/environment/README.md | 19 +++++++++++++ radix-engine/book/src/execution/lifecycle.md | 17 ------------ .../book/src/execution/lifecycle/README.md | 21 ++++++++++++++ .../{ => lifecycle}/bootup.drawio.png | Bin .../book/src/execution/lifecycle/bootup.md | 26 ++++++++++++++++++ .../book/src/execution/lifecycle/runtime.md | 7 +++++ .../src/execution/{ => lifecycle}/shutdown.md | 0 .../book/src/execution/wasm_environment.md | 2 +- 19 files changed, 126 insertions(+), 62 deletions(-) delete mode 100644 radix-engine/book/src/execution/bootup.md create mode 100644 radix-engine/book/src/execution/environment/README.md delete mode 100644 radix-engine/book/src/execution/lifecycle.md create mode 100644 radix-engine/book/src/execution/lifecycle/README.md rename radix-engine/book/src/execution/{ => lifecycle}/bootup.drawio.png (100%) create mode 100644 radix-engine/book/src/execution/lifecycle/bootup.md create mode 100644 radix-engine/book/src/execution/lifecycle/runtime.md rename radix-engine/book/src/execution/{ => lifecycle}/shutdown.md (100%) diff --git a/radix-engine-interface/src/api/actor_key_value_entry_api.rs b/radix-engine-interface/src/api/actor_key_value_entry_api.rs index 509dd713eb..8ef2cfef29 100644 --- a/radix-engine-interface/src/api/actor_key_value_entry_api.rs +++ b/radix-engine-interface/src/api/actor_key_value_entry_api.rs @@ -5,7 +5,8 @@ use sbor::rust::fmt::Debug; use sbor::rust::vec::Vec; pub trait ClientActorKeyValueEntryApi { - /// If the key value entry doesn't exist, it uses the default "Option::None" + /// Returns a handle for a specified key value entry in a collection. If an invalid collection + /// index or key is passed an error is returned. fn actor_open_key_value_entry( &mut self, object_handle: ActorStateHandle, @@ -14,6 +15,8 @@ pub trait ClientActorKeyValueEntryApi { flags: LockFlags, ) -> Result; + /// Removes an entry from a collection. If an invalid collection index or key is passed an + /// error is returned, otherwise the encoding of a value of an entry is returned. fn actor_remove_key_value_entry( &mut self, object_handle: ActorStateHandle, @@ -21,6 +24,8 @@ pub trait ClientActorKeyValueEntryApi { key: &Vec, ) -> Result, E>; + /// Removes an entry from a collection. If an invalid collection index or key is passed an + /// error is returned, otherwise the value of an entry is returned. fn actor_remove_key_value_entry_typed( &mut self, object_handle: ActorStateHandle, diff --git a/radix-engine-interface/src/api/actor_sorted_index_api.rs b/radix-engine-interface/src/api/actor_sorted_index_api.rs index cb8a96095e..47e3b4fc7d 100644 --- a/radix-engine-interface/src/api/actor_sorted_index_api.rs +++ b/radix-engine-interface/src/api/actor_sorted_index_api.rs @@ -5,9 +5,6 @@ use radix_engine_interface::api::CollectionIndex; use sbor::rust::prelude::*; use sbor::rust::vec::Vec; -pub trait SortedIndexKeyPayloadMarker {} -pub trait SortedIndexEntryPayloadMarker {} - pub trait ClientActorSortedIndexApi { /// Inserts an entry into a sorted index fn actor_sorted_index_insert( diff --git a/radix-engine-interface/src/api/blueprint_api.rs b/radix-engine-interface/src/api/blueprint_api.rs index 6dfa231b2e..638a9133fd 100644 --- a/radix-engine-interface/src/api/blueprint_api.rs +++ b/radix-engine-interface/src/api/blueprint_api.rs @@ -13,6 +13,7 @@ pub trait ClientBlueprintApi { args: Vec, ) -> Result, E>; + /// Retrieves the schema of type under a blueprint fn resolve_blueprint_type( &mut self, blueprint_type_id: &BlueprintTypeIdentifier, diff --git a/radix-engine-interface/src/api/costing_api.rs b/radix-engine-interface/src/api/costing_api.rs index b0300e37a4..409773bc8e 100644 --- a/radix-engine-interface/src/api/costing_api.rs +++ b/radix-engine-interface/src/api/costing_api.rs @@ -9,21 +9,30 @@ pub trait ClientCostingApi { /// Add cost units to the reserve. This should never fail. fn lock_fee(&mut self, locked_fee: LiquidFungibleResource, contingent: bool); + /// Consume an amount of cost units. fn consume_cost_units(&mut self, costing_entry: ClientCostingEntry) -> Result<(), E>; + /// Retrieve the cost unit limit for the transaction fn execution_cost_unit_limit(&mut self) -> Result; + /// Retrieve the cost unit price in XRD fn execution_cost_unit_price(&mut self) -> Result; + /// Retrieve the cost unit limit for finalization fn finalization_cost_unit_limit(&mut self) -> Result; + /// Retrieve the cost unit finalization price in XRD fn finalization_cost_unit_price(&mut self) -> Result; + /// Retrieve the usd price of XRD fn usd_price(&mut self) -> Result; + /// Retrieve the maximum allowable royalty per function fn max_per_function_royalty_in_xrd(&mut self) -> Result; + /// Retrieve the tip percentage of the transaction fn tip_percentage(&mut self) -> Result; + /// Retrieve the current fee balance in XRD fn fee_balance(&mut self) -> Result; } diff --git a/radix-engine-interface/src/api/key_value_entry_api.rs b/radix-engine-interface/src/api/key_value_entry_api.rs index bcb0b6fe2a..b2fcb83306 100644 --- a/radix-engine-interface/src/api/key_value_entry_api.rs +++ b/radix-engine-interface/src/api/key_value_entry_api.rs @@ -7,8 +7,10 @@ pub trait KeyValueKeyPayloadMarker {} pub trait KeyValueEntryPayloadMarker {} pub trait ClientKeyValueEntryApi { + /// Reads the value of a key value entry fn key_value_entry_get(&mut self, handle: KeyValueEntryHandle) -> Result, E>; + /// Reads the value of a key value entry and decodes it into a specific type fn key_value_entry_get_typed( &mut self, handle: KeyValueEntryHandle, @@ -18,12 +20,14 @@ pub trait ClientKeyValueEntryApi { Ok(value) } + /// Set the value of a key value entry fn key_value_entry_set( &mut self, handle: KeyValueEntryHandle, buffer: Vec, ) -> Result<(), E>; + /// Set the value of a key value entry fn key_value_entry_set_typed( &mut self, handle: KeyValueEntryHandle, @@ -33,9 +37,12 @@ pub trait ClientKeyValueEntryApi { self.key_value_entry_set(handle, buffer) } + /// Remove the value of a key value entry fn key_value_entry_remove(&mut self, handle: KeyValueEntryHandle) -> Result, E>; + /// Lock the value of a key value entry making the value immutable fn key_value_entry_lock(&mut self, handle: KeyValueEntryHandle) -> Result<(), E>; + /// Close the handle into the key value entry rendering it unusable after close fn key_value_entry_close(&mut self, handle: KeyValueEntryHandle) -> Result<(), E>; } diff --git a/radix-engine-interface/src/api/key_value_store_api.rs b/radix-engine-interface/src/api/key_value_store_api.rs index 02b2cd2294..52316ce8ab 100644 --- a/radix-engine-interface/src/api/key_value_store_api.rs +++ b/radix-engine-interface/src/api/key_value_store_api.rs @@ -141,7 +141,8 @@ pub trait ClientKeyValueStoreApi { /// Creates a new key value store with a given schema fn key_value_store_new(&mut self, data_schema: KeyValueStoreDataSchema) -> Result; - /// Lock a key value store entry for reading/writing + + /// Open a key value store entry for reading/writing fn key_value_store_open_entry( &mut self, node_id: &NodeId, @@ -149,6 +150,7 @@ pub trait ClientKeyValueStoreApi { flags: LockFlags, ) -> Result; + /// Removes an entry from a key value store fn key_value_store_remove_entry( &mut self, node_id: &NodeId, diff --git a/radix-engine-interface/src/api/mod.rs b/radix-engine-interface/src/api/mod.rs index 6fa6266d7d..eaf7e05465 100644 --- a/radix-engine-interface/src/api/mod.rs +++ b/radix-engine-interface/src/api/mod.rs @@ -48,12 +48,12 @@ pub type CollectionIndex = u8; pub trait ClientApi: ClientActorApi + ClientActorKeyValueEntryApi - + ClientObjectApi + + ClientActorIndexApi + + ClientActorSortedIndexApi + ClientKeyValueStoreApi + ClientKeyValueEntryApi - + ClientActorSortedIndexApi - + ClientActorIndexApi + ClientFieldApi + + ClientObjectApi + ClientBlueprintApi + ClientCostingApi + ClientTransactionRuntimeApi diff --git a/radix-engine-interface/src/api/object_api.rs b/radix-engine-interface/src/api/object_api.rs index e14a530ef7..b7fa5a509a 100644 --- a/radix-engine-interface/src/api/object_api.rs +++ b/radix-engine-interface/src/api/object_api.rs @@ -241,18 +241,20 @@ pub trait ClientObjectApi { /// Get the outer object of a visible object fn get_outer_object(&mut self, node_id: &NodeId) -> Result; - /// Pre-allocates a global address, for a future globalization. + /// Allocates a global address, for a future globalization. fn allocate_global_address( &mut self, blueprint_id: BlueprintId, ) -> Result<(GlobalAddressReservation, GlobalAddress), E>; + /// Allocates a specific virtual global address fn allocate_virtual_global_address( &mut self, blueprint_id: BlueprintId, global_address: GlobalAddress, ) -> Result; + /// Retrieve the global address of a given address reservation fn get_reservation_address(&mut self, node_id: &NodeId) -> Result; /// Moves an object currently in the heap into the global space making @@ -264,6 +266,7 @@ pub trait ClientObjectApi { address_reservation: Option, ) -> Result; + /// Globalizes with a new inner object and emits an event fn globalize_with_address_and_create_inner_object_and_emit_event( &mut self, node_id: NodeId, @@ -283,6 +286,7 @@ pub trait ClientObjectApi { args: Vec, ) -> Result, E>; + /// Calls a direct access method on an object fn call_direct_access_method( &mut self, receiver: &NodeId, diff --git a/radix-engine-interface/src/api/transaction_runtime_api.rs b/radix-engine-interface/src/api/transaction_runtime_api.rs index a34c063f0d..30b71989c4 100644 --- a/radix-engine-interface/src/api/transaction_runtime_api.rs +++ b/radix-engine-interface/src/api/transaction_runtime_api.rs @@ -4,13 +4,18 @@ use radix_common::crypto::Hash; use radix_common::types::GlobalAddress; pub trait ClientTransactionRuntimeApi { + /// Encode an address into Bech32. The HRP part is dependent on the network which is running. fn bech32_encode_address(&mut self, address: GlobalAddress) -> Result; + /// Retrieve the hash of the current transaction which is running. fn get_transaction_hash(&mut self) -> Result; + /// Generate a unique id fn generate_ruid(&mut self) -> Result<[u8; 32], E>; + /// Emit a log message which will be available in the transaction receipt fn emit_log(&mut self, level: Level, message: String) -> Result<(), E>; + /// End the transaction immediately with a given message to be included in the transaction receipt fn panic(&mut self, message: String) -> Result<(), E>; } diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index 4674ad24d7..7815cbb07b 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -26,22 +26,25 @@ - [Object Implementation]() - [System Module]() - [Kernel Layer](architecture/kernel/README.md) + - [Call Frame]() - [DB Partition Key]() - [DB Sort Key]() - [Database Layer](architecture/database/README.md) # Execution -- [Transaction Lifecycle](execution/lifecycle.md) - - [Bootup](execution/bootup.md) - - [Runtime]() - - [Shutdown](execution/shutdown.md) -- [WASM Environment](execution/wasm_environment.md) -- [Object Lifecycle]() - - [Instantiation]() - - [Destruction]() -- [State Reads/Writes]() -- [Invocations]() +- [Transaction Lifecycle](execution/lifecycle/README.md) + - [Bootup](execution/lifecycle/bootup.md) + - [Runtime](execution/lifecycle/runtime.md) + - [Shutdown](execution/lifecycle/shutdown.md) +- [Application Environment](execution/environment/README.md) + - [Object Lifecycle]() + - [Instantiation]() + - [Destruction]() + - [Global Address Reservation]() + - [State Reads/Writes]() + - [Key Value Stores]() + - [Invocations]() # Native Systems diff --git a/radix-engine/book/src/execution/bootup.md b/radix-engine/book/src/execution/bootup.md deleted file mode 100644 index ac6a0fc898..0000000000 --- a/radix-engine/book/src/execution/bootup.md +++ /dev/null @@ -1,25 +0,0 @@ -# Transaction Bootup - -The initialization of a transaction execution consists of two steps: -1. Initialize Stack -2. Invoke Transaction Processor - -![](bootup.drawio.png) - -## Initialize Stack - -Before a transaction is executed, initialization of the Kernel/System/VM stack occurs. During this -initialization phase, configuration is loaded from the database and the state of each layer is -initialized. - -For example, during System initialization the system modules to run are decided on. -If we are executing in preview mode with auth disabled, the auth system module may be disabled. - -The code for this can be found in [kernel.rs](../../src/kernel/kernel.rs) in the `Bootloader::execute` -method. - -## Invoke Transaction Processor - -Once the entire stack has been initialized along with the initial call frame, an invocation of a -well-known blueprint, `TRANSACTION_PROCESSOR`, is made with the arguments specified in the transaction. -From this point forward, normal transaction execution occurs. diff --git a/radix-engine/book/src/execution/environment/README.md b/radix-engine/book/src/execution/environment/README.md new file mode 100644 index 0000000000..e44cc9c061 --- /dev/null +++ b/radix-engine/book/src/execution/environment/README.md @@ -0,0 +1,19 @@ +# Application Environment + +## Call Frame + +On function entry a new call frame is created for the execution of the function. The call frame +contains all owned and referenced objects usable by the running function. + +The System layer exposes an API which only allows state to be read from and written to by the current +*actor*, or object which is being called. + + +The application layer +also accepts an SBOR encoded value representing the argument passed into the function. All owned objects +and referenced objects in the argument is guaranteed to be valid (i.e. owned/referenced in the current +call frame). + + +All references in the +frame are \ No newline at end of file diff --git a/radix-engine/book/src/execution/lifecycle.md b/radix-engine/book/src/execution/lifecycle.md deleted file mode 100644 index cee788466b..0000000000 --- a/radix-engine/book/src/execution/lifecycle.md +++ /dev/null @@ -1,17 +0,0 @@ -# Transaction Lifecycle - -Radix Engine is a state machine which follows: -``` -RadixEngine(State, Transaction) -> StateChange -``` - -There are three stages in the transaction lifecycle: -1. Bootup -2. Execution -3. Shutdown - -Bootup consists of setting up the state of the layered stack. - -Execution is running application logic. - -Shutdown is cleaning up the layered stack and creating the final StateChange receipt. \ No newline at end of file diff --git a/radix-engine/book/src/execution/lifecycle/README.md b/radix-engine/book/src/execution/lifecycle/README.md new file mode 100644 index 0000000000..212011ee99 --- /dev/null +++ b/radix-engine/book/src/execution/lifecycle/README.md @@ -0,0 +1,21 @@ +# Transaction Lifecycle + +Radix Engine is a transactional state machine which accepts a transaction and a given state and +outputs a state change. + +``` +radix_engine(State, Transaction) -> (StateChange, Output) +``` + +The state change can then be applied to the database to update it's state: + +``` +state_commit(State, StateChange) -> State +``` + +## Three Stages + +There are three stages in the transaction lifecycle: +1. *Bootup*, which consists of initializing the layers of the stack +2. *Execution*, which is the execution of the application logic specified by the transaction +3. *Shutdown*, which consists of cleaning up each layer and creating the final StateChange and Output diff --git a/radix-engine/book/src/execution/bootup.drawio.png b/radix-engine/book/src/execution/lifecycle/bootup.drawio.png similarity index 100% rename from radix-engine/book/src/execution/bootup.drawio.png rename to radix-engine/book/src/execution/lifecycle/bootup.drawio.png diff --git a/radix-engine/book/src/execution/lifecycle/bootup.md b/radix-engine/book/src/execution/lifecycle/bootup.md new file mode 100644 index 0000000000..125de422c6 --- /dev/null +++ b/radix-engine/book/src/execution/lifecycle/bootup.md @@ -0,0 +1,26 @@ +# Transaction Bootup + +The initialization of a transaction execution consists of two steps: +1. Initialize Stack +2. Invoke Transaction Processor + +![](bootup.drawio.png) + +## Initialize Stack + +Before a transaction is executed, initialization of the Kernel/System/VM stack occurs. During this +initialization phase, configuration is loaded from the database and the state of each layer is +initialized. + +| Layer | Initialization Description | +|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Kernel | Load Kernel version
Check transaction references
Create Initial Call Frame | +| System | Load System module configurations
Verify transaction has not been previously executed
Verify transaction is valid within epoch bounds
Initialize enabled System Modules | +| VM | Load Scrypto VM version | + + +## Invoke Transaction Processor + +Once the entire stack has been initialized along with the initial call frame, an invocation of a +well-known blueprint, `TRANSACTION_PROCESSOR`, is made with the arguments specified in the transaction. +From this point forward, normal transaction execution occurs. diff --git a/radix-engine/book/src/execution/lifecycle/runtime.md b/radix-engine/book/src/execution/lifecycle/runtime.md new file mode 100644 index 0000000000..d823b6ee61 --- /dev/null +++ b/radix-engine/book/src/execution/lifecycle/runtime.md @@ -0,0 +1,7 @@ +# Transaction Runtime + +Once transaction bootup has finished, the `TRANSACTION_PROCESSOR` blueprint function `run` is then +executed with transaction data as its argument. It executes on top of the initial call frame created +during kernel initialization. + +Once the `run` function has finished executing transaction shutdown begins. \ No newline at end of file diff --git a/radix-engine/book/src/execution/shutdown.md b/radix-engine/book/src/execution/lifecycle/shutdown.md similarity index 100% rename from radix-engine/book/src/execution/shutdown.md rename to radix-engine/book/src/execution/lifecycle/shutdown.md diff --git a/radix-engine/book/src/execution/wasm_environment.md b/radix-engine/book/src/execution/wasm_environment.md index 84a5952980..be9a93460a 100644 --- a/radix-engine/book/src/execution/wasm_environment.md +++ b/radix-engine/book/src/execution/wasm_environment.md @@ -1 +1 @@ -# WASM Environment +# Application Environment From fb5c177d83965b90ce4b9ed4444c210219f05580 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Thu, 2 May 2024 14:58:53 -0500 Subject: [PATCH 23/47] Add object lifecycle docs --- radix-engine-interface/src/api/mod.rs | 2 +- radix-engine/book/src/SUMMARY.md | 8 +-- .../book/src/execution/environment/README.md | 31 +++++++----- .../src/execution/environment/invocations.md | 30 ++++++++++++ .../environment/object_lifecycle.drawio | 49 +++++++++++++++++++ .../environment/object_lifecycle.drawio.svg | 4 ++ .../execution/environment/object_lifecycle.md | 36 ++++++++++++++ .../book/src/execution/wasm_environment.md | 1 - 8 files changed, 142 insertions(+), 19 deletions(-) create mode 100644 radix-engine/book/src/execution/environment/invocations.md create mode 100644 radix-engine/book/src/execution/environment/object_lifecycle.drawio create mode 100644 radix-engine/book/src/execution/environment/object_lifecycle.drawio.svg create mode 100644 radix-engine/book/src/execution/environment/object_lifecycle.md delete mode 100644 radix-engine/book/src/execution/wasm_environment.md diff --git a/radix-engine-interface/src/api/mod.rs b/radix-engine-interface/src/api/mod.rs index eaf7e05465..b7fbb284d6 100644 --- a/radix-engine-interface/src/api/mod.rs +++ b/radix-engine-interface/src/api/mod.rs @@ -42,7 +42,7 @@ pub const ACTOR_REF_AUTH_ZONE: ActorRefHandle = 8u32; pub type FieldIndex = u8; pub type CollectionIndex = u8; -/// Interface of the system, for blueprints and Node modules. +/// Interface of the system, for blueprints and system modules. /// /// For WASM blueprints, only a subset of the API is exposed at the moment. pub trait ClientApi: diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index 7815cbb07b..7c83baf9a2 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -38,13 +38,9 @@ - [Runtime](execution/lifecycle/runtime.md) - [Shutdown](execution/lifecycle/shutdown.md) - [Application Environment](execution/environment/README.md) - - [Object Lifecycle]() - - [Instantiation]() - - [Destruction]() - - [Global Address Reservation]() + - [Invocations](execution/environment/invocations.md) + - [Object Lifecycle](execution/environment/object_lifecycle.md) - [State Reads/Writes]() - - [Key Value Stores]() - - [Invocations]() # Native Systems diff --git a/radix-engine/book/src/execution/environment/README.md b/radix-engine/book/src/execution/environment/README.md index e44cc9c061..cf36c69562 100644 --- a/radix-engine/book/src/execution/environment/README.md +++ b/radix-engine/book/src/execution/environment/README.md @@ -1,19 +1,28 @@ # Application Environment -## Call Frame +Every method/function execution has a call frame associated with it. -On function entry a new call frame is created for the execution of the function. The call frame -contains all owned and referenced objects usable by the running function. +A call frame contains all owned and referenced objects usable by the running function. These objects +are referrable by `NodeId`. -The System layer exposes an API which only allows state to be read from and written to by the current -*actor*, or object which is being called. +## Invocations +Owned and referenced objects may have methods invoked (creating a new call frame). Owned objects may be +passed in as arguments and may be received in these invocations. -The application layer -also accepts an SBOR encoded value representing the argument passed into the function. All owned objects -and referenced objects in the argument is guaranteed to be valid (i.e. owned/referenced in the current -call frame). +## Object Creation/Destruction/Globalization +Objects of the current blueprint may be instantiated, creating a new owned object into the call frame, +or dropped, in which case the owned object gets removed from the call frame. -All references in the -frame are \ No newline at end of file +## Actor State Read/Write + +A call frame also contains a reference to the *actor*, or callee object (i.e. *self* in object-oriented +languages). This is maintained to allow read/writes of state for the given actor. + +## Other System Functions + +A set of other system functions are available to the application layer. Currently these include: +* Costing +* Transaction Runtime +* Crypto Utils \ No newline at end of file diff --git a/radix-engine/book/src/execution/environment/invocations.md b/radix-engine/book/src/execution/environment/invocations.md new file mode 100644 index 0000000000..3f52712338 --- /dev/null +++ b/radix-engine/book/src/execution/environment/invocations.md @@ -0,0 +1,30 @@ +# Invocations + +An invocation is started by the application layer by calling one of the invocation system calls: +* `object_call_method` +* `object_call_direct_access_method` +* `object_call_module_method` +* `blueprint_call_function` + +On one of these calls, the system then follows three phases: +1. Call Frame Setup +2. Execution +3. Call Frame Exit and Return + +## Call Frame Setup + +System module does its own checks (e.g. auth). + +Kernel invoke is called which setups a new call frame. The passed in objects in the arguments are verified +to be valid. + +## Execution + +Once the new call frame is setup, execution is passed to the application layer which may then execute it's +own logic in its application environment. + +## Call Frame Exit + +Once finished the system layer checks that the return value is of the correct schema given by the +blueprint definition. The kernel verifies that owned objects and references in the return value are +valid and the caller call frame is updated with any of these owned objects/references. \ No newline at end of file diff --git a/radix-engine/book/src/execution/environment/object_lifecycle.drawio b/radix-engine/book/src/execution/environment/object_lifecycle.drawio new file mode 100644 index 0000000000..f0451fa059 --- /dev/null +++ b/radix-engine/book/src/execution/environment/object_lifecycle.drawio @@ -0,0 +1,49 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/radix-engine/book/src/execution/environment/object_lifecycle.drawio.svg b/radix-engine/book/src/execution/environment/object_lifecycle.drawio.svg new file mode 100644 index 0000000000..11d99b2ed3 --- /dev/null +++ b/radix-engine/book/src/execution/environment/object_lifecycle.drawio.svg @@ -0,0 +1,4 @@ + + + +
Owned By CallFrame
Instantiate
Drop
Globalized
Globalize
Owned By Another Object
Move
 \ No newline at end of file diff --git a/radix-engine/book/src/execution/environment/object_lifecycle.md b/radix-engine/book/src/execution/environment/object_lifecycle.md new file mode 100644 index 0000000000..97374ce16c --- /dev/null +++ b/radix-engine/book/src/execution/environment/object_lifecycle.md @@ -0,0 +1,36 @@ +# Object Lifecycle + +![](object_lifecycle.drawio.svg) + +## Instantiation + +An object may be instantiated by using one of the system calls: +* `object_new_simple_object` +* `object_new_object` + +On instantiation the set of features, generic arguments, and initial state must be passed in to +construct the object. Only blueprints of the currently acting package may be instantiated. If the +blueprint is an inner blueprint, only an acting outer blueprint component may instantiate that inner +blueprint. + +## Destruction + +An object may be dropped by using the `object_drop` system call. + +## Globalization + +An object may be globalized using one of the system calls: +* `object_globalize` +* `object_globalize_with_address_and_create_inner_object_and_emit_event` + +Once globalized an object is associated with a global address and may be referenced without ownership +of the object. Thus, it may be referenced in a transaction or in blueprint code. + +## Moved to ownership by another object + +A call frame owned object may be moved to ownership by another object if it is moved via one of the +system calls: +* `object_new_simple_object` +* `object_new_object` +* `key_value_entry_set` +* `field_write` diff --git a/radix-engine/book/src/execution/wasm_environment.md b/radix-engine/book/src/execution/wasm_environment.md deleted file mode 100644 index be9a93460a..0000000000 --- a/radix-engine/book/src/execution/wasm_environment.md +++ /dev/null @@ -1 +0,0 @@ -# Application Environment From 452156abb4b175545570beba5fed9aee606029c8 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Thu, 2 May 2024 15:22:41 -0500 Subject: [PATCH 24/47] More documentation --- radix-engine/book/src/SUMMARY.md | 13 ++++++------ .../environment/state_reads_writes.md | 20 ++++++++++++++++++ .../README.md | 0 .../bootup.drawio.png | Bin .../bootup.md | 0 .../runtime.md | 0 .../shutdown.md | 0 7 files changed, 27 insertions(+), 6 deletions(-) create mode 100644 radix-engine/book/src/execution/environment/state_reads_writes.md rename radix-engine/book/src/execution/{lifecycle => transaction_lifecycle}/README.md (100%) rename radix-engine/book/src/execution/{lifecycle => transaction_lifecycle}/bootup.drawio.png (100%) rename radix-engine/book/src/execution/{lifecycle => transaction_lifecycle}/bootup.md (100%) rename radix-engine/book/src/execution/{lifecycle => transaction_lifecycle}/runtime.md (100%) rename radix-engine/book/src/execution/{lifecycle => transaction_lifecycle}/shutdown.md (100%) diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index 7c83baf9a2..783dfe119b 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -33,17 +33,18 @@ # Execution -- [Transaction Lifecycle](execution/lifecycle/README.md) - - [Bootup](execution/lifecycle/bootup.md) - - [Runtime](execution/lifecycle/runtime.md) - - [Shutdown](execution/lifecycle/shutdown.md) +- [Transaction Lifecycle](execution/transaction_lifecycle/README.md) + - [Bootup](execution/transaction_lifecycle/bootup.md) + - [Runtime](execution/transaction_lifecycle/runtime.md) + - [Shutdown](execution/transaction_lifecycle/shutdown.md) - [Application Environment](execution/environment/README.md) + - [Objects](execution/environment/object_lifecycle.md) - [Invocations](execution/environment/invocations.md) - - [Object Lifecycle](execution/environment/object_lifecycle.md) - - [State Reads/Writes]() + - [State Reads/Writes](execution/environment/state_reads_writes.md) # Native Systems +- [Type Checking]() - [Authorization](native/access_control/README) - [Role Definition](native/access_control/role_definition.md) - [Role Assignment](native/access_control/role_assignment.md) diff --git a/radix-engine/book/src/execution/environment/state_reads_writes.md b/radix-engine/book/src/execution/environment/state_reads_writes.md new file mode 100644 index 0000000000..3526e5cc7e --- /dev/null +++ b/radix-engine/book/src/execution/environment/state_reads_writes.md @@ -0,0 +1,20 @@ +# State Reads/Writes + +State Reads and Writes from objects may be only be done by the current actor using the following system calls: +* `actor_open_field` +* `actor_open_key_value_entry` +* `actor_index_insert` +* `actor_index_remove` +* `actor_index_scan_keys` +* `actor_index_drain` +* `actor_sorted_index_insert` +* `actor_sorted_index_remove` +* `actor_sorted_index_scan` + +Key Value Stores are a special type of object though which may be read/written to as long as one has +a reference to that key value store. This is accessible via the system call: +* `key_value_store_open_entry` + +## Fields + +## Collections \ No newline at end of file diff --git a/radix-engine/book/src/execution/lifecycle/README.md b/radix-engine/book/src/execution/transaction_lifecycle/README.md similarity index 100% rename from radix-engine/book/src/execution/lifecycle/README.md rename to radix-engine/book/src/execution/transaction_lifecycle/README.md diff --git a/radix-engine/book/src/execution/lifecycle/bootup.drawio.png b/radix-engine/book/src/execution/transaction_lifecycle/bootup.drawio.png similarity index 100% rename from radix-engine/book/src/execution/lifecycle/bootup.drawio.png rename to radix-engine/book/src/execution/transaction_lifecycle/bootup.drawio.png diff --git a/radix-engine/book/src/execution/lifecycle/bootup.md b/radix-engine/book/src/execution/transaction_lifecycle/bootup.md similarity index 100% rename from radix-engine/book/src/execution/lifecycle/bootup.md rename to radix-engine/book/src/execution/transaction_lifecycle/bootup.md diff --git a/radix-engine/book/src/execution/lifecycle/runtime.md b/radix-engine/book/src/execution/transaction_lifecycle/runtime.md similarity index 100% rename from radix-engine/book/src/execution/lifecycle/runtime.md rename to radix-engine/book/src/execution/transaction_lifecycle/runtime.md diff --git a/radix-engine/book/src/execution/lifecycle/shutdown.md b/radix-engine/book/src/execution/transaction_lifecycle/shutdown.md similarity index 100% rename from radix-engine/book/src/execution/lifecycle/shutdown.md rename to radix-engine/book/src/execution/transaction_lifecycle/shutdown.md From 6f45cd9ac5911a30a2174714dcc3799af47f256d Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Thu, 2 May 2024 17:35:59 -0500 Subject: [PATCH 25/47] More documentation --- radix-engine-interface/src/api/field_api.rs | 6 ++ radix-engine/book/src/README.md | 3 +- radix-engine/book/src/SUMMARY.md | 3 + .../src/architecture/application/README.md | 10 +- .../application/blueprint/inner_outer.md | 7 +- .../architecture/application/object/README.md | 8 ++ .../object/inner_outer_objects.drawio | 93 +++++++++++++++++++ .../object/inner_outer_objects.drawio.svg | 4 + .../application/object/inner_outer_objects.md | 7 ++ .../application/object/object_model.drawio | 52 +++++++++++ .../object/object_model.drawio.svg | 4 + .../application/object/object_modules.md | 12 +++ radix-engine/book/src/architecture/layers.md | 14 +-- 13 files changed, 201 insertions(+), 22 deletions(-) create mode 100644 radix-engine/book/src/architecture/application/object/README.md create mode 100644 radix-engine/book/src/architecture/application/object/inner_outer_objects.drawio create mode 100644 radix-engine/book/src/architecture/application/object/inner_outer_objects.drawio.svg create mode 100644 radix-engine/book/src/architecture/application/object/inner_outer_objects.md create mode 100644 radix-engine/book/src/architecture/application/object/object_model.drawio create mode 100644 radix-engine/book/src/architecture/application/object/object_model.drawio.svg create mode 100644 radix-engine/book/src/architecture/application/object/object_modules.md diff --git a/radix-engine-interface/src/api/field_api.rs b/radix-engine-interface/src/api/field_api.rs index 1abe6a7ed2..728e378abb 100644 --- a/radix-engine-interface/src/api/field_api.rs +++ b/radix-engine-interface/src/api/field_api.rs @@ -33,16 +33,20 @@ impl FieldPayloadMarker for &T {} /// A high level api to read/write fields pub trait ClientFieldApi { + // Retrieve the value of a field fn field_read(&mut self, handle: FieldHandle) -> Result, E>; + // Retrieve the value of a field fn field_read_typed(&mut self, handle: FieldHandle) -> Result { let buf = self.field_read(handle)?; let typed_substate: S = scrypto_decode(&buf).map_err(|e| e).unwrap(); Ok(typed_substate) } + // Write a value to a field fn field_write(&mut self, handle: FieldHandle, buffer: Vec) -> Result<(), E>; + // Write a value to a field fn field_write_typed( &mut self, handle: FieldHandle, @@ -52,7 +56,9 @@ pub trait ClientFieldApi { self.field_write(handle, buf) } + // Lock a field such that it is immutable fn field_lock(&mut self, handle: FieldHandle) -> Result<(), E>; + // Close a field handle so that it is no longer usable fn field_close(&mut self, handle: FieldHandle) -> Result<(), E>; } diff --git a/radix-engine/book/src/README.md b/radix-engine/book/src/README.md index 7df0710a6b..0ffa9a61f4 100644 --- a/radix-engine/book/src/README.md +++ b/radix-engine/book/src/README.md @@ -8,5 +8,6 @@ shared computing environment in terms of usability, security, performance, and m Unlike the EVM and other blockchain VMs, Radix Engine: * Is Object-Oriented +* Is Type-Safe * Enforces move/ownership semantics -* Introduces the ability to add system plugins to extend system functionality +* Has the ability to add system plugins to extend system functionality diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index 783dfe119b..a81f1ac04b 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -6,6 +6,9 @@ - [Layered Architecture](architecture/layers.md) - [Application Layer](architecture/application/README.md) + - [Object Model](architecture/application/object/README.md) + - [Inner and Outer Objects](architecture/application/object/inner_outer_objects.md) + - [Object Modules](architecture/application/object/object_modules.md) - [Blueprint](architecture/application/blueprint/README.md) - [Inner and Outer Blueprints](architecture/application/blueprint/inner_outer.md) - [Transience](architecture/application/blueprint/transience.md) diff --git a/radix-engine/book/src/architecture/application/README.md b/radix-engine/book/src/architecture/application/README.md index 09732c7a42..769e4e2c3a 100644 --- a/radix-engine/book/src/architecture/application/README.md +++ b/radix-engine/book/src/architecture/application/README.md @@ -1,14 +1,8 @@ # Application Layer -The application layer is responsible for defining high level logic which manipulates -object state. +The application layer is responsible for defining high level logic which manipulates objects. An application is defined by a *Package*, which contain zero or more *Blueprints*. Each blueprint defines object type information and logic which can create/manipulate/destroy -objects of that blueprint type. This logic may then be executed through function calls by other -objects/blueprints. - - - - +objects of that blueprint type. diff --git a/radix-engine/book/src/architecture/application/blueprint/inner_outer.md b/radix-engine/book/src/architecture/application/blueprint/inner_outer.md index be1fab67e4..3a7974f550 100644 --- a/radix-engine/book/src/architecture/application/blueprint/inner_outer.md +++ b/radix-engine/book/src/architecture/application/blueprint/inner_outer.md @@ -7,9 +7,4 @@ an associated outer blueprint defined in the same package. ![](inner_outer_blueprints.drawio.svg) -Inner blueprint objects may only be instantiated by an associated outer blueprint object. After -instantiation, inner blueprint objects may directly access the state of its outer blueprint component -avoiding invocation and new call frame overhead + costs. - -![](inner_outer_objects.drawio.svg) - +Inner blueprint objects may only be instantiated by an object of the associated outer blueprint. diff --git a/radix-engine/book/src/architecture/application/object/README.md b/radix-engine/book/src/architecture/application/object/README.md new file mode 100644 index 0000000000..5b8dac743e --- /dev/null +++ b/radix-engine/book/src/architecture/application/object/README.md @@ -0,0 +1,8 @@ +# Object Model + +Unlike Ethereum where the ledger state is a flat mapping between addresses and account states, Radix +Engine organizes its state into a forest of *objects*, each of which has a blueprint type. Child +objects are exclusively owned by its parent in the tree hierarchy. Each root object is assigned a +*global address*. + +![](object_model.drawio.svg) \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/object/inner_outer_objects.drawio b/radix-engine/book/src/architecture/application/object/inner_outer_objects.drawio new file mode 100644 index 0000000000..e19a32b4bf --- /dev/null +++ b/radix-engine/book/src/architecture/application/object/inner_outer_objects.drawio @@ -0,0 +1,93 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/radix-engine/book/src/architecture/application/object/inner_outer_objects.drawio.svg b/radix-engine/book/src/architecture/application/object/inner_outer_objects.drawio.svg new file mode 100644 index 0000000000..df2c5e6902 --- /dev/null +++ b/radix-engine/book/src/architecture/application/object/inner_outer_objects.drawio.svg @@ -0,0 +1,4 @@ + + + +
Account
Key Value Store
Vault
Vault
Radiswap
Vault
Resource Manager
Resource Manager
 \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/object/inner_outer_objects.md b/radix-engine/book/src/architecture/application/object/inner_outer_objects.md new file mode 100644 index 0000000000..bca080bbef --- /dev/null +++ b/radix-engine/book/src/architecture/application/object/inner_outer_objects.md @@ -0,0 +1,7 @@ +# Inner and Outer Objects + +Objects which are Inner Blueprints will have an associated Outer object of a given outer +Blueprint. Inner objects may directly access the state of its outer object avoiding +invocation and new call frame overhead + costs. + +![](inner_outer_objects.drawio.svg) \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/object/object_model.drawio b/radix-engine/book/src/architecture/application/object/object_model.drawio new file mode 100644 index 0000000000..178a13d95f --- /dev/null +++ b/radix-engine/book/src/architecture/application/object/object_model.drawio @@ -0,0 +1,52 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/radix-engine/book/src/architecture/application/object/object_model.drawio.svg b/radix-engine/book/src/architecture/application/object/object_model.drawio.svg new file mode 100644 index 0000000000..eee882c19d --- /dev/null +++ b/radix-engine/book/src/architecture/application/object/object_model.drawio.svg @@ -0,0 +1,4 @@ + + + +
Account
Key Value Store
Vault
Vault
Radiswap
Vault
 \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/object/object_modules.md b/radix-engine/book/src/architecture/application/object/object_modules.md new file mode 100644 index 0000000000..647ffa95e6 --- /dev/null +++ b/radix-engine/book/src/architecture/application/object/object_modules.md @@ -0,0 +1,12 @@ +# Object Modules + +The system may define additional state/logic to be stored per globalized object known as +an *Object Module*. + +An Object Module itself has a Blueprint type along with associated logic to manipulate +the state of the object module. + +Currently, there exists three object modules: +* RoleAssignment Object Module +* Metadata Object Module +* Royalty Object Module diff --git a/radix-engine/book/src/architecture/layers.md b/radix-engine/book/src/architecture/layers.md index f37e670205..5db4768afb 100644 --- a/radix-engine/book/src/architecture/layers.md +++ b/radix-engine/book/src/architecture/layers.md @@ -4,11 +4,11 @@ Radix Engine is organized into 5 layers. Each layer has specific responsibilitie provides an API to the layer above. Middle layers also provide a Callback API which the layer above must implement. -| Layer Name | Layer ID | Responsibilities | -|-------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Application | 5 | Defines Blueprints and Application Logic | -| VM | 4 | Interprets Application Code | -| System | 3 | Defines Package, Blueprint, Object abstractions
Defines System Standards such as Authorization and Versioning
Type Checks during Runtime | -| Kernel | 2 | Defines Node, Partition, Substate abstractions
Maintains Call Frame Stack
Manages Ownership/Reference handling invariants
Provides State Virtualization Mechanism | -| Database | 1 | Defines PartitionKey, SortKey abstractions | +| Layer Name | Layer ID | Responsibilities | +|-------------|----------|--------------------------------------------------------------------------------------------------------------------------| +| Application | 5 | Defines Blueprint Application Logic | +| VM | 4 | Executes Application Code | +| System | 3 | Defines Package, Blueprint, Object abstractions
Defines System Standards such as Authorization and Versioning | +| Kernel | 2 | Defines Node, Partition, Substate abstractions
Maintains Call Frame Stack
Maintains Ownership/Reference invariants | +| Database | 1 | Defines PartitionKey, SortKey abstractions | From eed6bcca7839b4879da6601e3902e0de37471176 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Fri, 3 May 2024 20:17:37 -0500 Subject: [PATCH 26/47] Add more documentation --- radix-engine-interface/src/api/key_value_store_api.rs | 1 - radix-engine/book/src/README.md | 3 +-- radix-engine/book/src/architecture/system/README.md | 11 ++++++----- radix-engine/book/src/architecture/vm/README.md | 10 ++++++---- .../blueprints/consensus_manager/consensus_manager.rs | 5 ++--- .../src/blueprints/consensus_manager/package.rs | 5 ++--- .../resource/fungible/fungible_resource_manager.rs | 7 +++---- 7 files changed, 20 insertions(+), 22 deletions(-) diff --git a/radix-engine-interface/src/api/key_value_store_api.rs b/radix-engine-interface/src/api/key_value_store_api.rs index 52316ce8ab..d5ef03815e 100644 --- a/radix-engine-interface/src/api/key_value_store_api.rs +++ b/radix-engine-interface/src/api/key_value_store_api.rs @@ -141,7 +141,6 @@ pub trait ClientKeyValueStoreApi { /// Creates a new key value store with a given schema fn key_value_store_new(&mut self, data_schema: KeyValueStoreDataSchema) -> Result; - /// Open a key value store entry for reading/writing fn key_value_store_open_entry( &mut self, diff --git a/radix-engine/book/src/README.md b/radix-engine/book/src/README.md index 0ffa9a61f4..a68e28b60c 100644 --- a/radix-engine/book/src/README.md +++ b/radix-engine/book/src/README.md @@ -7,7 +7,6 @@ Radix Engine was built out of the lack of Blockchain VMs specifically optimized shared computing environment in terms of usability, security, performance, and modularity. Unlike the EVM and other blockchain VMs, Radix Engine: -* Is Object-Oriented -* Is Type-Safe +* Is Object-Oriented and Type-Safe * Enforces move/ownership semantics * Has the ability to add system plugins to extend system functionality diff --git a/radix-engine/book/src/architecture/system/README.md b/radix-engine/book/src/architecture/system/README.md index e60ab350c0..f9850db4a8 100644 --- a/radix-engine/book/src/architecture/system/README.md +++ b/radix-engine/book/src/architecture/system/README.md @@ -1,8 +1,9 @@ # System Layer -The System Layer implements the application layer Package/Blueprint/Object abstraction on top of -the kernel Node/Partition/Substate abstraction. +The System Layer is responsible for: +* Defining the Package/Blueprint/Object abstraction +* Maintaining a set of System Modules, or pluggable software, which extends the +functionality of the system. -Additionally, the system layer maintains a set of System Modules, or pluggable software, which -extends the functionality of the system. For example, an Auth System Module provides a standard -mechanism for authorization/access control across the whole system. +The System Layer implements this by defining the Kernel Callback Object and using the +kernel Node/Partition/Substate abstractions. diff --git a/radix-engine/book/src/architecture/vm/README.md b/radix-engine/book/src/architecture/vm/README.md index 0f47874e87..341d638f13 100644 --- a/radix-engine/book/src/architecture/vm/README.md +++ b/radix-engine/book/src/architecture/vm/README.md @@ -1,7 +1,9 @@ # VM Layer -The VM Layer is responsible for providing the computing environment to the application layer. This -includes a Turing-complete VM as well as the interface to access the system layer. +The VM Layer is responsible for providing a Turing-complete computing environment and the +system layer interface to the application layer. The VM Layer does this by defining the +System Callback Object. -Radix Engine currently supports two VMs: a Scrypto WASM VM used to execute Scrypto applications and -a native VM which executes native packages which are compiled to the host’s environment. \ No newline at end of file +Radix Engine currently supports two VMs: +* A Scrypto WASM VM which exposes the system layer interface through WASM extern functions +* A Native VM which is currently compiled directly in the host's environment with the Radix Engine diff --git a/radix-engine/src/blueprints/consensus_manager/consensus_manager.rs b/radix-engine/src/blueprints/consensus_manager/consensus_manager.rs index e0ffa52f48..5223920602 100644 --- a/radix-engine/src/blueprints/consensus_manager/consensus_manager.rs +++ b/radix-engine/src/blueprints/consensus_manager/consensus_manager.rs @@ -3,7 +3,6 @@ use crate::blueprints::consensus_manager::VALIDATOR_ROLE; use crate::errors::ApplicationError; use crate::errors::RuntimeError; use crate::internal_prelude::*; -use crate::kernel::kernel_api::KernelNodeApi; use radix_common::constants::AuthAddresses; use radix_engine_interface::api::field_api::LockFlags; use radix_engine_interface::api::object_api::ModuleId; @@ -992,7 +991,7 @@ impl ConsensusManagerBlueprint { fn get_validator_xrd_cost(api: &mut Y) -> Result, RuntimeError> where - Y: KernelNodeApi + ClientApi, + Y: ClientApi, { let manager_handle = api.actor_open_field( ACTOR_STATE_SELF, @@ -1040,7 +1039,7 @@ impl ConsensusManagerBlueprint { api: &mut Y, ) -> Result<(ComponentAddress, Bucket, Bucket), RuntimeError> where - Y: KernelNodeApi + ClientApi, + Y: ClientApi, { if !xrd_payment.resource_address(api)?.eq(&XRD) { return Err(RuntimeError::ApplicationError( diff --git a/radix-engine/src/blueprints/consensus_manager/package.rs b/radix-engine/src/blueprints/consensus_manager/package.rs index c6c0a765ac..c9e4175814 100644 --- a/radix-engine/src/blueprints/consensus_manager/package.rs +++ b/radix-engine/src/blueprints/consensus_manager/package.rs @@ -1,7 +1,6 @@ use crate::blueprints::consensus_manager::{ConsensusManagerBlueprint, ValidatorBlueprint}; use crate::errors::{ApplicationError, RuntimeError}; use crate::internal_prelude::*; -use crate::kernel::kernel_api::KernelNodeApi; use radix_engine_interface::api::ClientApi; use radix_engine_interface::blueprints::consensus_manager::*; use radix_engine_interface::blueprints::package::PackageDefinition; @@ -26,7 +25,7 @@ impl ConsensusManagerNativePackage { api: &mut Y, ) -> Result where - Y: KernelNodeApi + ClientApi, + Y: ClientApi, { match export_name { CONSENSUS_MANAGER_CREATE_IDENT => { @@ -285,7 +284,7 @@ impl ConsensusManagerSecondsPrecisionNativeCode { api: &mut Y, ) -> Result where - Y: KernelNodeApi + ClientApi, + Y: ClientApi, { match export_name { CONSENSUS_MANAGER_GET_CURRENT_TIME_IDENT => { diff --git a/radix-engine/src/blueprints/resource/fungible/fungible_resource_manager.rs b/radix-engine/src/blueprints/resource/fungible/fungible_resource_manager.rs index 901a78a664..d7d0290654 100644 --- a/radix-engine/src/blueprints/resource/fungible/fungible_resource_manager.rs +++ b/radix-engine/src/blueprints/resource/fungible/fungible_resource_manager.rs @@ -2,7 +2,6 @@ use crate::blueprints::resource::*; use crate::errors::ApplicationError; use crate::errors::RuntimeError; use crate::internal_prelude::*; -use crate::kernel::kernel_api::KernelNodeApi; use lazy_static::lazy_static; use num_traits::pow::Pow; use radix_common::math::Decimal; @@ -401,7 +400,7 @@ impl FungibleResourceManagerBlueprint { api: &mut Y, ) -> Result where - Y: KernelNodeApi + ClientApi, + Y: ClientApi, { let (object_id, roles) = Self::create_object( Decimal::ZERO, @@ -435,7 +434,7 @@ impl FungibleResourceManagerBlueprint { api: &mut Y, ) -> Result<(ResourceAddress, Bucket), RuntimeError> where - Y: KernelNodeApi + ClientApi, + Y: ClientApi, { let (object_id, roles) = Self::create_object( initial_supply, @@ -481,7 +480,7 @@ impl FungibleResourceManagerBlueprint { api: &mut Y, ) -> Result where - Y: KernelNodeApi + ClientApi, + Y: ClientApi, { let address_reservation = match address_reservation { Some(address_reservation) => address_reservation, From f97d53b5634effea2b6d5b5552e179c91f794cf2 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Mon, 6 May 2024 09:58:37 -0500 Subject: [PATCH 27/47] More documentation --- radix-engine/book/src/SUMMARY.md | 9 --- .../src/architecture/application/README.md | 11 ++-- .../book/src/architecture/database.md | 1 - .../book/src/architecture/database/README.md | 7 ++- .../book/src/architecture/kernel/README.md | 14 ++++- .../book/src/architecture/system/README.md | 2 + .../book/src/architecture/vm/README.md | 19 +++++-- .../book/src/architecture/vm/vm_layer.drawio | 55 +++++++++++++++++++ .../src/architecture/vm/vm_layer.drawio.svg | 4 ++ 9 files changed, 99 insertions(+), 23 deletions(-) delete mode 100644 radix-engine/book/src/architecture/database.md create mode 100644 radix-engine/book/src/architecture/vm/vm_layer.drawio create mode 100644 radix-engine/book/src/architecture/vm/vm_layer.drawio.svg diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index a81f1ac04b..5a234a7760 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -22,16 +22,7 @@ - [Blueprint Modules](architecture/application/blueprint/blueprint_modules.md) - [VM Layer](architecture/vm/README.md) - [System Layer](architecture/system/README.md) - - [Nodes]() - - [Partitions]() - - [Substates]() - - [Blueprint Implementation]() - - [Object Implementation]() - - [System Module]() - [Kernel Layer](architecture/kernel/README.md) - - [Call Frame]() - - [DB Partition Key]() - - [DB Sort Key]() - [Database Layer](architecture/database/README.md) # Execution diff --git a/radix-engine/book/src/architecture/application/README.md b/radix-engine/book/src/architecture/application/README.md index 769e4e2c3a..866ecf564b 100644 --- a/radix-engine/book/src/architecture/application/README.md +++ b/radix-engine/book/src/architecture/application/README.md @@ -1,8 +1,11 @@ # Application Layer -The application layer is responsible for defining high level logic which manipulates objects. +The application layer is responsible for defining high level logic which manipulates objects +and produces events for the eventual use by off-ledger systems such as wallets and DApps. -An application is defined by a *Package*, which contain zero or more *Blueprints*. -Each blueprint defines object type information and logic which can create/manipulate/destroy -objects of that blueprint type. +## Implementation + +An application is implemented by publishing a *Package*, which contain zero or more *Blueprints*. +Each blueprint defines object type information and logic which can create, manipulate and +destroy objects of that blueprint type. diff --git a/radix-engine/book/src/architecture/database.md b/radix-engine/book/src/architecture/database.md deleted file mode 100644 index 02e60f370e..0000000000 --- a/radix-engine/book/src/architecture/database.md +++ /dev/null @@ -1 +0,0 @@ -# Database Layer diff --git a/radix-engine/book/src/architecture/database/README.md b/radix-engine/book/src/architecture/database/README.md index b8e7b1219d..b7381d3e05 100644 --- a/radix-engine/book/src/architecture/database/README.md +++ b/radix-engine/book/src/architecture/database/README.md @@ -1,2 +1,7 @@ -# Database +# Database Layer +The database layer is responsible for defining the partition-key / sort-key abstractions. + +## Implementation + +The database layer is implemented on top of a key-value database. diff --git a/radix-engine/book/src/architecture/kernel/README.md b/radix-engine/book/src/architecture/kernel/README.md index dc13bf5124..63b147562a 100644 --- a/radix-engine/book/src/architecture/kernel/README.md +++ b/radix-engine/book/src/architecture/kernel/README.md @@ -1,5 +1,13 @@ # Kernel Layer -The kernel layer implements Node/Partition/Substate abstraction on top of a key-value database as well -as maintains a call frame and transaction state updates, which are to be subsequently committed to the -database at the end of the transaction. \ No newline at end of file +The kernel layer is responsible for: +* Defining the Node/Partition/Substate abstraction +* Defining the Call Frame abstraction +* Maintaining Ownership/Reference invariants +* Managing transaction state updates, which are to be subsequently committed to the + database at the end of the transaction + +## Implementation + +The kernel layer is implemented on top of the database layer's Partition Key and Sort Key +abstractions. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/system/README.md b/radix-engine/book/src/architecture/system/README.md index f9850db4a8..2878119729 100644 --- a/radix-engine/book/src/architecture/system/README.md +++ b/radix-engine/book/src/architecture/system/README.md @@ -5,5 +5,7 @@ The System Layer is responsible for: * Maintaining a set of System Modules, or pluggable software, which extends the functionality of the system. +## Implementation + The System Layer implements this by defining the Kernel Callback Object and using the kernel Node/Partition/Substate abstractions. diff --git a/radix-engine/book/src/architecture/vm/README.md b/radix-engine/book/src/architecture/vm/README.md index 341d638f13..3847143b9b 100644 --- a/radix-engine/book/src/architecture/vm/README.md +++ b/radix-engine/book/src/architecture/vm/README.md @@ -1,9 +1,18 @@ # VM Layer -The VM Layer is responsible for providing a Turing-complete computing environment and the -system layer interface to the application layer. The VM Layer does this by defining the -System Callback Object. +The VM Layer is responsible for providing the application layer a Turing-complete computing +environment and the interface to the system layer interface. -Radix Engine currently supports two VMs: +Radix Engine currently supports two VM environments: * A Scrypto WASM VM which exposes the system layer interface through WASM extern functions -* A Native VM which is currently compiled directly in the host's environment with the Radix Engine +* A Native VM which directly compiles applications with Radix Engine in the host's environment. + +![](vm_layer.drawio.svg) + +## Implementation + +The VM Layer is implemented by defining the System Callback Object, which requires two callback +implementations: +1. `init` which is called on [transaction bootup](../../execution/transaction_lifecycle/bootup.md) +to initialize the vm layer +2. `invoke` which is called on any function/method call \ No newline at end of file diff --git a/radix-engine/book/src/architecture/vm/vm_layer.drawio b/radix-engine/book/src/architecture/vm/vm_layer.drawio new file mode 100644 index 0000000000..df2c6ec89c --- /dev/null +++ b/radix-engine/book/src/architecture/vm/vm_layer.drawio @@ -0,0 +1,55 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/radix-engine/book/src/architecture/vm/vm_layer.drawio.svg b/radix-engine/book/src/architecture/vm/vm_layer.drawio.svg new file mode 100644 index 0000000000..3149cba402 --- /dev/null +++ b/radix-engine/book/src/architecture/vm/vm_layer.drawio.svg @@ -0,0 +1,4 @@ + + + +
VM Layer
Application Layer
Scrypto Wasm VM
Native VM
System Layer
Scrypto Wasm
Native Code
extern call
function call
function call
function call
 \ No newline at end of file From db386e4555def4e605d8fa480bb66887462928a2 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Mon, 6 May 2024 10:21:38 -0500 Subject: [PATCH 28/47] Add kernel callback api rustdocs --- .../src/kernel/kernel_callback_api.rs | 56 ++++++++++++++----- 1 file changed, 43 insertions(+), 13 deletions(-) diff --git a/radix-engine/src/kernel/kernel_callback_api.rs b/radix-engine/src/kernel/kernel_callback_api.rs index 01be1678c3..cf55b47a34 100644 --- a/radix-engine/src/kernel/kernel_callback_api.rs +++ b/radix-engine/src/kernel/kernel_callback_api.rs @@ -143,11 +143,17 @@ pub trait ExecutionReceipt { fn set_resource_usage(&mut self, resources_usage: ResourcesUsage); } +/// Upper layer callback object which a kernel interacts with during execution pub trait KernelCallbackObject: Sized { + /// Data to be stored with each substate lock type LockData: Default + Clone; + /// Data to be stored with every call frame type CallFrameData: CallFrameReferences; + /// Initialization object type Init: Clone; + /// Output to be returned at the end of execution type ExecutionOutput; + /// Final receipt to be created after transaction execution type Receipt: ExecutionReceipt; /// Create the callback object (system layer) with data loaded from the substate store @@ -186,49 +192,63 @@ pub trait KernelCallbackObject: Sized { result: Result, ) -> Self::Receipt; + /// Callback before a node is pinned to it's device fn on_pin_node(&mut self, node_id: &NodeId) -> Result<(), RuntimeError>; + /// Callbacks before/on-io-access/after a new node is created fn on_create_node(api: &mut Y, event: CreateNodeEvent) -> Result<(), RuntimeError> where Y: KernelInternalApi; + /// Callbacks before/on-io-access/after a node is dropped fn on_drop_node(api: &mut Y, event: DropNodeEvent) -> Result<(), RuntimeError> where Y: KernelInternalApi; + /// Callback when a module is moved fn on_move_module(api: &mut Y, event: MoveModuleEvent) -> Result<(), RuntimeError> where Y: KernelInternalApi; + /// Callback before/on-io-access/after a substate is opened fn on_open_substate(api: &mut Y, event: OpenSubstateEvent) -> Result<(), RuntimeError> where Y: KernelInternalApi; + /// Callback before a substate is closed fn on_close_substate(api: &mut Y, event: CloseSubstateEvent) -> Result<(), RuntimeError> where Y: KernelInternalApi; + /// Callback before a substate is read fn on_read_substate(api: &mut Y, event: ReadSubstateEvent) -> Result<(), RuntimeError> where Y: KernelInternalApi; + /// Callback before a substate is written to fn on_write_substate(api: &mut Y, event: WriteSubstateEvent) -> Result<(), RuntimeError> where Y: KernelInternalApi; + /// Callback before/on-io-access a substate is set fn on_set_substate(&mut self, event: SetSubstateEvent) -> Result<(), RuntimeError>; + /// Callback before/on-io-access a substate is removed fn on_remove_substate(&mut self, event: RemoveSubstateEvent) -> Result<(), RuntimeError>; + /// Callback before/on-io-access a key scan occurs fn on_scan_keys(&mut self, event: ScanKeysEvent) -> Result<(), RuntimeError>; + /// Callback before/on-io-access a substate drain occurs fn on_drain_substates(&mut self, event: DrainSubstatesEvent) -> Result<(), RuntimeError>; + /// Callback before/on-io-access a sorted substate scan occurs fn on_scan_sorted_substates( &mut self, event: ScanSortedSubstatesEvent, ) -> Result<(), RuntimeError>; + /// Callback before an invocation and a new call frame is created fn before_invoke( invocation: &KernelInvocation, api: &mut Y, @@ -236,33 +256,41 @@ pub trait KernelCallbackObject: Sized { where Y: KernelApi; - fn after_invoke(output: &IndexedScryptoValue, api: &mut Y) -> Result<(), RuntimeError> - where - Y: KernelApi; - + /// Callback after a new call frame is created for a new invocation fn on_execution_start(api: &mut Y) -> Result<(), RuntimeError> where Y: KernelApi; - fn on_execution_finish(message: &CallFrameMessage, api: &mut Y) -> Result<(), RuntimeError> - where - Y: KernelApi; - - fn on_allocate_node_id(entity_type: EntityType, api: &mut Y) -> Result<(), RuntimeError> - where - Y: KernelApi; - + /// Callback on invocation. This is where the callback object should execute application logic. fn invoke_upstream( args: &IndexedScryptoValue, api: &mut Y, ) -> Result + where + Y: KernelApi; + + /// Callback after invocation during call frame cleanup and nodes are still owned by the executed + /// call frame + fn auto_drop(nodes: Vec, api: &mut Y) -> Result<(), RuntimeError> + where + Y: KernelApi; + + /// Callback right after execution of invocation and where call of execution still exists + fn on_execution_finish(message: &CallFrameMessage, api: &mut Y) -> Result<(), RuntimeError> where Y: KernelApi; - fn auto_drop(nodes: Vec, api: &mut Y) -> Result<(), RuntimeError> + /// Callback after an invocation and where invocation's call frame has already been destroyed + fn after_invoke(output: &IndexedScryptoValue, api: &mut Y) -> Result<(), RuntimeError> + where + Y: KernelApi; + + /// Callback before node id allocation + fn on_allocate_node_id(entity_type: EntityType, api: &mut Y) -> Result<(), RuntimeError> where Y: KernelApi; + /// Callback before a substate is marked as transient fn on_mark_substate_as_transient( &mut self, node_id: &NodeId, @@ -270,6 +298,7 @@ pub trait KernelCallbackObject: Sized { substate_key: &SubstateKey, ) -> Result<(), RuntimeError>; + /// Callback when a substate does not exist fn on_substate_lock_fault( node_id: NodeId, partition_num: PartitionNumber, @@ -279,6 +308,7 @@ pub trait KernelCallbackObject: Sized { where Y: KernelApi; + /// Callback before a node is dropped fn on_drop_node_mut(node_id: &NodeId, api: &mut Y) -> Result<(), RuntimeError> where Y: KernelApi; From 2a16827ccefb2a32904e92caf2eef9e96fa512fa Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Mon, 6 May 2024 10:38:29 -0500 Subject: [PATCH 29/47] Some API cleanup --- radix-engine-tests/tests/kernel/kernel.rs | 13 --- .../src/kernel/kernel_callback_api.rs | 23 ++-- radix-engine/src/system/system_callback.rs | 100 +++++++++--------- .../ledger_simulator/inject_costing_err.rs | 67 ++++-------- 4 files changed, 79 insertions(+), 124 deletions(-) diff --git a/radix-engine-tests/tests/kernel/kernel.rs b/radix-engine-tests/tests/kernel/kernel.rs index d94282a428..4fba10cd4b 100644 --- a/radix-engine-tests/tests/kernel/kernel.rs +++ b/radix-engine-tests/tests/kernel/kernel.rs @@ -246,19 +246,6 @@ impl KernelCallbackObject for TestCallbackObject { { Ok(()) } - - fn on_move_node( - _node_id: &NodeId, - _is_moving_down: bool, - _is_to_barrier: bool, - _destination_blueprint_id: Option, - _api: &mut Y, - ) -> Result<(), RuntimeError> - where - Y: KernelApi, - { - Ok(()) - } } enum MoveVariation { diff --git a/radix-engine/src/kernel/kernel_callback_api.rs b/radix-engine/src/kernel/kernel_callback_api.rs index cf55b47a34..996518d053 100644 --- a/radix-engine/src/kernel/kernel_callback_api.rs +++ b/radix-engine/src/kernel/kernel_callback_api.rs @@ -266,14 +266,14 @@ pub trait KernelCallbackObject: Sized { args: &IndexedScryptoValue, api: &mut Y, ) -> Result - where - Y: KernelApi; + where + Y: KernelApi; /// Callback after invocation during call frame cleanup and nodes are still owned by the executed /// call frame fn auto_drop(nodes: Vec, api: &mut Y) -> Result<(), RuntimeError> - where - Y: KernelApi; + where + Y: KernelApi; /// Callback right after execution of invocation and where call of execution still exists fn on_execution_finish(message: &CallFrameMessage, api: &mut Y) -> Result<(), RuntimeError> @@ -282,8 +282,8 @@ pub trait KernelCallbackObject: Sized { /// Callback after an invocation and where invocation's call frame has already been destroyed fn after_invoke(output: &IndexedScryptoValue, api: &mut Y) -> Result<(), RuntimeError> - where - Y: KernelApi; + where + Y: KernelApi; /// Callback before node id allocation fn on_allocate_node_id(entity_type: EntityType, api: &mut Y) -> Result<(), RuntimeError> @@ -312,15 +312,4 @@ pub trait KernelCallbackObject: Sized { fn on_drop_node_mut(node_id: &NodeId, api: &mut Y) -> Result<(), RuntimeError> where Y: KernelApi; - - // This is technically not a kernel event, but system event, per current implementation. - fn on_move_node( - node_id: &NodeId, - is_moving_down: bool, - is_to_barrier: bool, - destination_blueprint_id: Option, - api: &mut Y, - ) -> Result<(), RuntimeError> - where - Y: KernelApi; } diff --git a/radix-engine/src/system/system_callback.rs b/radix-engine/src/system/system_callback.rs index 80088130f8..dc4cfbe9ae 100644 --- a/radix-engine/src/system/system_callback.rs +++ b/radix-engine/src/system/system_callback.rs @@ -725,6 +725,56 @@ impl System { } println!("{:-^120}", "Finish"); } + + fn on_move_node( + node_id: &NodeId, + is_moving_down: bool, + is_to_barrier: bool, + destination_blueprint_id: Option, + api: &mut Y, + ) -> Result<(), RuntimeError> + where + Y: KernelApi, + { + let type_info = TypeInfoBlueprint::get_type(&node_id, api)?; + + match type_info { + TypeInfoSubstate::Object(object_info) => { + let mut service = SystemService::new(api); + let definition = service.load_blueprint_definition( + object_info.blueprint_info.blueprint_id.package_address, + &BlueprintVersionKey { + blueprint: object_info + .blueprint_info + .blueprint_id + .blueprint_name + .clone(), + version: BlueprintVersion::default(), + }, + )?; + if definition.hook_exports.contains_key(&BlueprintHook::OnMove) { + api.kernel_invoke(Box::new(KernelInvocation { + call_frame_data: Actor::BlueprintHook(BlueprintHookActor { + receiver: Some(node_id.clone()), + blueprint_id: object_info.blueprint_info.blueprint_id.clone(), + hook: BlueprintHook::OnMove, + }), + args: IndexedScryptoValue::from_typed(&OnMoveInput { + is_moving_down, + is_to_barrier, + destination_blueprint_id, + }), + })) + .map(|_| ()) + } else { + Ok(()) + } + } + TypeInfoSubstate::KeyValueStore(_) + | TypeInfoSubstate::GlobalAddressReservation(_) + | TypeInfoSubstate::GlobalAddressPhantom(_) => Ok(()), + } + } } impl KernelCallbackObject for System { @@ -1680,54 +1730,4 @@ impl KernelCallbackObject for System { } } } - - fn on_move_node( - node_id: &NodeId, - is_moving_down: bool, - is_to_barrier: bool, - destination_blueprint_id: Option, - api: &mut Y, - ) -> Result<(), RuntimeError> - where - Y: KernelApi, - { - let type_info = TypeInfoBlueprint::get_type(&node_id, api)?; - - match type_info { - TypeInfoSubstate::Object(object_info) => { - let mut service = SystemService::new(api); - let definition = service.load_blueprint_definition( - object_info.blueprint_info.blueprint_id.package_address, - &BlueprintVersionKey { - blueprint: object_info - .blueprint_info - .blueprint_id - .blueprint_name - .clone(), - version: BlueprintVersion::default(), - }, - )?; - if definition.hook_exports.contains_key(&BlueprintHook::OnMove) { - api.kernel_invoke(Box::new(KernelInvocation { - call_frame_data: Actor::BlueprintHook(BlueprintHookActor { - receiver: Some(node_id.clone()), - blueprint_id: object_info.blueprint_info.blueprint_id.clone(), - hook: BlueprintHook::OnMove, - }), - args: IndexedScryptoValue::from_typed(&OnMoveInput { - is_moving_down, - is_to_barrier, - destination_blueprint_id, - }), - })) - .map(|_| ()) - } else { - Ok(()) - } - } - TypeInfoSubstate::KeyValueStore(_) - | TypeInfoSubstate::GlobalAddressReservation(_) - | TypeInfoSubstate::GlobalAddressPhantom(_) => Ok(()), - } - } } diff --git a/scrypto-test/src/ledger_simulator/inject_costing_err.rs b/scrypto-test/src/ledger_simulator/inject_costing_err.rs index 132a25d744..23362573bf 100644 --- a/scrypto-test/src/ledger_simulator/inject_costing_err.rs +++ b/scrypto-test/src/ledger_simulator/inject_costing_err.rs @@ -107,6 +107,14 @@ impl KernelCallbackObject for InjectCostingError { Ok(Self { fail_after, system }) } + fn verify_boot_ref_value( + &mut self, + node_id: &NodeId, + value: &IndexedScryptoValue, + ) -> Result { + self.system.verify_boot_ref_value(node_id, value) + } + fn start( api: &mut Y, manifest_encoded_instructions: &[u8], @@ -141,14 +149,6 @@ impl KernelCallbackObject for InjectCostingError { self.system.create_receipt(track, executable, result) } - fn verify_boot_ref_value( - &mut self, - node_id: &NodeId, - value: &IndexedScryptoValue, - ) -> Result { - self.system.verify_boot_ref_value(node_id, value) - } - fn on_pin_node(&mut self, node_id: &NodeId) -> Result<(), RuntimeError> { self.maybe_err()?; self.system.on_pin_node(node_id) @@ -257,61 +257,61 @@ impl KernelCallbackObject for InjectCostingError { System::before_invoke(invocation, &mut api) } - fn after_invoke(output: &IndexedScryptoValue, api: &mut Y) -> Result<(), RuntimeError> + fn on_execution_start(api: &mut Y) -> Result<(), RuntimeError> where Y: KernelApi, { api.kernel_get_system_state().system.maybe_err()?; let mut api = wrapped_api!(api); - System::after_invoke(output, &mut api) + System::on_execution_start(&mut api) } - fn on_execution_start(api: &mut Y) -> Result<(), RuntimeError> + fn invoke_upstream( + args: &IndexedScryptoValue, + api: &mut Y, + ) -> Result where Y: KernelApi, { api.kernel_get_system_state().system.maybe_err()?; let mut api = wrapped_api!(api); - System::on_execution_start(&mut api) + System::invoke_upstream(args, &mut api) } - fn on_execution_finish(message: &CallFrameMessage, api: &mut Y) -> Result<(), RuntimeError> + fn auto_drop(nodes: Vec, api: &mut Y) -> Result<(), RuntimeError> where Y: KernelApi, { api.kernel_get_system_state().system.maybe_err()?; let mut api = wrapped_api!(api); - System::on_execution_finish(message, &mut api) + System::auto_drop(nodes, &mut api) } - fn on_allocate_node_id(entity_type: EntityType, api: &mut Y) -> Result<(), RuntimeError> + fn on_execution_finish(message: &CallFrameMessage, api: &mut Y) -> Result<(), RuntimeError> where Y: KernelApi, { api.kernel_get_system_state().system.maybe_err()?; let mut api = wrapped_api!(api); - System::on_allocate_node_id(entity_type, &mut api) + System::on_execution_finish(message, &mut api) } - fn invoke_upstream( - args: &IndexedScryptoValue, - api: &mut Y, - ) -> Result + fn after_invoke(output: &IndexedScryptoValue, api: &mut Y) -> Result<(), RuntimeError> where Y: KernelApi, { api.kernel_get_system_state().system.maybe_err()?; let mut api = wrapped_api!(api); - System::invoke_upstream(args, &mut api) + System::after_invoke(output, &mut api) } - fn auto_drop(nodes: Vec, api: &mut Y) -> Result<(), RuntimeError> + fn on_allocate_node_id(entity_type: EntityType, api: &mut Y) -> Result<(), RuntimeError> where Y: KernelApi, { api.kernel_get_system_state().system.maybe_err()?; let mut api = wrapped_api!(api); - System::auto_drop(nodes, &mut api) + System::on_allocate_node_id(entity_type, &mut api) } fn on_mark_substate_as_transient( @@ -347,27 +347,6 @@ impl KernelCallbackObject for InjectCostingError { let mut api = wrapped_api!(api); System::on_drop_node_mut(node_id, &mut api) } - - fn on_move_node( - node_id: &NodeId, - is_moving_down: bool, - is_to_barrier: bool, - destination_blueprint_id: Option, - api: &mut Y, - ) -> Result<(), RuntimeError> - where - Y: KernelApi, - { - api.kernel_get_system_state().system.maybe_err()?; - let mut api = wrapped_api!(api); - System::on_move_node( - node_id, - is_moving_down, - is_to_barrier, - destination_blueprint_id, - &mut api, - ) - } } pub struct WrappedKernelApi<'a, M: SystemCallbackObject + 'a, K: KernelApi>> { From 2370feec365071d817ad55322d982e0d791161bd Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Mon, 6 May 2024 11:47:11 -0500 Subject: [PATCH 30/47] Expand role definition documentation --- .../src/blueprints/package/invocations.rs | 2 ++ radix-engine/book/src/SUMMARY.md | 4 +-- .../book/src/native/access_control/README | 1 - .../book/src/native/access_control/README.md | 25 +++++++++-------- .../native/access_control/blueprint_module.md | 28 +++++++++++++++++++ .../native/access_control/role_definition.md | 4 --- 6 files changed, 45 insertions(+), 19 deletions(-) delete mode 100644 radix-engine/book/src/native/access_control/README create mode 100644 radix-engine/book/src/native/access_control/blueprint_module.md delete mode 100644 radix-engine/book/src/native/access_control/role_definition.md diff --git a/radix-engine-interface/src/blueprints/package/invocations.rs b/radix-engine-interface/src/blueprints/package/invocations.rs index 190ee6be83..deeee76003 100644 --- a/radix-engine-interface/src/blueprints/package/invocations.rs +++ b/radix-engine-interface/src/blueprints/package/invocations.rs @@ -190,6 +190,8 @@ impl Default for MethodAuthTemplate { #[derive(Debug, Clone, Eq, PartialEq, ScryptoSbor, ManifestSbor)] pub enum RoleSpecification { /// Roles are specified in the current blueprint and defined in the instantiated object. + /// The map contains keys for all possible roles, mapping to a list of roles which may update + /// the access rule for each role. Normal(IndexMap), /// Roles are specified in the *outer* blueprint and defined in the instantiated *outer* object. /// This may only be used by inner blueprints and is currently used by the Vault blueprints diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index 5a234a7760..c61dd881db 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -39,8 +39,8 @@ # Native Systems - [Type Checking]() -- [Authorization](native/access_control/README) - - [Role Definition](native/access_control/role_definition.md) +- [Access Control](native/access_control/README.md) + - [Blueprint Module](native/access_control/blueprint_module.md) - [Role Assignment](native/access_control/role_assignment.md) - [Auth Zone](native/access_control/authzone.md) - [Authorization Flow](native/access_control/authorization.md) diff --git a/radix-engine/book/src/native/access_control/README b/radix-engine/book/src/native/access_control/README deleted file mode 100644 index 17257a2e81..0000000000 --- a/radix-engine/book/src/native/access_control/README +++ /dev/null @@ -1 +0,0 @@ -# Authorization diff --git a/radix-engine/book/src/native/access_control/README.md b/radix-engine/book/src/native/access_control/README.md index bea80644bb..e92c442c0d 100644 --- a/radix-engine/book/src/native/access_control/README.md +++ b/radix-engine/book/src/native/access_control/README.md @@ -1,17 +1,18 @@ # Access Control -Unlike the majority of blockchains which rely on a caller identifier for access control, the Access Control -system uses a more distributed "Proof" system. Before accessing a protected method a caller must provide -specific "Proofs" of resources they have access to. These proofs must then match the required proofs -defined by protected method or function of the callee. +Unlike the majority of blockchains which rely on a caller identifier for access control, +the Access Control system uses a more distributed "Proof" system. Before accessing a protected +method a caller must provide specific "Proofs" of resources they have access to. These proofs +must then match the required proofs defined by protected method or function of the callee. The Access Control System is composed of four parts: -1. A Blueprint Module, which defines roles available to use for a given blueprint in a package -2. An Object Module, which provides role assignment or which resources are required to show proof for a given role -3. A System Module, which maintains an AuthZone, or the current proofs a runtime caller has -4. An AuthZone Blueprint, which allows a caller to update their current proofs - -These three modules allow a package creator to define roles which a component creator can assign definitions to, -which a caller must show proof for by updating their AuthZone. - +1. An [Access Control Blueprint Module](role_definition.md), +which defines function rules and roles available to use for a given blueprint in a package and which roles are able +to access which methods. +2. A [Role Assignment Object Module](role_assignment.md), +which assigns proof rules for each role defined in the object's blueprint's role definition. +3. An [AuthZone Blueprint](../../architecture/application/blueprint/README.md), which allows +a caller to update their current proofs. +4. An AuthZone System Module, which creates a new AuthZone for every new call frame and verifies + that AuthZone proofs match the requirements of accessing an object's function. \ No newline at end of file diff --git a/radix-engine/book/src/native/access_control/blueprint_module.md b/radix-engine/book/src/native/access_control/blueprint_module.md new file mode 100644 index 0000000000..277eed8fe0 --- /dev/null +++ b/radix-engine/book/src/native/access_control/blueprint_module.md @@ -0,0 +1,28 @@ +# Access Control Blueprint Module + +The access control [blueprint module](../../architecture/application/blueprint/blueprint_modules.md) defines three things: +* Function AccessRules +* Method accessibility +* Role Specification + +## Function AccessRules + +Each function is assigned an immutable access rule. + +## Method Accessibility + +Each method is assigned an accessibility rule, of which there are four options: + +| Accessibility Rule | Description | +|--------------------|--------------------------------------------------------------------------------| +| Public | Anyone can access the method | +| Outer Object Only | Only outer objects may access the method | +| Role Protected | Only callers who have satisfied any role in a given list may access the method | +| Own Package Only | Only the package this method is a part of may access the method | + +## Role Specification + +The roles which must be assigned on object instantiated are defined in role specification. +Furthermore, roles which may update the rules of other roles must be specified. + +For inner objects, it is also possible to defer role specification to the outer object. \ No newline at end of file diff --git a/radix-engine/book/src/native/access_control/role_definition.md b/radix-engine/book/src/native/access_control/role_definition.md deleted file mode 100644 index a7fd907696..0000000000 --- a/radix-engine/book/src/native/access_control/role_definition.md +++ /dev/null @@ -1,4 +0,0 @@ -# Role Definition - -All roles for a given object are defined (though not assigned!) at the Blueprint level by the Package creator. This -includes definitions regarding which methods a given role is given access to. \ No newline at end of file From 04d3d269bcb530a61f3be09ddb927952a99f1c26 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Mon, 6 May 2024 11:59:22 -0500 Subject: [PATCH 31/47] More updates --- radix-engine/book/src/native/access_control/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/radix-engine/book/src/native/access_control/README.md b/radix-engine/book/src/native/access_control/README.md index e92c442c0d..8c39014b32 100644 --- a/radix-engine/book/src/native/access_control/README.md +++ b/radix-engine/book/src/native/access_control/README.md @@ -7,11 +7,11 @@ must then match the required proofs defined by protected method or function of t The Access Control System is composed of four parts: -1. An [Access Control Blueprint Module](role_definition.md), +1. An [Access Control Blueprint Module](blueprint_module.md), which defines function rules and roles available to use for a given blueprint in a package and which roles are able to access which methods. 2. A [Role Assignment Object Module](role_assignment.md), -which assigns proof rules for each role defined in the object's blueprint's role definition. +which assigns proof rules for each role on object instantiation. 3. An [AuthZone Blueprint](../../architecture/application/blueprint/README.md), which allows a caller to update their current proofs. 4. An AuthZone System Module, which creates a new AuthZone for every new call frame and verifies From db85f0b89ddcd357e23cec7f9449730c214b20c9 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Tue, 7 May 2024 14:22:58 -0500 Subject: [PATCH 32/47] Expand Access Control System documentation --- radix-engine/book/src/SUMMARY.md | 8 +- .../book/src/native/access_control/README.md | 10 +- .../native/access_control/auth_stack.drawio | 192 +++++++++++++++ .../access_control/auth_stack.drawio.svg | 4 + .../src/native/access_control/auth_stack.svg | 4 + .../native/access_control/auth_zones.drawio | 218 ++++++++++++++++++ .../access_control/auth_zones.drawio.svg | 4 + .../native/access_control/authorization.md | 9 - .../src/native/access_control/authzone.md | 16 +- .../native/access_control/blueprint_module.md | 5 +- .../native/access_control/role_assignment.md | 10 +- .../native/access_control/system_module.md | 49 ++++ .../system/system_modules/auth/auth_module.rs | 14 +- 13 files changed, 506 insertions(+), 37 deletions(-) create mode 100644 radix-engine/book/src/native/access_control/auth_stack.drawio create mode 100644 radix-engine/book/src/native/access_control/auth_stack.drawio.svg create mode 100644 radix-engine/book/src/native/access_control/auth_stack.svg create mode 100644 radix-engine/book/src/native/access_control/auth_zones.drawio create mode 100644 radix-engine/book/src/native/access_control/auth_zones.drawio.svg delete mode 100644 radix-engine/book/src/native/access_control/authorization.md create mode 100644 radix-engine/book/src/native/access_control/system_module.md diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index c61dd881db..b5b4e48525 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -40,10 +40,10 @@ - [Type Checking]() - [Access Control](native/access_control/README.md) - - [Blueprint Module](native/access_control/blueprint_module.md) - - [Role Assignment](native/access_control/role_assignment.md) - - [Auth Zone](native/access_control/authzone.md) - - [Authorization Flow](native/access_control/authorization.md) + - [Access Control Blueprint Module](native/access_control/blueprint_module.md) + - [Role Assignment Object Module](native/access_control/role_assignment.md) + - [Auth Zone Blueprint](native/access_control/authzone.md) + - [Access Control System Module](native/access_control/system_module.md) - [Transaction Manifest]() - [Resources]() - [Royalties]() diff --git a/radix-engine/book/src/native/access_control/README.md b/radix-engine/book/src/native/access_control/README.md index 8c39014b32..aaa7e9b59b 100644 --- a/radix-engine/book/src/native/access_control/README.md +++ b/radix-engine/book/src/native/access_control/README.md @@ -11,8 +11,8 @@ The Access Control System is composed of four parts: which defines function rules and roles available to use for a given blueprint in a package and which roles are able to access which methods. 2. A [Role Assignment Object Module](role_assignment.md), -which assigns proof rules for each role on object instantiation. -3. An [AuthZone Blueprint](../../architecture/application/blueprint/README.md), which allows -a caller to update their current proofs. -4. An AuthZone System Module, which creates a new AuthZone for every new call frame and verifies - that AuthZone proofs match the requirements of accessing an object's function. \ No newline at end of file +which assigns access rules for each role on object instantiation. +3. An [AuthZone Blueprint](authzone.md), which allows a caller to update the proofs in their authzone. +4. An [Access Control System Module](system_module.md), which creates a new AuthZone for every +new call frame and verifies that AuthZone proofs match the requirements of accessing an +object's function. \ No newline at end of file diff --git a/radix-engine/book/src/native/access_control/auth_stack.drawio b/radix-engine/book/src/native/access_control/auth_stack.drawio new file mode 100644 index 0000000000..b3d6862fdf --- /dev/null +++ b/radix-engine/book/src/native/access_control/auth_stack.drawio @@ -0,0 +1,192 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/radix-engine/book/src/native/access_control/auth_stack.drawio.svg b/radix-engine/book/src/native/access_control/auth_stack.drawio.svg new file mode 100644 index 0000000000..884f8cb178 --- /dev/null +++ b/radix-engine/book/src/native/access_control/auth_stack.drawio.svg @@ -0,0 +1,4 @@ + + + +
Global Context 2
Global Context 1
Global Context 0
Call Frame 0
AuthZone 1
Owns
Call Frame 1
References
Call Frame 2
AuthZone 2
Owns
Parent
References
Call Frame 3
AuthZone 3
References
Owns
Call Frame 4
AuthZone 4
References
Global Caller
Global Caller
Call Frame 5
AuthZone 5
References
Owns
Owns
Parent
Global Caller
Call Frame 6
AuthZone 6
References
Owns
Parent
Global Caller
 \ No newline at end of file diff --git a/radix-engine/book/src/native/access_control/auth_stack.svg b/radix-engine/book/src/native/access_control/auth_stack.svg new file mode 100644 index 0000000000..3399bd221e --- /dev/null +++ b/radix-engine/book/src/native/access_control/auth_stack.svg @@ -0,0 +1,4 @@ + + + +
Global Context 2
Global Context 1
Global Context 0
Call Frame 0
AuthZone 1
Owns
Call Frame 1
References
Call Frame 2
AuthZone 2
Owns
Parent
References
Call Frame 3
AuthZone 3
References
Owns
Call Frame 4
AuthZone 4
References
Global Caller
Global Caller
Call Frame 5
AuthZone 5
References
Owns
Owns
Global Caller
Call Frame 6
AuthZone 6
References
Owns
Parent
Global Caller
Parent
 \ No newline at end of file diff --git a/radix-engine/book/src/native/access_control/auth_zones.drawio b/radix-engine/book/src/native/access_control/auth_zones.drawio new file mode 100644 index 0000000000..94f597d1ac --- /dev/null +++ b/radix-engine/book/src/native/access_control/auth_zones.drawio @@ -0,0 +1,218 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/radix-engine/book/src/native/access_control/auth_zones.drawio.svg b/radix-engine/book/src/native/access_control/auth_zones.drawio.svg new file mode 100644 index 0000000000..2d4b356708 --- /dev/null +++ b/radix-engine/book/src/native/access_control/auth_zones.drawio.svg @@ -0,0 +1,4 @@ + + + +
Global Context 2
Global Context 1
Global Context 0
Call Frame 0
AuthZone 1
Owns
Call Frame 1
References
Call Frame 2
AuthZone 2
Owns
Parent
References
Call Frame 3
AuthZone 3
References
Owns
Call Frame 4
AuthZone 4
References
Global Caller
Global Caller
Call Frame 5
AuthZone 5
References
Owns
Owns
Global Caller
Call Frame 6
AuthZone 6
References
Owns
Parent
Global Caller
AuthZone 7
Parent
Global Caller
Owns
Parent
 \ No newline at end of file diff --git a/radix-engine/book/src/native/access_control/authorization.md b/radix-engine/book/src/native/access_control/authorization.md deleted file mode 100644 index e53f91c00a..0000000000 --- a/radix-engine/book/src/native/access_control/authorization.md +++ /dev/null @@ -1,9 +0,0 @@ -# Authorization - -On rule check time, the AuthModule checks the proofs on the caller's AuthZone and determines which roles for this -object the caller has. If any of these roles match the list of roles assigned to the method, the caller is then -authorized to make the call. - -Unlike traditional RBAC where the role a user is acting is explicit, in this model roles are more implicit and -defined on what proofs the user has in their AuthZone. This makes it a cross between the well-known RBAC and -ABAC models. diff --git a/radix-engine/book/src/native/access_control/authzone.md b/radix-engine/book/src/native/access_control/authzone.md index 9c9b98217e..3ed5b278f8 100644 --- a/radix-engine/book/src/native/access_control/authzone.md +++ b/radix-engine/book/src/native/access_control/authzone.md @@ -1,8 +1,16 @@ # AuthZone To call a protected method, the caller must place these proofs into their [AuthZone](../../../blueprints/resource/auth_zone), -a space dedicated for using proofs for the purpose of authorized method access. On method call, the Auth Module -then checks the caller's AuthZone and compares it to the rules specified by the Callee. +a space dedicated for using proofs for the purpose of authorized method access. -These rules are specified by the Callee on Object instantiation and are defined by using a mixture of **Role-Based -Access Control** (RBAC) and **Attribute-Based Access Control** (ABAC) techniques. \ No newline at end of file +An AuthZone has the following methods: +* `pop` +* `push` +* `create_proof_of_amount` +* `create_proof_of_non_fungibles` +* `create_proof_of_all` +* `drop_proofs` +* `drop_signature_proofs` +* `drop_regular_proofs` +* `drain` +* `assert_access_rule` diff --git a/radix-engine/book/src/native/access_control/blueprint_module.md b/radix-engine/book/src/native/access_control/blueprint_module.md index 277eed8fe0..86a578f96d 100644 --- a/radix-engine/book/src/native/access_control/blueprint_module.md +++ b/radix-engine/book/src/native/access_control/blueprint_module.md @@ -1,6 +1,7 @@ # Access Control Blueprint Module -The access control [blueprint module](../../architecture/application/blueprint/blueprint_modules.md) defines three things: +The access control [blueprint module](../../architecture/application/blueprint/blueprint_modules.md) defines three +things for every blueprint: * Function AccessRules * Method accessibility * Role Specification @@ -25,4 +26,4 @@ Each method is assigned an accessibility rule, of which there are four options: The roles which must be assigned on object instantiated are defined in role specification. Furthermore, roles which may update the rules of other roles must be specified. -For inner objects, it is also possible to defer role specification to the outer object. \ No newline at end of file +For inner blueprints, it is also possible to defer role specification to the outer blueprint. \ No newline at end of file diff --git a/radix-engine/book/src/native/access_control/role_assignment.md b/radix-engine/book/src/native/access_control/role_assignment.md index 9999e77ada..a13a15be9c 100644 --- a/radix-engine/book/src/native/access_control/role_assignment.md +++ b/radix-engine/book/src/native/access_control/role_assignment.md @@ -1,7 +1,5 @@ -# Role Assignment - -On the callee side, instead of roles being assigned to a "user" (of which there is no concept in our decentralized -ledger), roles are assigned through resource ownership. For example, a "Staff" role could be assigned to anyone who -can show proof that they own a "Staff" resource token. This is defined at the callee's Object instantiation -through the [RoleAssignment](../../attached_modules/role_assignment) object module. +# Role Assignment Object Module +The role assignment [object module](../../architecture/application/object/object_modules.md) +assigns each role to an access rule. The object module is instantiated whenever an object gets +globalized. diff --git a/radix-engine/book/src/native/access_control/system_module.md b/radix-engine/book/src/native/access_control/system_module.md new file mode 100644 index 0000000000..d26b688d87 --- /dev/null +++ b/radix-engine/book/src/native/access_control/system_module.md @@ -0,0 +1,49 @@ +# Access Control System Module + +The Access Control System Module operates on every invocation: +1. Creates a new AuthZone +2. Resolve the Permission required to access the method/function invocation +3. Verifies that the Global Caller AuthZone has sufficient proofs to pass the AccessRule + +## AuthZone Creation + +At the start of every invocation, the access control system module creates a new +[AuthZone](authzone.md) in the call frame of the caller and adds a reference to this object +in the callee's call frame. This AuthZone effectively becomes the "Local AuthZone" of the callee. + +Every AuthZone references a global caller AuthZone and a parent AuthZone, the values of which +are dependent on if the invocation is a global object context switch or not. + +If the invocation is a global object context switch, the global caller of the new AuthZone +will reference the caller's AuthZone and will not have a parent AuthZone. If the invocation +is a local context switch, the caller's global caller is copied into the new AuthZone and the +parent will reference the caller's AuthZone. + +This pattern generates a stack which looks like: + +![](auth_stack.drawio.svg) + +## Permission Resolving + +Permission resolving involves loading up relevant state of the callee and generating a permission +object from this state. + +If the callee is a function call then the permission is loaded from the function access rules +specified in the blueprint's [access control blueprint module](blueprint_module.md). + +If the callee is a method call then the Method Accessibility is loaded from the callee's +[access control blueprint module](blueprint_module.md) as well as the state in the callee's +[Role Assignment Object Module](role_assignment.md). From these two states, the permission to +access the method is derived. + +## Auth Verification + +Auth verification then checks the resolved permission against the AuthZones in the current +global context as well as the Global Caller's context. + +![](auth_zones.drawio.svg) + +In the above drawing, Call Frame 6 is making a new invocation and the AuthZones checked are +3/4/5/6, the AuthZones belonging to the current Global Context as well as the Global Caller's +Context. + diff --git a/radix-engine/src/system/system_modules/auth/auth_module.rs b/radix-engine/src/system/system_modules/auth/auth_module.rs index a640f71959..6ab313b580 100644 --- a/radix-engine/src/system/system_modules/auth/auth_module.rs +++ b/radix-engine/src/system/system_modules/auth/auth_module.rs @@ -243,7 +243,7 @@ impl AuthModule { Y: KernelApi>, { let (auth_zone, parent_lock_handle) = { - let next_is_barrier = if let Some((receiver, direct_access)) = receiver { + let is_global_context_change = if let Some((receiver, direct_access)) = receiver { let object_info = system.get_object_info(receiver)?; object_info.is_global() || direct_access } else { @@ -263,12 +263,12 @@ impl AuthModule { .reference_origin(current_method_actor.node_id) .unwrap(); let self_auth_zone = current_method_actor.auth_zone; - match (current_ref_origin, next_is_barrier) { - // Actor is part of the global component state tree AND next actor is a barrier + match (current_ref_origin, is_global_context_change) { + // Actor is part of the global component state tree AND next actor is a global context change (ReferenceOrigin::Global(address), true) => { (Some((address.into(), Reference(self_auth_zone))), None) } - // Actor is part of the global component state tree AND next actor is not a barrier + // Actor is part of the global component state tree AND next actor is NOT a global context change (ReferenceOrigin::Global(..), false) => { Self::copy_global_caller(system, &self_auth_zone)? } @@ -276,7 +276,7 @@ impl AuthModule { (ReferenceOrigin::DirectlyAccessed, _) => (None, None), // Actor is a non-global reference (ReferenceOrigin::SubstateNonGlobalReference(..), _) => (None, None), - // Actor ia a frame-owned object + // Actor is a frame-owned object (ReferenceOrigin::FrameOwned, _) => { let caller = Self::copy_global_caller(system, &self_auth_zone)?; ( @@ -291,7 +291,7 @@ impl AuthModule { Actor::Function(function_actor) => { let self_auth_zone = function_actor.auth_zone; let global_caller = function_actor.as_global_caller(); - if next_is_barrier { + if is_global_context_change { (Some((global_caller, Reference(self_auth_zone))), None) } else { Self::copy_global_caller(system, &self_auth_zone)? @@ -299,7 +299,7 @@ impl AuthModule { } }; - let auth_zone_parent = if next_is_barrier { + let auth_zone_parent = if is_global_context_change { None } else { system From 36c707156cfd0c697319bce2168990c93f0ad0cd Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Wed, 8 May 2024 09:42:13 -0500 Subject: [PATCH 33/47] Add type checking document --- radix-engine/book/src/SUMMARY.md | 2 +- .../book/src/native/type_checking/README.md | 11 ++ .../type_checking/type_checking_arch.drawio | 164 ++++++++++++++++++ .../type_checking_arch.drawio.svg | 4 + 4 files changed, 180 insertions(+), 1 deletion(-) create mode 100644 radix-engine/book/src/native/type_checking/README.md create mode 100644 radix-engine/book/src/native/type_checking/type_checking_arch.drawio create mode 100644 radix-engine/book/src/native/type_checking/type_checking_arch.drawio.svg diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index b5b4e48525..6e02c8c441 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -38,7 +38,7 @@ # Native Systems -- [Type Checking]() +- [Type Checking](native/type_checking/README.md) - [Access Control](native/access_control/README.md) - [Access Control Blueprint Module](native/access_control/blueprint_module.md) - [Role Assignment Object Module](native/access_control/role_assignment.md) diff --git a/radix-engine/book/src/native/type_checking/README.md b/radix-engine/book/src/native/type_checking/README.md new file mode 100644 index 0000000000..f9802ca35c --- /dev/null +++ b/radix-engine/book/src/native/type_checking/README.md @@ -0,0 +1,11 @@ +# Type Checking + +The Type Checking System checks that payloads coming from the application layer match the +schema defined in the Blueprint. This includes: +* Object Fields/Collections +* Function Input/Output +* Events + +The Type Checking System supports generics. + +![](type_checking_arch.drawio.svg) \ No newline at end of file diff --git a/radix-engine/book/src/native/type_checking/type_checking_arch.drawio b/radix-engine/book/src/native/type_checking/type_checking_arch.drawio new file mode 100644 index 0000000000..219a4aa83b --- /dev/null +++ b/radix-engine/book/src/native/type_checking/type_checking_arch.drawio @@ -0,0 +1,164 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/radix-engine/book/src/native/type_checking/type_checking_arch.drawio.svg b/radix-engine/book/src/native/type_checking/type_checking_arch.drawio.svg new file mode 100644 index 0000000000..0567e773fa --- /dev/null +++ b/radix-engine/book/src/native/type_checking/type_checking_arch.drawio.svg @@ -0,0 +1,4 @@ + + + +
Fields
Collections
Functions
Events
Generics
Types
PayloadDef
Scrypto Schema
Resolved
Index
Def
Unresolved Generic
Blueprint
Object
BlueprintId
Generic Substitutions
Remote
Local
 \ No newline at end of file From e056ab17d5ab9ef3a98a491cea875a47dad6208b Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Wed, 8 May 2024 10:16:46 -0500 Subject: [PATCH 34/47] Add more documentation --- radix-engine/book/src/SUMMARY.md | 1 + .../src/architecture/application/blueprint/hooks.md | 13 +++++++++++++ radix-engine/book/src/native/resources/README.md | 10 ++++++++++ 3 files changed, 24 insertions(+) create mode 100644 radix-engine/book/src/architecture/application/blueprint/hooks.md create mode 100644 radix-engine/book/src/native/resources/README.md diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index 6e02c8c441..136d1c42a1 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -18,6 +18,7 @@ - [Collections](architecture/application/blueprint/collections.md) - [Events](architecture/application/blueprint/events.md) - [Functions](architecture/application/blueprint/functions.md) + - [Hooks](architecture/application/blueprint/hooks.md) - [Types](architecture/application/blueprint/types.md) - [Blueprint Modules](architecture/application/blueprint/blueprint_modules.md) - [VM Layer](architecture/vm/README.md) diff --git a/radix-engine/book/src/architecture/application/blueprint/hooks.md b/radix-engine/book/src/architecture/application/blueprint/hooks.md new file mode 100644 index 0000000000..3e67f5454e --- /dev/null +++ b/radix-engine/book/src/architecture/application/blueprint/hooks.md @@ -0,0 +1,13 @@ +# Hooks + +> **_NOTE:_** Hooks are currently only available for use by native packages. + +Hooks define logic which get executed when certain system events occur. + +There are currently three types of hooks: + +| Hook Name | Description | +|--------------|----------------------------------------------------------------------------------| +| OnVirtualize | Called when a substate fault occurs on a virtual address of this blueprint type. | +| OnMove | Called when an object of this blueprint type is moved between call frames. | +| OnDrop | Called when an object of this blueprint type is dropped. | diff --git a/radix-engine/book/src/native/resources/README.md b/radix-engine/book/src/native/resources/README.md new file mode 100644 index 0000000000..8ec26f7d1b --- /dev/null +++ b/radix-engine/book/src/native/resources/README.md @@ -0,0 +1,10 @@ +# Resources + +The Resource system manages asset logic across the system. + +It is composed of: +* Resource Package which consists of + * Fungible/Non-Fungible Bucket Blueprint + * Fungible/Non-Fungible Proof Blueprint + * Fungible/Non-Fungible Vault Blueprint + * Fungible/Non-Fungible Resource Manager Blueprint From 2706415d4e625acdb5e9c7efdb6c2cfd20369d21 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Wed, 8 May 2024 12:03:01 -0500 Subject: [PATCH 35/47] More documentation --- radix-engine/book/src/SUMMARY.md | 7 ++++--- .../application}/type_checking/README.md | 0 .../type_checking/type_checking_arch.drawio | 0 .../type_checking/type_checking_arch.drawio.svg | 0 radix-engine/book/src/architecture/layers.md | 14 +++++++------- .../book/src/architecture/system/README.md | 1 + 6 files changed, 12 insertions(+), 10 deletions(-) rename radix-engine/book/src/{native => architecture/application}/type_checking/README.md (100%) rename radix-engine/book/src/{native => architecture/application}/type_checking/type_checking_arch.drawio (100%) rename radix-engine/book/src/{native => architecture/application}/type_checking/type_checking_arch.drawio.svg (100%) diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index 136d1c42a1..90c1602887 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -21,6 +21,7 @@ - [Hooks](architecture/application/blueprint/hooks.md) - [Types](architecture/application/blueprint/types.md) - [Blueprint Modules](architecture/application/blueprint/blueprint_modules.md) + - [Type Checking](architecture/application/type_checking/README.md) - [VM Layer](architecture/vm/README.md) - [System Layer](architecture/system/README.md) - [Kernel Layer](architecture/kernel/README.md) @@ -39,14 +40,14 @@ # Native Systems -- [Type Checking](native/type_checking/README.md) +- [Transaction Manifest]() +- [Resources](native/resources/README.md) - [Access Control](native/access_control/README.md) - [Access Control Blueprint Module](native/access_control/blueprint_module.md) - [Role Assignment Object Module](native/access_control/role_assignment.md) - [Auth Zone Blueprint](native/access_control/authzone.md) - [Access Control System Module](native/access_control/system_module.md) -- [Transaction Manifest]() -- [Resources]() +- [Costing/Limits]() - [Royalties]() - [Metadata]() diff --git a/radix-engine/book/src/native/type_checking/README.md b/radix-engine/book/src/architecture/application/type_checking/README.md similarity index 100% rename from radix-engine/book/src/native/type_checking/README.md rename to radix-engine/book/src/architecture/application/type_checking/README.md diff --git a/radix-engine/book/src/native/type_checking/type_checking_arch.drawio b/radix-engine/book/src/architecture/application/type_checking/type_checking_arch.drawio similarity index 100% rename from radix-engine/book/src/native/type_checking/type_checking_arch.drawio rename to radix-engine/book/src/architecture/application/type_checking/type_checking_arch.drawio diff --git a/radix-engine/book/src/native/type_checking/type_checking_arch.drawio.svg b/radix-engine/book/src/architecture/application/type_checking/type_checking_arch.drawio.svg similarity index 100% rename from radix-engine/book/src/native/type_checking/type_checking_arch.drawio.svg rename to radix-engine/book/src/architecture/application/type_checking/type_checking_arch.drawio.svg diff --git a/radix-engine/book/src/architecture/layers.md b/radix-engine/book/src/architecture/layers.md index 5db4768afb..fddcd1a9a9 100644 --- a/radix-engine/book/src/architecture/layers.md +++ b/radix-engine/book/src/architecture/layers.md @@ -4,11 +4,11 @@ Radix Engine is organized into 5 layers. Each layer has specific responsibilitie provides an API to the layer above. Middle layers also provide a Callback API which the layer above must implement. -| Layer Name | Layer ID | Responsibilities | -|-------------|----------|--------------------------------------------------------------------------------------------------------------------------| -| Application | 5 | Defines Blueprint Application Logic | -| VM | 4 | Executes Application Code | -| System | 3 | Defines Package, Blueprint, Object abstractions
Defines System Standards such as Authorization and Versioning | -| Kernel | 2 | Defines Node, Partition, Substate abstractions
Maintains Call Frame Stack
Maintains Ownership/Reference invariants | -| Database | 1 | Defines PartitionKey, SortKey abstractions | +| Layer Name | Layer ID | Responsibilities | +|-------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Application | 5 | Defines Blueprint Application Logic | +| VM | 4 | Executes Application Code | +| System | 3 | Defines Actor abstraction (Memory Protection)
Defines Package, Blueprint, Object abstractions
Defines System Standards such as Authorization and Versioning | +| Kernel | 2 | Defines Node, Partition, Substate abstractions
Maintains Call Frame Stack
Maintains Ownership/Reference invariants | +| Database | 1 | Defines PartitionKey, SortKey abstractions | diff --git a/radix-engine/book/src/architecture/system/README.md b/radix-engine/book/src/architecture/system/README.md index 2878119729..5f5d46d74d 100644 --- a/radix-engine/book/src/architecture/system/README.md +++ b/radix-engine/book/src/architecture/system/README.md @@ -1,6 +1,7 @@ # System Layer The System Layer is responsible for: +* Defining Actor abstraction and memory protection * Defining the Package/Blueprint/Object abstraction * Maintaining a set of System Modules, or pluggable software, which extends the functionality of the system. From 33a9b73497f8c828cea9974530830e0fd66c5663 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Wed, 8 May 2024 13:52:15 -0500 Subject: [PATCH 36/47] Add more documentation --- radix-engine/book/src/SUMMARY.md | 7 +++++-- .../architecture/application/object/inner_outer_objects.md | 6 +++--- .../src/architecture/application/object/object_modules.md | 6 +++--- 3 files changed, 11 insertions(+), 8 deletions(-) diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index 90c1602887..f23e35755f 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -6,8 +6,11 @@ - [Layered Architecture](architecture/layers.md) - [Application Layer](architecture/application/README.md) - - [Object Model](architecture/application/object/README.md) - - [Inner and Outer Objects](architecture/application/object/inner_outer_objects.md) + - [Object](architecture/application/object/README.md) + - [Blueprint]() + - [Outer Object](architecture/application/object/inner_outer_objects.md) + - [Features]() + - [Generics]() - [Object Modules](architecture/application/object/object_modules.md) - [Blueprint](architecture/application/blueprint/README.md) - [Inner and Outer Blueprints](architecture/application/blueprint/inner_outer.md) diff --git a/radix-engine/book/src/architecture/application/object/inner_outer_objects.md b/radix-engine/book/src/architecture/application/object/inner_outer_objects.md index bca080bbef..c70552f852 100644 --- a/radix-engine/book/src/architecture/application/object/inner_outer_objects.md +++ b/radix-engine/book/src/architecture/application/object/inner_outer_objects.md @@ -1,7 +1,7 @@ -# Inner and Outer Objects +# Outer Objects Objects which are Inner Blueprints will have an associated Outer object of a given outer -Blueprint. Inner objects may directly access the state of its outer object avoiding -invocation and new call frame overhead + costs. +Blueprint. Objects of an Inner Blueprint may directly access the state of its outer object +avoiding invocation and new call frame overhead + costs. ![](inner_outer_objects.drawio.svg) \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/object/object_modules.md b/radix-engine/book/src/architecture/application/object/object_modules.md index 647ffa95e6..81a8428048 100644 --- a/radix-engine/book/src/architecture/application/object/object_modules.md +++ b/radix-engine/book/src/architecture/application/object/object_modules.md @@ -7,6 +7,6 @@ An Object Module itself has a Blueprint type along with associated logic to mani the state of the object module. Currently, there exists three object modules: -* RoleAssignment Object Module -* Metadata Object Module -* Royalty Object Module +* RoleAssignment Object Module (Required) +* Metadata Object Module (Required) +* Royalty Object Module (Optional) From 53c556ff7f9738a401ba0d135b648898451c3213 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Thu, 9 May 2024 13:31:10 -0500 Subject: [PATCH 37/47] Add more documentation --- radix-engine/book/src/SUMMARY.md | 9 ++++++--- .../application/blueprint/blueprint_modules.md | 4 ++-- .../architecture/application/object/object_modules.md | 6 +++--- .../book/src/native/access_control/role_assignment.md | 5 +++-- radix-engine/book/src/native/costing_limits/README.md | 5 +++++ radix-engine/book/src/native/metadata/README.md | 5 +++++ radix-engine/book/src/native/metadata/object_module.md | 4 ++++ radix-engine/book/src/native/royalties/README.md | 8 ++++++++ .../book/src/native/royalties/component_royalties.md | 4 ++++ .../book/src/native/royalties/package_royalties.md | 4 ++++ 10 files changed, 44 insertions(+), 10 deletions(-) create mode 100644 radix-engine/book/src/native/costing_limits/README.md create mode 100644 radix-engine/book/src/native/metadata/README.md create mode 100644 radix-engine/book/src/native/metadata/object_module.md create mode 100644 radix-engine/book/src/native/royalties/README.md create mode 100644 radix-engine/book/src/native/royalties/component_royalties.md create mode 100644 radix-engine/book/src/native/royalties/package_royalties.md diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index f23e35755f..1c8037e073 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -50,9 +50,12 @@ - [Role Assignment Object Module](native/access_control/role_assignment.md) - [Auth Zone Blueprint](native/access_control/authzone.md) - [Access Control System Module](native/access_control/system_module.md) -- [Costing/Limits]() -- [Royalties]() -- [Metadata]() +- [Costing/Limits](native/costing_limits/README.md) +- [Royalties](native/royalties/README.md) + - [Package Royalties Blueprint Module](native/royalties/package_royalties.md) + - [Component Royalties Object Module](native/royalties/component_royalties.md) +- [Metadata](native/metadata/README.md) + - [Metadata Object Module](native/metadata/object_module.md) # Protocol - [Genesis Bootstrap]() diff --git a/radix-engine/book/src/architecture/application/blueprint/blueprint_modules.md b/radix-engine/book/src/architecture/application/blueprint/blueprint_modules.md index 32ee4941ff..8465b3cff0 100644 --- a/radix-engine/book/src/architecture/application/blueprint/blueprint_modules.md +++ b/radix-engine/book/src/architecture/application/blueprint/blueprint_modules.md @@ -4,5 +4,5 @@ The system may define additional state to be stored per blueprint known as Bluep every blueprint definition must initialize these modules. Currently there exists two blueprint modules: -* Auth Blueprint Module -* Royalty Blueprint Module \ No newline at end of file +* [Auth](../../../native/access_control/blueprint_module.md) +* [Package Royalties](../../../native/royalties/package_royalties.md) \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/object/object_modules.md b/radix-engine/book/src/architecture/application/object/object_modules.md index 81a8428048..7d12cc5a1c 100644 --- a/radix-engine/book/src/architecture/application/object/object_modules.md +++ b/radix-engine/book/src/architecture/application/object/object_modules.md @@ -7,6 +7,6 @@ An Object Module itself has a Blueprint type along with associated logic to mani the state of the object module. Currently, there exists three object modules: -* RoleAssignment Object Module (Required) -* Metadata Object Module (Required) -* Royalty Object Module (Optional) +* [RoleAssignment](../../../native/access_control/role_assignment.md) (Required) +* [Metadata](../../../native/metadata/object_module.md) (Required) +* [Component Royalties](../../../native/royalties/component_royalties.md) (Optional) diff --git a/radix-engine/book/src/native/access_control/role_assignment.md b/radix-engine/book/src/native/access_control/role_assignment.md index a13a15be9c..af2e7f2027 100644 --- a/radix-engine/book/src/native/access_control/role_assignment.md +++ b/radix-engine/book/src/native/access_control/role_assignment.md @@ -1,5 +1,6 @@ # Role Assignment Object Module The role assignment [object module](../../architecture/application/object/object_modules.md) -assigns each role to an access rule. The object module is instantiated whenever an object gets -globalized. +assigns each role to an access rule. + +The rules associated with a role may be updated or defaulted to the "owner role". \ No newline at end of file diff --git a/radix-engine/book/src/native/costing_limits/README.md b/radix-engine/book/src/native/costing_limits/README.md new file mode 100644 index 0000000000..48e829bb3b --- /dev/null +++ b/radix-engine/book/src/native/costing_limits/README.md @@ -0,0 +1,5 @@ +# Costing / Limits + +The Costing and Limits System is responsible for bounding physical resources used in a +transaction. It does this by maintaining a System Module which interacts with the resource +system such that resources used in transaction require a payment of some resource. \ No newline at end of file diff --git a/radix-engine/book/src/native/metadata/README.md b/radix-engine/book/src/native/metadata/README.md new file mode 100644 index 0000000000..a1eeba9393 --- /dev/null +++ b/radix-engine/book/src/native/metadata/README.md @@ -0,0 +1,5 @@ +# Metadata + +Metadata stores string keys with metadata values for any object and package. + +This is implemented as a single [Object Module](object_module.md). \ No newline at end of file diff --git a/radix-engine/book/src/native/metadata/object_module.md b/radix-engine/book/src/native/metadata/object_module.md new file mode 100644 index 0000000000..b006c21b10 --- /dev/null +++ b/radix-engine/book/src/native/metadata/object_module.md @@ -0,0 +1,4 @@ +# Metadata Object Module + +The metadata [object module](../../architecture/application/object/object_modules.md) allows +a user to set/update/delete metadata associated with a given object. \ No newline at end of file diff --git a/radix-engine/book/src/native/royalties/README.md b/radix-engine/book/src/native/royalties/README.md new file mode 100644 index 0000000000..0677898244 --- /dev/null +++ b/radix-engine/book/src/native/royalties/README.md @@ -0,0 +1,8 @@ +# Royalties + +Royalties allow a package deployer and a component owner to receive royalties on every function +or method call. + +This is implemented in two parts: +* [Package Royalties Blueprint Module](package_royalties.md). +* [Component Royalties Object Module](component_royalties.md). diff --git a/radix-engine/book/src/native/royalties/component_royalties.md b/radix-engine/book/src/native/royalties/component_royalties.md new file mode 100644 index 0000000000..a6c4ec0022 --- /dev/null +++ b/radix-engine/book/src/native/royalties/component_royalties.md @@ -0,0 +1,4 @@ +# Component Royalties Object Module + +The component royalties object module allows the owner to set royalties per method and withdraw +earned royalties. \ No newline at end of file diff --git a/radix-engine/book/src/native/royalties/package_royalties.md b/radix-engine/book/src/native/royalties/package_royalties.md new file mode 100644 index 0000000000..7491790789 --- /dev/null +++ b/radix-engine/book/src/native/royalties/package_royalties.md @@ -0,0 +1,4 @@ +# Package Royalties Blueprint Module + +The package royalties blueprint module allows the blueprint owner to set royalties per function +and withdraw earned royalties. \ No newline at end of file From 132f58cbfd03e3357a46dd8641ea96aa5395e0c8 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Thu, 9 May 2024 15:06:23 -0500 Subject: [PATCH 38/47] More documentation --- radix-engine/book/src/SUMMARY.md | 6 +++--- .../src/architecture/application/object/blueprint_id.md | 5 +++++ .../book/src/architecture/application/object/features.md | 4 ++++ .../application/object/generic_substitutions.md | 4 ++++ 4 files changed, 16 insertions(+), 3 deletions(-) create mode 100644 radix-engine/book/src/architecture/application/object/blueprint_id.md create mode 100644 radix-engine/book/src/architecture/application/object/features.md create mode 100644 radix-engine/book/src/architecture/application/object/generic_substitutions.md diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index 1c8037e073..1b64bf3742 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -7,10 +7,10 @@ - [Layered Architecture](architecture/layers.md) - [Application Layer](architecture/application/README.md) - [Object](architecture/application/object/README.md) - - [Blueprint]() + - [BlueprintId](architecture/application/object/blueprint_id.md) - [Outer Object](architecture/application/object/inner_outer_objects.md) - - [Features]() - - [Generics]() + - [Features](architecture/application/object/features.md) + - [Generic Substitutions](architecture/application/object/generic_substitutions.md) - [Object Modules](architecture/application/object/object_modules.md) - [Blueprint](architecture/application/blueprint/README.md) - [Inner and Outer Blueprints](architecture/application/blueprint/inner_outer.md) diff --git a/radix-engine/book/src/architecture/application/object/blueprint_id.md b/radix-engine/book/src/architecture/application/object/blueprint_id.md new file mode 100644 index 0000000000..393e275dc8 --- /dev/null +++ b/radix-engine/book/src/architecture/application/object/blueprint_id.md @@ -0,0 +1,5 @@ +# Blueprint Id + +Every object is associated with a blueprint id which consists of +` + `. A blueprint id uniquely identifies the +[blueprint](../blueprint/README.md) of an object. diff --git a/radix-engine/book/src/architecture/application/object/features.md b/radix-engine/book/src/architecture/application/object/features.md new file mode 100644 index 0000000000..cadddf4680 --- /dev/null +++ b/radix-engine/book/src/architecture/application/object/features.md @@ -0,0 +1,4 @@ +# Features + +An object's features describes optional features an object may have. An object's features +must be a subset of the total [features](../blueprint/features.md) defined in a blueprint. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/object/generic_substitutions.md b/radix-engine/book/src/architecture/application/object/generic_substitutions.md new file mode 100644 index 0000000000..5f139a94a6 --- /dev/null +++ b/radix-engine/book/src/architecture/application/object/generic_substitutions.md @@ -0,0 +1,4 @@ +# Generic Substitutions + +If an object's blueprint defines generic arguments then these are replaced with the +type specified in an object's generic substitutions list. From e3ca6cfc73d2181f290f9b501b4292c1748456e8 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Fri, 10 May 2024 10:21:41 -0500 Subject: [PATCH 39/47] Add more documentation --- radix-engine/book/src/SUMMARY.md | 7 ++++--- .../book/src/native/transaction_processor/README.md | 7 +++++++ .../book/src/native/transaction_processor/blueprint.md | 6 ++++++ radix-engine/book/src/protocol/genesis_bootstrap.md | 9 +++++++++ radix-engine/book/src/protocol/protocol_updates.md | 4 ++++ 5 files changed, 30 insertions(+), 3 deletions(-) create mode 100644 radix-engine/book/src/native/transaction_processor/README.md create mode 100644 radix-engine/book/src/native/transaction_processor/blueprint.md create mode 100644 radix-engine/book/src/protocol/genesis_bootstrap.md create mode 100644 radix-engine/book/src/protocol/protocol_updates.md diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index 1b64bf3742..bae89ad7a7 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -43,7 +43,8 @@ # Native Systems -- [Transaction Manifest]() +- [Transaction Processor](native/transaction_processor/README.md) + - [Transaction Processor Blueprint](native/transaction_processor/blueprint.md) - [Resources](native/resources/README.md) - [Access Control](native/access_control/README.md) - [Access Control Blueprint Module](native/access_control/blueprint_module.md) @@ -58,6 +59,6 @@ - [Metadata Object Module](native/metadata/object_module.md) # Protocol -- [Genesis Bootstrap]() -- [Protocol Updates]() +- [Genesis Bootstrap](protocol/genesis_bootstrap.md) +- [Protocol Updates](protocol/protocol_updates.md) \ No newline at end of file diff --git a/radix-engine/book/src/native/transaction_processor/README.md b/radix-engine/book/src/native/transaction_processor/README.md new file mode 100644 index 0000000000..ffceba742a --- /dev/null +++ b/radix-engine/book/src/native/transaction_processor/README.md @@ -0,0 +1,7 @@ +# Transaction Processor + +The transaction processor is the initial application layer call frame made during +the [transaction boot process](../../execution/transaction_lifecycle/bootup.md) and executes a transaction manifest which is encoded in +a transaction. + +It consists of a blueprint with a single `run` function. \ No newline at end of file diff --git a/radix-engine/book/src/native/transaction_processor/blueprint.md b/radix-engine/book/src/native/transaction_processor/blueprint.md new file mode 100644 index 0000000000..2bbad50d40 --- /dev/null +++ b/radix-engine/book/src/native/transaction_processor/blueprint.md @@ -0,0 +1,6 @@ +# Transaction Processor Blueprint + +The transaction processor blueprint has a single `run` function which accepts a transaction +manifest. + +The manifest is a series of instructions which the transaction processor interprets and executes. \ No newline at end of file diff --git a/radix-engine/book/src/protocol/genesis_bootstrap.md b/radix-engine/book/src/protocol/genesis_bootstrap.md new file mode 100644 index 0000000000..ad66af9de5 --- /dev/null +++ b/radix-engine/book/src/protocol/genesis_bootstrap.md @@ -0,0 +1,9 @@ +# Genesis Bootstrap + +Bootstrapping a Radix Engine requires flashing several system substates and then the execution +of several genesis transactions. + +Specifically, the substates of the `Package` blueprint and object module blueprints are flashed. + +Once flashed, `Package::publish` calls may now be called to create the rest of the native +blueprints. diff --git a/radix-engine/book/src/protocol/protocol_updates.md b/radix-engine/book/src/protocol/protocol_updates.md new file mode 100644 index 0000000000..59d8c75ef8 --- /dev/null +++ b/radix-engine/book/src/protocol/protocol_updates.md @@ -0,0 +1,4 @@ +# Protocol Updates + +Similar to genesis bootstrapping, a protocol update is a series of transactions which includes +a set of substates to flash and a set of transactions to execute. From a24ab9f87fda51a785ce8a50144dd1c332f39650 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Mon, 13 May 2024 16:05:48 -0500 Subject: [PATCH 40/47] Updates on documentation --- radix-engine/book/src/README.md | 2 +- radix-engine/book/src/SUMMARY.md | 12 ++++++------ .../book/src/architecture/application/README.md | 6 +++--- .../application/blueprint/blueprint_modules.md | 2 +- .../architecture/application/blueprint/features.md | 5 +++-- .../application/blueprint/functions.md | 12 +++++++----- .../architecture/application/blueprint/generics.md | 5 ++--- .../application/blueprint/transience.md | 3 ++- .../src/architecture/application/object/README.md | 14 ++++++++++---- .../architecture/application/object/features.md | 2 +- .../application/object/generic_substitutions.md | 4 ++-- .../application/object/inner_outer_objects.md | 6 +++--- .../application/object/object_modules.drawio.svg | 4 ++++ .../application/object/object_modules.md | 4 +++- radix-engine/book/src/architecture/layers.md | 14 +++++++------- radix-engine/book/src/architecture/vm/README.md | 2 -- .../book/src/execution/environment/README.md | 10 ++++++---- .../src/execution/transaction_lifecycle/README.md | 2 +- .../src/execution/transaction_lifecycle/bootup.md | 2 +- .../src/execution/transaction_lifecycle/runtime.md | 6 +++--- .../src/native/{access_control => auth}/README.md | 4 ++-- .../{access_control => auth}/auth_stack.drawio | 0 .../{access_control => auth}/auth_stack.drawio.svg | 0 .../native/{access_control => auth}/auth_stack.svg | 0 .../{access_control => auth}/auth_zones.drawio | 0 .../{access_control => auth}/auth_zones.drawio.svg | 0 .../native/{access_control => auth}/authzone.md | 0 .../{access_control => auth}/blueprint_module.md | 0 .../{access_control => auth}/role_assignment.md | 0 .../{access_control => auth}/system_module.md | 4 ++-- radix-engine/book/src/native/metadata/README.md | 2 +- 31 files changed, 71 insertions(+), 56 deletions(-) create mode 100644 radix-engine/book/src/architecture/application/object/object_modules.drawio.svg rename radix-engine/book/src/native/{access_control => auth}/README.md (89%) rename radix-engine/book/src/native/{access_control => auth}/auth_stack.drawio (100%) rename radix-engine/book/src/native/{access_control => auth}/auth_stack.drawio.svg (100%) rename radix-engine/book/src/native/{access_control => auth}/auth_stack.svg (100%) rename radix-engine/book/src/native/{access_control => auth}/auth_zones.drawio (100%) rename radix-engine/book/src/native/{access_control => auth}/auth_zones.drawio.svg (100%) rename radix-engine/book/src/native/{access_control => auth}/authzone.md (100%) rename radix-engine/book/src/native/{access_control => auth}/blueprint_module.md (100%) rename radix-engine/book/src/native/{access_control => auth}/role_assignment.md (100%) rename radix-engine/book/src/native/{access_control => auth}/system_module.md (95%) diff --git a/radix-engine/book/src/README.md b/radix-engine/book/src/README.md index a68e28b60c..68624dab25 100644 --- a/radix-engine/book/src/README.md +++ b/radix-engine/book/src/README.md @@ -1,7 +1,7 @@ # What is Radix Engine? Radix Engine is a deterministic, transaction-based state machine that updates ledger state by -incrementally executing transactions. +sequentially executing transactions. Radix Engine was built out of the lack of Blockchain VMs specifically optimized for a DeFi shared computing environment in terms of usability, security, performance, and modularity. diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index bae89ad7a7..88b9c1e40a 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -20,7 +20,7 @@ - [Fields](architecture/application/blueprint/fields.md) - [Collections](architecture/application/blueprint/collections.md) - [Events](architecture/application/blueprint/events.md) - - [Functions](architecture/application/blueprint/functions.md) + - [Functions/Methods](architecture/application/blueprint/functions.md) - [Hooks](architecture/application/blueprint/hooks.md) - [Types](architecture/application/blueprint/types.md) - [Blueprint Modules](architecture/application/blueprint/blueprint_modules.md) @@ -46,11 +46,11 @@ - [Transaction Processor](native/transaction_processor/README.md) - [Transaction Processor Blueprint](native/transaction_processor/blueprint.md) - [Resources](native/resources/README.md) -- [Access Control](native/access_control/README.md) - - [Access Control Blueprint Module](native/access_control/blueprint_module.md) - - [Role Assignment Object Module](native/access_control/role_assignment.md) - - [Auth Zone Blueprint](native/access_control/authzone.md) - - [Access Control System Module](native/access_control/system_module.md) +- [Auth](native/auth/README.md) + - [Auth Blueprint Module](native/auth/blueprint_module.md) + - [Role Assignment Object Module](native/auth/role_assignment.md) + - [Auth Zone Blueprint](native/auth/authzone.md) + - [Auth System Module](native/auth/system_module.md) - [Costing/Limits](native/costing_limits/README.md) - [Royalties](native/royalties/README.md) - [Package Royalties Blueprint Module](native/royalties/package_royalties.md) diff --git a/radix-engine/book/src/architecture/application/README.md b/radix-engine/book/src/architecture/application/README.md index 866ecf564b..b0beb1669d 100644 --- a/radix-engine/book/src/architecture/application/README.md +++ b/radix-engine/book/src/architecture/application/README.md @@ -5,7 +5,7 @@ and produces events for the eventual use by off-ledger systems such as wallets a ## Implementation -An application is implemented by publishing a *Package*, which contain zero or more *Blueprints*. -Each blueprint defines object type information and logic which can create, manipulate and -destroy objects of that blueprint type. +An application is added to the system by publishing a *Package*, which contain zero or +more *Blueprints*. Each blueprint defines object type information and logic which can create, +manipulate and destroy objects of that blueprint type. diff --git a/radix-engine/book/src/architecture/application/blueprint/blueprint_modules.md b/radix-engine/book/src/architecture/application/blueprint/blueprint_modules.md index 8465b3cff0..b01e106c1c 100644 --- a/radix-engine/book/src/architecture/application/blueprint/blueprint_modules.md +++ b/radix-engine/book/src/architecture/application/blueprint/blueprint_modules.md @@ -4,5 +4,5 @@ The system may define additional state to be stored per blueprint known as Bluep every blueprint definition must initialize these modules. Currently there exists two blueprint modules: -* [Auth](../../../native/access_control/blueprint_module.md) +* [Auth](../../../native/auth/blueprint_module.md) * [Package Royalties](../../../native/royalties/package_royalties.md) \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/blueprint/features.md b/radix-engine/book/src/architecture/application/blueprint/features.md index ecb72733a7..5001312f8c 100644 --- a/radix-engine/book/src/architecture/application/blueprint/features.md +++ b/radix-engine/book/src/architecture/application/blueprint/features.md @@ -2,7 +2,8 @@ > **_NOTE:_** Features are currently only available for use by native packages. -Features provide a mechanism to express conditional execution and conditional stored state. -The set of features to be used are specified per object on instantiation. +Features provide a mechanism to express conditional execution and conditional stored state +(using [Field Conditions](fields.md#field-condition)). The set of features to be used are specified +[per object](../object/features.md) on instantiation. Features are identified by string. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/blueprint/functions.md b/radix-engine/book/src/architecture/application/blueprint/functions.md index d0827a1a24..90f8305c21 100644 --- a/radix-engine/book/src/architecture/application/blueprint/functions.md +++ b/radix-engine/book/src/architecture/application/blueprint/functions.md @@ -1,8 +1,10 @@ -# Functions +# Functions/Methods -Functions define executable logic. +Functions/Methods define executable logic. A function is executable logic which does not directly +depend on the internal state of an object. A method is executable logic which directly depends +on internal state of an object, known as *receiver*. -A function signature is defined by an input/output schema as well as whether an object receiver -must be specified. +Every function/method is defined by an input/output schema which describes the signature of the +function/method. -Functions are identified by string. +Functions/Methods are identified by string. diff --git a/radix-engine/book/src/architecture/application/blueprint/generics.md b/radix-engine/book/src/architecture/application/blueprint/generics.md index 31f2bf75c6..0919e7a13a 100644 --- a/radix-engine/book/src/architecture/application/blueprint/generics.md +++ b/radix-engine/book/src/architecture/application/blueprint/generics.md @@ -2,8 +2,7 @@ > **_NOTE:_** Generics are currently only available for use by native packages. -Generics to a blueprint may be specified which will then require an object instantiator to -specify generic parameters during instantiation. Such a generic can then be used in defining function -or state schemas. +Generics to a blueprint requires an object instantiator to specify [generic substitutions](../object/generic_substitutions.md) +during instantiation. Such a generic can then be used in defining function or state schemas. Generics in a Blueprint are identified by index. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/blueprint/transience.md b/radix-engine/book/src/architecture/application/blueprint/transience.md index 0b6b8ddebf..263e147295 100644 --- a/radix-engine/book/src/architecture/application/blueprint/transience.md +++ b/radix-engine/book/src/architecture/application/blueprint/transience.md @@ -2,4 +2,5 @@ > **_NOTE:_** Transience is currently only available for use by native packages. -If a blueprint is specified to be transient, all objects of this blueprint cannot be persisted. +If a blueprint is specified to be transient, all objects of this blueprint cannot be persisted and must +be created/dropped within the lifecycle of a transaction. diff --git a/radix-engine/book/src/architecture/application/object/README.md b/radix-engine/book/src/architecture/application/object/README.md index 5b8dac743e..a9d92c0fdb 100644 --- a/radix-engine/book/src/architecture/application/object/README.md +++ b/radix-engine/book/src/architecture/application/object/README.md @@ -1,8 +1,14 @@ # Object Model Unlike Ethereum where the ledger state is a flat mapping between addresses and account states, Radix -Engine organizes its state into a forest of *objects*, each of which has a blueprint type. Child -objects are exclusively owned by its parent in the tree hierarchy. Each root object is assigned a -*global address*. +Engine organizes its state into a forest of *objects*. Child objects are exclusively owned by its +parent in the tree hierarchy. Each root object is assigned a *global address*. -![](object_model.drawio.svg) \ No newline at end of file +![](object_model.drawio.svg) + +Each object has: +* A [BlueprintId](blueprint_id.md) (type) +* An optional [Outer Object](inner_outer_objects.md) +* A list of [Features](features.md) +* A list of [Generic Substitutions](generic_substitutions.md) +* A set of [Object Modules](object_modules.md) \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/object/features.md b/radix-engine/book/src/architecture/application/object/features.md index cadddf4680..d259f1d096 100644 --- a/radix-engine/book/src/architecture/application/object/features.md +++ b/radix-engine/book/src/architecture/application/object/features.md @@ -1,4 +1,4 @@ # Features An object's features describes optional features an object may have. An object's features -must be a subset of the total [features](../blueprint/features.md) defined in a blueprint. \ No newline at end of file +must be a subset of the total [features](../blueprint/features.md) defined in the object's blueprint. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/object/generic_substitutions.md b/radix-engine/book/src/architecture/application/object/generic_substitutions.md index 5f139a94a6..a99b11a67b 100644 --- a/radix-engine/book/src/architecture/application/object/generic_substitutions.md +++ b/radix-engine/book/src/architecture/application/object/generic_substitutions.md @@ -1,4 +1,4 @@ # Generic Substitutions -If an object's blueprint defines generic arguments then these are replaced with the -type specified in an object's generic substitutions list. +If an object's blueprint defines [generic arguments](../blueprint/generics.md) then these +are replaced with the types specified in an object's generic substitutions list. diff --git a/radix-engine/book/src/architecture/application/object/inner_outer_objects.md b/radix-engine/book/src/architecture/application/object/inner_outer_objects.md index c70552f852..a6f2a0661a 100644 --- a/radix-engine/book/src/architecture/application/object/inner_outer_objects.md +++ b/radix-engine/book/src/architecture/application/object/inner_outer_objects.md @@ -1,7 +1,7 @@ # Outer Objects -Objects which are Inner Blueprints will have an associated Outer object of a given outer -Blueprint. Objects of an Inner Blueprint may directly access the state of its outer object -avoiding invocation and new call frame overhead + costs. +Objects which have a blueprint which is an [Inner Blueprint](inner_outer_objects.md) will have an +associated Outer object of a given outer Blueprint. Objects of an Inner Blueprint may directly access +the state of its outer object avoiding invocation and new call frame overhead + costs. ![](inner_outer_objects.drawio.svg) \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/object/object_modules.drawio.svg b/radix-engine/book/src/architecture/application/object/object_modules.drawio.svg new file mode 100644 index 0000000000..e4834d6bad --- /dev/null +++ b/radix-engine/book/src/architecture/application/object/object_modules.drawio.svg @@ -0,0 +1,4 @@ + + + +
Object Modules
Object Modules
Metadata
Component Royalties
Metadata
Role
Assignment
Role
Assignment
Account
Key Value Store
Vault
Vault
Radiswap
Vault
Vault
 \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/object/object_modules.md b/radix-engine/book/src/architecture/application/object/object_modules.md index 7d12cc5a1c..bd8a910f67 100644 --- a/radix-engine/book/src/architecture/application/object/object_modules.md +++ b/radix-engine/book/src/architecture/application/object/object_modules.md @@ -6,7 +6,9 @@ an *Object Module*. An Object Module itself has a Blueprint type along with associated logic to manipulate the state of the object module. +![](object_modules.drawio.svg) + Currently, there exists three object modules: -* [RoleAssignment](../../../native/access_control/role_assignment.md) (Required) +* [RoleAssignment](../../../native/auth/role_assignment.md) (Required) * [Metadata](../../../native/metadata/object_module.md) (Required) * [Component Royalties](../../../native/royalties/component_royalties.md) (Optional) diff --git a/radix-engine/book/src/architecture/layers.md b/radix-engine/book/src/architecture/layers.md index fddcd1a9a9..71139d43a3 100644 --- a/radix-engine/book/src/architecture/layers.md +++ b/radix-engine/book/src/architecture/layers.md @@ -4,11 +4,11 @@ Radix Engine is organized into 5 layers. Each layer has specific responsibilitie provides an API to the layer above. Middle layers also provide a Callback API which the layer above must implement. -| Layer Name | Layer ID | Responsibilities | -|-------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Application | 5 | Defines Blueprint Application Logic | -| VM | 4 | Executes Application Code | -| System | 3 | Defines Actor abstraction (Memory Protection)
Defines Package, Blueprint, Object abstractions
Defines System Standards such as Authorization and Versioning | -| Kernel | 2 | Defines Node, Partition, Substate abstractions
Maintains Call Frame Stack
Maintains Ownership/Reference invariants | -| Database | 1 | Defines PartitionKey, SortKey abstractions | +| Layer Name | Responsibilities | +|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Application | Defines Blueprint Application Logic | +| VM | Executes Application Code | +| System | Defines Actor abstraction (Memory Protection)
Defines Package, Blueprint, Object abstractions
Defines System Standards such as Authorization and Versioning | +| Kernel | Defines Node, Partition, Substate abstractions
Maintains Call Frame Stack
Maintains Ownership/Reference invariants | +| Database | Defines PartitionKey, SortKey abstractions | diff --git a/radix-engine/book/src/architecture/vm/README.md b/radix-engine/book/src/architecture/vm/README.md index 3847143b9b..a43b9182af 100644 --- a/radix-engine/book/src/architecture/vm/README.md +++ b/radix-engine/book/src/architecture/vm/README.md @@ -7,8 +7,6 @@ Radix Engine currently supports two VM environments: * A Scrypto WASM VM which exposes the system layer interface through WASM extern functions * A Native VM which directly compiles applications with Radix Engine in the host's environment. -![](vm_layer.drawio.svg) - ## Implementation The VM Layer is implemented by defining the System Callback Object, which requires two callback diff --git a/radix-engine/book/src/execution/environment/README.md b/radix-engine/book/src/execution/environment/README.md index cf36c69562..dd1899b61f 100644 --- a/radix-engine/book/src/execution/environment/README.md +++ b/radix-engine/book/src/execution/environment/README.md @@ -1,6 +1,6 @@ # Application Environment -Every method/function execution has a call frame associated with it. +Every method/function execution has a call frame associated with it managed by the Kernel. A call frame contains all owned and referenced objects usable by the running function. These objects are referrable by `NodeId`. @@ -20,9 +20,11 @@ or dropped, in which case the owned object gets removed from the call frame. A call frame also contains a reference to the *actor*, or callee object (i.e. *self* in object-oriented languages). This is maintained to allow read/writes of state for the given actor. -## Other System Functions +## System Module Functions -A set of other system functions are available to the application layer. Currently these include: +Additional system functions are available to the application layer implemented by System Modules. +Currently, these include: +* Events +* Logging * Costing * Transaction Runtime -* Crypto Utils \ No newline at end of file diff --git a/radix-engine/book/src/execution/transaction_lifecycle/README.md b/radix-engine/book/src/execution/transaction_lifecycle/README.md index 212011ee99..90928e1aaa 100644 --- a/radix-engine/book/src/execution/transaction_lifecycle/README.md +++ b/radix-engine/book/src/execution/transaction_lifecycle/README.md @@ -1,7 +1,7 @@ # Transaction Lifecycle Radix Engine is a transactional state machine which accepts a transaction and a given state and -outputs a state change. +outputs a state change and additional output. ``` radix_engine(State, Transaction) -> (StateChange, Output) diff --git a/radix-engine/book/src/execution/transaction_lifecycle/bootup.md b/radix-engine/book/src/execution/transaction_lifecycle/bootup.md index 125de422c6..b8d73e08a7 100644 --- a/radix-engine/book/src/execution/transaction_lifecycle/bootup.md +++ b/radix-engine/book/src/execution/transaction_lifecycle/bootup.md @@ -1,6 +1,6 @@ # Transaction Bootup -The initialization of a transaction execution consists of two steps: +The bootup and initialization of a transaction consists of two steps: 1. Initialize Stack 2. Invoke Transaction Processor diff --git a/radix-engine/book/src/execution/transaction_lifecycle/runtime.md b/radix-engine/book/src/execution/transaction_lifecycle/runtime.md index d823b6ee61..48d3442966 100644 --- a/radix-engine/book/src/execution/transaction_lifecycle/runtime.md +++ b/radix-engine/book/src/execution/transaction_lifecycle/runtime.md @@ -1,7 +1,7 @@ # Transaction Runtime -Once transaction bootup has finished, the `TRANSACTION_PROCESSOR` blueprint function `run` is then -executed with transaction data as its argument. It executes on top of the initial call frame created -during kernel initialization. +Once transaction bootup has finished, the [Transaction Processor Blueprint](../../native/transaction_processor/blueprint.md) +function `run` is then executed with transaction data as its argument. It executes on top of the initial call frame created +during kernel initialization in a standard [application environment](../environment/README.md). Once the `run` function has finished executing transaction shutdown begins. \ No newline at end of file diff --git a/radix-engine/book/src/native/access_control/README.md b/radix-engine/book/src/native/auth/README.md similarity index 89% rename from radix-engine/book/src/native/access_control/README.md rename to radix-engine/book/src/native/auth/README.md index aaa7e9b59b..9d6671ba9a 100644 --- a/radix-engine/book/src/native/access_control/README.md +++ b/radix-engine/book/src/native/auth/README.md @@ -1,7 +1,7 @@ -# Access Control +# Auth Unlike the majority of blockchains which rely on a caller identifier for access control, -the Access Control system uses a more distributed "Proof" system. Before accessing a protected +the Auth system uses a more distributed "Proof" system. Before accessing a protected method a caller must provide specific "Proofs" of resources they have access to. These proofs must then match the required proofs defined by protected method or function of the callee. diff --git a/radix-engine/book/src/native/access_control/auth_stack.drawio b/radix-engine/book/src/native/auth/auth_stack.drawio similarity index 100% rename from radix-engine/book/src/native/access_control/auth_stack.drawio rename to radix-engine/book/src/native/auth/auth_stack.drawio diff --git a/radix-engine/book/src/native/access_control/auth_stack.drawio.svg b/radix-engine/book/src/native/auth/auth_stack.drawio.svg similarity index 100% rename from radix-engine/book/src/native/access_control/auth_stack.drawio.svg rename to radix-engine/book/src/native/auth/auth_stack.drawio.svg diff --git a/radix-engine/book/src/native/access_control/auth_stack.svg b/radix-engine/book/src/native/auth/auth_stack.svg similarity index 100% rename from radix-engine/book/src/native/access_control/auth_stack.svg rename to radix-engine/book/src/native/auth/auth_stack.svg diff --git a/radix-engine/book/src/native/access_control/auth_zones.drawio b/radix-engine/book/src/native/auth/auth_zones.drawio similarity index 100% rename from radix-engine/book/src/native/access_control/auth_zones.drawio rename to radix-engine/book/src/native/auth/auth_zones.drawio diff --git a/radix-engine/book/src/native/access_control/auth_zones.drawio.svg b/radix-engine/book/src/native/auth/auth_zones.drawio.svg similarity index 100% rename from radix-engine/book/src/native/access_control/auth_zones.drawio.svg rename to radix-engine/book/src/native/auth/auth_zones.drawio.svg diff --git a/radix-engine/book/src/native/access_control/authzone.md b/radix-engine/book/src/native/auth/authzone.md similarity index 100% rename from radix-engine/book/src/native/access_control/authzone.md rename to radix-engine/book/src/native/auth/authzone.md diff --git a/radix-engine/book/src/native/access_control/blueprint_module.md b/radix-engine/book/src/native/auth/blueprint_module.md similarity index 100% rename from radix-engine/book/src/native/access_control/blueprint_module.md rename to radix-engine/book/src/native/auth/blueprint_module.md diff --git a/radix-engine/book/src/native/access_control/role_assignment.md b/radix-engine/book/src/native/auth/role_assignment.md similarity index 100% rename from radix-engine/book/src/native/access_control/role_assignment.md rename to radix-engine/book/src/native/auth/role_assignment.md diff --git a/radix-engine/book/src/native/access_control/system_module.md b/radix-engine/book/src/native/auth/system_module.md similarity index 95% rename from radix-engine/book/src/native/access_control/system_module.md rename to radix-engine/book/src/native/auth/system_module.md index d26b688d87..51449f32df 100644 --- a/radix-engine/book/src/native/access_control/system_module.md +++ b/radix-engine/book/src/native/auth/system_module.md @@ -1,6 +1,6 @@ -# Access Control System Module +# Auth System Module -The Access Control System Module operates on every invocation: +The Auth System Module operates on every invocation: 1. Creates a new AuthZone 2. Resolve the Permission required to access the method/function invocation 3. Verifies that the Global Caller AuthZone has sufficient proofs to pass the AccessRule diff --git a/radix-engine/book/src/native/metadata/README.md b/radix-engine/book/src/native/metadata/README.md index a1eeba9393..d4f0d29a82 100644 --- a/radix-engine/book/src/native/metadata/README.md +++ b/radix-engine/book/src/native/metadata/README.md @@ -2,4 +2,4 @@ Metadata stores string keys with metadata values for any object and package. -This is implemented as a single [Object Module](object_module.md). \ No newline at end of file +This is implemented as a [Metadata Object Module](object_module.md). \ No newline at end of file From 4eaa62da88eee84593a2479fa83c474fc8056ab7 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Mon, 13 May 2024 17:06:38 -0500 Subject: [PATCH 41/47] Cleanup and more documentation --- .../tests/fuzz_kernel.rs | 13 ------------ radix-engine/book/book.toml | 1 - radix-engine/book/src/SUMMARY.md | 1 + .../blueprint/blueprint_modules.md | 4 ++-- .../application/object/object_modules.md | 2 +- .../src/architecture/system/system_modules.md | 6 ++++++ .../book/src/native/auth/system_module.md | 3 ++- radix-engine/src/kernel/README.md | 5 ----- radix-engine/src/system/README.md | 21 ------------------- 9 files changed, 12 insertions(+), 44 deletions(-) create mode 100644 radix-engine/book/src/architecture/system/system_modules.md delete mode 100644 radix-engine/src/kernel/README.md delete mode 100644 radix-engine/src/system/README.md diff --git a/radix-engine-monkey-tests/tests/fuzz_kernel.rs b/radix-engine-monkey-tests/tests/fuzz_kernel.rs index cc2853905c..37dde3f70a 100644 --- a/radix-engine-monkey-tests/tests/fuzz_kernel.rs +++ b/radix-engine-monkey-tests/tests/fuzz_kernel.rs @@ -273,19 +273,6 @@ impl KernelCallbackObject for TestCallbackObject { { Ok(()) } - - fn on_move_node( - _node_id: &NodeId, - _is_moving_down: bool, - _is_to_barrier: bool, - _destination_blueprint_id: Option, - _api: &mut Y, - ) -> Result<(), RuntimeError> - where - Y: KernelApi, - { - Ok(()) - } } struct KernelFuzzer { diff --git a/radix-engine/book/book.toml b/radix-engine/book/book.toml index 308b658d27..9338326487 100644 --- a/radix-engine/book/book.toml +++ b/radix-engine/book/book.toml @@ -1,5 +1,4 @@ [book] -authors = ["Joshua Primero"] language = "en" multilingual = false src = "src" diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index 88b9c1e40a..6cb0363896 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -27,6 +27,7 @@ - [Type Checking](architecture/application/type_checking/README.md) - [VM Layer](architecture/vm/README.md) - [System Layer](architecture/system/README.md) + - [System Modules](architecture/system/system_modules.md) - [Kernel Layer](architecture/kernel/README.md) - [Database Layer](architecture/database/README.md) diff --git a/radix-engine/book/src/architecture/application/blueprint/blueprint_modules.md b/radix-engine/book/src/architecture/application/blueprint/blueprint_modules.md index b01e106c1c..cc8694b656 100644 --- a/radix-engine/book/src/architecture/application/blueprint/blueprint_modules.md +++ b/radix-engine/book/src/architecture/application/blueprint/blueprint_modules.md @@ -4,5 +4,5 @@ The system may define additional state to be stored per blueprint known as Bluep every blueprint definition must initialize these modules. Currently there exists two blueprint modules: -* [Auth](../../../native/auth/blueprint_module.md) -* [Package Royalties](../../../native/royalties/package_royalties.md) \ No newline at end of file +* [Auth Blueprint Module](../../../native/auth/blueprint_module.md) +* [Package Royalties Blueprint Module](../../../native/royalties/package_royalties.md) \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/object/object_modules.md b/radix-engine/book/src/architecture/application/object/object_modules.md index bd8a910f67..e092afa087 100644 --- a/radix-engine/book/src/architecture/application/object/object_modules.md +++ b/radix-engine/book/src/architecture/application/object/object_modules.md @@ -1,7 +1,7 @@ # Object Modules The system may define additional state/logic to be stored per globalized object known as -an *Object Module*. +an *Object Module*. The system can define whether an Object Module is required or optional. An Object Module itself has a Blueprint type along with associated logic to manipulate the state of the object module. diff --git a/radix-engine/book/src/architecture/system/system_modules.md b/radix-engine/book/src/architecture/system/system_modules.md new file mode 100644 index 0000000000..27ffa228a8 --- /dev/null +++ b/radix-engine/book/src/architecture/system/system_modules.md @@ -0,0 +1,6 @@ +# System Modules + +System Modules are modules which can be added to the system to extend functionality. + +System Modules are stateful and may expose a set of functions to the application layer as well +as execute additional logic within a system call. \ No newline at end of file diff --git a/radix-engine/book/src/native/auth/system_module.md b/radix-engine/book/src/native/auth/system_module.md index 51449f32df..dd74c55cae 100644 --- a/radix-engine/book/src/native/auth/system_module.md +++ b/radix-engine/book/src/native/auth/system_module.md @@ -1,6 +1,7 @@ # Auth System Module -The Auth System Module operates on every invocation: +The Auth System Module is a [system module](../../architecture/system/system_modules.md) which operates +on every invocation: 1. Creates a new AuthZone 2. Resolve the Permission required to access the method/function invocation 3. Verifies that the Global Caller AuthZone has sufficient proofs to pass the AccessRule diff --git a/radix-engine/src/kernel/README.md b/radix-engine/src/kernel/README.md deleted file mode 100644 index 0698a456ba..0000000000 --- a/radix-engine/src/kernel/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Kernel - -The primary goal of the Kernel in the Radix Engine is to maintain Ownership and Reference invariants. More specifically, -the Kernel enforces that there is one and only one owner for any Node object in the system and that every reference to a Node -object is a valid reference (no dangling pointers or NULL pointers). \ No newline at end of file diff --git a/radix-engine/src/system/README.md b/radix-engine/src/system/README.md deleted file mode 100644 index e52357da1d..0000000000 --- a/radix-engine/src/system/README.md +++ /dev/null @@ -1,21 +0,0 @@ -# System - -The System Layer acts as a rather fat layer between the application and the kernel. It provides -a layer through which all applications must interact with and thus allows for both application standardization -(e.g. Authorization) and global services (e.g. Type Checking and Memory Protection). - -## System Modules - -The system uses pluggable modules to implement application standardization. - -| Module | Description | -|---------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [Auth](system_modules/auth) | Manages Authorization of Blueprint function and method calls. | -| [Costing](system_modules/costing) | Manages Runtime costing (aka "gas") as well as Royalties. Stops execution of a transaction if all reserves have been used. | -| [Limits](system_modules/limits) | Similar to costing except rather than deal with a costing reserve simply tracks explicit resource usage during a transaction. Stops execution of a transaction if any limit is hit. | -| [Runtime](system_modules/transaction_runtime) | Stores transaction runtime state which is not stored on ledger but may be used by the application layer, the transaction id, for example. | -| [Execution Trace](system_modules/execution_trace) | Keeps track of various information during runtime to return in the receipt. | -| [Kernel Trace](system_modules/kernel_trace) | Logs various information as it occurs during runtime. | - -Note that concepts such as Type Checking and Memory Protection are not currently implemented as modules as they -are "deeper" constructs in the System Layer (at least in the present moment). \ No newline at end of file From 484b59862d4190eb03ecd6a8fecfca7dd400a4ed Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Tue, 21 May 2024 10:49:57 -0500 Subject: [PATCH 42/47] Add more description to VM layer --- radix-engine/book/src/architecture/layers.md | 14 +++++----- .../book/src/architecture/vm/README.md | 28 +++++++++++++------ 2 files changed, 27 insertions(+), 15 deletions(-) diff --git a/radix-engine/book/src/architecture/layers.md b/radix-engine/book/src/architecture/layers.md index 71139d43a3..3814035f61 100644 --- a/radix-engine/book/src/architecture/layers.md +++ b/radix-engine/book/src/architecture/layers.md @@ -4,11 +4,11 @@ Radix Engine is organized into 5 layers. Each layer has specific responsibilitie provides an API to the layer above. Middle layers also provide a Callback API which the layer above must implement. -| Layer Name | Responsibilities | -|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Application | Defines Blueprint Application Logic | -| VM | Executes Application Code | -| System | Defines Actor abstraction (Memory Protection)
Defines Package, Blueprint, Object abstractions
Defines System Standards such as Authorization and Versioning | -| Kernel | Defines Node, Partition, Substate abstractions
Maintains Call Frame Stack
Maintains Ownership/Reference invariants | -| Database | Defines PartitionKey, SortKey abstractions | +| Layer Name | Responsibilities | +|--------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Application](application/README.md) | Defines Blueprint Application Logic | +| [VM](vm/README.md) | Executes Application Code | +| [System](system/README.md) | Defines Actor abstraction (Memory Protection)
Defines Package, Blueprint, Object abstractions
Defines System Standards such as Authorization and Versioning | +| [Kernel](kernel/README.md) | Defines Node, Partition, Substate abstractions
Maintains Call Frame Stack
Maintains Ownership/Reference invariants | +| Database | Defines PartitionKey, SortKey abstractions | diff --git a/radix-engine/book/src/architecture/vm/README.md b/radix-engine/book/src/architecture/vm/README.md index a43b9182af..5b9be55efb 100644 --- a/radix-engine/book/src/architecture/vm/README.md +++ b/radix-engine/book/src/architecture/vm/README.md @@ -1,16 +1,28 @@ # VM Layer The VM Layer is responsible for providing the application layer a Turing-complete computing -environment and the interface to the system layer interface. - -Radix Engine currently supports two VM environments: -* A Scrypto WASM VM which exposes the system layer interface through WASM extern functions -* A Native VM which directly compiles applications with Radix Engine in the host's environment. +environment and the interface to the system layer. ## Implementation +Radix Engine currently supports two VM environments: +* A Scrypto WASM VM which exposes the system layer through WASM extern functions +* A Native VM which directly compiles applications with Radix Engine in the host's environment + The VM Layer is implemented by defining the System Callback Object, which requires two callback implementations: -1. `init` which is called on [transaction bootup](../../execution/transaction_lifecycle/bootup.md) -to initialize the vm layer -2. `invoke` which is called on any function/method call \ No newline at end of file +1. `init` which is called on [transaction bootup](../../execution/transaction_lifecycle/bootup.md) to initialize the vm layer +2. `invoke` which is the entrypoint for any function or method invocation + +### Invoke Callback + +On `invoke`, the VM layer loads the code and the vm environment associated with the invocation. + +If the vm environment is WASM, a new WASM instance is created with a fresh heap and stack. +The exported function associated with the invocation is then called with the invocation arguments. +Extern functions expose a subset of the system layer's api which the application can call. + +If the vm environment is Native, the function must have been compiled with Radix Engine and the +function is just called directly. Because all applications using the Native VM are trusted, Native VM +applications are not isolated from the Radix Engine and share the same memory space. The full system +layer API is also exposed to Native VM applications. From eeebbf570619f6995e6d2a6360d788cdb56d34ed Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Wed, 22 May 2024 09:59:36 -0500 Subject: [PATCH 43/47] Add Actor documentation --- radix-engine/book/src/SUMMARY.md | 3 +++ .../book/src/architecture/system/README.md | 5 +++-- .../book/src/architecture/system/actor.md | 20 +++++++++++++++++ .../book/src/architecture/vm/README.md | 22 +++++-------------- .../book/src/architecture/vm/native_vm.md | 7 ++++++ .../book/src/architecture/vm/scrypto_vm.md | 8 +++++++ 6 files changed, 47 insertions(+), 18 deletions(-) create mode 100644 radix-engine/book/src/architecture/system/actor.md create mode 100644 radix-engine/book/src/architecture/vm/native_vm.md create mode 100644 radix-engine/book/src/architecture/vm/scrypto_vm.md diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index 6cb0363896..85b8ac2413 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -26,7 +26,10 @@ - [Blueprint Modules](architecture/application/blueprint/blueprint_modules.md) - [Type Checking](architecture/application/type_checking/README.md) - [VM Layer](architecture/vm/README.md) + - [Scrypto WASM VM](architecture/vm/scrypto_vm.md) + - [Native VM](architecture/vm/native_vm.md) - [System Layer](architecture/system/README.md) + - [Actor](architecture/system/actor.md) - [System Modules](architecture/system/system_modules.md) - [Kernel Layer](architecture/kernel/README.md) - [Database Layer](architecture/database/README.md) diff --git a/radix-engine/book/src/architecture/system/README.md b/radix-engine/book/src/architecture/system/README.md index 5f5d46d74d..25d15abf9e 100644 --- a/radix-engine/book/src/architecture/system/README.md +++ b/radix-engine/book/src/architecture/system/README.md @@ -8,5 +8,6 @@ functionality of the system. ## Implementation -The System Layer implements this by defining the Kernel Callback Object and using the -kernel Node/Partition/Substate abstractions. +The System Layer is implemented by defining the Kernel Callback Object and defining the +Actor/Package/Blueprint/Object abstractings on top of the kernel's Node/Partition/Substate +abstractions. diff --git a/radix-engine/book/src/architecture/system/actor.md b/radix-engine/book/src/architecture/system/actor.md new file mode 100644 index 0000000000..590c34ad21 --- /dev/null +++ b/radix-engine/book/src/architecture/system/actor.md @@ -0,0 +1,20 @@ +# Actor + +An actor is the acting entity currently executing. The system layer exposes an Api for retrieving +state and additional info of the current actor. + +There are five types of actors: + +| Actor Name | Description | +|---------------|-------------------------------------------------------------------------------------------------------| +| Root | The initial application of all transactions. | +| Method | A call on an object. Has direct access to state of the running object. | +| Function | A stateless function call. Has no direct access to any state. | +| Method Hook | A callback call on an object defined by the system. Has direct access to state of the running object. | +| Function Hook | A callback stateless function call defined by the system. Has no direct access to any state. | + +## Implementation + +The state of the current actor is stored per call frame as `CallFrameData`. The system exposes an +interface which can access the state of the currently acting object (if there is one). Thus, the system +prevents higher layers from accessing state of call frame objects which aren't the actor. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/vm/README.md b/radix-engine/book/src/architecture/vm/README.md index 5b9be55efb..27a543531a 100644 --- a/radix-engine/book/src/architecture/vm/README.md +++ b/radix-engine/book/src/architecture/vm/README.md @@ -3,26 +3,16 @@ The VM Layer is responsible for providing the application layer a Turing-complete computing environment and the interface to the system layer. -## Implementation - Radix Engine currently supports two VM environments: -* A Scrypto WASM VM which exposes the system layer through WASM extern functions -* A Native VM which directly compiles applications with Radix Engine in the host's environment +* A [Scrypto WASM VM](scrypto_vm.md) which exposes the system layer through WASM extern functions +* A [Native VM](native_vm.md) which directly compiles applications with Radix Engine in the host's environment + +## Implementation The VM Layer is implemented by defining the System Callback Object, which requires two callback implementations: 1. `init` which is called on [transaction bootup](../../execution/transaction_lifecycle/bootup.md) to initialize the vm layer 2. `invoke` which is the entrypoint for any function or method invocation -### Invoke Callback - -On `invoke`, the VM layer loads the code and the vm environment associated with the invocation. - -If the vm environment is WASM, a new WASM instance is created with a fresh heap and stack. -The exported function associated with the invocation is then called with the invocation arguments. -Extern functions expose a subset of the system layer's api which the application can call. - -If the vm environment is Native, the function must have been compiled with Radix Engine and the -function is just called directly. Because all applications using the Native VM are trusted, Native VM -applications are not isolated from the Radix Engine and share the same memory space. The full system -layer API is also exposed to Native VM applications. +On `invoke`, the VM layer determines the appropriate VM environment and then calls the associated +application layer logic. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/vm/native_vm.md b/radix-engine/book/src/architecture/vm/native_vm.md new file mode 100644 index 0000000000..2ed7612e64 --- /dev/null +++ b/radix-engine/book/src/architecture/vm/native_vm.md @@ -0,0 +1,7 @@ +# Native VM + +On `invoke` of a function/method which executes natively, the function must have been compiled with +Radix Engine and is just called directly. Because all applications using the Native VM are trusted, +Native VM applications are not isolated from the Radix Engine and share the same memory space. + +The full system layer API is also exposed to Native VM applications. diff --git a/radix-engine/book/src/architecture/vm/scrypto_vm.md b/radix-engine/book/src/architecture/vm/scrypto_vm.md new file mode 100644 index 0000000000..2e7c0140c0 --- /dev/null +++ b/radix-engine/book/src/architecture/vm/scrypto_vm.md @@ -0,0 +1,8 @@ +# Scrypto Wasm VM + +On `invoke` of a method which executes in a Scrypto Wasm VM, the VM layer loads the WASM code +associated with the invocation and creates a new WASM instance with a fresh heap and stack. +The exported function associated with the invocation is then called with the +invocation arguments. + +Extern functions are mapped to subset of the system layer's api which the application can call. \ No newline at end of file From b5eb80d3ef34a51da14b008da36745339f319b91 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Thu, 23 May 2024 11:40:42 -0500 Subject: [PATCH 44/47] Add Object Impl documentation --- radix-engine/book/src/SUMMARY.md | 4 +++- .../actor.md => application/actor/README.md} | 8 +------- .../book/src/architecture/system/README.md | 6 ++---- .../architecture/system/actor_implementation.md | 7 +++++++ .../architecture/system/object_implementation.md | 15 +++++++++++++++ 5 files changed, 28 insertions(+), 12 deletions(-) rename radix-engine/book/src/architecture/{system/actor.md => application/actor/README.md} (66%) create mode 100644 radix-engine/book/src/architecture/system/actor_implementation.md create mode 100644 radix-engine/book/src/architecture/system/object_implementation.md diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index 85b8ac2413..8a673a163b 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -25,11 +25,13 @@ - [Types](architecture/application/blueprint/types.md) - [Blueprint Modules](architecture/application/blueprint/blueprint_modules.md) - [Type Checking](architecture/application/type_checking/README.md) + - [Actor](architecture/application/actor/README.md) - [VM Layer](architecture/vm/README.md) - [Scrypto WASM VM](architecture/vm/scrypto_vm.md) - [Native VM](architecture/vm/native_vm.md) - [System Layer](architecture/system/README.md) - - [Actor](architecture/system/actor.md) + - [Object Impl](architecture/system/object_implementation.md) + - [Actor Impl](architecture/system/actor_implementation.md) - [System Modules](architecture/system/system_modules.md) - [Kernel Layer](architecture/kernel/README.md) - [Database Layer](architecture/database/README.md) diff --git a/radix-engine/book/src/architecture/system/actor.md b/radix-engine/book/src/architecture/application/actor/README.md similarity index 66% rename from radix-engine/book/src/architecture/system/actor.md rename to radix-engine/book/src/architecture/application/actor/README.md index 590c34ad21..8f3d75a472 100644 --- a/radix-engine/book/src/architecture/system/actor.md +++ b/radix-engine/book/src/architecture/application/actor/README.md @@ -1,7 +1,6 @@ # Actor -An actor is the acting entity currently executing. The system layer exposes an Api for retrieving -state and additional info of the current actor. +An actor is the acting entity currently executing and determines what state can be directly read. There are five types of actors: @@ -13,8 +12,3 @@ There are five types of actors: | Method Hook | A callback call on an object defined by the system. Has direct access to state of the running object. | | Function Hook | A callback stateless function call defined by the system. Has no direct access to any state. | -## Implementation - -The state of the current actor is stored per call frame as `CallFrameData`. The system exposes an -interface which can access the state of the currently acting object (if there is one). Thus, the system -prevents higher layers from accessing state of call frame objects which aren't the actor. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/system/README.md b/radix-engine/book/src/architecture/system/README.md index 25d15abf9e..62cddee897 100644 --- a/radix-engine/book/src/architecture/system/README.md +++ b/radix-engine/book/src/architecture/system/README.md @@ -1,13 +1,11 @@ # System Layer The System Layer is responsible for: -* Defining Actor abstraction and memory protection -* Defining the Package/Blueprint/Object abstraction +* Defining the Package/Blueprint/[Object](object_implementation.md) abstraction +* Defining [Actor](actor_implementation.md) abstraction and memory protection * Maintaining a set of System Modules, or pluggable software, which extends the functionality of the system. -## Implementation - The System Layer is implemented by defining the Kernel Callback Object and defining the Actor/Package/Blueprint/Object abstractings on top of the kernel's Node/Partition/Substate abstractions. diff --git a/radix-engine/book/src/architecture/system/actor_implementation.md b/radix-engine/book/src/architecture/system/actor_implementation.md new file mode 100644 index 0000000000..7d289cc6ac --- /dev/null +++ b/radix-engine/book/src/architecture/system/actor_implementation.md @@ -0,0 +1,7 @@ +# Actor Implementation + +The system layer is responsible for defining the [Actor](../application/actor/README.md) abstraction. + +The state of the current actor is stored per call frame as `CallFrameData`. The system exposes an +interface which can access the state of the currently acting object (if there is one). Thus, the system +prevents higher layers from accessing state of call frame objects which aren't the actor. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/system/object_implementation.md b/radix-engine/book/src/architecture/system/object_implementation.md new file mode 100644 index 0000000000..8f2c24dc90 --- /dev/null +++ b/radix-engine/book/src/architecture/system/object_implementation.md @@ -0,0 +1,15 @@ +# Object Implementation + +The system layer defines the [Object](../application/object/README.md) abstraction on top of the +kernel's Node/Partition/Substate abstraction. + +The system layer maps every object to a unique NodeId and under every NodeId the partitions are +mapped in the following manner: + +| | Partition Number | +|-------------------|------------------| +| Type Info | 0 | +| Schema Data | 1 | +| Object Modules | 2-31 | +| Reserved | 32-63 | +| Application State | 64-255 | From 4186c4c776daf37494463361ed40d70cb8b23b82 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Fri, 24 May 2024 09:53:05 -0500 Subject: [PATCH 45/47] Cleanup documentation --- radix-blueprint-schema-init/src/lib.rs | 4 ++-- .../src/api/actor_key_value_entry_api.rs | 4 ++-- radix-engine-interface/src/api/costing_api.rs | 4 ++-- radix-engine-interface/src/api/field_api.rs | 12 ++++++------ radix-engine-interface/src/api/mod.rs | 2 +- radix-engine/book/src/SUMMARY.md | 2 +- .../src/architecture/application/blueprint/README.md | 4 ++-- .../application/blueprint/collections.md | 2 +- .../src/architecture/application/blueprint/types.md | 4 ++-- .../src/architecture/application/object/features.md | 5 +++-- .../architecture/application/type_checking/README.md | 11 ----------- .../architecture/application/type_system/README.md | 11 +++++++++++ .../type_checking_arch.drawio | 0 .../type_checking_arch.drawio.svg | 0 .../book/src/execution/environment/README.md | 2 +- .../book/src/execution/environment/invocations.md | 4 ++-- radix-engine/book/src/native/auth/README.md | 4 ++-- radix-engine/book/src/native/auth/auth_stack.svg | 4 ---- .../book/src/native/auth/blueprint_module.md | 4 ++-- radix-engine/book/src/native/auth/system_module.md | 8 ++++---- 20 files changed, 44 insertions(+), 47 deletions(-) delete mode 100644 radix-engine/book/src/architecture/application/type_checking/README.md create mode 100644 radix-engine/book/src/architecture/application/type_system/README.md rename radix-engine/book/src/architecture/application/{type_checking => type_system}/type_checking_arch.drawio (100%) rename radix-engine/book/src/architecture/application/{type_checking => type_system}/type_checking_arch.drawio.svg (100%) delete mode 100644 radix-engine/book/src/native/auth/auth_stack.svg diff --git a/radix-blueprint-schema-init/src/lib.rs b/radix-blueprint-schema-init/src/lib.rs index d26a3c3b8e..3fab82407b 100644 --- a/radix-blueprint-schema-init/src/lib.rs +++ b/radix-blueprint-schema-init/src/lib.rs @@ -32,7 +32,7 @@ pub enum BlueprintHook { pub struct BlueprintSchemaInit { /// List of generic parameters which must be provided on component instantiation and the bounds of these generics pub generics: Vec, - /// Sbor schema which describes types by index + /// Sbor schema which describes various types, each identified by a usize pub schema: VersionedScryptoSchema, /// Describes schema of state by mapping fields/collection indices as a generic or directly into the Sbor schema pub state: BlueprintStateSchemaInit, @@ -66,7 +66,7 @@ impl Default for BlueprintSchemaInit { } } -/// Describes the number of fields and collections some Blueprint has as well +/// Describes the fields and collections some Blueprint has as well /// as the schema and properties of each field and collection #[derive(Debug, Clone, PartialEq, Eq, Default, ScryptoSbor, ManifestSbor)] pub struct BlueprintStateSchemaInit { diff --git a/radix-engine-interface/src/api/actor_key_value_entry_api.rs b/radix-engine-interface/src/api/actor_key_value_entry_api.rs index 91755d4e33..281b604300 100644 --- a/radix-engine-interface/src/api/actor_key_value_entry_api.rs +++ b/radix-engine-interface/src/api/actor_key_value_entry_api.rs @@ -16,7 +16,7 @@ pub trait SystemActorKeyValueEntryApi { ) -> Result; /// Removes an entry from a collection. If an invalid collection index or key is passed an - /// error is returned, otherwise the encoding of a value of an entry is returned. + /// error is returned, otherwise the encoding of a value of the entry is returned. fn actor_remove_key_value_entry( &mut self, object_handle: ActorStateHandle, @@ -25,7 +25,7 @@ pub trait SystemActorKeyValueEntryApi { ) -> Result, E>; /// Removes an entry from a collection. If an invalid collection index or key is passed an - /// error is returned, otherwise the value of an entry is returned. + /// error is returned, otherwise the value of the entry is returned. fn actor_remove_key_value_entry_typed( &mut self, object_handle: ActorStateHandle, diff --git a/radix-engine-interface/src/api/costing_api.rs b/radix-engine-interface/src/api/costing_api.rs index b9c595cb7a..d87d79b87e 100644 --- a/radix-engine-interface/src/api/costing_api.rs +++ b/radix-engine-interface/src/api/costing_api.rs @@ -18,10 +18,10 @@ pub trait SystemCostingApi { /// Retrieve the cost unit price in XRD fn execution_cost_unit_price(&mut self) -> Result; - /// Retrieve the cost unit limit for finalization + /// Retrieve the finalization cost unit limit fn finalization_cost_unit_limit(&mut self) -> Result; - /// Retrieve the cost unit finalization price in XRD + /// Retrieve the finalization cost unit price in XRD fn finalization_cost_unit_price(&mut self) -> Result; /// Retrieve the usd price of XRD diff --git a/radix-engine-interface/src/api/field_api.rs b/radix-engine-interface/src/api/field_api.rs index 07cf443112..7295a2b718 100644 --- a/radix-engine-interface/src/api/field_api.rs +++ b/radix-engine-interface/src/api/field_api.rs @@ -33,20 +33,20 @@ impl FieldPayloadMarker for &T {} /// System api to read/write fields pub trait SystemFieldApi { - // Retrieve the value of a field + /// Retrieve the value of a field fn field_read(&mut self, handle: FieldHandle) -> Result, E>; - // Retrieve the value of a field + /// Retrieve the value of a field fn field_read_typed(&mut self, handle: FieldHandle) -> Result { let buf = self.field_read(handle)?; let typed_substate: S = scrypto_decode(&buf).map_err(|e| e).unwrap(); Ok(typed_substate) } - // Write a value to a field + /// Write a value to a field fn field_write(&mut self, handle: FieldHandle, buffer: Vec) -> Result<(), E>; - // Write a value to a field + /// Write a value to a field fn field_write_typed( &mut self, handle: FieldHandle, @@ -56,9 +56,9 @@ pub trait SystemFieldApi { self.field_write(handle, buf) } - // Lock a field such that it is immutable + /// Lock a field such that it becomes immutable fn field_lock(&mut self, handle: FieldHandle) -> Result<(), E>; - // Close a field handle so that it is no longer usable + /// Close a field handle so that it is no longer usable fn field_close(&mut self, handle: FieldHandle) -> Result<(), E>; } diff --git a/radix-engine-interface/src/api/mod.rs b/radix-engine-interface/src/api/mod.rs index 784a0998c4..3b2af3ad5f 100644 --- a/radix-engine-interface/src/api/mod.rs +++ b/radix-engine-interface/src/api/mod.rs @@ -40,7 +40,7 @@ pub const ACTOR_REF_AUTH_ZONE: ActorRefHandle = 8u32; pub type FieldIndex = u8; pub type CollectionIndex = u8; -/// Interface of the system, for blueprints and system modules. +/// Interface of the system, for blueprints and object modules. /// /// For WASM blueprints, only a subset of the API is exposed at the moment. pub trait SystemApi: diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index 8a673a163b..55a8a84acb 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -24,7 +24,7 @@ - [Hooks](architecture/application/blueprint/hooks.md) - [Types](architecture/application/blueprint/types.md) - [Blueprint Modules](architecture/application/blueprint/blueprint_modules.md) - - [Type Checking](architecture/application/type_checking/README.md) + - [Type System](architecture/application/type_system/README.md) - [Actor](architecture/application/actor/README.md) - [VM Layer](architecture/vm/README.md) - [Scrypto WASM VM](architecture/vm/scrypto_vm.md) diff --git a/radix-engine/book/src/architecture/application/blueprint/README.md b/radix-engine/book/src/architecture/application/blueprint/README.md index 03826c8db5..8d1d482400 100644 --- a/radix-engine/book/src/architecture/application/blueprint/README.md +++ b/radix-engine/book/src/architecture/application/blueprint/README.md @@ -1,8 +1,8 @@ # Blueprint A Blueprint is the Radix Engine equivalent of Classes/Types in Object-Oriented Languages. -It acts as a type identifier for an object and describes shared properties of all objects -of that blueprint such as function/method interfaces. +It acts as a type identifier for an object and describes shared properties and behavior of +all objects of that blueprint. Each blueprint has a unique name within its package and are globally identifiable by ` + `. diff --git a/radix-engine/book/src/architecture/application/blueprint/collections.md b/radix-engine/book/src/architecture/application/blueprint/collections.md index 1c43328b76..664460ebaa 100644 --- a/radix-engine/book/src/architecture/application/blueprint/collections.md +++ b/radix-engine/book/src/architecture/application/blueprint/collections.md @@ -2,7 +2,7 @@ > **_NOTE:_** Collections are currently only available for use by native packages. -A collections is a set of data which can be read/loaded incrementally. There are currently three types +A collection is a set of data which share the same schema. There are currently three types of collections: 1. Key-Value Collection 2. Index Collection diff --git a/radix-engine/book/src/architecture/application/blueprint/types.md b/radix-engine/book/src/architecture/application/blueprint/types.md index 9bc7fb159c..1c541bc3f8 100644 --- a/radix-engine/book/src/architecture/application/blueprint/types.md +++ b/radix-engine/book/src/architecture/application/blueprint/types.md @@ -1,6 +1,6 @@ # Types -A blueprint may associate a schema to a name. This name can then be used externally to specify a -schema defined by this blueprint. +A blueprint may associate a schema to a name. This name combined with the blueprint ID can be used +to specify a type. Types are identified by string. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/object/features.md b/radix-engine/book/src/architecture/application/object/features.md index d259f1d096..8c9415c91a 100644 --- a/radix-engine/book/src/architecture/application/object/features.md +++ b/radix-engine/book/src/architecture/application/object/features.md @@ -1,4 +1,5 @@ # Features -An object's features describes optional features an object may have. An object's features -must be a subset of the total [features](../blueprint/features.md) defined in the object's blueprint. \ No newline at end of file +An object's features describes is a subset of the total [features](../blueprint/features.md) defined +in the object's blueprint. Having a feature enabled/disabled can modify both behavior and state stored +for the object. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/type_checking/README.md b/radix-engine/book/src/architecture/application/type_checking/README.md deleted file mode 100644 index f9802ca35c..0000000000 --- a/radix-engine/book/src/architecture/application/type_checking/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# Type Checking - -The Type Checking System checks that payloads coming from the application layer match the -schema defined in the Blueprint. This includes: -* Object Fields/Collections -* Function Input/Output -* Events - -The Type Checking System supports generics. - -![](type_checking_arch.drawio.svg) \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/type_system/README.md b/radix-engine/book/src/architecture/application/type_system/README.md new file mode 100644 index 0000000000..f27fa99c94 --- /dev/null +++ b/radix-engine/book/src/architecture/application/type_system/README.md @@ -0,0 +1,11 @@ +# Type System + +The Type System checks that payloads coming from the application layer match the schema defined in +the Blueprint. This includes: +* Object Fields/Collections +* Function Input/Output +* Events + +The Type Checking System supports generics. + +![](type_checking_arch.drawio.svg) \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/type_checking/type_checking_arch.drawio b/radix-engine/book/src/architecture/application/type_system/type_checking_arch.drawio similarity index 100% rename from radix-engine/book/src/architecture/application/type_checking/type_checking_arch.drawio rename to radix-engine/book/src/architecture/application/type_system/type_checking_arch.drawio diff --git a/radix-engine/book/src/architecture/application/type_checking/type_checking_arch.drawio.svg b/radix-engine/book/src/architecture/application/type_system/type_checking_arch.drawio.svg similarity index 100% rename from radix-engine/book/src/architecture/application/type_checking/type_checking_arch.drawio.svg rename to radix-engine/book/src/architecture/application/type_system/type_checking_arch.drawio.svg diff --git a/radix-engine/book/src/execution/environment/README.md b/radix-engine/book/src/execution/environment/README.md index dd1899b61f..e9b2507d70 100644 --- a/radix-engine/book/src/execution/environment/README.md +++ b/radix-engine/book/src/execution/environment/README.md @@ -3,7 +3,7 @@ Every method/function execution has a call frame associated with it managed by the Kernel. A call frame contains all owned and referenced objects usable by the running function. These objects -are referrable by `NodeId`. +are referrable by `NodeId` and system-defined indices. ## Invocations diff --git a/radix-engine/book/src/execution/environment/invocations.md b/radix-engine/book/src/execution/environment/invocations.md index 3f52712338..2b4a3432f3 100644 --- a/radix-engine/book/src/execution/environment/invocations.md +++ b/radix-engine/book/src/execution/environment/invocations.md @@ -15,8 +15,8 @@ On one of these calls, the system then follows three phases: System module does its own checks (e.g. auth). -Kernel invoke is called which setups a new call frame. The passed in objects in the arguments are verified -to be valid. +Kernel invoke is called which setups a new call frame. The arguments are verified against the input +schema of the function defined by the blueprint definition. ## Execution diff --git a/radix-engine/book/src/native/auth/README.md b/radix-engine/book/src/native/auth/README.md index 9d6671ba9a..ae1c8870b6 100644 --- a/radix-engine/book/src/native/auth/README.md +++ b/radix-engine/book/src/native/auth/README.md @@ -3,7 +3,7 @@ Unlike the majority of blockchains which rely on a caller identifier for access control, the Auth system uses a more distributed "Proof" system. Before accessing a protected method a caller must provide specific "Proofs" of resources they have access to. These proofs -must then match the required proofs defined by protected method or function of the callee. +must then match the requirements of the callee function or method. The Access Control System is composed of four parts: @@ -15,4 +15,4 @@ which assigns access rules for each role on object instantiation. 3. An [AuthZone Blueprint](authzone.md), which allows a caller to update the proofs in their authzone. 4. An [Access Control System Module](system_module.md), which creates a new AuthZone for every new call frame and verifies that AuthZone proofs match the requirements of accessing an -object's function. \ No newline at end of file +object's method. \ No newline at end of file diff --git a/radix-engine/book/src/native/auth/auth_stack.svg b/radix-engine/book/src/native/auth/auth_stack.svg deleted file mode 100644 index 3399bd221e..0000000000 --- a/radix-engine/book/src/native/auth/auth_stack.svg +++ /dev/null @@ -1,4 +0,0 @@ - - - -
Global Context 2
Global Context 1
Global Context 0
Call Frame 0
AuthZone 1
Owns
Call Frame 1
References
Call Frame 2
AuthZone 2
Owns
Parent
References
Call Frame 3
AuthZone 3
References
Owns
Call Frame 4
AuthZone 4
References
Global Caller
Global Caller
Call Frame 5
AuthZone 5
References
Owns
Owns
Global Caller
Call Frame 6
AuthZone 6
References
Owns
Parent
Global Caller
Parent
 \ No newline at end of file diff --git a/radix-engine/book/src/native/auth/blueprint_module.md b/radix-engine/book/src/native/auth/blueprint_module.md index 86a578f96d..61fd998cc6 100644 --- a/radix-engine/book/src/native/auth/blueprint_module.md +++ b/radix-engine/book/src/native/auth/blueprint_module.md @@ -1,6 +1,6 @@ -# Access Control Blueprint Module +# Auth Blueprint Module -The access control [blueprint module](../../architecture/application/blueprint/blueprint_modules.md) defines three +The auth [blueprint module](../../architecture/application/blueprint/blueprint_modules.md) defines three things for every blueprint: * Function AccessRules * Method accessibility diff --git a/radix-engine/book/src/native/auth/system_module.md b/radix-engine/book/src/native/auth/system_module.md index dd74c55cae..42b48ecd71 100644 --- a/radix-engine/book/src/native/auth/system_module.md +++ b/radix-engine/book/src/native/auth/system_module.md @@ -3,8 +3,8 @@ The Auth System Module is a [system module](../../architecture/system/system_modules.md) which operates on every invocation: 1. Creates a new AuthZone -2. Resolve the Permission required to access the method/function invocation -3. Verifies that the Global Caller AuthZone has sufficient proofs to pass the AccessRule +2. Resolve the requirements to access the method/function invocation +3. Verifies that the Global Caller AuthZone has sufficient proofs to meet the requirements ## AuthZone Creation @@ -29,10 +29,10 @@ This pattern generates a stack which looks like: Permission resolving involves loading up relevant state of the callee and generating a permission object from this state. -If the callee is a function call then the permission is loaded from the function access rules +If the callee is a function then the permission is loaded from the function access rules specified in the blueprint's [access control blueprint module](blueprint_module.md). -If the callee is a method call then the Method Accessibility is loaded from the callee's +If the callee is a method then the Method Accessibility is loaded from the callee's [access control blueprint module](blueprint_module.md) as well as the state in the callee's [Role Assignment Object Module](role_assignment.md). From these two states, the permission to access the method is derived. From c0355321ec23d260e7349c1a66e01359a88bb071 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Fri, 24 May 2024 10:32:57 -0500 Subject: [PATCH 46/47] Add Blueprint documentation --- radix-engine/book/src/SUMMARY.md | 4 +- .../book/src/architecture/system/README.md | 8 ++- ...{actor_implementation.md => actor_impl.md} | 0 .../src/architecture/system/blueprint_impl.md | 8 +++ .../system/bp_partition_mapping.drawio | 55 +++++++++++++++++++ .../system/bp_partition_mapping.drawio.svg | 4 ++ ...bject_implementation.md => object_impl.md} | 0 .../book/src/architecture/vm/README.md | 5 +- 8 files changed, 77 insertions(+), 7 deletions(-) rename radix-engine/book/src/architecture/system/{actor_implementation.md => actor_impl.md} (100%) create mode 100644 radix-engine/book/src/architecture/system/blueprint_impl.md create mode 100644 radix-engine/book/src/architecture/system/bp_partition_mapping.drawio create mode 100644 radix-engine/book/src/architecture/system/bp_partition_mapping.drawio.svg rename radix-engine/book/src/architecture/system/{object_implementation.md => object_impl.md} (100%) diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index 55a8a84acb..1d91467a23 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -30,8 +30,8 @@ - [Scrypto WASM VM](architecture/vm/scrypto_vm.md) - [Native VM](architecture/vm/native_vm.md) - [System Layer](architecture/system/README.md) - - [Object Impl](architecture/system/object_implementation.md) - - [Actor Impl](architecture/system/actor_implementation.md) + - [Object Impl](architecture/system/object_impl.md) + - [Actor Impl](architecture/system/actor_impl.md) - [System Modules](architecture/system/system_modules.md) - [Kernel Layer](architecture/kernel/README.md) - [Database Layer](architecture/database/README.md) diff --git a/radix-engine/book/src/architecture/system/README.md b/radix-engine/book/src/architecture/system/README.md index 62cddee897..530700c122 100644 --- a/radix-engine/book/src/architecture/system/README.md +++ b/radix-engine/book/src/architecture/system/README.md @@ -1,11 +1,13 @@ # System Layer The System Layer is responsible for: -* Defining the Package/Blueprint/[Object](object_implementation.md) abstraction -* Defining [Actor](actor_implementation.md) abstraction and memory protection -* Maintaining a set of System Modules, or pluggable software, which extends the +* Defining the [Object](object_impl.md), [Blueprint](blueprint_impl.md), and Package abstraction +* Defining [Actor](actor_impl.md) abstraction and memory protection +* Maintaining a set of [System Modules](system_modules.md), or pluggable software, which extends the functionality of the system. +## Implementation + The System Layer is implemented by defining the Kernel Callback Object and defining the Actor/Package/Blueprint/Object abstractings on top of the kernel's Node/Partition/Substate abstractions. diff --git a/radix-engine/book/src/architecture/system/actor_implementation.md b/radix-engine/book/src/architecture/system/actor_impl.md similarity index 100% rename from radix-engine/book/src/architecture/system/actor_implementation.md rename to radix-engine/book/src/architecture/system/actor_impl.md diff --git a/radix-engine/book/src/architecture/system/blueprint_impl.md b/radix-engine/book/src/architecture/system/blueprint_impl.md new file mode 100644 index 0000000000..66d4b5697d --- /dev/null +++ b/radix-engine/book/src/architecture/system/blueprint_impl.md @@ -0,0 +1,8 @@ +# Blueprint Implementation + +## State to Partition Mapping + +The mapping from Fields and Collection indices to Partition Number is managed by the System Layer +and done at a per blueprint basis. + +![](bp_partition_mapping.drawio.svg) \ No newline at end of file diff --git a/radix-engine/book/src/architecture/system/bp_partition_mapping.drawio b/radix-engine/book/src/architecture/system/bp_partition_mapping.drawio new file mode 100644 index 0000000000..cc86218ed3 --- /dev/null +++ b/radix-engine/book/src/architecture/system/bp_partition_mapping.drawio @@ -0,0 +1,55 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/radix-engine/book/src/architecture/system/bp_partition_mapping.drawio.svg b/radix-engine/book/src/architecture/system/bp_partition_mapping.drawio.svg new file mode 100644 index 0000000000..72313571bf --- /dev/null +++ b/radix-engine/book/src/architecture/system/bp_partition_mapping.drawio.svg @@ -0,0 +1,4 @@ + + + +
Fields
Collection0
Collection1
Base Partition + 0
Base Partition + 1
Base Partition + 2
Base Partition
 \ No newline at end of file diff --git a/radix-engine/book/src/architecture/system/object_implementation.md b/radix-engine/book/src/architecture/system/object_impl.md similarity index 100% rename from radix-engine/book/src/architecture/system/object_implementation.md rename to radix-engine/book/src/architecture/system/object_impl.md diff --git a/radix-engine/book/src/architecture/vm/README.md b/radix-engine/book/src/architecture/vm/README.md index 27a543531a..712c08645a 100644 --- a/radix-engine/book/src/architecture/vm/README.md +++ b/radix-engine/book/src/architecture/vm/README.md @@ -1,7 +1,8 @@ # VM Layer -The VM Layer is responsible for providing the application layer a Turing-complete computing -environment and the interface to the system layer. +The VM Layer is responsible for passing control from the system to the application as well as +providing the application layer a Turing-complete computing environment and the interface to the +system layer. Radix Engine currently supports two VM environments: * A [Scrypto WASM VM](scrypto_vm.md) which exposes the system layer through WASM extern functions From ab5b2974ad573abc436d42d08f1a5ca3d444f6d4 Mon Sep 17 00:00:00 2001 From: Joshua Primero Date: Fri, 24 May 2024 10:40:52 -0500 Subject: [PATCH 47/47] Add Blueprint impl to summary --- radix-engine/book/src/SUMMARY.md | 1 + 1 file changed, 1 insertion(+) diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index 1d91467a23..096be6ed8d 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -31,6 +31,7 @@ - [Native VM](architecture/vm/native_vm.md) - [System Layer](architecture/system/README.md) - [Object Impl](architecture/system/object_impl.md) + - [Blueprint Impl](architecture/system/blueprint_impl.md) - [Actor Impl](architecture/system/actor_impl.md) - [System Modules](architecture/system/system_modules.md) - [Kernel Layer](architecture/kernel/README.md)