(self.webpackChunk_N_E=self.webpackChunk_N_E||[]).push([[138],{57687:function(e,n,a){(window.__NEXT_P=window.__NEXT_P||[]).push(["/en/build/smart-contracts/book/package-upgrades",function(){return a(46742)}])},46742:function(e,n,a){"use strict";a.r(n),a.d(n,{useTOC:function(){return d}});var t=a(31549),i=a(82910),r=a(15801),s=a(46977),o=a(13844);function d(e){return[{value:"How it works",id:"how-it-works",depth:2},{value:"How to upgrade",id:"how-to-upgrade",depth:2},{value:"Upgrade policies",id:"upgrade-policies",depth:2},{value:"Compatibility rules",id:"compatibility-rules",depth:2},{value:"Security considerations for dependencies",id:"security-considerations-for-dependencies",depth:2},{value:"Programmatic upgrade",id:"programmatic-upgrade",depth:2}]}n.default=(0,i.c)(function(e){let{toc:n=d(e)}=e,a={a:"a",code:"code",em:"em",h1:"h1",h2:"h2",li:"li",p:"p",pre:"pre",span:"span",ul:"ul",...(0,s.a)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(a.h1,{children:"Package Upgrades"}),"\n",(0,t.jsx)(a.p,{children:"Move code (e.g., Move modules) on the Aptos blockchain can be upgraded. This\nallows code owners and module developers to update and evolve their contracts\nunder a single, stable, well-known account address that doesn’t change. If a\nmodule upgrade happens, all consumers of that module will automatically receive\nthe latest version of the code (e.g., the next time they interact with it)."}),"\n",(0,t.jsxs)(a.p,{children:["The Aptos blockchain natively supports different ",(0,t.jsx)(a.em,{children:"upgrade policies"}),", which allow\nmove developers to explicitly define the constraints around how their move code\ncan be upgraded. The default policy is ",(0,t.jsx)(a.em,{children:"backwards compatible"}),". This means that\ncode upgrades are accepted only if they guarantee that no existing resource storage\nor public APIs are broken by the upgrade (including public functions).\nThis compatibility checking is possible because of Move’s strongly typed bytecode\nsemantics."]}),"\n",(0,t.jsxs)(a.p,{children:["We note, however, that even compatible upgrades can have hazardous effects on\napplications and dependent Move code (for example, if the semantics of the underlying\nmodule are modified). As a result, developers should be careful when depending on\nthird-party Move code that can be upgraded on-chain. See\n",(0,t.jsx)(a.a,{href:"#security-considerations-for-dependencies",children:"Security considerations for dependencies"}),"\nfor more details."]}),"\n",(0,t.jsx)(a.h2,{id:n[0].id,children:n[0].value}),"\n",(0,t.jsxs)(a.p,{children:["Move code upgrades on the Aptos blockchain happen at the ",(0,t.jsx)(a.a,{href:"packages",children:"Move package"}),"\ngranularity. A package specifies an upgrade policy in the ",(0,t.jsx)(a.code,{children:"Move.toml"})," manifest:"]}),"\n",(0,t.jsx)(a.pre,{tabIndex:"0","data-language":"toml","data-word-wrap":"","data-copy":"",children:(0,t.jsxs)(a.code,{children:[(0,t.jsxs)(a.span,{children:[(0,t.jsx)(a.span,{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"},children:"["}),(0,t.jsx)(a.span,{style:{"--shiki-light":"#6F42C1","--shiki-dark":"#B392F0"},children:"package"}),(0,t.jsx)(a.span,{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"},children:"]"})]}),"\n",(0,t.jsxs)(a.span,{children:[(0,t.jsx)(a.span,{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"},children:"name = "}),(0,t.jsx)(a.span,{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"},children:'"MyApp"'})]}),"\n",(0,t.jsxs)(a.span,{children:[(0,t.jsx)(a.span,{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"},children:"version = "}),(0,t.jsx)(a.span,{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"},children:'"0.0.1"'})]}),"\n",(0,t.jsxs)(a.span,{children:[(0,t.jsx)(a.span,{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"},children:"upgrade_policy = "}),(0,t.jsx)(a.span,{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"},children:'"compatible"'})]}),"\n",(0,t.jsx)(a.span,{children:(0,t.jsx)(a.span,{style:{"--shiki-light":"#B31D28","--shiki-light-font-style":"italic","--shiki-dark":"#FDAEB7","--shiki-dark-font-style":"italic"},children:"..."})})]})}),"\n",(0,t.jsx)(o.U,{type:"info",children:(0,t.jsx)(a.p,{children:"Aptos checks compatibility at the time a Move package is published via an Aptos transaction. This transaction will abort if deemed incompatible."})}),"\n",(0,t.jsx)(a.h2,{id:n[1].id,children:n[1].value}),"\n",(0,t.jsxs)(a.p,{children:["To upgrade already published Move code, simply attempt to republish the code at\nthe same address that it was previously published. This can be done by following the\ninstructions for code compilation and publishing using the\n",(0,t.jsx)(a.a,{href:"../../cli/working-with-move-contracts",children:"Aptos CLI"}),". For an example,\nsee the ",(0,t.jsx)(a.a,{href:"../../guides/first-move-module",children:"Your First Move Module"})," tutorial."]}),"\n",(0,t.jsx)(a.h2,{id:n[2].id,children:n[2].value}),"\n",(0,t.jsx)(a.p,{children:"There are two different upgrade policies currently supported by Aptos:"}),"\n",(0,t.jsxs)(a.ul,{children:["\n",(0,t.jsxs)(a.li,{children:[(0,t.jsx)(a.code,{children:"compatible"}),": these upgrades must be backwards compatible, specifically:","\n",(0,t.jsxs)(a.ul,{children:["\n",(0,t.jsx)(a.li,{children:"For storage, all old struct declarations must be the same in\nthe new code. This ensures that the existing state of storage is\ncorrectly interpreted by the new code. However, new struct declarations\ncan be added."}),"\n",(0,t.jsx)(a.li,{children:"For APIs, all existing public functions must have the same signature as\nbefore. New functions, including public and entry functions, can be added."}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(a.li,{children:[(0,t.jsx)(a.code,{children:"immutable"}),": the code is not upgradeable and is guaranteed to stay the same\nforever."]}),"\n"]}),"\n",(0,t.jsxs)(a.p,{children:["Those policies are ordered regarding strength such that ",(0,t.jsx)(a.code,{children:"compatible < immutable"}),",\ni.e., compatible is weaker than immutable. The policy of a package on-chain can\nonly get stronger, not weaker. Moreover, the policy of all dependencies of a\npackage must be stronger or equal to the policy of the given package. For example,\nan ",(0,t.jsx)(a.code,{children:"immutable"})," package cannot refer directly or indirectly to a ",(0,t.jsx)(a.code,{children:"compatible"})," package.\nThis gives users the guarantee that no unexpected updates can happen under the hood."]}),"\n",(0,t.jsxs)(a.p,{children:["Note that there is one exception to the above rule: framework packages\ninstalled at addresses ",(0,t.jsx)(a.code,{children:"0x1"})," to ",(0,t.jsx)(a.code,{children:"0xa"})," are exempted from the dependency check.\nThis is necessary so one can define an ",(0,t.jsx)(a.code,{children:"immutable"})," package based on the standard\nlibraries, which have the ",(0,t.jsx)(a.code,{children:"compatible"})," policy to allow critical upgrades and fixes."]}),"\n",(0,t.jsx)(a.h2,{id:n[3].id,children:n[3].value}),"\n",(0,t.jsxs)(a.p,{children:["When using ",(0,t.jsx)(a.code,{children:"compatible"})," upgrade policy, a module package can be upgraded. However, updates to existing modules already\npublished previously need to be compatible and follow the rules below:"]}),"\n",(0,t.jsxs)(a.ul,{children:["\n",(0,t.jsx)(a.li,{children:"All existing structs’ fields cannot be updated. This means no new fields can be added and existing fields cannot be\nmodified. Struct abilities also cannot be changed (no new ones added or existing removed)."}),"\n",(0,t.jsx)(a.li,{children:"All public and entry functions cannot change their signature (argument types, type argument, return types). However,\nargument names can change."}),"\n",(0,t.jsxs)(a.li,{children:[(0,t.jsx)(a.code,{children:"public(friend)"})," functions are treated as private and thus their signature can arbitrarily change. This is safe as\nonly modules in the same package can call friend functions anyway, and they need to be updated if the signature changes."]}),"\n"]}),"\n",(0,t.jsx)(a.p,{children:"When updating your modules, if you see an incompatible error, make sure to check the above rules and fix any violations."}),"\n",(0,t.jsx)(a.h2,{id:n[4].id,children:n[4].value}),"\n",(0,t.jsx)(a.p,{children:"As mentioned above, even compatible upgrades can have disastrous effects for\napplications that depend on the upgraded code. These effects can come from bugs,\nbut they can also be the result of malicious upgrades. For example,\nan upgraded dependency can suddenly make all functions abort, breaking the\noperation of your Move code. Alternatively, an upgraded dependency can make\nall functions suddenly cost much more gas to execute then before the upgrade.\nAs result, dependencies to upgradeable packages need to be handled with care:"}),"\n",(0,t.jsxs)(a.ul,{children:["\n",(0,t.jsxs)(a.li,{children:["The safest dependency is, of course, an ",(0,t.jsx)(a.code,{children:"immutable"})," package. This guarantees\nthat the dependency will never change, including its transitive dependencies.\nIn order to update an immutable package, the owner would have to introduce a\nnew major version, which is practically like deploying a new, separate\nand independent package. This is because major versioning can be expressed\nonly by name (e.g. ",(0,t.jsx)(a.code,{children:"module feature_v1"})," and ",(0,t.jsx)(a.code,{children:"module feature_v2"}),"). However,\nnot all package owners like to publish their code as ",(0,t.jsx)(a.code,{children:"immutable"}),", because this\ntakes away the ability to fix bugs and update the code in place."]}),"\n",(0,t.jsxs)(a.li,{children:["If you have a dependency to a ",(0,t.jsx)(a.code,{children:"compatible"})," package, it is highly\nrecommended you know and understand the entity publishing the package.\nThe highest level of assurance is when the package is governed by a\nDecentralized Autonomous Organization (DAO) where no single user can initiate\nan upgrade; a vote or similar has to be taken. This is the case for the Aptos\nframework."]}),"\n"]}),"\n",(0,t.jsx)(a.h2,{id:n[5].id,children:n[5].value}),"\n",(0,t.jsxs)(a.p,{children:["In general, Aptos offers, via the Move module ",(0,t.jsx)(a.code,{children:"aptos_framework::code"}),",\nways to publish code from anywhere in your smart contracts. However,\nnotice that code published in the current transaction can be executed\nonly after that transaction ends."]}),"\n",(0,t.jsxs)(a.p,{children:["The Aptos framework itself, including all the on-chain administration logic, is\nan example for programmatic upgrade. The framework is marked as ",(0,t.jsx)(a.code,{children:"compatible"}),".\nUpgrades happen via specific generated governance scripts. For more details,\nsee ",(0,t.jsx)(a.a,{href:"../../../network/blockchain/governance",children:"Aptos Governance"}),"."]})]})},"/en/build/smart-contracts/book/package-upgrades",{filePath:"pages/en/build/smart-contracts/book/package-upgrades.mdx",timestamp:1728425436e3,pageMap:r.v,frontMatter:{},title:"Package Upgrades"},"undefined"==typeof RemoteContent?d:RemoteContent.useTOC)},13844:function(e,n,a){"use strict";a.d(n,{U:function(){return d}});var t=a(31549),i=a(78364),r=a(83185);let s={default:"\uD83D\uDCA1",error:"\uD83D\uDEAB",info:(0,t.jsx)(r.AV,{className:"_mt-1"}),warning:"⚠️"},o={default:(0,i.Z)("_border-orange-100 _bg-orange-50 _text-orange-800 dark:_border-orange-400/30 dark:_bg-orange-400/20 dark:_text-orange-300"),error:(0,i.Z)("_border-red-200 _bg-red-100 _text-red-900 dark:_border-red-200/30 dark:_bg-red-900/30 dark:_text-red-200"),info:(0,i.Z)("_border-blue-200 _bg-blue-100 _text-blue-900 dark:_border-blue-200/30 dark:_bg-blue-900/30 dark:_text-blue-200"),warning:(0,i.Z)("_border-yellow-100 _bg-yellow-50 _text-yellow-900 dark:_border-yellow-200/30 dark:_bg-yellow-700/30 dark:_text-yellow-200")};function d({children:e,type:n="default",emoji:a=s[n]}){return(0,t.jsxs)("div",{className:(0,i.Z)("nextra-callout _overflow-x-auto _mt-6 _flex _rounded-lg _border _py-2 ltr:_pr-4 rtl:_pl-4","contrast-more:_border-current contrast-more:dark:_border-current",o[n]),children:[(0,t.jsx)("div",{className:"_select-none _text-xl ltr:_pl-3 ltr:_pr-2 rtl:_pr-3 rtl:_pl-2",style:{fontFamily:'"Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"'},children:a}),(0,t.jsx)("div",{className:"_w-full _min-w-0 _leading-7",children:e})]})}},82910:function(e,n,a){"use strict";a.d(n,{c:function(){return d}});var t=a(31549),i=a(74271),r=a(14553),s=a(55754),o=a(46977);function d(e,n,a,t){let r=globalThis[i.ud];return r.route=n,r.pageMap=a.pageMap,r.context[n]={Content:e,pageOpts:a,useTOC:t},l}function l({__nextra_pageMap:e=[],__nextra_dynamic_opts:n,...a}){let o=globalThis[i.ud],{Layout:d,themeConfig:l}=o,{route:h,locale:p}=(0,r.t)(),u=o.context[h];if(!u)throw Error(`No content found for the "${h}" route. Please report it as a bug.`);let{pageOpts:g,useTOC:m,Content:b}=u;if(h.startsWith("/["))g.pageMap=e;else for(let{route:n,children:a}of e){let e=n.split("/").slice(p?2:1);(function e(n,[a,...t]){for(let i of n)if("children"in i&&a===i.name)return t.length?e(i.children,t):i})(g.pageMap,e).children=a}if(n){let{title:e,frontMatter:a}=n;g={...g,title:e,frontMatter:a}}return(0,t.jsx)(d,{themeConfig:l,pageOpts:g,pageProps:a,children:(0,t.jsx)(s.F,{value:a,children:(0,t.jsx)(c,{useTOC:m,children:(0,t.jsx)(b,{...a})})})})}function c({children:e,useTOC:n}){let{wrapper:a}=(0,o.a)();return(0,t.jsx)(h,{useTOC:n,wrapper:a,children:e})}function h({children:e,useTOC:n,wrapper:a,...i}){let r=n(i);return a?(0,t.jsx)(a,{toc:r,children:e}):e}}},function(e){e.O(0,[68889,15801,92888,49774,40179],function(){return e(e.s=57687)}),_N_E=e.O()}]);