filecoin 0.0.0 → 0.5.1

package/package.json

@@ -1,16 +1,55 @@
 {
   "name": "filecoin",
-  "version": "0.0.0",
-  "description": "Filecoin IPLD Data Structures Documentaiton",
-  "main": "index.js",
+  "version": "0.5.1",
+  "description": "Command-line interface for Filecoin storage",
+  "license": "MIT",
+  "author": "Hugo Dias <hugomrdias@gmail.com>",
+  "homepage": "https://github.com/filecoin-project/agents/tree/main/packages/filecoin-cli#readme",
   "repository": {
     "type": "git",
-    "url": "https://github.com/ipld/specs/tree/master/data-structures/filecoin"
+    "url": "git+https://github.com/filecoin-project/agents.git",
+    "directory": "packages/filecoin-cli"
   },
-  "keywords": [
-    "filecoin",
-    "ipld"
+  "bugs": {
+    "url": "https://github.com/filecoin-project/agents/issues"
+  },
+  "type": "module",
+  "bin": {
+    "filecoin": "./bin/filecoin.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "skills",
+    "README.md"
   ],
-  "author": "Rod <rod@vagg.org> (http://r.va.gg/)",
-  "license": "Apache-2.0"
-}
+  "devDependencies": {
+    "@filoz/synapse-core": "^0.10.1",
+    "@ipld/car": "^5.4.7",
+    "@types/node": "26.5.1",
+    "clipact": "0.4.0",
+    "env-paths": "^4.0.0",
+    "esbuild": "0.28.2",
+    "ipfs-unixfs-exporter": "^16.2.3",
+    "ipfs-unixfs-importer": "^17.1.1",
+    "iso-conf": "^0.4.2",
+    "multiformats": "^14.0.5",
+    "typescript": "7.0.2",
+    "viem": "^2.56.9",
+    "zod": "4.6.5"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rm -rf dist skills",
+    "build": "node scripts/build.ts",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test 'test/**/*.test.ts'",
+    "lint": "biome check .",
+    "check": "pnpm typecheck && pnpm test && pnpm lint"
+  }
+}

package/skills/filecoin/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: filecoin
+description: Store files and folders on Filecoin with the filecoin CLI, return links to share them, and retrieve and verify them later. Use when the user asks to publish, store, share, back up, retrieve, or verify content on Filecoin.
+---
+
+# Filecoin for Agents
+
+`filecoin` stores a file (its exact bytes) or a folder (a UnixFS CAR served over IPFS) on Filecoin and returns links to share it. A person owns the wallet and approves what you may do. You never hold the wallet key.
+
+## Run it
+
+Run `filecoin` when it is on the PATH. Otherwise run `npx -y filecoin` in its place, which needs Node.js 24 or newer.
+
+Every command writes one JSON object to stdout: `data` on success or `error` on failure, then optional `next` steps. Branch on `error.code`, never on stderr text.
+
+Don't guess flags or fields. The installed CLI describes itself:
+
+- `filecoin --help` lists the commands, and `filecoin <command> --help` shows examples and flags.
+- `filecoin schema <command>` gives the input and output JSON Schemas, and what each error code means.
+
+## Workflow
+
+1. `filecoin status` shows whether a session key is approved and the account is funded.
+2. `filecoin put <path> --dry-run` reports the size, provider, cost, and missing authorization without storing anything.
+3. `filecoin put <path>` stores it. Give the user `data.urls.browser` exactly as returned, with `data.resource.ref`.
+4. `filecoin get <ref>` downloads the content and verifies it. `filecoin ls` and `filecoin inspect <ref>` find what was stored.
+
+## Rules
+
+- Never ask for or pass a private key. Logging in needs the user: `auth_required` or `login_pending` means relay the `by: "user"` step (the filecoin-app approval link) and stop. After the user approves, run `filecoin login --check` once to confirm. On `session_conflict`, keep the saved key unless the user agrees to approve a new one.
+- `insufficient_funds` and `session_expired` also need the user. Relay their `next` steps.
+- `filecoin delete <ref>` needs `--yes`. On `confirmation_required`, relay the reason and rerun with `--yes` only after the user agrees.
+- Never repeat a failed or interrupted `put` or `delete`: that starts a new paid operation. Run the `filecoin operations resume <id>` command from `next` instead. Errors with a filecoin CLI code also carry the ID in `error.details.operationId`. Find lost operation IDs with `filecoin operations ls --incomplete`.
+- Retry only when `error.retryable` is `true`, after `retryAfterSeconds` when present.
+
+## Read more only when you need it
+
+Fetch these pages; each is Markdown:
+
+- No browser to open, or a disk that is gone when the session ends, such as a cloud sandbox: read [Cloud agents](https://poc.filecoin.cloud/agents.md#cloud-agents) before `filecoin login`.
+- A link returns 404, the user wants proof the content is intact, or `filecoin ls` is missing content stored elsewhere: read [Retrieve and verify](https://poc.filecoin.cloud/docs/retrieve.md).

package/basic_types.md

@@ -1,94 +0,0 @@
-# Filecoin Data Structures Basic Types
-
-These types are used throughout the Filecoin data structures.
-
-```ipldsch
-# Address is a `https://github.com/filecoin-project/go-address` in its binary byte format.
-# It may be used as a hamt key, and will be often visualized or presented to users
-# in its more readable string form.
-type Address bytes
-
-# Go big.Int
-# Prefer presenting to users either as a number or a string view of the decimal number
-# for readability.
-type BigInt bytes
-
-# An indicator of which RPC method on an actor a message should trigger execution of.
-type MethodNum int
-
-# The 'f0...' subset of Addresses used for the actual indexes of actors in a state root.
-type ActorID int
-
-# the height of a block in the chain. Should fit in an Int64
-type ChainEpoch int
-
-# the ChainEpoch as bytes, where the integer is converted to its string form and
-# the string's bytes are used
-type ChainEpochBytes bytes
-
-type TokenAmount BigInt
-
-type PaddedPieceSize int
-
-type PeerID bytes
-
-type SectorSize int
-
-type SectorNumber int
-
-# the SectorNumber as bytes, where the integer is encoded as a uvarint and the
-# resulting bytes are used
-type SectorNumberBytes bytes
-
-type PartitionNumber int
-
-type BitField bytes
-
-type StoragePower BigInt
-
-type DataCap StoragePower
-
-type DealID int
-
-# the DealID as bytes, where the integer is encoded as a uvarint and the resulting
-# bytes are used
-type DealIDBytes bytes
-
-type DealWeight BigInt
-
-type Multiaddr bytes
-
-type RegisteredSealProof int
-
-type TransactionID # TxnID
-
-# the TransactionID as bytes, where the integer is encoded as a varint (not uvarint)
-# and the resulting bytes are used
-type TransactionIDBytes bytes
-
-# A quantity of space x time (in byte-epochs) representing power committed to the network for some duration.
-type Spacetime BigInt
-
-type ExitCode int
-
-# Message parameters are encoded as DAG-CBOR and the resulting bytes are
-# embedded as `Params` fields in some structs.
-# See the Filecoin Messages Data Structures document for encoded DAG-CBOR message
-# params
-type CborEncodedParams Bytes
-
-# Message receipt returns are encoded as DAG-CBOR and the resulting bytes are
-# embedded as the `Return` field in `MessageReceipt`.
-# See the Filecoin Messages Data Structures document for encoded DAG-CBOR message
-# returns
-type CborEncodedReturn Bytes
-```
-
-## Crypto Types
-
-```ipldsch
-type Signature union {
-  SignatureSecp256k1 1
-  SignatureBLS 2
-} representation byteprefix
-```

package/chain.md

@@ -1,280 +0,0 @@
-# Filecoin Main Chain Data Structures
-
-* [Genesis Block](#genesis-block)
-* [Chain](#chain)
-* [Messages](#messages)
-* [Actors](#actors)
-  * [Actor type linking](#actor-type-linking)
-
-## Genesis Block
-
-There is a single block at the base of the entire chain with this layout. It is
-the only structure that uses an actual Map at the representation level (other
-structs use the `tuple` representation which encodes them as Lists). It is
-encoded with DAG-CBOR with a SHA2-256 which gives the CID:
-`bafyreiaqpwbbyjo4a42saasj36kkrpv4tsherf2e7bvezkert2a7dhonoi`.
-
-This block is not referenced as height `0` as this is reserved for the first
-`BlockHeader` block which carries the initial state (see below). This block
-links Filecoin to the Ethereum chain.
-
-Note that this block does not conform to strict DAG-CBOR in that its Map keys
-are not sorted according to canonical rules. Therefore it does not round-trip
-cleanly through current DAG-CBOR codecs, although current codecs are able to
-decode it.
-
-```ipldsch
-type Genesis struct {
-  Datetime String
-  Network String
-  Token String
-  TokenAmounts TokenAmounts
-  Message String
-}
-
-type TokenAmounts struct {
-  TotalSupply String
-  Miners String
-  ProtocolLabs {String:String}
-}
-```
-
-## Chain
-
-`TipSetKey` is the type for linking to the parent `BlockHeader`s. It is
-important to note that its type hint, of referring to only `BlockHeader` blocks,
-does not hold true at chain height **`0`** (CID
-`bafy2bzacecnamqgqmifpluoeldx7zzglxcljo6oja4vrmtj7432rphldpdmm2`). This block
-contains a single parent CID referring to the `Genesis` (above, CID
-`bafyreiaqpwbbyjo4a42saasj36kkrpv4tsherf2e7bvezkert2a7dhonoi`).
-
-```ipldsch
-# The `ParentStateRoot` link will point either directly to `ActorsHAMT' for v0
-# or `StateRoot` which links to `ActorsHAMT` for v2.
-# See Lotus chain/state/LoadStateTree()
-type StateRootLink &Any
-
-# See note above about the single case where this type hint does not hold true.
-type TipSetKey [&BlockHeader]
-
-type BlockHeader struct {
-  Miner Address
-  Ticket nullable Ticket
-  ElectionProof nullable ElectionProof
-  BeaconEntries [BeaconEntry]
-  WinPoStProof [PoStProof]
-  Parents TipSetKey
-  ParentWeight Bytes
-  Height ChainEpoch
-  ParentStateRoot StateRootLink
-  ParentMessageReceipts &MessageReceiptAMT
-  Messages &TxMeta
-  BLSAggregate nullable Signature
-  Timestamp Int
-  BlockSig nullable Signature
-  ForkSignaling Int
-  ParentBaseFee TokenAmount
-} representation tuple
-
-type Ticket struct {
-  VRFProof Bytes
-} representation tuple
-
-type ElectionProof struct {
-  WinCount Int
-  VRFProof Bytes
-} representation tuple
-
-type BeaconEntry struct {
-  Round Int
-  Data Bytes
-} representation tuple
-
-type PoStProof struct {
-  PoStProof Int
-  ProofBytes Bytes
-} representation tuple
-```
-
-**AMT**: This is an ADL representing `type MessageReceiptList [MessageReceipt]`.
-
-```ipldsch
-type MessageReceiptAMT struct {
-  height Int
-  count Int
-  node MessageReceiptAMTNode
-} representation tuple
-
-# This can also be the root of a block
-type MessageReceiptAMTNode struct {
-  bitmap Bytes
-  children [&MessageReceiptAMTNode]
-  values [&Message]
-} representation tuple
-
-type MessageReceipt struct {
-  ExitCode ExitCode
-  Return   CborEncodedReturn
-  GasUsed  Int
-} representation tuple
-```
-
-```ipldsch
-type StateRoot struct {
-  Version Int
-  Actors &ActorsHAMT
-  Info &StateInfo
-} representation tuple
-```
-
-Note that `StateInfo` is an [empty struct](https://github.com/filecoin-project/lotus/blob/f225b7b928de73e20dd8b8d4d075a56fbf3b8a25/chain/types/state.go#L26), which encodes as an empty CBOR array (`0x80`).
-
-```ipldsch
-type StateInfo struct {
-} representation tuple
-```
-
-## Messages
-
-See **[Filecoin Messages Data Structures](messages.md)** for details on the CBOR encoded message `Params` and message returns.
-
-```ipldsch
-type TxMeta struct {
-  BlsMessages &MessageLinkAMT
-  SecpkMessages &SignedMessageLinkAMT
-} representation tuple
-```
-
-```ipldsch
-type Message struct {
-  Version Int
-  To Address
-  From Address
-  Nonce Int
-  Value BigInt
-  GasLimit Int
-  GasFeeCap BigInt
-  GasPremium BigInt
-  Method MethodNum
-  Params CborEncodedParams
-} representation tuple
-
-type SignedMessage struct {
-  Message Message
-  Signature Signature
-} representation tuple
-```
-
-**AMT**: This is an ADL representing `type MessagesList [&Message]`.
-
-```ipldsch
-type MessageLinkAMT struct {
-  height Int
-  count Int
-  node MessageLinkAMTNode
-} representation tuple
-
-# This can also be the root of a block
-type MessageLinkAMTNode struct {
-  bitmap Bytes
-  children [&MessageLinkAMTNode]
-  values [&Message]
-} representation tuple
-```
-
-**AMT**: This is an ADL representing `type SignedMessagesList [&SignedMessage]`.
-
-Note this is identical in layout to `MessagesList` and contains links at the leaves, but is listed here for completeness.
-
-```ipldsch
-type SignedMessageLinkAMT struct {
-  height Int
-  count Int
-  node SignedMessageLinkAMTNode
-} representation tuple
-
-# This can also be the root of a block
-type SignedMessageLinkAMTNode struct {
-  bitmap Bytes
-  children [&SignedMessageLinkAMTNode]
-  values [&SignedMessage]
-} representation tuple
-```
-
-## Actors
-
-See **[Filecoin Actor State Data Structures](state.md)** for details on the Actor State objects that attach to the state tree `ActorsHAMT` as `ActorStateLink` and are differentiated by the type `Code` described below.
-
-### Actor type linking
-
-Actors are identified by a Code which is represented as a CID. The current form
-uses a `raw` codec combined with an `identity` multihash to encode a set of
-fixed strings uniquely representing the Actor type. Version 0 Actors use the
-prefix `fil/1/` while version 2 Actors use the prefix `fil/2/`, followed by the
-Actor name.
-
-The `code` field in the `Actor` struct contains this CID and indicates the type
-of block to be found when following the `head` link to load the specific Actor
-state.
-
-| Code string | Actor state type | CID | CID Bytes |
-| --- | --- | --- | --- |
-| `"fil/1/init"` | [`InitV0State`](#initv0state) | `bafkqactgnfwc6mjpnfxgs5a` | `0x0155000a66696c2f312f696e6974` |
-| `"fil/2/init"` | [`InitV2State`](#initv2state) | `bafkqactgnfwc6mrpnfxgs5a` | `0x0155000a66696c2f322f696e6974` |
-| `"fil/1/cron"` | [`CronV0State`](#cronv0state) | `bafkqactgnfwc6mjpmnzg63q` | `0x0155000a66696c2f312f63726f6e` |
-| `"fil/2/cron"` | [`CronV2State`](#cronv2state) | `bafkqactgnfwc6mrpmnzg63q` | `0x0155000a66696c2f322f63726f6e` |
-| `"fil/1/reward"` | [`RewardV0State`](#rewardv0state) | `bafkqaddgnfwc6mjpojsxoylsmq` | `0x0155000c66696c2f312f726577617264` |
-| `"fil/2/reward"` | [`RewardV2State`](#rewardv2state) | `bafkqaddgnfwc6mrpojsxoylsmq` | `0x0155000c66696c2f322f726577617264` |
-| `"fil/1/account"` | [`AccountV0State`](#accountv0state) | `bafkqadlgnfwc6mjpmfrwg33vnz2a` | `0x0155000d66696c2f312f6163636f756e74` |
-| `"fil/2/account"` | [`AccountV2State`](#accountv2state) | `bafkqadlgnfwc6mrpmfrwg33vnz2a` | `0x0155000d66696c2f322f6163636f756e74` |
-| `"fil/1/storagemarket"` | [`MarketV0State`](#marketv0state) | `bafkqae3gnfwc6mjpon2g64tbm5sw2ylsnnsxi` | `0x0155001366696c2f312f73746f726167656d61726b6574` |
-| `"fil/2/storagemarket"` | [`MarketV2State`](#marketv2state) | `bafkqae3gnfwc6mrpon2g64tbm5sw2ylsnnsxi` | `0x0155001366696c2f322f73746f726167656d61726b6574` |
-| `"fil/1/storageminer"` | [`MinerV0State`](#minerv0state) | `bafkqaetgnfwc6mjpon2g64tbm5sw22lomvza` | `0x0155001266696c2f312f73746f726167656d696e6572` |
-| `"fil/2/storageminer"` | [`MinerV2State`](#minerv2state) | `bafkqaetgnfwc6mrpon2g64tbm5sw22lomvza` | `0x0155001266696c2f322f73746f726167656d696e6572` |
-| `"fil/1/multisig"` | [`MultisigV0State`](#multisigv0state) | `bafkqadtgnfwc6mjpnv2wy5djonuwo` | `0x0155000e66696c2f312f6d756c7469736967` |
-| `"fil/2/multisig"` | [`MultisigV2State`](#multisigv2state) | `bafkqadtgnfwc6mrpnv2wy5djonuwo` | `0x0155000e66696c2f322f6d756c7469736967` |
-| `"fil/1/paymentchannel"` | [`PaychV0State`](#paychv0state) | `bafkqafdgnfwc6mjpobqxs3lfnz2gg2dbnzxgk3a` | `0x0155001466696c2f312f7061796d656e746368616e6e656c` |
-| `"fil/2/paymentchannel"` | [`PaychV2State`](#paychv2state) | `bafkqafdgnfwc6mrpobqxs3lfnz2gg2dbnzxgk3a` | `0x0155001466696c2f322f7061796d656e746368616e6e656c` |
-| `"fil/1/storagepower"` | [`PowerV0State`](#powerv0state) | `bafkqaetgnfwc6mjpon2g64tbm5sxa33xmvza` | `0x0155001266696c2f312f73746f72616765706f776572` |
-| `"fil/2/storagepower"` | [`PowerV2State`](#powerv2state) | `bafkqaetgnfwc6mrpon2g64tbm5sxa33xmvza` | `0x0155001266696c2f322f73746f72616765706f776572` |
-| `"fil/1/verifiedregistry"` | [`VerifregV0State`](#verifregv0state) | `bafkqaftgnfwc6mjpozsxe2lgnfswi4tfm5uxg5dspe` | `0x0155001666696c2f312f76657269666965647265676973747279` |
-| `"fil/2/verifiedregistry"` | [`VerifregV2State`](#verifregv2state) | `bafkqaftgnfwc6mrpozsxe2lgnfswi4tfm5uxg5dspe` | `0x0155001666696c2f322f76657269666965647265676973747279` |
-| `"fil/1/system"` | [`SystemV0State`](#systemv0state) | `bafkqaddgnfwc6mjpon4xg5dfnu` | `0x0155000c66696c2f312f73797374656d` |
-| `"fil/2/system"` | [`SystemV2State`](#systemv2state) | `bafkqaddgnfwc6mrpon4xg5dfnu` | `0x0155000c66696c2f322f73797374656d` |
-
-**HAMT**: This is an ADL representing `type ActorsMap {Address:Actors}`.
-
-```ipldsch
-# An inline CID encoded as raw+identity, see above
-type ActorCode &Any
-
-# An implicit union of each actor state types, keyed by the `ActorCode` (`code`)
-# field and its variations listed above
-type ActorStateLink &Any
-
-type ActorsHAMT struct {
-  map Bytes
-  data [ ActorsHAMTElement ]
-} representation tuple
-
-type ActorsHAMTElement union {
-  | ActorsHAMTLink "0"
-  | ActorsHAMTBucket "1"
-} representation keyed
-
-type ActorsHAMTLink &ActorsHAMT
-
-type ActorsHAMTBucket [ ActorsHAMTBucketEntry ]
-
-type ActorsHAMTBucketEntry struct {
-  key Address
-  value Actor # inline
-} representation tuple
-
-type Actor struct {
-  code ActorCode
-  head ActorStateLink
-  nonce CallSeqNum
-  balance BigInt
-} representation tuple
-```

package/index.js

@@ -1 +0,0 @@
-console.log('See README.md for an index of documents available in this package')