@inco/js 0.1.20 → 0.1.22

package/README.md

@@ -1,50 +1,106 @@
-# @inco/js (called `@inco/js` for now)
+# @inco/js
 
 The @inco/js package contains the TypeScript SDK for creating dapps built on Inco.
 
-## Install the package
+## Current Status: Active Development
 
-Since the package is private in the Github package registry, you'll need to use npm to log in into the registry first. Obviously, this is only needed if you want to access the package from outside the monorepo, as the monorepo already has workspaces set up.
+The SDK is currently going through active development, to support all new features that Inco offers. As such, do expect breaking changes in subsequent releases, which will be documented in the [CHANGELOG](./CHANGELOG.md). The current state of `@inco/js` includes all low-level blocks to build functional dapps, but an improved public-facing API is also in the works.
 
-1. Create a Github Personal Access Token (Classic)
+## Install
 
-Go to the [Personal Access Tokens](https://github.com/settings/tokens) page on Github, and create a new access token with the `read:packages` permission. Give it an explicit name like `inco-js-npm-github-pkg-registry`, and save the access token in a secure place, e.g. your password manager.
-
-2. Login via npm to Github Package Registry.
+Choose your favorite package manager:
 
 ```bash
-cd /path/to/my/project
-npm login --scope=@inco-fhevm --registry=https://npm.pkg.github.com
+npm install @inco/js
+# or
+bun install @inco/js
+# or
+yarn add @inco/js
 ```
 
-You'll be asked to enter Username and Password. Put in your Github username, and paste the access token on step 1 as password.
-
-3. Tell npm to look into Github Package Registry.
-
-Create a new `.npmrc` in `/path/to/my/project`, with the following lines:
+## Usage
 
-```
-@inco-fhevm:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=${READ_PACKAGE_TOKEN}
+A typical usage of `@inco/js` includes 3 steps:
+
+1. Encrypting a value.
+2. Posting the ciphertext to the contract, which will perform confidential computes on it.
+3. Requesting a reencryption of the result of the computation.
+
+### 1. Encrypt a value
+
+```ts
+import { getSupportedChain, getViemChain, handleTypes, HexString } from '@inco/js';
+import { EciesScheme, encryptionSchemes, PlaintextWithContextOf } from '@inco/js/encryption';
+import {
+  decodeSecp256k1PublicKey,
+  generateSecp256k1Keypair,
+  getActiveLightningDeployment,
+  getEciesEncryptor,
+} from '@inco/js/lite';
+import { createWalletClient, hexToBytes } from 'viem';
+
+// Setup. Do it once at initialization.
+const chain = getSupportedChain('baseSepolia');
+const lightningConfig = getActiveLightningDeployment(chain);
+const walletClient = createWalletClient({
+    chain: getViemChain(chain),
+    account: /* Choose your account */,
+    transport: /* Choose your transport */,
+});
+const dappAddress = '0x0000000000000000000000000000000000000000'; // Put your contract address here
+
+// Define plaintext, along with context needed for verification.
+const plaintext = 42n; // bigint
+const plaintextWithContext: PlaintextWithContextOf<EciesScheme, typeof handleTypes.euint256> = {
+    plaintext: {
+        scheme: encryptionSchemes.ecies,
+        value: plaintext,
+        type: handleTypes.euint256,
+    },
+    context: {
+        hostChainId: BigInt(chain.id),
+        aclAddress: lightningConfig.executorAddress,
+        userAddress: walletClient.account.address,
+        contractAddress: dappAddress,
+    },
+};
+
+// Encrypt.
+const ephemeralKeypair = await generateSecp256k1Keypair();
+const eciesPubKey = decodeSecp256k1PublicKey(hexToBytes(lightningConfig.eciesPublicKey));
+const encryptor = getEciesEncryptor({
+    scheme: encryptionSchemes.ecies,
+    pubKeyA: eciesPubKey,
+    privKeyB: ephemeralKeypair,
+});
+const { ciphertext } = await encryptor(plaintextWithContext);
+console.log(ciphertext.value); // Will print the encrypted value as hex
 ```
 
-Then, you can do `npm install @inco/js`!
+### 2. Post the ciphertext to the contract
 
-Note: If using bun or another package manager, take a look how they manage install scopes.
+For this step, there is nothing specific to the `@inco/js`. We recommend continue using [viem](https://viem.sh). In particular, take a look at their [`writeContract`](https://viem.sh/docs/contract/writeContract) methods to make a transaction on chain, and pass in the `ciphertext.value` from the previous step as the input ciphertext.
 
-4. Resources
+### 3. Request a reencryption
 
-- Github docs: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry
-- Medium article: https://medium.com/@aamiralihussain53/a-guide-to-publishing-private-npm-package-on-github-9c533a251e2d
+After submitting your transaction, the Inco covalidators will process your request and perform the computation. In your contract, the result handle of the computation should be stored on chain, let's call it `resultHandle` of type `Handle` (hex).
 
-## Usage
-
-Currently, there are no docs as how to use the @inco/js package, as it only exposes low-level functions. There's some API work to do to make it more user-friendly.
+```ts
+import { incoLiteReencryptor } from "@inco/js/lite";
+import { Hex } from "viem";
 
-To take a look at the low-level functions, see [the E2E test](./test/incolite.ts), which shows how to encrypt, send an encrypted input to the host chain, request a reencrypt and wait for a decrypt.
-
-## Publishing the package
+// Reencrypt.
+let resultHandle = "0x..." as Hex; // Retrieve it, e.g. by reading from your dapp contract.
+const reencryptor = await incoLiteReencryptor({
+  chainId: BigInt(chain.id),
+  walletClient: walletClient,
+}); // This step will ask you to sign an EIP-712 needed for reencryption verification
+const resultPlaintext = await reencryptor({
+  handle: resultHandle,
+});
+console.log(resultPlaintext.value); // Plaintext of the final result after computation
+```
 
-Currently the publishing process is manual, and anyone with enough rights can run `bun run publish:github` to publish to the Github Packages registry.
+## License
 
-Some gitops process should replace this manual setup.
+See the [LICENSE](./LICENSE) file.