launchpad package

CollectDepositGns withdraws the GNS amount recorded by a deposit.

Parameters:

• cur: current realm context; callers use cross(cur) when crossing into this realm.
• depositID: identifier of the deposit whose GNS is collected.

Returns:

• amount: GNS amount withdrawn from the deposit.
• err: non-nil when the deposit cannot be collected.

Halt check: reverts while the Withdraw halt scope is active.

CollectEmissionReward collects accumulated launchpad emission rewards.

Parameters:

• cur: current realm context; callers use cross(cur) when crossing into this realm.

Halt check: reverts while the Withdraw halt scope is active.

CollectProtocolFee collects protocol-fee rewards allocated to project recipients.

Parameters:

• cur: current realm context; callers use cross(cur) when crossing into this realm.

Halt check: reverts while the Withdraw halt scope is active.

CollectProtocolFeeReward collects accumulated launchpad protocol-fee rewards for a token path.

Parameters:

• cur: current realm context; callers use cross(cur) when crossing into this realm.
• tokenPath: token path whose accumulated protocol-fee reward is collected.

Halt check: reverts while the Withdraw halt scope is active.

CollectRewardByDepositId collects the project-token reward earned by a deposit.

Parameters:

• cur: current realm context; callers use cross(cur) when crossing into this realm.
• depositID: identifier of the deposit whose reward is collected.

Returns:

• amount: project-token reward amount transferred to the depositor.

Halt check: reverts while the Withdraw halt scope is active.

CreateProject creates a new launchpad project callable by the administrator or governance.

Parameters:

• cur: current realm context; callers use cross(cur) when crossing into this realm.
• name: human-readable project name.
• tokenPath: token path whose tokens are distributed as project rewards.
• recipient: address authorized to receive project rewards and project proceeds.
• depositAmount: total reward-token amount allocated to the project.
• conditionTokens: optional `*PAD*`-separated token paths required for deposits.
• conditionAmounts: optional `*PAD*`-separated required amounts matching conditionTokens.
• tier30Ratio: reward allocation ratio for the 30-day tier.
• tier90Ratio: reward allocation ratio for the 90-day tier.
• tier180Ratio: reward allocation ratio for the 180-day tier.
• startTime: Unix timestamp at which project reward distribution starts.

Returns:

• projectId: identifier assigned to the newly created project.

Halt check: reverts while the Launchpad halt scope is active.

DepositGns deposits GNS into a selected launchpad project tier.

Parameters:

• cur: current realm context; callers use cross(cur) when crossing into this realm.
• targetProjectTierID: project-tier identifier in `{projectID}:{tierDuration}` form.
• depositAmount: amount of GNS to stake in the selected tier.
• referrer: optional referral address associated with the deposit.

Returns:

• depositId: identifier assigned to the newly created deposit.

Halt check: reverts while the Launchpad halt scope is active.

GetCurrentDepositId returns the current deposit counter value.

Returns:

• depositId: current deposit counter value; it is not incremented by this read.

GetDepositAmount returns the deposit amount of a deposit by its ID.

Parameters:

• depositId: unique identifier of the deposit to inspect.

Returns:

• amount: GNS principal deposited, in base units.
• err: non-nil when depositId does not identify a stored deposit.

GetDepositCount returns the total number of deposits.

Returns:

• count: number of deposit records currently stored.

GetDepositCreatedAt returns the created time of a deposit by its ID.

Parameters:

• depositId: unique identifier of the deposit to inspect.

Returns:

• createdAt: deposit creation Unix timestamp in seconds.
• err: non-nil when depositId does not identify a stored deposit.

GetDepositCreatedHeight returns the created height of a deposit by its ID.

Parameters:

• depositId: unique identifier of the deposit to inspect.

Returns:

• height: creation block height of the deposit.
• err: non-nil when depositId does not identify a stored deposit.

GetDepositEndTime returns the end time of a deposit by its ID.

Parameters:

• depositId: unique identifier of the deposit to inspect.

Returns:

• endTime: deposit lock/end Unix timestamp in seconds.
• err: non-nil when depositId does not identify a stored deposit.

GetDepositProjectID returns the project ID of a deposit by its ID.

Parameters:

• depositId: unique identifier of the deposit to inspect.

Returns:

• projectId: project identifier associated with the deposit.
• err: non-nil when depositId does not identify a stored deposit.

GetDepositProjectTierID returns the project tier ID of a deposit by its ID.

Parameters:

• depositId: unique identifier of the deposit to inspect.

Returns:

• projectTierId: composite project-tier identifier derived from the deposit's project and tier.
• err: non-nil when depositId does not identify a stored deposit.

GetDepositTier returns the tier of a deposit by its ID.

Parameters:

• depositId: unique identifier of the deposit to inspect.

Returns:

• tier: tier duration key selected by the deposit.
• err: non-nil when depositId does not identify a stored deposit.

GetDepositWithdrawnHeight returns the withdrawn height of a deposit by its ID.

Parameters:

• depositId: unique identifier of the deposit to inspect.

Returns:

• height: withdrawal block height; zero when the deposit has not been withdrawn.
• err: non-nil when depositId does not identify a stored deposit.

GetDepositWithdrawnTime returns the withdrawn time of a deposit by its ID.

Parameters:

• depositId: unique identifier of the deposit to inspect.

Returns:

• withdrawnAt: withdrawal Unix timestamp in seconds; zero when the deposit has not been withdrawn.
• err: non-nil when depositId does not identify a stored deposit.

GetImplementationPackagePath returns the package path of the currently active implementation.

Returns:

• packagePath: package path of the active implementation

GetProjectActiveStatus returns whether a project is currently active.

Parameters:

• projectId: unique identifier of the project to inspect.

Returns:

• active: true when the project is active at the current Unix time; false when it is inactive.
• err: non-nil when projectId does not identify a stored project.

GetProjectCreatedAt returns the created time of a project by its ID.

Parameters:

• projectId: unique identifier of the launchpad project to inspect.

Returns:

• createdAt: Unix timestamp in seconds at which the project was created.
• err: non-nil when projectId does not identify a stored project.

GetProjectCreatedHeight returns the created height of a project by its ID.

Parameters:

• projectId: unique identifier of the launchpad project to inspect.

Returns:

• height: block height at which the project was created.
• err: non-nil when projectId does not identify a stored project.

GetProjectDepositAmount returns the deposit amount of a project by its ID.

Parameters:

• projectId: unique identifier of the launchpad project to inspect.

Returns:

• amount: project-token amount initially allocated to the project, in token base units.
• err: non-nil when projectId does not identify a stored project.

GetProjectName returns the name of a project by its ID.

Parameters:

• projectId: unique identifier of the launchpad project to inspect.

Returns:

• name: stored project name.
• err: non-nil when projectId does not identify a stored project.

GetProjectTierDistributeAmountPerSecondX128 returns the distribute amount per second (Q128) of a project tier.

Parameters:

• projectId: unique identifier of the project containing the tier.
• tier: tier duration key, such as 30, 90, or 180.

Returns:

• amountPerSecondX128: project-token distribution rate per second in Q128 fixed-point units; nil when no value is available.
• err: non-nil when the project or tier cannot be found.

GetProjectTierEndTime returns the end time of a project tier.

Parameters:

• projectId: unique identifier of the project containing the tier.
• tier: tier duration key, such as 30, 90, or 180.

Returns:

• endTime: tier end timestamp in Unix seconds.
• err: non-nil when the project or tier cannot be found.

GetProjectTierRewardAccumulatedDistributeAmount returns a legacy reward-manager field. The v1 reward paths do not maintain it, so normal reads return zero unless it was explicitly set.

Parameters:

• projectTierId: composite project-tier identifier whose manager is requested.

Returns:

• amount: legacy accumulated distribution amount in token base units; v1 accounting normally leaves it at zero unless explicitly set.
• err: non-nil when projectTierId does not identify a stored reward manager.

GetProjectTierRewardAccumulatedRewardPerDepositX128 returns the accumulated reward per deposit (Q128) of a reward manager.

Parameters:

• projectTierId: composite project-tier identifier whose manager is requested.

Returns:

• accumulatedRewardPerDepositX128: accumulated reward index per deposited GNS unit in Q128 fixed-point units; nil when no value is available.
• err: non-nil when projectTierId does not identify a stored reward manager.

GetProjectTierRewardAccumulatedTime returns the accumulated time of a reward manager.

Parameters:

• projectTierId: composite project-tier identifier whose manager is requested.

Returns:

• time: last reward-accumulation timestamp in Unix seconds, or zero before accumulation.
• err: non-nil when projectTierId does not identify a stored reward manager.

GetProjectTierRewardClaimableDuration returns the reward claimable duration of a reward manager.

Parameters:

• projectTierId: composite project-tier identifier whose manager is requested.

Returns:

• duration: reward claimable window in seconds.
• err: non-nil when projectTierId does not identify a stored reward manager.

GetProjectTierRewardDistributeAmountPerSecondX128 returns the distribute amount per second (Q128) of a reward manager.

Parameters:

• projectTierId: composite project-tier identifier whose manager is requested.

Returns:

• amountPerSecondX128: reward distribution rate per second in Q128 fixed-point token units; nil when no value is available.
• err: non-nil when projectTierId does not identify a stored reward manager.

GetProjectTierRewardDistributeEndTime returns the distribute end time of a reward manager.

Parameters:

• projectTierId: composite project-tier identifier whose manager is requested.

Returns:

• endTime: reward distribution end timestamp in Unix seconds.
• err: non-nil when projectTierId does not identify a stored reward manager.

GetProjectTierRewardDistributeStartTime returns the distribute start time of a reward manager.

Parameters:

• projectTierId: composite project-tier identifier whose manager is requested.

Returns:

• startTime: reward distribution start timestamp in Unix seconds.
• err: non-nil when projectTierId does not identify a stored reward manager.

GetProjectTierRewardManagerCount returns the total number of reward managers.

Returns:

• count: number of project-tier reward managers currently stored.

GetProjectTierRewardTotalClaimedAmount returns the total claimed amount of a reward manager.

Parameters:

• projectTierId: composite project-tier identifier whose manager is requested.

Returns:

• amount: total reward amount claimed from the manager, in token base units.
• err: non-nil when projectTierId does not identify a stored reward manager.

GetProjectTierRewardTotalDistributeAmount returns the total distribute amount of a reward manager.

Parameters:

• projectTierId: composite project-tier identifier whose manager is requested.

Returns:

• amount: total reward allocation managed for the project tier, in token base units.
• err: non-nil when projectTierId does not identify a stored reward manager.

GetProjectTierRewards returns a read-only view of a project tier's reward states, keyed by deposit ID. Reading an entry yields a clone, so the view cannot mutate realm state. nil is returned when the project tier does not exist.

Parameters:

• projectId: unique identifier of the project containing the tier.
• tier: tier duration key, such as 30, 90, or 180.

Returns:

• rewards: read-only tree of reward states keyed by deposit ID; nil when the tier's reward manager is unavailable.

GetProjectTierStartTime returns the start time of a project tier.

Parameters:

• projectId: unique identifier of the project containing the tier.
• tier: tier duration key, such as 30, 90, or 180.

Returns:

• startTime: tier start timestamp in Unix seconds.
• err: non-nil when the project or tier cannot be found.

GetProjectTierTotalCollectedAmount returns the total collected amount of a project tier.

Parameters:

• projectId: unique identifier of the project containing the tier.
• tier: tier duration key, such as 30, 90, or 180.

Returns:

• amount: cumulative project-token reward collected from the tier, in token base units.
• err: non-nil when the project or tier cannot be found.

GetProjectTierTotalDepositAmount returns the total deposit amount of a project tier.

Parameters:

• projectId: unique identifier of the project containing the tier.
• tier: tier duration key, such as 30, 90, or 180.

Returns:

• amount: cumulative GNS principal deposited into the tier, in base units.
• err: non-nil when the project or tier cannot be found.

GetProjectTierTotalDepositCount returns the total deposit count of a project tier.

Parameters:

• projectId: unique identifier of the project containing the tier.
• tier: tier duration key, such as 30, 90, or 180.

Returns:

• count: cumulative number of deposits created in the tier.
• err: non-nil when the project or tier cannot be found.

GetProjectTierTotalDistributeAmount returns the total distribute amount of a project tier.

Parameters:

• projectId: unique identifier of the project containing the tier.
• tier: tier duration key, such as 30, 90, or 180.

Returns:

• amount: total project-token allocation for the tier, in token base units.
• err: non-nil when the project or tier cannot be found.

GetProjectTierTotalWithdrawAmount returns the total withdraw amount of a project tier.

Parameters:

• projectId: unique identifier of the project containing the tier.
• tier: tier duration key, such as 30, 90, or 180.

Returns:

• amount: cumulative GNS principal withdrawn from the tier, in base units.
• err: non-nil when the project or tier cannot be found.

GetProjectTierTotalWithdrawCount returns the total withdraw count of a project tier.

Parameters:

• projectId: unique identifier of the project containing the tier.
• tier: tier duration key, such as 30, 90, or 180.

Returns:

• count: cumulative number of withdrawals completed in the tier.
• err: non-nil when the project or tier cannot be found.

GetProjectTiersRatios returns the tiers ratios map of a project by its ID.

Parameters:

• projectId: unique identifier of the launchpad project to inspect.

Returns:

• tiersRatios: cloned map from tier duration to its allocation ratio.
• err: non-nil when projectId does not identify a stored project.

GetProjectTokenPath returns the token path of a project by its ID.

Parameters:

• projectId: unique identifier of the launchpad project to inspect.

Returns:

• tokenPath: reward-token contract path configured for the project.
• err: non-nil when projectId does not identify a stored project.

GetProjects returns a read-only view of every project, keyed by project ID. Callers paginate it themselves through IterateByOffset. Reading an entry yields a clone, so the view cannot mutate realm state.

Returns:

• projects: read-only tree keyed by project ID; reading an entry yields a clone.

GetTotalGNSStakedAmount returns the total amount of GNS currently staked across all launchpad deposits.

Returns:

• amount: total GNS principal currently staked across launchpad deposits, in base units.

MakeProjectID combines a token path and creation height into a project identifier.

Parameters:

• tokenPath: token path associated with the project.
• createdHeight: block height at which the project was created.

Returns:

• projectID: identifier in "{tokenPath}:{createdHeight}" form.

MakeProjectTierID constructs the tier identifier from a project ID and duration. The resulting identifier uses the "{projectID}:{duration}" format.

Parameters:

• projectID: unique launchpad project identifier associated with the tier.
• duration: tier duration in days, such as 30, 90, or 180.

Returns:

• projectTierID: identifier combining projectID and duration with a colon.

NewBPTreeN allocates a BP-tree under /r/gnoswap/launchpad's realm context (the realm that declares Project/Deposit/RewardManager). The tree's PkgID is therefore /r/gnoswap/launchpad, matching the domain values it stores, so tree.Set leaf-slot writes clear the readonly-taint gate regardless of which realm (launchpad/v1, mock, tests) calls Set. Implementations, mocks, and tests must allocate launchpad trees through here rather than calling bptree.NewBPTreeN directly in their own realm.

Parameters:

• fanout: branching factor passed to the BP-tree constructor.

Returns:

• tree: new BP-tree allocated under the launchpad realm's package context.

RegisterInitializer registers a new launchpad implementation version. This function is called by each version (v1, v2, etc.) during initialization to register their implementation with the proxy system.

The initializer function creates a new instance of the implementation using the provided launchpadStore interface.

Security: Only contracts within the domain path can register initializers. Each package path can only register once to prevent duplicate registrations.

Parameters:

• cur: current realm context; callers use cross(cur) when crossing into this realm.
• initializer: callback that receives the implementation realm context and launchpad store, then returns the version's ILaunchpad implementation; its leading integer discriminator is invoked as 0.

Render delegates web rendering to the active implementation.

TransferLeftFromProjectByAdmin transfers unreserved reward tokens from an ended project. Active depositor claims remain reserved and are excluded; only the administrator may call it.

Parameters:

• cur: current realm context; callers use cross(cur) when crossing into this realm.
• projectID: identifier of the ended project whose remaining balance is transferred.
• recipient: destination address for the transferable balance.

Returns:

• amount: number of reward tokens transferred after active claims are reserved.

Halt check: reverts while the Launchpad halt scope is active.

UpgradeImpl switches the active launchpad implementation to a different version. This function allows seamless upgrades from one version to another without data migration or downtime.

Security: Only admin or governance can perform upgrades. The new implementation must have been previously registered via RegisterInitializer.

Parameters:

• cur: current realm context; callers use cross(cur) when crossing into this realm.
• packagePath: registered package path of the launchpad implementation to activate.

NewCounter creates a new Counter starting at zero.

Returns:

• counter: counter initialized with current ID zero.

DefaultDeposit returns the zero Deposit value.

Returns:

• deposit: zero-valued Deposit with no identifier, amounts, timestamps, or withdrawal markers.

GetDeposit retrieves a deposit by its ID.

Parameters:

• depositId: unique identifier of the deposit to inspect.

Returns:

• deposit: stored deposit value.
• err: non-nil when depositId does not identify a stored deposit.

MakeDeposit returns a new Deposit value with the given values.

Parameters:

• depositID: unique identifier to assign to the new deposit.
• projectID: launchpad project identifier associated with the deposit.
• tier: tier duration in days; launchpad tiers use 30, 90, or 180.
• depositor: account address making the deposit.
• depositAmount: amount of GNS deposited for the project.
• createdHeight: block height at which the deposit was created.
• createdTime: creation timestamp in Unix seconds.
• endTime: tier end timestamp in Unix seconds.

Returns:

• deposit: new Deposit populated with the supplied fields and zero withdrawal markers.

NewLaunchpadStore creates a new launchpad store instance with the provided KV store. This function is used by the upgrade system to create storage instances for each implementation.

Parameters:

• kvStore: key-value store used to persist launchpad state.

Returns:

• launchpadStore: storage implementation backed by kvStore.

NewProject creates a project with empty conditions, tiers, and tier-ratio maps.

Parameters:

• name: human-readable project name.
• tokenPath: token path whose tokens are distributed as project rewards.
• depositAmount: total reward-token amount allocated to the project.
• recipient: address authorized to receive project rewards.
• createdHeight: block height at which the project is created.
• createdAt: Unix timestamp at which the project is created.

Returns:

• project: initialized project with an ID derived from tokenPath and createdHeight.

GetProjectCondition retrieves a specific condition of a project. Returns a cloned condition to prevent external modification.

Parameters:

• projectId: unique identifier of the project containing the condition.
• tokenPath: token contract path used as the condition key.

Returns:

• condition: cloned condition for the requested token; nil when the implementation returns no condition without an error.
• err: non-nil when the project or condition cannot be found.

NewProjectCondition creates a project condition for a token path and minimum amount.

Parameters:

• tokenPath: token contract path whose balance is required.
• minimumAmount: minimum balance in the token's base units.

Returns:

• condition: newly allocated project condition containing the supplied values.

NewProjectConditionsWithError parses parallel *PAD*-separated token paths and minimum amounts.

Parameters:

• conditionTokens: *PAD*-separated token contract paths, in condition order.
• conditionAmounts: *PAD*-separated decimal int64 minimum amounts paired by index with conditionTokens; entries beyond the token list are not consumed.

Returns:

• conditions: parsed available conditions in the same order as their token paths; empty when both inputs are empty.
• err: nil on successful parsing; non-nil when a token lacks a matching amount, an amount is not a valid int64, or a condition is unavailable.

GetProjectTier retrieves a specific tier of a project. Returns a cloned tier to prevent external modification.

Parameters:

• projectId: unique identifier of the project containing the tier.
• tier: tier duration key, such as 30, 90, or 180.

Returns:

• projectTier: cloned project tier; nil when the implementation supplies no tier without an error.
• err: non-nil when the project or tier cannot be found.

NewProjectTier returns a pointer to a new ProjectTier with the given values.

Parameters:

• projectID: launchpad project identifier associated with the tier.
• tierDuration: tier duration in days; launchpad tiers use 30, 90, or 180.
• totalDistributeAmount: total token amount allocated for this tier.
• startTime: tier start timestamp in Unix seconds.
• endTime: tier end timestamp in Unix seconds.

Returns:

• tier: new ProjectTier with the supplied identity, allocation, and time window; counters and rates start at zero.

GetProjectTierRewardManager retrieves a reward manager by project tier ID. Returns a cloned reward manager to prevent external modification.

Parameters:

• projectTierId: composite project-tier identifier whose manager is requested.

Returns:

• rewardManager: cloned reward manager; nil when the implementation supplies no manager without an error.
• err: non-nil when projectTierId does not identify a stored reward manager.

NewRewardManager returns a pointer to a new RewardManager with the given values.

Parameters:

• totalDistributeAmount: total reward allocation for the tier in token base units.
• distributeStartTime: reward distribution start timestamp in Unix seconds.
• distributeEndTime: reward distribution end timestamp in Unix seconds.
• rewardCollectableDuration: duration in seconds for which each accrued reward remains claimable.

Returns:

• rewardManager: initialized manager with zeroed accounting counters and an empty reward tree.

GetRewardState retrieves a reward state by project tier ID and deposit ID. Returns a cloned reward state to prevent external modification.

Parameters:

• projectTierId: composite project-tier identifier containing the reward state.
• depositId: deposit identifier whose reward state is requested.

Returns:

• rewardState: cloned reward state; nil when the implementation supplies no state without an error.
• err: non-nil when the reward manager or reward state cannot be found.

NewRewardState creates a reward state initialized from a reward-per-deposit index.

Parameters:

• accumulatedRewardPerDepositX128: current accumulated reward-per-deposit index in Q128 fixed-point units; it becomes this deposit's initial price debt.
• depositAmount: GNS amount staked by the deposit, in base units.
• distributeStartTime: Unix timestamp in seconds when this deposit begins accruing rewards.
• distributeEndTime: Unix timestamp in seconds when this deposit stops accruing rewards.
• claimableTime: Unix timestamp in seconds after which the accrued reward can be claimed.

Returns:

• rewardState: newly allocated state with claimed and legacy accumulation fields initialized to zero.