invocation.js

  1. import { Asset } from './asset';
  2. import { Address } from './address';
  3. import { scValToNative } from './scval';
  5. /**
  6.  * @typedef CreateInvocation
  7.  *
  8.  * @prop {'wasm'|'sac'} type  a type indicating if this creation was a custom
  9.  *    contract or a wrapping of an existing Stellar asset
  10.  * @prop {string} [token] when `type=='sac'`, the canonical {@link Asset} that
  11.  *    is being wrapped by this Stellar Asset Contract
  12.  * @prop {object} [wasm]  when `type=='wasm'`, add'l creation parameters
  13.  *
  14.  * @prop {string} wasm.hash     hex hash of WASM bytecode backing this contract
  15.  * @prop {string} wasm.address  contract address of this deployment
  16.  * @prop {string} wasm.salt     hex salt that the user consumed when creating
  17.  *    this contract (encoded in the resulting address)
  18.  * @prop {any[]}  [wasm.constructorArgs] a list of natively-represented values
  19.  *    (see {@link scValToNative}) that are passed to the constructor when
  20.  *    creating this contract
  21.  */
  23. /**
  24.  * @typedef ExecuteInvocation
  25.  *
  26.  * @prop {string} source    the strkey of the contract (C...) being invoked
  27.  * @prop {string} function  the name of the function being invoked
  28.  * @prop {any[]}  args      the natively-represented parameters to the function
  29.  *    invocation (see {@link scValToNative} for rules on how they're
  30.  *    represented a JS types)
  31.  */
  33. /**
  34.  * @typedef InvocationTree
  35.  * @prop {'execute' | 'create'} type  the type of invocation occurring, either
  36.  *    contract creation or host function execution
  37.  * @prop {CreateInvocation | ExecuteInvocation} args  the parameters to the
  38.  *    invocation, depending on the type
  39.  * @prop {InvocationTree[]} invocations   any sub-invocations that (may) occur
  40.  *    as a result of this invocation (i.e. a tree of call stacks)
  41.  */
  43. /**
  44.  * Turns a raw invocation tree into a human-readable format.
  45.  *
  46.  * This is designed to make the invocation tree easier to understand in order to
  47.  * inform users about the side-effects of their contract calls. This will help
  48.  * make informed decisions about whether or not a particular invocation will
  49.  * result in what you expect it to.
  50.  *
  51.  * @param {xdr.SorobanAuthorizedInvocation} root  the raw XDR of the invocation,
  52.  *    likely acquired from transaction simulation. this is either from the
  53.  *    {@link Operation.invokeHostFunction} itself (the `func` field), or from
  54.  *    the authorization entries ({@link xdr.SorobanAuthorizationEntry}, the
  55.  *    `rootInvocation` field)
  56.  *
  57.  * @returns {InvocationTree}  a human-readable version of the invocation tree
  58.  *
  59.  * @example
  60.  * Here, we show a browser modal after simulating an arbitrary transaction,
  61.  * `tx`, which we assume has an `Operation.invokeHostFunction` inside of it:
  62.  *
  63.  * ```typescript
  64.  * import { Server, buildInvocationTree } from '@stellar/stellar-sdk';
  65.  *
  66.  * const s = new Server("fill in accordingly");
  67.  *
  68.  * s.simulateTransaction(tx).then(
  69.  *  (resp: SorobanRpc.SimulateTransactionResponse) => {
  70.  *    if (SorobanRpc.isSuccessfulSim(resp) && ) {
  71.  *      // bold assumption: there's a valid result with an auth entry
  72.  *      alert(
  73.  *        "You are authorizing the following invocation:\n" +
  74.  *        JSON.stringify(
  75.  *          buildInvocationTree(resp.result!.auth[0].rootInvocation()),
  76.  *          null,
  77.  *          2
  78.  *        )
  79.  *      );
  80.  *    }
  81.  *  }
  82.  * );
  83.  * ```
  84.  */
  85. export function buildInvocationTree(root) {
  86.   const fn = root.function();
  88.   /** @type {InvocationTree} */
  89.   const output = {};
  91.   /** @type {xdr.CreateContractArgs|xdr.CreateContractArgsV2|xdr.InvokeContractArgs} */
  92.   const inner = fn.value();
  94.   switch (fn.switch().value) {
  95.     // sorobanAuthorizedFunctionTypeContractFn
  96.     case 0:
  97.       output.type = 'execute';
  98.       output.args = {
  99.         source: Address.fromScAddress(inner.contractAddress()).toString(),
  100.         function: inner.functionName(),
  101.         args: inner.args().map((arg) => scValToNative(arg))
  102.       };
  103.       break;
  105.     // sorobanAuthorizedFunctionTypeCreateContractHostFn
  106.     // sorobanAuthorizedFunctionTypeCreateContractV2HostFn
  107.     case 1: // fallthrough: just no ctor args in V1
  108.     case 2: {
  109.       const createV2 = fn.switch().value === 2;
  110.       output.type = 'create';
  111.       output.args = {};
  113.       // If the executable is a WASM, the preimage MUST be an address. If it's a
  114.       // token, the preimage MUST be an asset. This is a cheeky way to check
  115.       // that, because wasm=0, token=1 and address=0, asset=1 in the XDR switch
  116.       // values.
  117.       //
  118.       // The first part may not be true in V2, but we'd need to update this code
  119.       // anyway so it can still be an error.
  120.       const [exec, preimage] = [inner.executable(), inner.contractIdPreimage()];
  121.       if (!!exec.switch().value !== !!preimage.switch().value) {
  122.         throw new Error(
  123.           `creation function appears invalid: ${JSON.stringify(
  124.             inner
  125.           )} (should be wasm+address or token+asset)`
  126.         );
  127.       }
  129.       switch (exec.switch().value) {
  130.         // contractExecutableWasm
  131.         case 0: {
  132.           /** @type {xdr.ContractIdPreimageFromAddress} */
  133.           const details = preimage.fromAddress();
  135.           output.args.type = 'wasm';
  136.           output.args.wasm = {
  137.             salt: details.salt().toString('hex'),
  138.             hash: exec.wasmHash().toString('hex'),
  139.             address: Address.fromScAddress(details.address()).toString(),
  140.             // only apply constructor args for WASM+CreateV2 scenario
  141.             ...(createV2 && {
  142.               constructorArgs: inner
  143.                 .constructorArgs()
  144.                 .map((arg) => scValToNative(arg))
  145.             }) // empty indicates V2 and no ctor, undefined indicates V1
  146.           };
  147.           break;
  148.         }
  150.         // contractExecutableStellarAsset
  151.         case 1:
  152.           output.args.type = 'sac';
  153.           output.args.asset = Asset.fromOperation(
  154.             preimage.fromAsset()
  155.           ).toString();
  156.           break;
  158.         default:
  159.           throw new Error(`unknown creation type: ${JSON.stringify(exec)}`);
  160.       }
  162.       break;
  163.     }
  165.     default:
  166.       throw new Error(
  167.         `unknown invocation type (${fn.switch()}): ${JSON.stringify(fn)}`
  168.       );
  169.   }
  171.   output.invocations = root.subInvocations().map((i) => buildInvocationTree(i));
  172.   return output;
  173. }
  175. /**
  176.  * @callback InvocationWalker
  177.  *
  178.  * @param {xdr.SorobanAuthorizedInvocation} node  the currently explored node
  179.  * @param {number} depth  the depth of the tree this node is occurring at (the
  180.  *    root starts at a depth of 1)
  181.  * @param {xdr.SorobanAuthorizedInvocation} [parent]  this `node`s parent node,
  182.  *    if any (i.e. this doesn't exist at the root)
  183.  *
  184.  * @returns {boolean|null|void}   returning exactly `false` is a hint to stop
  185.  *    exploring, other values are ignored
  186.  */
  188. /**
  189.  * Executes a callback function on each node in the tree until stopped.
  190.  *
  191.  * Nodes are walked in a depth-first order. Returning `false` from the callback
  192.  * stops further depth exploration at that node, but it does not stop the walk
  193.  * in a "global" view.
  194.  *
  195.  * @param {xdr.SorobanAuthorizedInvocation} root  the tree to explore
  196.  * @param {InvocationWalker} callback  the callback to execute for each node
  197.  * @returns {void}
  198.  */
  199. export function walkInvocationTree(root, callback) {
  200.   walkHelper(root, 1, callback);
  201. }
  203. function walkHelper(node, depth, callback, parent) {
  204.   if (callback(node, depth, parent) === false /* allow void rv */) {
  205.     return;
  206.   }
  208.   node
  209.     .subInvocations()
  210.     .forEach((i) => walkHelper(i, depth + 1, callback, node));
  211. }