sporeprotocol / spore-sdk

The Ultimate TypeScript SDK for Spore Protocol

Spore SDK

「The Ultimate TypeScript SDK for Spore Protocol」

Spore SDK is a comprehensive web development kit specifically designed for seamless integration with Spore, an on-chain asset protocol to power digital asset ownership, distribution, and value capture, built on top of CKB.

With Spore SDK, developers gain access to powerful tools and resources that enable them to effortlessly create spore-related dapps, fully leveraging the immense potential of Spore Protocol.

Features

• ⚡ Composed APIs for efficient spores/clusters interactions with minimal time overhead
• 🧩 Joint APIs for building advanced transactions as a fun block-building process
• 🛠️ Utilities for encoding/decoding data of spores/clusters
• 🎹 Fully written in TypeScript

Documentation

Full documentation and instructions, visit: Spore Docs.

Getting started

Installation

Go through the recipe Start using Spore SDK for installation.

Running in Node.js

• Follow the tutorial to learn about spore creation: Create your first Spore
• Refer to specific code snippets: Spore Examples

Running in browsers

• Follow the tutorial to build a dapp from scratch: Create simple on-chain blog
• Explore all featured dapp demos: Spore Demos

Development

Toolchain & utilities

• @spore-sdk/core - Provides essential tools for constructing basic and advanced transactions on spores and clusters. Additionally, it offers convenient utilities for handling serialization of spores/clusters

Reference

• Examples - Code block examples for implementing basic and specific features

• Demos - Demo applications with full functionality, including seamless integration with wallets

API

• Composed APIs - Efficient APIs to build Spore transactions with minimal time overhead

• Utilities - Handy helper functions to save developers' time and effort

Community

Chat everything about Spore here:

• Join our discord channel: HaCKBee
• Contact via email: [email protected]

Contributing

To submit pull requests, make sure:

• Please submit pull requests based on the beta branch
• Please ensure your commit styling won't conflict with the existing commits
• Please provide a clear and descriptive title and description for your pull requests

License

MIT License

spore-sdk's Issues

Co-build intergration

Status

• What is co-build
• What needs to be implemented in the SDK
• Implement co-build in the SDK
• Tests

Reference

Transfer spore error prompt Resolve failed Unknown

Steps to reproduce the behavior:
1、This cell can also be queried during Transfer Spore
2、Build another transaction immediately upon sending it

Error prompt appears:

Error: {"code":-301,"message":"TransactionFailedToResolve: Resolve failed Unknown(OutPoint(0xe6967e78d3b87471a3fa8e2c644dd26004dfda44b79ad26c71e762ec2431edab00000000))","data":"Resolve(Unknown(OutPoint(0xe6967e78d3b87471a3fa8e2c644dd26004dfda44b79ad26c71e762ec2431edab00000000)))"}

Report the needed CKB if transaction failed with insufficient capacity

Description

current information lacks concrete CKB number to prompt developer the potential mistake in estimation transaction CKB cost, for a better development experience, we should enrich our log printings on insufficient capacity occurs.

Need to complete Github CI test in native CKB node

Feature limitation for different versions of type scripts

In #31, a new version of SporeType is added to the testnet config, the new contract supports a lot of new features:

• Lock Proxy in Spore creation
• Cluster Proxy/Agent
• Spore Mutant
• ...

The mentioned new features are not supported in the previous version of SporeType. However, structurally, all versions of SporeType scripts share the same logic/codec in the spore-sdk. This could potentially lead to an issue where old versions of scripts may attempt to use new/unsupported features.

Therefore, we may need a design to separate different versions of scripts and limit their capabilities. For example, we can define a new prop features (map/object type) and define what feature can a specific version of script use:

- SporeType
  tags: [v1]
  features:
    mutant: false
    clusterLockProxy: false
    clusterProxyAgent: false
- SporeType
  tags: [v2, latest]
  features:
    mutant: true
    clusterLockProxy: true
    clusterProxyAgent: true

Should use Uint8 for ClusterAgentArgs.minPayment

The codec ClusterAgentArgs.minPayment is using Uint16 as type, which should be modified to Uint8.

The error messages for checking the type of the target cell need improvement.

• Using an older version of the SDK cannot transfer the new version of Spore, and the error message needs to be improved.

https://github.com/sporeprotocol/spore-sdk/blob/beta/packages/core/src/api/joints/spore/getSpore.ts#L22C1-L26C4

A typo in the compose-api doc

1. In transferCluster API's props, the "destroy" should not be mentioned:
   https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/composed-apis.md?plain=1#L224

2. Also, the declaration of "outPoint" is not clear enough.

Missing SporeData.clusterId validations

By definition, the SporeData.clusterId property should be an optional Type ID, represented by a 32-byte hash or nothing. However, its corresponding codec is BytesOpt instead of Byte32. This means that if you pass an incorrect format of clusterId and attempt to find a cluster cell, the SDK won't recognize the error.

To address this issue, we should implement logic to pre-check spore/cluster IDs before using them. This will help ensure that the IDs are in the correct format and can be properly processed by the SDK.

The `injectCapacityAndPayFee` method has an unnecessary prop

The injectCapacityAndPayFee method asks for a fee prop, I think it's redundant and should be deprecated.

Remove `minPayment` from the transferClusterProxy API

The decision here is to remove the prop from the API, to mark the type args of ClusterProxy as permanent.

Ref: sporeprotocol/spore-contract#30

Maintain an api-doc for sdk utilities

Users are unaware of the utilities provided by the spore-sdk.
To address this, we need to maintain an API documentation for the utilities.

Duplicated capacity colelction

Just found a duplicated piece of code in the createSpore API that it collects capacity at least twice in the transaction building process. It wouldn't really cost a huge trouble to the users, but it may ask the capacity founders for more capacity when building the transaction. And even if the issue exists, those extra capacity will be returned in the outputs.

Ref:
https://github.com/sporeprotocol/spore-sdk/blob/beta/packages/core/src/api/composed/spore/createSpore.ts#L73-L80

The logic of the `meltSpore` API is strange

Since spores are defaultly filled with capacity margin, the meltSpore API should not ask for fromInfos.

Translate the error of continuously creating Spore into a user-friendly message.

Steps to reproduce the behavior:

1.Create Spores consecutively using the same account

####Error message

Error: {"code":-1107,"message":"PoolRejectedDuplicatedTransaction: Transaction(Byte32(0xfdc622e564f2883adbe51dea3ca727141a72f5b30276739fb6293eebb62c8966)) already exist in transaction_pool","data":"Duplicated(Byte32(0xfdc622e564f2883adbe51dea3ca727141a72f5b30276739fb6293eebb62c8966))"}

An unexpected null reading issue in test ci

An error occurred when attempting to read the result of RPC.getLiveCell(): Cannot read properties of null (reading 'output'). It looks the actual return type differs from the defined type. Another thing is, this error should be catched in the retryWork API, it's kinda weird that the error is even thrown publicly.

Error:
https://github.com/sporeprotocol/spore-sdk/actions/runs/7442739846/job/20246618026#step:8:1811

Souce:
https://github.com/sporeprotocol/spore-sdk/blob/beta/packages/core/src/helpers/cell.ts#L27-L39

Lumos: dependencies or peerDependencies

Lumos is a collection of packages that developers commonly use for developing dapps on CKB. It serves as a foundation for the spore-sdk and plays a significant role in managing cells and witnesses.

However, I sometimes encounter a dilemma. The spore-sdk lists lumos as a dependency in its package.json, but when lumos releases a new version, the spore-sdk doesn't automatically update to the latest version. It lags behind in this regard.

One potential solution is to move lumos from dependencies to peerDependencies. This allows developers to freely choose which version of lumos they want to use. However, this solution has a drawback: unlike dependencies, developers must manually specify and install peerDependencies into their dapp projects (as dependencies or devDependencies).

In conclusion:

• If specify in dependencies:
  • Pro - Developers don't have to manually manage lumos in most cases
  • Con - When lumos has a breaking update/fix, the spore-sdk must also release a new version
• If specify in peerDependencies:
  • Pro - Developers can freely choose which version of lumos they want to use
  • Con - Developers must manually specify and install lumos in their dapp projects

Select default scripts by tags

Currently we have specified a tags field in each version of the SporeScript, like the following:

{
  Spore: {
    versions: [
      {
        tags: ['v2', 'preview'],
        script: { ... },
        cellDep: { ... }
      },
      {
        tags: ['v1'],
        script: { ... },
        cellDep: { ... }
      },
    ]
  }
}

But no tag was used during the lifecycle of Spore/Cluster ...
I'm planning to support filtering SporeScripts with tags, a draft:

getSporeScript(config, 'Spore') // select the latest Spore script
getSporeScriptWithTags(config, 'Spore', ['v1']) // select the latest v2 Spore script
getSporeScriptWithTags(config, 'Spore', ['preview']) // select the latest preview Spore script

Change "Predefined" to "Default"

Context:

I feel Default is easier to understand than Predefined?
e.g defaultConfig or defaultSetting

Changes:

Inside SDK - export type PredefinedSporeConfigScriptName = 'Spore' | 'Cluster';

Used in "spore-fire-example" - const config = predefinedSporeConfigs.Aggron4;

Deprecating `predefinedSporeConfigs.Aggron4`

The config predefinedSporeConfigs.Aggron4 is deprecated in #79.
It's now recommended to use predefinedSporeConfigs.Testnet instead.

We should replace all usages of the variable from our docs/examples/demos.

In `transferSpore`, `outPoint` references the spore of another account.

####Steps to reproduce the behavior:
1.Create a createSore using account A
2.In transferSpore, outPoint references the spore created by account A.
3.In signAndSendTransaction, use account B.

####example
https://github.com/ShookLyngs/spore-sdk/blob/fef9f042eb85a1293b3c37ff2db347a3049279a7/packages/core/src/__tests__/invisible-fee.test.ts#L94-L120

####Error message

Error: {"code":-302,"message":"TransactionFailedToVerify: Verification failed Script(TransactionScriptError { source: Inputs[0].Lock, cause: ValidationFailure: see the error code -31 in the page https://nervosnetwork.github.io/ckb-script-error-codes/by-type-hash/9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8.html#-31 })","data":"Verification(Error { kind: Script, inner: TransactionScriptError { source: Inputs[0].Lock, cause: ValidationFailure: see the error code -31 in the page https://nervosnetwork.github.io/ckb-script-error-codes/by-type-hash/9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8.html#-31 } })"}

Rewrite on-chain transaction-related tests

Description

Currently, our on-chain transaction-related test cases, such as creating/transferring Spores on the CKB testnet, can only be run locally with manual adjustments. This is hindering our goal of implementing GitHub Automations. Therefore, I'd like to rewrite all the following test cases, focusing on testing the major features of Spore.

Status

• Rewrite Spore & Cluster basic tests
• Rewrite ClusterProxy & ClsuterAgent tests

Tests

Basics

Cluster

• Create a Cluster (v2)
• Transfer a Cluster (v2)

Spore

Basic operations

• Create a Spore
• Transfer a Spore
• Melt a Spore

Immortal

• Create an immortal Spore
• Try melt an immortal Spore

Referencing Cluster

• Create a Spore with Cluster (v2)
  • via cell reference
  • via lock proxy
• Create a Spore with Cluster (v1)
  • via cell reference

ClusterProxy & ClsuterAgent

ClusterProxy

• Create a ClusterProxy with Cluster (v2)
  • via cell reference
  • via lock proxy
• Craete a ClusterProxy with Clsuter (v1)
  • via cell reference
• Transfer a ClusterProxy
• Melt a ClusterProxy

ClusterAgent

• Create a ClusterAgent with ClusterProxy
  • via cell reference
  • via payment
• Transfer a ClusterAgent
• Melt a ClusterAgent

Spore

• Create a Spore with ClusterAgent
  • via cell reference
  • via lock proxy

Automatically test the SDK with GitHub Actions

We have 2 kinds of tests right now:

• Tests that cost capacity - Can run locally
• Tests that are don't cost capacity - Can run in github actions

@Dawn-githup In order to set up github actions to automatically test the sdk, we need a to address the capacity costing issue.

Automatically search all of Spore cells with different code hashes

Description

spore-sdk current has only one selection to show Spore cells with fixed code hash, but in reality, we are supposed to have more than one versions of Spore cells, and the responsibility to filter them all is on our side not the application layer, so we've got to implement this feature for compatibility use.

maybe I guess, this feature also should be enabled in spore-graphql project.

Cannot encode from utf-8 raw string

Description

The bytes.bytifyRawString method only supports encoding/decoding of the ASCII charset, so whenever we encode a UTF-8 raw sting with the method, it throws "Invalid UTF-8 raw string!". For this reason, we need to provide a new utility function to handle the encoding/decoding of the UTF-8 charset.

Solutions

Use TextEncoder and TextDecoder

• Node: https://stackoverflow.com/questions/69187442/const-utf8encoder-new-textencoder-in-node-js
• Browser: https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder
• Caniuse: https://caniuse.com/?search=TextEncoder

Use Buffer

• https://github.com/ckb-js/lumos/blob/93d7f7e7a5e9454911a902be3f0fc7e96e8d3125/packages/codec/examples/custom-codec-utf8string.ts