feat: contract builder

[sp-io]

Add contract builder api to simplify the usage for newcomers

[github-actions]

license-eye has checked 736 files.

Valid	Invalid	Ignored	Fixed
247	36	453	0

Click to see the invalid file list

• packages/contract-builder/src/adapter/ContractAdapter.ts
• packages/contract-builder/src/adapter/ContractAdapterBuilder.ts
• packages/contract-builder/src/adapter/ContractProxy.ts
• packages/contract-builder/src/adapter/WitnessInterceptor.ts
• packages/contract-builder/src/adapter/WitnessManager.ts
• packages/contract-builder/src/config/AdapterConfig.ts
• packages/contract-builder/src/config/PrivateStateConfig.ts
• packages/contract-builder/src/config/RetryConfig.ts
• packages/contract-builder/src/errors/AdapterError.ts
• packages/contract-builder/src/errors/PrivateStateError.ts
• packages/contract-builder/src/errors/WitnessError.ts
• packages/contract-builder/src/index.ts
• packages/contract-builder/src/private-state/PrivateStateManager.ts
• packages/contract-builder/src/providers/browser-preset.ts
• packages/contract-builder/src/providers/environment.ts
• packages/contract-builder/src/providers/factory.ts
• packages/contract-builder/src/providers/index.ts
• packages/contract-builder/src/providers/nodejs-preset.ts
• packages/contract-builder/src/providers/types.ts
• packages/contract-builder/src/types/adapter-types.ts
• packages/contract-builder/src/types/contract-types.ts
• packages/contract-builder/src/types/external-contract-types.ts
• packages/contract-builder/src/types/type-utils.ts
• packages/contract-builder/src/types/witness-types.ts
• packages/contract-builder/src/utils/logger-wrapper.ts
• packages/contract-builder/src/utils/retry-logic.ts
• packages/contract-builder/src/utils/type-helpers.ts
• packages/contract-builder/tests/integration/adapter-with-witnesses.test.ts
• packages/contract-builder/tests/types/ide-autocomplete-demo.ts
• packages/contract-builder/tests/types/type-tests.ts
• packages/contract-builder/tests/unit/ContractAdapter.test.ts
• packages/contract-builder/tests/unit/ContractProxy.test.ts
• packages/contract-builder/tests/unit/PrivateStateManager.test.ts
• packages/contract-builder/tests/unit/WitnessInterceptor.test.ts
• packages/contract-builder/tests/unit/WitnessManager.test.ts
• packages/contract-builder/tests/unit/retry-logic.test.ts

Use this command to fix any missing license headers

```bash

docker run -it --rm -v $(pwd):/github/workspace apache/skywalking-eyes header fix

</details>

[github-actions]

Title	Lines	Statements	Branches	Functions
platform-js		63.69% (107/168)	67.81% (59/87)	47.27% (26/55)

[github-actions]

Title	Lines	Statements	Branches	Functions
compact-js		87.82% (137/156)	60% (12/20)	82.85% (58/70)
compact-js-node
compact-js-command		68.25% (258/378)	49.58% (60/121)	61.41% (78/127)

[github-actions]

Unit Test Results - MidnightJS

 22 files   70 suites   2m 1s ⏱️
305 tests 302 ✅ 3 💤 0 ❌
624 runs  618 ✅ 6 💤 0 ❌

Results for commit 948eae6.

♻️ This comment has been updated with latest results.

[MidnightCI]

E2E Tests Results

e2e_tests_reports: Run #2044

Tests 📝	Passed ✅	Failed ❌	Skipped ⏭️	Pending ⏳	Other ❓	Flaky 🍂	Duration ⏱️
104	97	0	7	0	0	0	6m 34s

🎉 All tests passed!

Suites

97 passed, 0 failed, and 7 other

Suite	Passed	Failed	Other	Duration
✅ testkit-js/testkit-js-e2e/test/contract-builder.it.test.ts         ✅ Contract Builder E2E Tests > Test 1: Deploy and increment counter using contract-builder > should deploy counter contract and increment the value         ✅ Contract Builder E2E Tests > Test 2: Private state management with contract-builder > should manage private state updates correctly         ✅ Contract Builder E2E Tests > Test 2: Private state management with contract-builder > should handle multiple increments correctly         ✅ Contract Builder E2E Tests > Test 3: Connect to deployed contract > should connect to existing contract and maintain state	✅ 4	❌ 0	⏭️ 0	4m 33s
✅ testkit-js/testkit-js-e2e/test/contracts.blocktime.it.test.ts         ✅ Block Time Contract Tests > blockTimeLt tests > should succeed when both device time and node time are less than future time         ✅ Block Time Contract Tests > blockTimeLt tests > should fail immediately on device when device time is already past the check time         ⏭️ Block Time Contract Tests > blockTimeLt tests > should succeed on device but fail on node when submission is delayed         ✅ Block Time Contract Tests > blockTimeLt tests > should succeed when both device time and node time are greater than past time         ✅ Block Time Contract Tests > blockTimeLt tests > should fail immediately on device when device time is less than check time         ✅ Block Time Contract Tests > blockTimeLt tests > should succeed even with submission delay when checking past time         ✅ Block Time Contract Tests > blockTimeLt tests > should succeed when both device time and node time are greater than past time         ✅ Block Time Contract Tests > blockTimeLt tests > should fail when device time is not greater than check time         ✅ Block Time Contract Tests > blockTimeLt tests > should succeed when both device time and node time are less than or equal to future time         ✅ Block Time Contract Tests > blockTimeLt tests > should fail immediately on device when device time exceeds check time         ⏭️ Block Time Contract Tests > blockTimeLt tests > should succeed on device but fail on node when submission delay causes time to exceed threshold         ✅ Block Time Contract Tests > blockTimeLt tests > should demonstrate different failure points for Lt check > Immediate past time - fails on device         ⏭️ Block Time Contract Tests > blockTimeLt tests > should demonstrate different failure points for Lt check > Near future time with delay - succeeds on device, fails on node         ✅ Block Time Contract Tests > blockTimeLt tests > should demonstrate different failure points for Lt check > Far future time - succeeds on both device and node         ✅ Block Time Contract Tests > blockTimeLt tests > should handle maximum time values         ✅ Block Time Contract Tests > blockTimeLt tests > should handle zero time value	✅ 13	❌ 0	⏭️ 3	2m 48s
✅ testkit-js/testkit-js-e2e/test/contracts.it.test.ts         ✅ Contracts API > should execute constructor and circuits of contracts with private state         ✅ Contracts API > should create unproven call and deploy transactions for contract with private state         ✅ Contracts API > should deploy contract on the chain [@slow]         ✅ Contracts API > should return deployed contract if it exists on specific address         ✅ Contracts API > should return deployed contract if it exists on specific address without initialPrivateState         ✅ Contracts API > should throw error if contract address has wrong format - length         ✅ Contracts API > should return deployed contract if it exists on specific address with initialPrivateState and empty local private state store         ✅ Contracts API > should return deployed contract if it exists on specific address with different initialPrivateState         ✅ Contracts API > should wait indefinitely until contract exists on specific address [@slow]         ✅ Contracts API > should throw for incompatible contract types that differ by circuit ids         ✅ Contracts API > should throw for incompatible contract types with same shape but different verifier keys         ✅ Contracts API > should return contract interface and execute circuit operations [@slow]         ✅ Contracts API > should throw error on undefined public state at wrong address         ✅ Contracts API > should submit a deploy transaction [@slow]         ✅ Contracts API > should submit transaction that calls circuit in contract [@slow]         ✅ Contracts API > should throw error if private state is undefined         ✅ Contracts API > should throw error if public state is undefined         ✅ Contracts API > should throw error if contract address has wrong format - not hex         ✅ Contracts API > should return the latest observed state of a deployed contract and is independent of the chain state         ✅ Contracts API > should wait indefinitely until state change, if stopped returns last contract state [@slow]	✅ 20	❌ 0	⏭️ 0	3m 18s
✅ testkit-js/testkit-js-e2e/test/contracts.scopedtx.it.test.ts         ✅ Scoped Transaction Contract Tests > should submit scoped transaction that calls circuit in contract [@slow]	✅ 1	❌ 0	⏭️ 0	17.4s
✅ testkit-js/testkit-js-e2e/test/contracts.singlecontract.nostate.it.test.ts         ✅ Contracts API > should execute constructor and circuits of contracts with no private state         ✅ Contracts API > should deploy and find contracts with no private state [@slow]         ✅ Contracts API > should create unproven call and deploy transactions for contract with no private state         ✅ Contracts API > should submit deploy and call transactions for contracts with no private state [@slow]	✅ 4	❌ 0	⏭️ 0	1m 31s
✅ testkit-js/testkit-js-e2e/test/contracts.snarkupgrade.it.test.ts         ✅ Contracts API Snark Upgrade [dedicated contract] [@slow] > should successfully remove verifier key using submitRemoveVerifierKeyTx         ✅ Contracts API Snark Upgrade [dedicated contract] [@slow] > should successfully remove verifier key using createContractMaintenanceTxInterface         ✅ Contracts API Snark Upgrade [dedicated contract] [@slow] > should successfully remove verifier key and disable circuit operation         ✅ Contracts API Snark Upgrade [dedicated contract] [@slow] > should succeed on verifier key insertion retry after removal         ✅ Contracts API Snark Upgrade [dedicated contract] [@slow] > should fail when inserting verifier key for wrong circuit after removal	✅ 5	❌ 0	⏭️ 0	3m 15s
✅ testkit-js/testkit-js-e2e/test/contracts.snarkupgrade.singlecontract.it.test.ts         ✅ Contracts API Snark Upgrade [single contract] > submitReplaceAuthorityTx - successful replace authority with new key[@slow]         ✅ Contracts API Snark Upgrade [single contract] > submitReplaceAuthorityTx - successful replace authority with same key [@slow]         ✅ Contracts API Snark Upgrade [single contract] > submitReplaceAuthorityTx - should fail on replace contract that is not deployed to contract address         ✅ Contracts API Snark Upgrade [single contract] > submitReplaceAuthorityTx - should fail when signing key for contract address does not exist         ✅ Contracts API Snark Upgrade [single contract] > submitInsertVerifierKeyTx - should fail on invalid verifier key         ✅ Contracts API Snark Upgrade [single contract] > submitInsertVerifierKeyTx - successful insert on not present circuitId [@slow]         ✅ Contracts API Snark Upgrade [single contract] > submitInsertVerifierKeyTx - should fail on contract not present on contract address         ✅ Contracts API Snark Upgrade [single contract] > submitInsertVerifierKeyTx - should fail on providers for different contract with different API         ✅ Contracts API Snark Upgrade [single contract] > submitRemoveVerifierKeyTx - should fail on not present circuitId         ✅ Contracts API Snark Upgrade [single contract] > submitRemoveVerifierKeyTx - should fail on contract not present on contract address         ✅ Contracts API Snark Upgrade [single contract] > submitRemoveVerifierKeyTx - should fail on providers for different contract with different API         ✅ Contracts API Snark Upgrade [single contract] > createContractMaintenanceTxInterface - replaceAuthority - successful replace authority with the new one [@slow]         ✅ Contracts API Snark Upgrade [single contract] > createContractMaintenanceTxInterface - replaceAuthority - successful replace authority with the same one [@slow]         ✅ Contracts API Snark Upgrade [single contract] > createContractMaintenanceTxInterface - replaceAuthority - should fail on contract not present on contract address         ✅ Contracts API Snark Upgrade [single contract] > createContractMaintenanceTxInterface - insertVerifierKey - fail when key is still present         ✅ Contracts API Snark Upgrade [single contract] > createContractMaintenanceTxInterface - insertVerifierKey - success when no key present [@slow]         ✅ Contracts API Snark Upgrade [single contract] > createCircuitMaintenanceTxInterfaces - insertVerifierKey - fail when key is already present         ✅ Contracts API Snark Upgrade [single contract] > createCircuitMaintenanceTxInterfaces - insertVerifierKey - success when no key present [@slow]         ✅ Contracts API Snark Upgrade [single contract] > createCircuitMaintenanceTxInterfaces - removeVerifierKey - should fail on contract not present on contract address	✅ 19	❌ 0	⏭️ 0	3m 36s
✅ testkit-js/testkit-js-e2e/test/contracts.snarkupgrade.smoke.it.test.ts         ✅ Contracts API Snark Upgrade [@slow][@smoke] > should update verifier keys from one contract to another [@smoke]         ✅ Contracts API Snark Upgrade [@slow][@smoke] > should fail on operate with previous authority after replacement	✅ 2	❌ 0	⏭️ 0	3m 36s
✅ testkit-js/testkit-js-e2e/test/indexer-public-data-provider.observable1.it.test.ts         ✅ Indexer API > should return the history of states starting from defined blockHash (inclusive:true, expected:1,2) [@slow]         ✅ Indexer API > should return the history of states starting from defined blockHash (inclusive:false, expected:2) [@slow]         ✅ Indexer API > should return the history of states starting from defined txId (inclusive:true, expected states:1,2) [@slow]         ✅ Indexer API > should return the history of states starting from defined txId (inclusive:false, expected states:2) [@slow]	✅ 4	❌ 0	⏭️ 0	3m 38s
✅ testkit-js/testkit-js-e2e/test/indexer-public-data-provider.observable2.it.test.ts         ✅ Indexer API > should return the history of states starting from defined blockHeight (inclusive:true, expected states:1,2) [@slow]         ✅ Indexer API > should return the history of states starting from defined blockHeight (inclusive:false, expected states:2) [@slow]         ✅ Indexer API > should return the entire history of states of the contract with the given address (config:{ type: 'all' }, expected states:0,1,2) [@slow]         ✅ Indexer API > should return the history of states of the contract with the given address, starting with the most recent state (config:{ type: 'latest' }, expected states:1,2) [@slow]	✅ 4	❌ 0	⏭️ 0	3m 36s
✅ testkit-js/testkit-js-e2e/test/indexer-public-data-provider.singlecontract.it.test.ts         ✅ Indexer API > queryDeployContractState - should return a contract state equivalent to the initial contract state produced during deployment construction         ✅ Indexer API > queryContractState - should return the current contract state of a deployed contract         ✅ Indexer API > queryContractState - should return the current contract state of a deployed contract at defined block height         ✅ Indexer API > queryContractState - should return the current contract state of a deployed contract at defined block hash         ✅ Indexer API > queryContractState - should return null on no contract at contract address         ✅ Indexer API > queryZSwapAndContractState - should return the current ZSwap chain state and contract state of a deployed contract         ✅ Indexer API > queryZSwapAndContractState - should return null on no contract at contract address         ✅ Indexer API > watchForDeployTxData - should return the data of the transaction containing the deployment of the contract with the given address         ✅ Indexer API > watchForTxData - should return the data of the transaction containing the contract call with the given transaction id         ✅ Indexer API > watchForContractState - should immediately return the current state of a deployed contract	✅ 10	❌ 0	⏭️ 0	91ms
✅ testkit-js/testkit-js-e2e/test/nodejs.it.test.ts         ✅ Ledger API - NodeJS Integration Tests > should run ESM module successfully         ✅ Ledger API - NodeJS Integration Tests > should run CJS module with expected exit code	✅ 2	❌ 0	⏭️ 0	1m 23s
✅ testkit-js/testkit-js-e2e/test/proof-server.it.test.ts         ✅ Proof server integration > should create proofs successfully for deploy and call transactions         ✅ Proof server integration > should create proofs with transactions that has succesfull well-formedness         ✅ Proof server integration > should throw error for invalid ZKConfig circuitId         ✅ Proof server integration > should throw error for undefined ZKConfig         ✅ Proof server integration > should execute 5 proveTx calls in parallel without errors	✅ 5	❌ 0	⏭️ 0	1.7s
✅ testkit-js/testkit-js-e2e/test/unshielded.it.test.ts         ✅ Unshielded tokens > should mint tokens         ✅ Unshielded tokens > should get balance of tokens - 0 value         ⏭️ Unshielded tokens > should get balance of tokens - greater than         ⏭️ Unshielded tokens > should get balance of tokens - less than         ✅ Unshielded tokens > should receive tokens - invalid         ⏭️ Unshielded tokens > should receive tokens - wallet         ⏭️ Unshielded tokens > should send tokens to wallet         ✅ Unshielded tokens > should mint native tokens	✅ 4	❌ 0	⏭️ 4	1m 6s

Github Test Reporter by CTRF 💚

🔄 This comment has been updated

[github-actions]

Title	Lines	Statements	Branches	Functions
contracts		86.41% (407/471)	76.23% (154/202)	86.66% (91/105)
fetch-zk-config-provider		94.73% (18/19)	77.77% (7/9)	100% (6/6)
http-client-proof-provider		80% (24/30)	80% (8/10)	71.42% (5/7)
indexer-public-data-provider		38.61% (100/259)	25.21% (30/119)	18.01% (20/111)
level-private-state-provider		93.07% (121/130)	84.21% (32/38)	100% (32/32)
logger-provider		100% (15/15)	100% (0/0)	100% (8/8)
node-zk-config-provider		100% (11/11)	100% (0/0)	100% (5/5)
utils		86.79% (46/53)	80.48% (33/41)	63.63% (7/11)

[CLAassistant]

All committers have signed the CLA.