CU-86dtb1g9a - Improvements on invokeFunction documentation

common/changes/@cityofzion/neon-dappkit/CU-86dtb1g9a_2024-05-15-18-52.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@cityofzion/neon-dappkit",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@cityofzion/neon-dappkit"
+}

packages/neon-dappkit/NEON-INVOKER.md

@@ -71,18 +71,19 @@ const resp = await invoker.invokeFunction({
         ]
     }],
     signers: [{
-        scopes: 'Global'
+        scopes: 'CalledByEntry',
+        account: '0x857a247939db5c7cd3a7bb14791280c09e824bea'
     }]
 })
 ```
 
 Options for each `signer`:
 
 - `scopes`: to specify which scopes should be used to sign the transaction, [learn more](https://developers.neo.org/docs/n3/foundation/Transactions#scopes). This property accepts them as a string as seen on the examples, or as a number, which can be imported from `WitnessScope` of `neon-js`.
-- `account`: to specify which account's scripthash should be used to sign the transaction, otherwise the wallet will use the user's selected account to sign.
-- `allowedContracts`: when the `scopes` property is set as `CustomContracts`, you should use this property to specify which contracts are allowed
-- `allowedGroups`: when the `scopes` property is set as `CustomGroups`, you should use this property to specify which groups are allowed
-- `rules`: to specify which rules should be used to sign the transaction, [learn more](https://developers.neo.org/docs/n3/foundation/Transactions#witnessrule).
+- `account`: to specify which account's scripthash should be used to sign the transaction, otherwise the wallet will use the user's selected account to sign. If the value starts with "0x", then it will be trimmed to use the rest of the hexstring. It does not accept addresses, only scripthashes.
+- `allowedContracts`: when the `scopes` property is set as `CustomContracts`, you should use this property to specify a list with the script hash of the contracts that are allowed.
+- `allowedGroups`: when the `scopes` property is set as `CustomGroups`, you should use this property to specify the public key of the groups that are allowed.
+- `rules`: are needed when you have a complex scope and need to use logic to allow or deny which smart contracts have access to the signature. To specify which rules should be used to sign the transaction, [learn more](https://developers.neo.org/docs/n3/foundation/Transactions#witnessrule).
 
 Options for each `invocation`:
 
@@ -115,6 +116,66 @@ const resp = await invoker.invokeFunction({
     extraSystemFee: 1000000, // minimum system fee + 1 GAS
     networkFeeOverride: 3000000 // sending 3 GAS instead of the minimum network fee
 })
+const respCustomContracts = await invoker.invokeFunction({
+    invocations: [{
+        // ...
+    },
+    {
+        // ...
+    }],
+    signers: [{
+        scopes: 'CustomContracts',
+        account: '857a247939db5c7cd3a7bb14791280c09e824bea', // signer account scripthash
+        allowedContracts: [ // Using CustomContracts means that the signature is valid only these contracts below
+            '0xd2a4cff31913016155e38e474a2c06d08be276cf', // GAS token
+            '0xef4073a0f2b305a38ec4050e4d3d28bc40ea63f5', // NEO token
+        ]
+    }],
+})
+const respCustomGroups = await invoker.invokeFunction({
+    invocations: [{
+        // ...
+    },
+    {
+        // ...
+    }],
+    signers: [{
+        scopes: 'CustomGroups',
+        account: '857a247939db5c7cd3a7bb14791280c09e824bea', // signer account scripthash
+        allowedGroups: [ // When using CustomGroups you need to list the pubkey of the groups you want to allow
+            '03ab362a4eda62d22505ffe5a5e5422f1322317e8088afedb7c5029801e1ece806'
+        ]
+    }],
+})
+const respRules = await invoker.invokeFunction({
+    invocations: [{
+        // ...
+    },
+    {
+        // ...
+    }],
+    signers: [{
+        scopes: 'Rules',
+        account: '857a247939db5c7cd3a7bb14791280c09e824bea', // signer account scripthash
+        rules: [
+            {   // This rule will allow the signature only if the contract is called by the NEO token or by the entry point
+                action: 'Allow',
+                condition: {
+                    type: "Or",
+                    expressions: [
+                        {
+                            type: "CalledByContract",
+                            hash: "0xef4073a0f2b305a38ec4050e4d3d28bc40ea63f5"    
+                        },
+                        {
+                            type: "CalledByEntry"
+                        }
+                    ]
+                }
+            }
+        ]
+    }],
+})
 ```
 
 ### Calling TestInvoke