signet.js 0.0.2-beta.6 → 0.0.3

package/.eslintrc.json

@@ -0,0 +1,55 @@
+{
+  "env": {
+    "browser": true,
+    "es2021": true
+  },
+  "extends": [
+    "standard-with-typescript",
+    "plugin:import/typescript",
+    "plugin:prettier/recommended"
+  ],
+  "parserOptions": {
+    "project": ["./tsconfig.json", "./tsconfig.eslint.json"]
+  },
+  "rules": {
+    "@typescript-eslint/strict-boolean-expressions": "off",
+    "@typescript-eslint/prefer-nullish-coalescing": "off",
+    "import/order": [
+      "error",
+      {
+        "groups": [
+          "builtin",
+          "external",
+          "internal",
+          "parent",
+          "sibling",
+          "index"
+        ],
+        "pathGroups": [
+          {
+            "pattern": "@chains",
+            "group": "internal"
+          },
+          {
+            "pattern": "@chains/**",
+            "group": "internal"
+          },
+          {
+            "pattern": "@utils",
+            "group": "internal"
+          },
+          {
+            "pattern": "@utils/**",
+            "group": "internal"
+          }
+        ],
+        "pathGroupsExcludedImportTypes": ["builtin"],
+        "newlines-between": "always",
+        "alphabetize": {
+          "order": "asc",
+          "caseInsensitive": true
+        }
+      }
+    ]
+  }
+}

package/.prettierrc

@@ -0,0 +1 @@
+{ "singleQuote": true, "trailingComma": "es5", "semi": false }

package/babel.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  presets: [
+    ['@babel/preset-env', { targets: { node: 'current' } }],
+    '@babel/preset-typescript',
+  ],
+}

package/docs/pages/index.mdx

@@ -0,0 +1,36 @@
+## Introduction
+
+Managing multiple accounts across different blockchains is a headache. Every chain has its own wallets, private keys, and authentication systems, making cross-chain interactions complex and fragmented. But what if a single abstract account could seamlessly control multiple accounts across different chains—without compromising security? That's now possible through Chain Signatures.
+
+### What Are Chain Signatures?
+
+Chain Signatures are programmable digital signatures that enable cross-chain control, allowing one account on one blockchain to securely manage accounts and assets on entirely different chains.
+The system:
+
+- **Derives keys** from a single base key.
+- Allows third parties (e.g., dApps, wallets, or protocols) to **request signatures** on-chain.
+- Introduces **flexible usage controls**, such as daily spending limits or rate limits, by combining these keys with custom on-chain logic.
+
+### Benefits & Use Cases:
+
+- **One Identity, Many Chains**: Instead of juggling multiple wallets, a single signature from your Ethereum account could authorize actions on any other supported EVM or non-EVM chain, without needing to manage separate private keys.
+- **Seamless Cross-Chain Transactions**: Move assets or execute smart contract functions across different chains, without relying on third-party bridges or centralized custodians.
+- **Usage Controls**: rate or time-based restrictions can be enforced by the on-chain contract that manages key usage (e.g., "this key can only send up to 1 ETH per day").
+- **Recovery or Fallback Conditions**: Instead of storing private keys in a single hardware device, you can use a multi-party computation (MPC) setup that offers user-friendly ways to recover accounts.
+- **Signs the Arbitrary State of a Foreign Chain**: Gives your smart contract awareness of whether a transaction it signed went through so that it can perform actions accordingly. For example, it allows for a smart contract to keep track of local chain assets based on the foreign chain's state.
+
+## How It Works?
+
+### Contract Background
+
+The **ChainSignatures** contract:
+
+- Holds a base public key (`publicKey`), expressed in affine coordinates on the secp256k1 curve.
+- Derives new public keys for each `(user, path)` combination by computing an integer `epsilon` (based on a `path` string and user’s address) and performing an EC point addition:
+
+  ```
+  DerivedPubKey = BasePubKey + (epsilon × G)
+  ```
+
+- Allows a user to request a signature on a 32-byte payload by calling `sign(...)`. A minimal deposit may be required to discourage spam; any unused deposit is refunded once the request is completed.
+- Awaits the **MPC network** to compute the actual ECDSA signature offline, then call `respond(...)` with that signature. The contract then emits an event with the signature, and refunds the deposit.

package/docs/pages/signetjs/advanced/chain-signatures-contract.mdx

@@ -0,0 +1,52 @@
+# Implementing a Custom Chain Signature Contract
+
+This guide explains how to implement a custom Chain Signature Contract to provide as argument when instantiating a Chain instance.
+
+## Overview
+
+The `ChainSignatureContract` is an abstract class that defines the interface for interacting with the Sig Network infrastructure.
+
+- Key Derivation: Derive the child key from the root key using Sig Network key derivation function
+- Sign: Sigs the given payload using Sig Network MPC
+- Current Fee: Gets the current signature deposit that handles network congestion
+- Root Public Key: Gets the root public key of the Smart Contract on Sig Network MPC
+
+While the library includes a default implementation for the NEAR protocol, you have the flexibility to implement your own contract for other blockchain networks.
+
+## Using the NEAR Implementation
+
+```ts twoslash
+// [!include ~/snippets/code/near/env.ts]
+// ---cut---
+import { utils, EVM } from 'signet.js'
+
+const contract = new utils.chains.near.ChainSignatureContract({
+  networkId: 'testnet',
+  contractId: 'v1.signer-prod.testnet',
+  accountId,
+  keypair,
+})
+
+const evmChain = new EVM({
+  rpcUrl: 'https://mainnet.infura.io/v3/YOUR-PROJECT-ID',
+  contract,
+})
+```
+
+## Implementing a Custom Chain Signature Contract
+
+To create your own implementation to use on the [Chain](./chain.mdx) Instance, your contract must implement the `BaseChainSignatureContract` interface.
+
+In case you need you want all Sig Network Smart Contract capabilities, you can implement the `ChainSignatureContract` interface.
+
+```ts twoslash
+// [!include ~/../src/chains/ChainSignatureContract.ts]
+```
+
+### Example: NEAR Implementation
+
+Below is the reference implementation for the NEAR, which you can use as a guide for implementing your own chain signature contract:
+
+```ts twoslash
+// [!include ~/../src/utils/chains/near/ChainSignatureContract.ts]
+```

package/docs/pages/signetjs/advanced/chain.mdx

@@ -0,0 +1,45 @@
+# Chain
+
+Chain is the most basic interface of the signet.js library. It provides a standard set of methods that all chains must implement.
+
+With this interface you will be able to interact with Sig Network smart contracts in a standard way to:
+
+- getBalance
+- deriveAddressAndPublicKey
+- serializeTransaction
+- deserializeTransaction
+- prepareTransactionForSigning
+- attachTransactionSignature
+- broadcastTx
+
+If you wanna have a look this is the chain interface with a brief description of each method:
+
+```ts twoslash
+// [!include ~/../src/chains/Chain.ts]
+```
+
+# Implementing a New Chain
+
+This guide explains how to implement support for a new blockchain network in the signet.js library.
+
+## Overview
+
+To add support for a new blockchain, you need to implement the `Chain` interface:
+
+## Step-by-Step Guide
+
+### 1. Create the Chain Types
+
+First, define the transaction types for your chain:
+
+```ts twoslash
+// [!include ~/../src/chains/EVM/types.ts]
+```
+
+### 2. Implement the Chain Interface
+
+Create a new class that implements the `Chain` interface:
+
+```ts twoslash
+// [!include ~/../src/chains/EVM/EVM.ts]
+```

package/docs/pages/signetjs/chains/bitcoin/bitcoin.mdx

@@ -0,0 +1,171 @@
+# Bitcoin Chain Implementation
+
+The Bitcoin chain implementation supports both Bitcoin mainnet and testnet networks, with a focus on P2WPKH (Native SegWit) transactions.
+
+## Configuration
+
+```ts twoslash filename="base.ts"
+// [!include ~/snippets/code/contract.ts]
+// ---cut---
+import { Bitcoin, BTCRpcAdapters } from 'signet.js'
+
+// Initialize the RPC adapter using Mempool
+const btcRpcAdapter = new BTCRpcAdapters.Mempool('https://mempool.space/api')
+
+// Initialize the chain
+const chain = new Bitcoin({
+  network: 'testnet', // 'mainnet' | 'testnet' | 'regtest'
+  contract,
+  btcRpcAdapter,
+})
+```
+
+## RPC Adapter
+
+The RPC adapter is a class that provides an interface for interacting with the Bitcoin network. It handles essential operations such as:
+
+- Fetching UTXOs (Unspent Transaction Outputs)
+- Retrieving transaction details
+- Getting current network fees
+- Broadcasting transactions
+- Querying address balances
+
+The adapter abstracts away the complexity of different Bitcoin API providers, allowing you to easily switch between services like Mempool.space, BlockCypher, or your own Bitcoin node.
+
+For detailed implementation and configuration options, see the [RPC Adapter](/signetjs/chains/bitcoin/btc-rpc-adapter) documentation.
+
+## Methods
+
+### getBalance
+
+Gets the native token balance of an address in the chain's base units.
+
+```ts twoslash
+// [!include base.ts]
+// ---cut---
+const { balance, decimals } = await chain.getBalance('bc1qx...')
+```
+
+**Parameters:**
+
+- `address`: The Bitcoin P2WPKH address to check
+
+**Returns:**
+
+- The balance in the chain's base units as a bigint
+- The number of decimals used to format the balance
+
+### deriveAddressAndPublicKey
+
+Derives an Bitcoin address and public key from a predecessor ID and derivation path.
+
+```ts twoslash
+// [!include base.ts]
+// ---cut---
+const { address, publicKey } = await chain.deriveAddressAndPublicKey(
+  'bc1qx...',
+  'any_string'
+)
+```
+
+**Parameters:**
+
+- `predecessor`: The wallet/contract address requesting the signature
+- `path`: The derivation path to use
+
+**Returns:**
+
+- Object containing:
+  - `address`: The derived Bitcoin P2WPKH address
+  - `publicKey`: The corresponding public key in SEC1 uncompressed format
+
+### prepareTransactionForSigning
+
+Prepares a transaction for MPC signing.
+
+```ts twoslash filename="unsigned-transaction.ts"
+// [!include base.ts]
+// ---cut---
+import { BTCTransactionRequest } from 'signet.js'
+
+// Simple transfer format
+const transactionRequest: BTCTransactionRequest = {
+  from: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
+  to: 'bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4',
+  value: '0.001', // 0.001 BTC
+  publicKey: '0235a3...',
+}
+
+const { transaction: unsignedTransaction, hashesToSign } =
+  await chain.prepareTransactionForSigning(transactionRequest)
+```
+
+### attachTransactionSignature
+
+Adds signatures to a PSBT.
+
+```ts twoslash filename="add-signature.ts"
+// [!include unsigned-transaction.ts]
+// ---cut---
+import { RSVSignature } from 'signet.js'
+
+// Ideally it would be a request to the Sig Network Smart Contract
+const rsvSignatures: RSVSignature[] = [
+  {
+    r: '0x...',
+    s: '0x...',
+    v: 27,
+  },
+]
+
+const signedTx = chain.attachTransactionSignature({
+  transaction: unsignedTransaction,
+  rsvSignatures,
+})
+```
+
+**Parameters:**
+
+- `transaction`: The unsigned transaction with PSBT
+- `rsvSignatures`: Array of RSV signatures from MPC
+
+**Returns:**
+
+- The serialized signed transaction in hex format
+
+### broadcastTx
+
+Broadcasts a signed transaction to the network.
+
+```ts twoslash
+// [!include base.ts]
+// ---cut---
+const txHash = await chain.broadcastTx('0x...transactionSerialized')
+```
+
+**Parameters:**
+
+- `txSerialized`: The serialized signed transaction
+
+**Returns:**
+
+- The transaction hash
+
+## Types
+
+The following types are used on the Bitcoin chain:
+
+```ts twoslash
+// [!include ~/../src/chains/Bitcoin/types.ts]
+```
+
+## Technical Details
+
+The implementation:
+
+- Uses `bitcoinjs-lib` for transaction handling
+- Supports P2WPKH (Native SegWit) addresses
+- Handles automatic UTXO selection and change outputs
+- Supports custom fee rates through the RPC adapter
+- Uses PSBT (Partially Signed Bitcoin Transactions)
+- Supports both mainnet and testnet networks../../../../snippets/docs/chain/broadcast-tx

package/docs/pages/signetjs/chains/bitcoin/btc-rpc-adapter.mdx

@@ -0,0 +1,26 @@
+# Implementing a Bitcoin RPC Adapter
+
+This guide explains how to implement a custom RPC adapter for interacting with Bitcoin nodes or services.
+
+## Overview
+
+The `BTCRpcAdapter` provides an abstraction layer for Bitcoin-specific operations like UTXO management, balance queries, and transaction broadcasting. You might want to implement a custom adapter when:
+
+- Using a different Bitcoin API provider
+- Implementing specialized UTXO selection strategies
+
+## Base Class
+
+In order to implement a custom adapter, you need to implement the `BTCRpcAdapter` abstract class:
+
+```ts twoslash
+// [!include ~/../src/chains/Bitcoin/BTCRpcAdapter/BTCRpcAdapter.ts]
+```
+
+### 2. Example
+
+There is an example implementation of the `BTCRpcAdapter` abstract class in the `Mempool` class:
+
+```ts twoslash
+// [!include ~/../src/chains/Bitcoin/BTCRpcAdapter/Mempool/Mempool.ts]
+```

package/docs/pages/signetjs/chains/cosmos.mdx

@@ -0,0 +1,171 @@
+# Cosmos Chain Implementation
+
+The Cosmos chain implementation supports Cosmos SDK-based networks (Cosmos Hub, Osmosis, etc.) with a focus on standard transactions and IBC transfers.
+
+## Configuration
+
+```ts twoslash filename="base.ts"
+// [!include ~/snippets/code/contract.ts]
+// ---cut---
+import { Cosmos } from 'signet.js'
+
+const chain = new Cosmos({
+  chainId: 'cosmoshub-4', // Chain ID of the target network
+  contract,
+})
+```
+
+## Methods
+
+### getBalance
+
+Gets the native token balance of an address in the chain's base units.
+
+```ts twoslash
+// [!include base.ts]
+// ---cut---
+const { balance, decimals } = await chain.getBalance('cosmos1...')
+```
+
+**Parameters:**
+
+- `address`: The Cosmos bech32 address to check
+
+**Returns:**
+
+- The balance in the chain's base units as a bigint
+- The number of decimals used to format the balance
+
+### deriveAddressAndPublicKey
+
+Derives an Cosmos bech32 address and public key from a predecessor ID and derivation path.
+
+```ts twoslash
+// [!include base.ts]
+// ---cut---
+const { address, publicKey } = await chain.deriveAddressAndPublicKey(
+  'cosmos1...',
+  'any_string'
+)
+```
+
+**Parameters:**
+
+- `predecessor`: The wallet/contract address requesting the signature
+- `path`: The derivation path to use
+
+**Returns:**
+
+- Object containing:
+  - `address`: The derived Cosmos bech32 address
+  - `publicKey`: The corresponding public key in SEC1 uncompressed format
+
+### prepareTransactionForSigning
+
+Prepares a transaction for MPC signing.
+
+```ts twoslash filename="unsigned-transaction.ts"
+// [!include base.ts]
+// ---cut---
+import { CosmosTransactionRequest } from 'signet.js'
+import { MsgSend } from 'cosmjs-types/cosmos/bank/v1beta1/tx'
+
+// Create a token transfer message
+const transactionRequest: CosmosTransactionRequest = {
+  address: 'cosmos1...',
+  publicKey: '0350e8...',
+  messages: [
+    {
+      typeUrl: '/cosmos.bank.v1beta1.MsgSend',
+      value: {
+        fromAddress: 'cosmos1...',
+        toAddress: 'cosmos1...',
+        amount: [
+          {
+            denom: 'uatom',
+            amount: '1000000',
+          },
+        ],
+      },
+    },
+  ],
+  memo: 'Token transfer',
+}
+
+const { transaction: unsignedTransaction, hashesToSign } =
+  await chain.prepareTransactionForSigning(transactionRequest)
+```
+
+### attachTransactionSignature
+
+Adds signatures to a transaction.
+
+```ts twoslash filename="add-signature.ts"
+// [!include unsigned-transaction.ts]
+// ---cut---
+import { RSVSignature } from 'signet.js'
+
+// Ideally it would be a request to the Sig Network Smart Contract
+const rsvSignatures: RSVSignature[] = [
+  {
+    r: '0x...',
+    s: '0x...',
+    v: 27,
+  },
+]
+
+const signedTx = chain.attachTransactionSignature({
+  transaction: unsignedTransaction,
+  rsvSignatures,
+})
+```
+
+**Parameters:**
+
+- `transaction`: The unsigned transaction
+- `rsvSignatures`: Array of RSV signatures from MPC
+
+**Returns:**
+
+- The serialized signed transaction in hex format
+
+### broadcastTx
+
+Broadcasts a signed transaction to the network.
+
+```ts twoslash
+// [!include base.ts]
+// ---cut---
+const txHash = await chain.broadcastTx('0x...transactionSerialized')
+```
+
+**Parameters:**
+
+- `txSerialized`: The serialized signed transaction
+
+**Returns:**
+
+- The transaction hash
+
+## Types
+
+The following types are used on the Cosmos chain:
+
+```ts twoslash
+// [!include ~/../src/chains/Cosmos/types.ts]
+```
+
+## Technical Details
+
+The implementation:
+
+- Uses `@cosmjs/stargate` for transaction handling
+- Supports SIGN_MODE_DIRECT signing
+- Uses Protobuf for message encoding
+- Supports standard Cosmos SDK messages:
+  - Bank (Send, MultiSend)
+  - Staking (Delegate, Undelegate, Redelegate)
+  - Distribution (Withdraw Rewards)
+  - IBC (Transfer)
+- Handles automatic fee calculation based on gas prices
+- Supports custom message types through the Registry