Abyss

SDK integration guide

Install SDK 0.12.0, discover an admitted profile, then build a launch around one saved plan. Your wallet signs the unsigned transactions returned by the SDK.

Install an SDK

Both packages publish version 0.12.0:

LanguageInstallFull guide
TypeScriptpnpm add @black-market/sdk@0.12.0 viemTypeScript lifecycle guide
Pythonpython -m pip install black-market-sdk==0.12.0Python launch guide

The guides and example links below follow main. Use the files matching your installed package when copying code. The TypeScript repository examples require Node 24+; Python requires 3.10+.

1. Choose an offering

Run discovery on Robinhood Chain mainnet, chain ID 4663. Check each profile's admitted flag and refusal reason; registry entries can include retired profiles. Do not hard-code a profile count. Compare ordinary app hooks, or follow the separate UFG treasury route.

TypeScript discovery

This snippet only reads chain state:

import {
  createProtocolPublicClient,
  getAddresses,
  launchLifecycleAbi,
  readLifecycleProfiles,
} from "@black-market/sdk";

const chainId = 4663;
const addresses = getAddresses(chainId);
const client = createProtocolPublicClient({
  chainId,
  rpcUrl: "https://rpc.mainnet.chain.robinhood.com/",
});
if (await client.getChainId() !== chainId) {
  throw new Error("RPC chain mismatch");
}
const registry = await client.readContract({
  address: addresses.launchOrchestrator,
  abi: launchLifecycleAbi,
  functionName: "registry",
});
if (registry.toLowerCase() !== addresses.launchImplementationRegistry.toLowerCase()) {
  throw new Error("Orchestrator and registry are not the same deployment graph");
}
const profiles = await readLifecycleProfiles({
  client,
  orchestrator: addresses.launchOrchestrator,
});
console.table(profiles.map(({ id, admitted, reason }) => ({ id, admitted, reason })));

Lifecycle APIs also have a browser-safe @black-market/sdk/lifecycle entry point.

Python discovery

from web3 import Web3
from black_market_sdk import get_launch_addresses, read_lifecycle_profiles

chain_id = 4663
client = Web3(Web3.HTTPProvider("https://rpc.mainnet.chain.robinhood.com/"))
if client.eth.chain_id != chain_id:
    raise RuntimeError("RPC chain mismatch")
addresses = get_launch_addresses(chain_id)
profiles = read_lifecycle_profiles(
    client, orchestrator=addresses.orchestrator, offset=0, limit=100
)
for profile in profiles:
    print(profile.id, profile.admitted, profile.reason)

Use the current address table when checking the selected deployment.

2. Price the token and allocate supply

Choose total supply and one opening valuation, then divide the supply between markets. Use deriveLaunchPoolRecipe / derive_launch_pool_recipe for the quote ratio and tick alignment, and deriveLaunchPositionRanges / derive_launch_position_ranges for SDK range recipes. The pricing tutorial covers decimals, orientation, continuous coverage and the boundary tail.

The eleven ordinary examples use $5,000 through EXAMPLE_TARGET_MARKET_CAP_USD; the app uses a $15,000 minimum/default. These are different defaults, not price recommendations.

3. Prepare and save the plan

Call prepareAndPlanLifecycleLaunch / prepare_and_plan_lifecycle_launch with an explicit atomic or staged mode. It prepares pool-bound hook salts and plans that mode. Canonical Abyss uses config1; current pool-bound V4 uses config6. Copy the profile's bindings and terms from discovery, then use the matching SDK encoder.

Save the returned plan with serializeLaunchPlan / launch_plan_to_dict, plus mode, confirmation policy and receipt references. Restore it with parseLaunchPlan / launch_plan_from_dict. Use TypeScript bigint or Python int for amounts and fixed-point prices; portable JSON stores large integers as decimal strings.

4. Check what simulation proved

simulateLaunchPlan / simulate_launch_plan reports the proven steps and any deferred work. Robinhood's default aggregate simulation budget is 50M gas. A large staged plan can prove begin/preparation without proving activation. Staging still needs one final activation transaction.

Opening-buy calibration through buySlippageBps / buy_slippage_bps needs actual activation outputs. If activation is deferred, use a provider with a sufficient simulation budget or simplify the launch before committing. The TypeScript examples expose EXAMPLE_SIMULATION_GAS_CAP; raise it only when the RPC supports that budget.

5. Sign only the next step

Call buildNextTransaction / build_next_transaction immediately before each wallet request. Check account, chain, target, native value, calldata and gas. Submit that unsigned transaction, retain its reference, and use readLaunchProgress / read_launch_progress before continuing. For an existing plan, planLaunch / plan_launch resumes planning against current chain progress.

An interrupted launch keeps its original identity. Do not generate a new nonce to retry a pending transaction. Use the recovery steps.

6. Publish the existing token

After a successful activation receipt, check Active, then publish metadata and wait for API indexing. Set LAUNCH_API_URL=https://api.abyss.trading for the examples. Their publication flow handles metadata authorization and optional image upload. An API timeout after activation calls for publication recovery, not another deployment.

Run a complete example

Each SDK has 11 ordinary cases: ERC20 V4, ERC20 Abyss, ERC404 V4, ERC404 Abyss, ERC20 V4 staking, ERC20 Abyss dividends, ERC20 mixed-venue burn, ERC404 mixed-venue dividends, ERC20 V4 depth, ERC20 multi-quote, and ERC20 multi-quote mixed-venue dividends. See the TypeScript example inventory or Python example inventory.

Run from the matching SDK checkout after installing its dependencies; run pnpm build first for TypeScript. Configure one signer source using that repository's examples/.env.example. Dry runs derive the public creator address but do not sign, broadcast, upload or publish:

LAUNCH_API_URL=https://api.abyss.trading node examples/launch-erc20-v4.ts
LAUNCH_API_URL=https://api.abyss.trading python examples/launch_erc20_v4.py

Adding --broadcast authorizes signing, real spending and publication. It creates a fresh plan; it does not submit the dry run's plan. After any partial execution, use the same case with --resume <original-run-dir> instead. Resume can send the remaining transactions and does not need --broadcast. Keep recovery files private. The eleven cases are not UFG runners; use the treasury guide for that route.

7. Collect fees and claim income

Creators and holders can use the app's fee and reward actions. Hook-author royalties use the SDK reference below.

Hook-author reference

Submit a design through abyss-hooks. Registry admission and author terms are separate from a source merge. The four ordinary app hooks have zero author royalty.

Claim author earnings with an SDK

Hook-author royalty claims have no web UI. Read credits by asset, build an unsigned claim and submit it through your wallet:

TaskTypeScriptPython
Read author identity and payoutreadLifecycleAuthorread_lifecycle_author
Find the author's fee hubsreadAuthorHubsread_author_hubs
Read credited earningsreadDeveloperFeesread_developer_fees
Build a claim for one hub and assetbuildClaimDeveloperFeesTransactionbuild_claim_developer_fees_transaction
Build a bounded page of claimsbuildClaimDeveloperFeesPageTransactionbuild_claim_developer_fees_page_transaction
Check payment resultsdecodeDeveloperClaimReceiptdecode_developer_claim_receipt

Use the TypeScript author and V3 fee guide or Python author and fee-claim guide for arguments. Start from the current implementation registry; the helpers authenticate each fee hub.

Claims pay the author's current registered payout wallet without collecting new market fees. Decode the receipt: a paginated claim can contain failed payment rows even when its transaction succeeds.

Author payout controls

The author identity stays fixed. Its payout controller or registry administrator can change the payout wallet, including the destination of existing credits. This is separate from a creator transferring fee ownership. See royalty limits and rounding.

On this page