first commit

.gitignore

@@ -0,0 +1,2 @@
+node_modules
+build

.npmignore

@@ -0,0 +1,2 @@
+src
+tsconfig.json

README.md

@@ -0,0 +1,195 @@
+# Polkadot API for Smart Contracts compiled via Solang
+
+This library allows to deploy and call into smart contracts that have been compiled from Solidity to wasm via Solang.
+
+It has two main functions:
+
+- deploy (instantiate) a smart contract
+- execute a message call to an existing smart contract
+
+These functions are meant to be used very flexibly and they have the following special features:
+
+1. Both functions allow to either specify a keypair or a general signer in order to sign the extrinsics. The keypair is generally useful for command line tools whereas the signer is more useful in a browser context, where it can give access to a wallets or browser extensions.
+
+2. In certain applications it can be necessary to extend the extrinsics created by these two functions, e.g., to wrap them into a sudo call. For that reason these functions allow to specify an optional argument `modifyExtrinsic` that allows the caller to arbitrarily change or extend the created extrinsic.
+
+3. Contracts usually emit events and these events can be emitted by contracts (recursively) called by the original contract. In order to properly decode the binary data contained in the event, one needs to lookup the abi of the respective contract emitting the event. For that reason both functions take an optional argument `lookupAbi` that allows the caller to provide the abi for any deployed contract (identified through the contract address).
+
+4. They can correctly decode the return value of message calls, i.e., whether a message call reverted (including the revert message) or whether it panicked and why it panicked.
+
+## Deploy a smart contract
+
+The function `deployContract` has the following arguments:
+
+- `api`: the polkadot-js `ApiPromise` object
+
+  This is the `ApiPromise` object that polkadot-js creates when connecting to an RPC node of a chain.
+
+- `abi`: The abi (metadata) of the smart contract
+
+  This needs to be an object of type `Abi`. It can be constructed from the metadata JSON file (that is generated by Solang) as follows:
+
+  ```
+  const metadata = JSON.parse(metadataString);
+  new Abi(metadata, api.registry.getChainProperties());
+  ```
+
+- `signer`: Specifies the signer of the extrinsic submitted to the chain.
+
+  This can either be a keypair or any generic signer. If it is a keypair, then it needs to have the format
+
+  ```
+  {
+    type: "keypair";
+    keypair: KeyringPair;
+  }
+  ```
+
+  If it is a generic signer, then it needs to have the format
+
+  ```
+  {
+    type: "signer";
+    address: string; // the address of the signer
+    signer: Signer;
+  }
+  ```
+
+- `constructorArguments`: the array with the arguments to the constructor
+- `constructorName`: an optional argument to specify the constructor
+
+  This is `new` by default. Contracts that are compiled via Solidity usually only have the `new` constructor.
+
+- `limits`: the resource limits
+
+  These limits specify the resources that are allowed to be used for the execution. They need to be specified as the type
+
+  ```
+  {
+    gas: {
+      refTime: string | number;
+      proofSize: string | number;
+    };
+    storageDeposit?: string | number;
+  }
+  ```
+
+  The `gas.refTime` and `gas.proofSize` entries specify limits of the gas usage. The optional argument `storageDeposit` specifies a limit for the storage deposit.
+
+- `modifyExtrinsic`: allows to extend the generated extrinsic.
+
+  This is an optional function that allows the caller to extend, modify or wrap the extrinsic created by `deployContract` before it is submitted to the chain.
+
+- `lookupAbi`: provide abi for deployed contracts
+
+  This is an optional argument that allows to provide the abi of any deployed contract (specified by the address of the contract). This allows `deployContract` to properly decode events emitted during contract execuction.
+
+The return value of this function is an object that contains the field `type`. This fields indicate the execution status and is either one of the values:
+
+- `"success"`: in this case the deployment was successful and the return object also contains the entries `events` (which is the collection of (decoded) contract events that were emitted during contract execution), the `deploymentAddress` and the `transactionFee` that the signer had to pay
+- `"error"`: in this case there was a general error when submitting the extrinsic and the return object contains the entry `error` (a string with an error description)
+- `"reverted"`: in this case the contract reverted and the return object contains the revert message in the entry `description`
+- `"panic"`: in this case the contract panicked and the return object contains the entries `errorCode` (a numerical error code) and `explanation` (an explanation of the error code)
+
+## Execute a Message Call
+
+The function `messageCall` has the following arguments:
+
+- `api`: the polkadot-js `ApiPromise` object
+
+  This is the `ApiPromise` object that polkadot-js creates when connecting to an RPC node of a chain.
+
+- `abi`: The abi (metadata) of the smart contract
+
+  This needs to be an object of type `Abi`. It can be constructed from the metadata JSON file (that is generated by Solang) as follows:
+
+  ```
+  const metadata = JSON.parse(metadataString);
+  new Abi(metadata, api.registry.getChainProperties());
+  ```
+
+- `contractDeploymentAddress`: the address of the contract
+
+  This needs to be the address of a deployed contracts that has the abi specified by `abi`
+
+- `callerAddress`: the address of the caller of the contract
+
+- `getSigner`: a callback to provide the signer of the extrinsic
+
+  This callback will only be invoked when the message is mutating and therefore requires that an extrinsic is submitted to the chain (otherwise, `messageCall` will only make an rpc call). The address associated with the signer should be the same as `callerAddress`.
+
+- `messageName`: the name of the message
+
+- `messageArguments`: the array with the arguments to the message
+
+- `limits`: the resource limits
+
+  These limits specify the resources that are allowed to be used for the execution. They need to be specified as the type
+
+  ```
+  {
+    gas: {
+      refTime: string | number;
+      proofSize: string | number;
+    };
+    storageDeposit?: string | number;
+  }
+  ```
+
+  The `gas.refTime` and `gas.proofSize` entries specify limits of the gas usage. The optional argument `storageDeposit` specifies a limit for the storage deposit.
+
+- `getSigner`: Specifies the signer of the extrinsic submitted to the chain.
+
+  This can either be a keypair or any generic signer. If it is a keypair, then it needs to have the format
+
+  ```
+  {
+    type: "keypair";
+    keypair: KeyringPair;
+  }
+  ```
+
+  If it is a generic signer, then it needs to have the format
+
+  ```
+  {
+    type: "signer";
+    address: string; // the address of the signer
+    signer: Signer;
+  }
+  ```
+
+- `modifyExtrinsic`: allows to extend the generated extrinsic.
+
+  This is an optional function that allows the caller to extend, modify or wrap the extrinsic created by `messageCall` before it is submitted to the chain.
+
+- `lookupAbi`: provide abi for deployed contracts
+
+  This is an optional argument that allows to provide the abi of any deployed contract (specified by the address of the contract). This allows `messageCall` to properly decode events emitted during contract execuction.
+
+The return value of this function is an object that contains two entries `execution` and `result`. The `execution` entry contains the field `type`, which can be either one of
+
+- `onlyQuery`: in this case only the rpc method has been executed because an error occurred before submitting an extrinsic or because the message is immutable and does not require an extrinsic
+- `extrinsic`: an extrinsic has been submitted to execute the message call – in this case the `execution` object also contains the entries `contractEvents` (which is the collection of (decoded) contract events that were emitted during contract execution) and the `transactionFee` that the signer had to pay
+
+The `result` object has the field `type` which is either one of the following values:
+
+- `"success"`: in this case the deployment was message call was successful and it contains a return value in the entry `value`
+- `"error"`: in this case there was a general error when submitting the extrinsic and the return object contains the entry `error` (a string with an error description)
+- `"reverted"`: in this case the contract reverted and the return object contains the revert message in the entry `description`
+- `"panic"`: in this case the contract panicked and the return object contains the entries `errorCode` (a numerical error code) and `explanation` (an explanation of the error code)
+
+## Submit an Extrinsic
+
+Additionally this module also exposes a function `submitExtrinsic` that allows to submit an arbitrary extrinsic and that processes the chain events in order to determine the execution status of the extrinsic.
+
+It has two arguments:
+
+- `extrinsic`: the extrinsic itself
+- `signer`: as for the other two functions this specifies the signer of the extrinsic submitted to the chain.
+
+This function only returns after the extrinsic has been executed on-chain. The return value of this function is an object with the following entries:
+
+- `transactionFee`: the transaction fee that the signer had to pay for the execution
+- `events`: the array of all Substrate events generated during execution
+- `status`: this is an object whose `type` entry is either `"success"` or `"error"`. In the latter case this object also contains the entry `error`, which is a string of the error message

package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@pendulum-chain/api-solang",
+  "version": "0.0.7",
+  "description": "Interface to interact with smart contracts compiled via Solang",
+  "main": "build/index.js",
+  "devDependencies": {
+    "@types/node": "^20.6.0",
+    "rimraf": "^5.0.1",
+    "typescript": "^5.2.2"
+  },
+  "peerDependencies": {
+    "@polkadot/api": "^10.9.1",
+    "@polkadot/api-contract": "^10.9.1",
+    "@polkadot/keyring": "^12.3.2",
+    "@polkadot/types": "^10.9.1",
+    "@polkadot/types-codec": "^10.9.1",
+    "@polkadot/util": "^12.3.2",
+    "@polkadot/util-crypto": "^12.3.2"
+  },
+  "type": "commonjs",
+  "scripts": {
+    "build": "npm run clean && tsc",
+    "clean": "rimraf build",
+    "prepublishOnly": "npm run build",
+    "simplyPublish": "npm publish --workspace @pendulum-chain/api-solang --access public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pendulum-chain/wasm-deploy.git"
+  },
+  "keywords": [
+    "Solang",
+    "wasm",
+    "smart",
+    "contracts",
+    "Polkadot",
+    "Substrate"
+  ],
+  "author": "Pendulum",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/pendulum-chain/wasm-deploy/issues"
+  },
+  "homepage": "https://github.com/pendulum-chain/wasm-deploy#readme"
+}