From 77361b7dcfd3965e20c5781c7cee335e5983003b Mon Sep 17 00:00:00 2001 From: dtfiedler Date: Thu, 24 Oct 2024 09:16:39 -0500 Subject: [PATCH] chore(docs): update README with auction APIs --- README.md | 139 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) diff --git a/README.md b/README.md index 824a4431..153b06cb 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,9 @@ This is the home of [ar.io] SDK. This SDK provides functionality for interacting - [`getGateways({ cursor, limit, sortBy, sortOrder })`](#getgateways-cursor-limit-sortby-sortorder-) - [`getArNSRecord({ name })`](#getarnsrecord-name-) - [`getArNSRecords({ cursor, limit, sortBy, sortOrder })`](#getarnsrecords-cursor-limit-sortby-sortorder-) + - [`getAuctions({ cursor, limit, sortBy, sortOrder })`](#getauctions-cursor-limit-sortby-sortorder-) + - [`getAuction({ name })`](#getauction-name-) + - [`getAuctionPrice({ name, type, years, intervalMs })`](#getauctionprice-name-type-years-intervalms-) - [`getDemandFactor()`](#getdemandfactor) - [`getObservations({ epochIndex })`](#getobservations-epochindex-) - [`getDistributions({ epochIndex })`](#getdistributions-epochindex-) @@ -68,6 +71,7 @@ This is the home of [ar.io] SDK. This SDK provides functionality for interacting - [`removeRecord({ undername })`](#removerecord-undername-) - [`setName({ name })`](#setname-name-) - [`setTicker({ ticker })`](#setticker-ticker-) + - [`releaseName({ name, ioProcessId })`](#releasename-name-ioprocessid-) - [Configuration](#configuration-1) - [Logging](#logging) - [Configuration](#configuration-2) @@ -595,6 +599,128 @@ Available `sortBy` options are any of the keys on the record object, e.g. `name` } ``` +#### `getAuctions({ cursor, limit, sortBy, sortOrder })` + +Retrieves all active auctions of the IO process, paginated and sorted by the specified criteria. The `cursor` used for pagination is the last auction name from the previous request. + +```typescript +const io = IO.init(); +const auctions = await io.getAuctions({ + limit: 100, + sortBy: 'endTimestamp', + sortOrder: 'asc', // return the auctions ending soonest first +}); +``` + +
+ Output + +```json +{ + "items": [ + { + "name": "permalink", + "endTimestamp": 1730985241349, + "startTimestamp": 1729775641349, + "baseFee": 250000000, + "demandFactor": 1.05256, + "initiator": "GaQrvEMKBpkjofgnBi_B3IgIDmY_XYelVLB6GcRGrHc", + "settings": { + "durationMs": 1209600000, + "decayRate": 0.000000000016847809193121693, + "scalingExponent": 190, + "startPriceMultiplier": 50 + } + } + ] +} +``` + +#### `getAuction({ name })` + +Retrieves the auction data for the specified auction name. + +```typescript +const io = IO.init(); +const auction = await io.getAuction({ name: 'permalink' }); +``` + +
+ Output + +```json +{ + "name": "permalink", + "endTimestamp": 1730985241349, + "startTimestamp": 1729775641349, + "baseFee": 250000000, + "demandFactor": 1.05256, + "initiator": "GaQrvEMKBpkjofgnBi_B3IgIDmY_XYelVLB6GcRGrHc", + "settings": { + "durationMs": 1209600000, + "decayRate": 0.000000000016847809193121693, + "scalingExponent": 190, + "startPriceMultiplier": 50 + } +} +``` + +
+ +#### `getAuctionPrice({ name, type, years, intervalMs })` + +Retrieves the auction price curve of the specified auction name for the specified type, duration, and interval. The `intervalMs` is the number of milliseconds between price points on the curve. The default interval is 15 minutes. + +```typescript +const io = IO.init(); +const priceCurve = await io.getAuctionPrice({ + name: 'permalink', + type: 'lease', + years: 1, + intervalMs: 3600000, // 1 hour price intervals (default is 15 minutes) +}); +``` + +
+ Output + +```json +{ + "name": "permalink", + "type": "lease", + "currentPrice": 12582015000, + "years": 1, + "prices": { + "1730412841349": 1618516789, + "1729908841349": 8210426826, + "1730722441349": 592768907, + "1730859241349": 379659914, + "1730866441349": 370850139, + "1730884441349": 349705277, + "1730150041349": 3780993370, + "1730031241349": 5541718397, + "1730603641349": 872066253, + "1730715241349": 606815377, + "1730942041349": 289775172, + "1730916841349": 314621977, + "1730484841349": 1281957300, + "1730585641349": 924535164, + "1730232841349": 2895237473, + "1730675641349": 690200977, + "1730420041349": 1581242331, + "1729786441349": 12154428186, + "1730308441349": 2268298483, + "1730564041349": 991657913, + "1730081641349": 4712427282, + "1730909641349": 322102563, + "1730945641349": 286388732, + "1730024041349": 5671483398, + "1729937641349": 7485620175 + // ... + } +} +``` +
#### `getDemandFactor()` @@ -1379,6 +1505,19 @@ const { id: txId } = await ant.setTicker( ); ``` +#### `releaseName({ name, ioProcessId })` + +Releases a name from the auction and makes it available for auction on the IO contract. The name must be permanently owned by the releasing wallet. 50% of the winning bid will be distributed to the ANT owner at the time of release. If no bids, the name will be released and can be reregistered by anyone. + +_Note: Requires `signer` to be provided on `ANT.init` to sign the transaction._ + +```typescript +const { id: txId } = await ant.releaseName({ + name: 'permalink', + ioProcessId: IO_TESTNET_PROCESS_ID, // releases the name owned by the ANT and sends it to auction on the IO contract +}); +``` + ### Configuration ANT clients can be configured to use custom AO process. Refer to [AO Connect] for more information on how to configure the AO process to use specific AO infrastructure.